@kolkrabbi/kol-workshop 0.6.0 → 0.18.1

package/src/shell/RightRail.jsx

@@ -0,0 +1,168 @@
+import { useState } from 'react'
+import RailSection from './RailSection.jsx'
+import RailRow from './RailRow.jsx'
+
+/**
+ * RightRail — THE right rail. One component, every route.
+ *
+ * WHY IT EXISTS (user ruling 2026-08-01). The rail was TWO components:
+ * `AutoToc` in the showcase's ShellChrome served every non-vault page, and
+ * `DocReaderSidebar` in DocumentationReader overrode it through
+ * ShellTocContext on a vault route. They disagreed about which sections exist —
+ * one had Top tags and no Related, the other had Related and tag chips and no
+ * Top tags — so sections appeared and vanished as you moved, and an edit to one
+ * rail was invisible in the other. That is the same two-systems fault the rail
+ * LADDER (RailSection) and the rail ROW (RailRow) were each built to end, one
+ * level further out.
+ *
+ * THE SECTION SET IS FIXED — *"these are not conditional, they should be
+ * STANDARDISED"*. Every section renders on every route. A section with nothing
+ * in it renders with `(0)` and an empty body; it does not disappear, because a
+ * rail whose shape depends on its content teaches the reader nothing.
+ *
+ *   THIS PAGE  ── Contents        the headings of the open document
+ *   LINKS      ── Quick actions   what you can do from here
+ *              ── Tags            THIS page's tags first and brighter, then
+ *                                 the rest of the system underneath
+ *              ── Related         other documents this one names, and its
+ *                                 sources
+ *
+ * `LINKS`, after one turn as `TOOLS` (2026-08-01). The left rail already has a
+ * `TOOLS` category — the routes the app serves — so the same word sat on the
+ * same rung in both rails meaning two unrelated things. The right rail's is the
+ * one that moved: its contents ARE destinations plus the actions that reach
+ * them, and the left rail's TOOLS is a fixed route list that cannot be renamed
+ * without lying about what it holds.
+ *
+ * ONE Tags section, not two. `Tags` and `Top tags` were separate groups saying
+ * the same word twice; a reader had to learn which was which. They are one list
+ * now, ordered: this page's own tags at the top carrying `emphasis` ink, the
+ * system's most-used underneath at the resting stop. Order and ink carry the
+ * distinction the two headings used to.
+ *
+ * THE DIV RULE — *"sometimes you group things sometimes not, there is no rule
+ * in the madness"*. There is one now, and it is applied without exception:
+ *
+ *   1. An L1 category ALWAYS wraps its groups in `.shell-rail-stack-inner`.
+ *   2. An L2 group ALWAYS wraps its rows in `nav.shell-nav-items`.
+ *   3. Nothing else wraps anything. No bare children at a rung, no conditional
+ *      wrapper, no `<div>` added because one section happened to need spacing.
+ *
+ * Spacing therefore comes from exactly two classes, both theme-owned, and a
+ * section cannot acquire its own geometry by accident.
+ *
+ * @param {Array}    toc          [{ id, label, sub }] — headings of the open doc
+ * @param {string}   [activeId]   the heading currently in view (the caller owns
+ *                                the scroll spy; both rails must agree on it)
+ * @param {Array}    related      [{ id, href, label }] — label is the target's
+ *                                own SHORT title, never a wikilink display text
+ * @param {Array}    actions      [{ id, label, icon, to?, onClick? }]
+ * @param {Array}    topTags      [{ tag, count }] — the way in, not a dump
+ * @param {Array}    tags         [string] — this page's own tags
+ * @param {Function} renderTag    (tag) => node — the chip renderer, injected so
+ *                                this package does not reach into kol-component
+ * @param {Function} onTagClick   (tag) => void
+ */
+export default function RightRail({
+  toc = [],
+  activeId,
+  related = [],
+  actions = [],
+  topTags = [],
+  tags = [],
+  renderTag,
+  onTagClick,
+  icon: IconComponent,
+}) {
+  /* One collapse map, not a useState per section — a section added later must
+   * not need a new hook at the top of this function. */
+  const [collapsed, setCollapsed] = useState({})
+  const toggle = (key) => setCollapsed((c) => ({ ...c, [key]: !c[key] }))
+
+  /* A tag shown as "this page's" must not repeat below as "the system's". */
+  const own = new Set(tags)
+  const otherTags = topTags.filter(({ tag }) => !own.has(tag))
+
+  /* Every group is described here rather than spelled out in JSX below, so a
+   * section cannot be present in one branch and missing in another — the exact
+   * defect that split the two rails. */
+  const group = (key, label, count, children) => (
+    <RailSection
+      level={2}
+      label={label}
+      count={count}
+      collapsed={!!collapsed[key]}
+      onToggle={() => toggle(key)}
+      icon={IconComponent}
+    >
+      <nav className="shell-nav-items">{children}</nav>
+    </RailSection>
+  )
+
+  return (
+    <div className="shell-rail-stack">
+      <RailSection level={1} label="This page">
+        <div className="shell-rail-stack-inner">
+          {group('toc', 'Contents', toc.length,
+            toc.map((h) => (
+              <RailRow key={h.id} href={`#${h.id}`} active={h.id === activeId} sub={h.sub}>
+                {h.label}
+              </RailRow>
+            ))
+          )}
+        </div>
+      </RailSection>
+
+      <RailSection level={1} label="Links">
+        <div className="shell-rail-stack-inner">
+          {group('actions', 'Quick actions', actions.length,
+            actions.map((a) => (
+              <RailRow key={a.id} to={a.to} onClick={a.onClick} icon={a.icon}>
+                {a.label}
+              </RailRow>
+            ))
+          )}
+
+          {/* ONE list, two ranks. This page's tags lead and carry `emphasis`;
+            * the system's most-used follow at the resting stop with their
+            * count. `otherTags` filters out anything already shown above, so a
+            * tag cannot appear twice in one list. */}
+          {group('tags', 'Tags', tags.length + otherTags.length, (
+            <>
+              {tags.map((tag) => (
+                <RailRow
+                  key={`own-${tag}`}
+                  onClick={() => onTagClick?.(tag)}
+                  icon={IconComponent ? <IconComponent name="hash-02" size={14} /> : null}
+                  className="shell-nav-item--own"
+                >
+                  {renderTag ? renderTag(tag) : tag}
+                </RailRow>
+              ))}
+              {otherTags.map(({ tag, count }) => (
+                <RailRow
+                  key={`top-${tag}`}
+                  onClick={() => onTagClick?.(tag)}
+                  icon={IconComponent ? <IconComponent name="hash-02" size={14} /> : null}
+                  trailing={count}
+                  className="shell-nav-item--muted"
+                >
+                  {renderTag ? renderTag(tag) : tag}
+                </RailRow>
+              ))}
+            </>
+          ))}
+
+          {/* Related carries SOURCES too (user ruling 2026-08-01) — a repo URL
+            * or an external reference is another document this one names, and
+            * splitting them made two sections that answer the same question. */}
+          {group('related', 'Related', related.length,
+            related.map((r) => (
+              <RailRow key={r.id} to={r.href} href={r.url}>{r.label}</RailRow>
+            ))
+          )}
+        </div>
+      </RailSection>
+    </div>
+  )
+}

package/src/shell/ShellLayout.jsx

@@ -2,8 +2,10 @@ import { createContext, useState, useEffect, Suspense } from 'react'
 import { Outlet, Link, useLocation, useNavigate } from 'react-router-dom'
 import { ShellHeader } from '@kolkrabbi/kol-framework'
 import ShellSidebar from './ShellSidebar.jsx'
-import { Button, ShellDrawer, ShellSearchOverlay, Tooltip } from '@kolkrabbi/kol-component'
+import { Button, IconFrame, ShellDrawer, ShellSearchOverlay, Tooltip } from '@kolkrabbi/kol-component'
 import { matchSearchItems } from '../engine/search.js'
+import { useTagMode } from '../tags/TagModeContext.jsx'
+import TagModeOverlay from '../tags/TagModeOverlay.jsx'
 import { Asset } from '@kolkrabbi/kol-brand/svg'
 
 // Pages can register right-rail TOC content via this context.
@@ -37,9 +39,33 @@ const MainColumn = ({ children, fullHeight }) => (
     className={`w-full min-w-0 h-full min-h-0 ${fullHeight ? 'overflow-hidden flex flex-col' : 'overflow-y-auto overscroll-none'}`}
     style={fullHeight ? undefined : { scrollbarGutter: 'stable' }}
   >
+    {/* THE cap lives HERE (2026-07-31), on the CONTENT — not on the grid that
+      * holds the rails. The theme's law is written about a page ("content
+      * LEFT-ANCHORED inside"), and the rails are chrome, not page. Capping the
+      * grid centred all three columns and pulled both rails inward off the
+      * viewport edge; the rails now sit flush at the chrome inset and only the
+      * main column carries a cap.
+      *
+      * It caps at CANVAS, not shell (user ruling 2026-07-31). Shell is the
+      * frame token and the middle grid track can never reach it — after both
+      * rails, gutters and inset there is ~1516 of room at a 2200 window — so a
+      * shell cap here was real code that could never fire, and every page just
+      * inherited whatever the window gave it. Canvas is the rung that binds.
+      * One decision, made once: 14 pages needed no per-page cap.
+      * `fullHeight` stays uncapped on purpose — it IS the fill-the-viewport
+      * escape hatch (iframe embeds).
+      *
+      * LEFT-ANCHORED, not centred (user ruling 2026-08-01). The capped div
+      * below carried `mx-auto`, which centres the column inside the main
+      * track — so above the canvas width the content drifted away from the
+      * rail it is supposed to line up with. The one-frame law has said
+      * "content LEFT-ANCHORED inside" since 2026-07-28 (kol-theme.css content
+      * block; docs/documentation/01-foundations/05-layout-systems.md): the
+      * FRAME centres in the viewport, the CONTENT does not centre in the
+      * frame. `validate:width` W4 asserts it now. */}
     {fullHeight
       ? children
-      : <div className="pt-6 md:pt-6 lg:pt-8 pb-16">{children}</div>
+      : <div className="w-full max-w-[var(--kol-content-canvas)] pt-6 md:pt-6 lg:pt-8 pb-16">{children}</div>
     }
   </main>
 )
@@ -52,11 +78,13 @@ const MainColumn = ({ children, fullHeight }) => (
  * decision and must not be stated twice differently. */
 const TocColumn = ({ children }) => (
   <aside aria-label="Table of contents" className="shell-sidebar-sticky hidden xl:block shrink-0 h-full min-h-0 overflow-y-auto overflow-x-hidden overscroll-none pt-6 md:pt-6 lg:pt-8 pb-8">
-    {/* The 224px lives HERE, not on the grid track (see gridCols). An inner
-      * wrapper with a width means a rail whose content renders null measures
-      * zero and the column collapses — the page gets the space back instead of
-      * staring at a reserved empty gutter. */}
-    <div className="w-56 empty:hidden">{children}</div>
+    {/* The WIDTH IS THE GRID TRACK now (--kol-shell-toc-w, see gridCols), not
+      * an inner wrapper. It used to be `w-56 empty:hidden` here precisely so a
+      * rail whose content rendered null would measure zero and let the main
+      * column reclaim the space — REVERSED by user ruling 2026-08-01: an empty
+      * rail still holds its column, because a rail that disappears re-flows
+      * main and the same page ends up at two different widths. */}
+    <div className="w-full">{children}</div>
   </aside>
 )
 
@@ -64,8 +92,21 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
   const [isNavDrawerOpen, setIsNavDrawerOpen] = useState(false)
   const [navCollapsed, setNavCollapsed] = useState(false)
   const [tocCollapsed, setTocCollapsed] = useState(false)
-  const [isSearchOpen, setIsSearchOpen] = useState(false)
-  const [searchQuery, setSearchQuery] = useState('')
+  /* ONE QUERY (user ruling 2026-08-01). The palette's text used to live here
+   * while tags lived in TagModeContext — two states, and therefore two
+   * surfaces. Both facets are the context's now. The local pair survives ONLY
+   * for a consumer mounting the shell without a TagModeProvider, where the
+   * context is the inert fallback and every keystroke would no-op. */
+  const tagMode = useTagMode()
+  const [localOpen, setLocalOpen] = useState(false)
+  const [localQuery, setLocalQuery] = useState('')
+
+  const isSearchOpen = tagMode.isProvided ? tagMode.isOpen : localOpen
+  const searchQuery = tagMode.isProvided ? tagMode.text : localQuery
+  const setSearchQuery = tagMode.isProvided ? tagMode.setText : setLocalQuery
+  const setIsSearchOpen = tagMode.isProvided
+    ? (v) => (v ? tagMode.openTagMode() : tagMode.closeTagMode())
+    : setLocalOpen
   const [tocContent, setTocContent] = useState(null)
   const [isFullHeight, setIsFullHeight] = useState(false)
   const [isShortcutsOpen, setIsShortcutsOpen] = useState(false)
@@ -103,33 +144,38 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
   }, [])
 
   const effectiveTocContent = tocContent ?? defaultTocContent
-  /* An element is truthy even when the component inside it renders nothing, so
-   * this alone reserved a 224px rail on every route — including ones with no
-   * headings. Three fixes were rejected before this one: measuring the mounted
-   * column DEADLOCKS (once the column unmounts the probe is gone and can never
-   * report content again); calling a render-prop inline makes the consumer's
-   * hooks belong to THIS component, one refactor away from a crash; and a
-   * boolean prop puts the answer in the consumer, which doesn't know either.
+  /* THE RAIL HOLDS ITS COLUMN, EMPTY OR NOT (user ruling 2026-08-01).
+   *
+   * This used to hunt for a way to tell whether the rail had real content, so
+   * an empty one could collapse and hand its space back to main. That whole
+   * question is now moot — and it was the wrong question. A rail that vanishes
+   * on content-less routes means / renders at one main width and /foundations
+   * at another: the layout becomes a property of the page's content instead of
+   * the shell. The user caught it on the home page, where the TOC has no
+   * headings to show.
    *
-   * The column decides for itself instead. The track is `auto`, not a fixed
-   * 224px, and the width lives on the rail's CONTENT — so a rail that renders
-   * nothing collapses to zero and the main column takes the space back. No
-   * signal to keep in sync, nothing to deadlock. */
+   * So the track is RESERVED whenever the viewport is wide enough and the user
+   * has not collapsed it by hand. `hasToc` survives for ONE job — whether the
+   * header offers a toggle at all — because a control that collapses an
+   * already-empty rail is noise. Collapsing is still a user action, and a user
+   * action is allowed to change the layout; content appearing is not. */
   const hasToc = Boolean(effectiveTocContent)
   const showNav = !navCollapsed
-  const showToc = hasToc && !tocCollapsed
+  const showToc = !tocCollapsed
 
   const layoutType = showNav && showToc ? 'nav-toc' : showNav ? 'nav' : showToc ? 'toc' : 'none'
 
-  /* `auto`, not `224px` — see hasToc above. The width is declared on the rail's
-   * content (TocColumn's inner wrapper), so a rail with nothing in it measures
-   * zero and the main column reclaims the space. */
+  /* A FIXED track (--kol-shell-toc-w), not `auto`. `auto` sized the column to
+   * its content, which is exactly what let an empty rail measure zero. Both
+   * rail widths are tokens: the left is --kol-sidenav-w (the one number every
+   * grid track that lines up with it already reads), the right is
+   * --kol-shell-toc-w. */
   const gridCols = showNav
     ? showToc
-      ? 'lg:grid-cols-[256px_minmax(0,1fr)] xl:grid-cols-[256px_minmax(0,1fr)_auto]'
-      : 'lg:grid-cols-[256px_minmax(0,1fr)]'
+      ? 'lg:grid-cols-[var(--kol-sidenav-w)_minmax(0,1fr)] xl:grid-cols-[var(--kol-sidenav-w)_minmax(0,1fr)_var(--kol-shell-toc-w)]'
+      : 'lg:grid-cols-[var(--kol-sidenav-w)_minmax(0,1fr)]'
     : showToc
-      ? 'xl:grid-cols-[minmax(0,1fr)_auto]'
+      ? 'xl:grid-cols-[minmax(0,1fr)_var(--kol-shell-toc-w)]'
       : ''
 
   // Adapt the old flat `routes` + callbacks to the DS ShellHeader API
@@ -176,7 +222,12 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
     <>
       {actions}
       <Tooltip label="Search">
-        <Button variant="ghost" quiet iconOnly="search" iconSize={18} onClick={() => setIsSearchOpen(true)} aria-label="Search" />
+        {/* IconFrame at the `lg` rung (user ruling 2026-08-01). Two faults in
+          * one call: it was a Button, and at the default `md` rung it drew the
+          * solo-lg glyph inside an `md` square while every neighbour sat on
+          * `lg`. `quiet` is gone too — on ghost it rested at oq-48 × 0.5, which
+          * made search the faintest thing in a row of oq-64 controls. */}
+        <IconFrame name="search" variant="nav" size="lg" onClick={() => setIsSearchOpen(true)} aria-label="Search" />
       </Tooltip>
     </>
   )
@@ -237,10 +288,19 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
               * Tailwind's 16/20/24 steps instead of the ramp's 20/32/48 — so
               * every consumer page inherited the raw viewport (measured 2152px
               * of frame at a 2200px window against an 1800px law). Every
-              * page-level width fix is downstream of this line. */}
+              * page-level width fix is downstream of this line.
+              *
+              * CORRECTED 2026-07-31: that fix capped THIS element, which holds
+              * all three columns — so the whole chrome centred and both rails
+              * were dragged inward off the viewport edge. The chrome frame
+              * takes the full available width and the rails justify to it; the
+              * cap moved one level down onto MainColumn's content, which is
+              * what the theme's law is written about. Same disease as
+              * --kol-container-max stopping at 1600 under an 1800 law: one
+              * element, two answers. */}
             <div
-              className="mx-auto h-full w-full max-w-[var(--kol-content-shell)]"
-              style={{ paddingInline: 'var(--kol-pad-section-x)' }}
+              className="h-full w-full"
+              style={{ paddingInline: 'var(--kol-pad-chrome-x)' }}
             >
               {/* gap lives in .shell-content-grid (theme) — a gap-8 utility here
                 * outranks the layered theme rule at every width and killed the
@@ -261,6 +321,10 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
                     </div>
                   </MainColumn>
 
+                  {/* Mounted on showToc alone — NOT on whether there is content
+                    * to put in it. An empty TocColumn is the point: it holds
+                    * the grid's third track so main keeps one width across
+                    * every route (user ruling 2026-08-01). */}
                   {showToc && (
                     <TocColumn>
                       {effectiveTocContent}
@@ -292,20 +356,32 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
             query={searchQuery}
             onQueryChange={setSearchQuery}
             results={searchResults}
+            /* THE EXPANDED BODY (user ruling 2026-08-01). The tag browser is
+             * not a sibling overlay — it is this palette's second state. Enter
+             * commits the query and swaps the result rows for the full body;
+             * committed tags ride along as chips on the same query. */
+            expanded={tagMode.isProvided && tagMode.expanded}
+            onExpand={() => tagMode.setExpanded?.(true)}
+            chips={tagMode.isProvided ? tagMode.activeTags : []}
+            onRemoveChip={tagMode.removeTag}
+            placeholder="Search…"
             onSelect={(item) => {
+              /* `action` before `href`: not every hit is a destination. A tag
+               * row FILTERS the same query and the palette STAYS OPEN — closing
+               * it was the behaviour that forced tags into a second overlay.
+               * Only a destination dismisses. */
+              if (typeof item?.action === 'function') {
+                item.action()
+                setSearchQuery('')
+                return
+              }
               setIsSearchOpen(false)
               setSearchQuery('')
-              /* `action` before `href`: not every hit is a destination. A tag
-               * row toggles state rather than navigating, and without this the
-               * palette could only ever hold things that live at a URL — which
-               * is why the tag search had to be a second, separate search box
-               * that knew nothing about this one. The consumer supplies the
-               * closure; the shell stays ignorant of what it does. */
-              if (typeof item?.action === 'function') item.action()
-              else if (item?.href) navigate(item.href)
+              if (item?.href) navigate(item.href)
             }}
-            placeholder="Search…"
-          />
+          >
+            {tagMode.isProvided && tagMode.expanded ? <TagModeOverlay /> : null}
+          </ShellSearchOverlay>
 
           {/* The `?` sheet. Rendered FROM the SHORTCUTS array above, so the help
             * and the bindings are one source — a shortcut can't be documented

package/src/shell/ShellSidebar.jsx

@@ -1,6 +1,8 @@
 import { useState, useEffect } from 'react'
-import { NavLink, Link, useLocation } from 'react-router-dom'
-import { Icon, Tooltip } from '@kolkrabbi/kol-component'
+import { useLocation } from 'react-router-dom'
+import { Icon } from '@kolkrabbi/kol-component'
+import RailSection from './RailSection.jsx'
+import RailRow from './RailRow.jsx'
 
 const getSectionRootPath = (route, basePath) => {
   if (route.path !== undefined && route.path !== null) {
@@ -63,115 +65,68 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
     setCollapsedSections((prev) => ({ ...prev, [route.id]: !prev[route.id] }))
   }
 
+  /* No count at L1 — the eyebrow names a body of material and the tally lives
+   * on the groups inside it (user ruling 2026-08-01). RailSection refuses one
+   * at this rung, so there is nothing to compute here. */
   return (
-    <div className="space-y-4">
-      {/* kol-helper-10 types the wrapper box itself (was an untyped 16px box) */}
-      <div className="shell-sidebar-toggle shell-sidebar-label kol-doc-eyebrow" style={{ justifyContent: 'space-between', paddingRight: '4px' }}>
-        {labelTo ? (
-          <Link to={labelTo} className="shell-sidebar-label kol-doc-eyebrow" onClick={(e) => {
-            if (navCollapsed && handleToggle) handleToggle()
-            if (onNavigate) onNavigate(e)
-          }}>
-            {label}
-          </Link>
-        ) : (
-          /* Same voice as the labelTo branch. This read `kol-helper-10
-           * text-meta`, so the one rail mounted without a labelTo (the vault's
-           * "Documentation") rendered its label at a different size and colour
-           * from its two siblings — a type fork caused purely by which props
-           * the consumer happened to pass. */
-          <button type="button" className="shell-sidebar-label kol-doc-eyebrow" onClick={handleToggle}>{label}</button>
-        )}
-        <Tooltip label={navCollapsed ? `Expand ${label}` : `Collapse ${label}`}>
-          <button
-            type="button"
-            onClick={handleToggle}
-            aria-label={navCollapsed ? `Expand ${label}` : `Collapse ${label}`}
-            aria-expanded={!navCollapsed}
-            className="flex items-center justify-center"
-            style={{ height: '16.5px', marginBottom: '8px' }}
-          >
-            <Icon
-              name="chevron-down"
-              size={10}
-              className={`stroke-[2.5] transition-transform ${navCollapsed ? '' : 'rotate-180'}`}
-            />
-          </button>
-        </Tooltip>
-      </div>
+    /* One rail layout, one class (2026-08-01). This was `space-y-4` against the
+     * right rail's `space-y-6` against the outer `flex flex-col gap-6` — three
+     * spellings of the same stack, and `space-y` fights any child that owns a
+     * margin, which the eyebrow box does. */
+    <div className="shell-rail-stack-inner">
+      <RailSection
+        level={1}
+        label={label}
+        to={labelTo}
+        collapsed={navCollapsed}
+        onToggle={handleToggle}
+        onNavigate={onNavigate}
+      >
+        <div className="shell-rail-stack-inner">
+          {routes.map((route) => {
+            /* A group with no children is not a group — it is a link. It used
+             * to render as a header anyway: a chevron that rotated over an
+             * empty body, no count, and no navigation, so clicking "Icons" or
+             * "Components" in the tree did nothing at all while looking like
+             * it should. `collapsible` is what that distinction is now. */
+            const hasChildren = route.children?.length > 0
 
-      {!navCollapsed && <div className="space-y-4">
-        {routes.map((route) => {
-          const isExpanded = !collapsedSections[route.id]
-
-          /* A group with no children is not a group — it is a link. It used to
-           * render as a header anyway: a chevron that rotated over an empty
-           * body, no count, and no navigation, so clicking "Icons" or
-           * "Components" in the tree did nothing at all while looking like it
-           * should. Now the chevron and the toggle only appear when there is
-           * something to expand, and a childless row goes where it says. */
-          const hasChildren = route.children?.length > 0
-          const headerClass = 'shell-nav-group-header w-full text-left kol-mono-14 text-body'
-
-          return (
-            <div key={route.id} className="shell-nav-group">
-              {hasChildren ? (
-                <button
-                  type="button"
-                  className={headerClass}
-                  onClick={() => handleSectionClick(route)}
-                  aria-expanded={isExpanded}
+            return (
+              <div key={route.id} className="shell-nav-group">
+                <RailSection
+                  level={2}
+                  label={route.label}
+                  count={hasChildren ? route.children.length : undefined}
+                  /* THE HEADER ALWAYS LINKS (2026-08-02). It used to link only
+                   * when the group had NO children, so a chapter with pages had
+                   * a dead header and its index had to ride as a row inside
+                   * itself. RailSection already separates the two gestures —
+                   * the label navigates, the rest of the row toggles — so a
+                   * group can open its landing page and still collapse. */
+                  to={route.path ?? getSectionRootPath(route, basePath)}
+                  collapsible={hasChildren}
+                  collapsed={!!collapsedSections[route.id]}
+                  onToggle={() => handleSectionClick(route)}
+                  onNavigate={onNavigate}
+                  icon={Icon}
                 >
-                  <span className="flex items-center gap-2">
-                    <Icon
-                      name="chevron-right"
-                      size={12}
-                      className={`transition-transform ${isExpanded ? 'rotate-90' : ''}`}
-                    />
-                    {route.label}
-                  </span>
-                  <span className="kol-mono-14 text-subtle">({route.children.length})</span>
-                </button>
-              ) : (
-                <Link
-                  to={getSectionRootPath(route, basePath)}
-                  className={headerClass}
-                  onClick={onNavigate}
-                >
-                  {/* aligned with the expandable rows' label column — the
-                    * chevron's width, kept as space so the two kinds of row
-                    * share a left edge */}
-                  <span className="flex items-center gap-2">
-                    <span aria-hidden="true" style={{ width: 12 }} />
-                    {route.label}
-                  </span>
-                </Link>
-              )}
-
-              {isExpanded && route.children?.length > 0 && (
-                <div className="shell-nav-items">
-                  {route.children.map((child) => {
-                    const childPath = getChildPath(child, basePath)
-                    return (
-                      <NavLink
+                  <nav className="shell-nav-items">
+                    {(route.children ?? []).map((child) => (
+                      <RailRow
                         key={child.id}
-                        to={childPath}
-                        end
-                        className={({ isActive }) =>
-                          `shell-nav-item kol-mono-14 ${isActive ? 'text-emphasis' : 'text-body'}`
-                        }
-                        onClick={onNavigate}
+                        to={getChildPath(child, basePath)}
+                        onNavigate={onNavigate}
                       >
-                        <span className="shell-nav-item-title">{child.label}</span>
-                      </NavLink>
-                    )
-                  })}
-                </div>
-              )}
-            </div>
-          )
-        })}
-      </div>}
+                        {child.label}
+                      </RailRow>
+                    ))}
+                  </nav>
+                </RailSection>
+              </div>
+            )
+          })}
+        </div>
+      </RailSection>
     </div>
   )
 }

package/src/shell/index.js

@@ -9,3 +9,14 @@
 export { default as ShellLayout } from './ShellLayout.jsx'
 export { ShellTocContext, ShellFullHeightContext, ShellTocCollapsedContext } from './ShellLayout.jsx'
 export { default as ShellSidebar } from './ShellSidebar.jsx'
+/* RailSection — THE rail ladder. Every rail header at every rung comes from
+ * here, in both rails; see the file header for why a class alone was not
+ * enough. `pnpm validate:rails` R4 asserts it. */
+export { default as RailSection } from './RailSection.jsx'
+/* RailRow — THE L3 rail row. The look lives in `.shell-nav-item`; this owns the
+ * markup so nine hand-written utility stacks cannot come back. R4 asserts it. */
+export { default as RailRow } from './RailRow.jsx'
+/* RightRail — THE right rail, one component for every route. It replaced two
+ * that disagreed about which sections exist, which is why sections used to
+ * appear and vanish. The section set is fixed and unconditional. */
+export { default as RightRail } from './RightRail.jsx'