@kolkrabbi/kol-workshop 0.6.0 → 0.11.0

package/src/engine/index.js

@@ -2,7 +2,7 @@
  * The pure docs engine — zero dependencies, no React, no Vite.
  * Everything here is a plain function over strings/data.
  */
-export { parseDocsMarkdown, extractHashtags } from './parse-markdown.js'
+export { parseDocsMarkdown, extractHashtags, processInlineMarkdown } from './parse-markdown.js'
 export { parseFrontmatter } from './frontmatter.js'
 export { buildInventory, buildInventoryCounts } from './build-inventory.js'
 export { matchSearchItems } from './search.js'
@@ -15,6 +15,7 @@ export {
   subsectionPrefixes,
   categoryLabels,
   cleanTitle,
+  fileLabel,
   getTagColor,
   groupDocsByMajor,
 } from './doc-helpers.js'

package/src/engine/parse-markdown.js

@@ -21,7 +21,11 @@ export const extractHashtags = (content) => {
  * Supports: bold, italic, inline code, links, images, color swatches, hashtags.
  * Returns a token array; the render layer turns tokens into elements.
  */
-const processInlineMarkdown = (text) => {
+/* EXPORTED 2026-08-01. The props table needs the token producer so its cells
+ * can render `backticked` code as a chip instead of printing the backticks.
+ * It was module-private, which is why the table had no way to do it and the
+ * gap read as "the table is bad" rather than "the parser was unreachable". */
+export const processInlineMarkdown = (text) => {
   if (!text) return []
 
   const tokens = []

package/src/shell/RailRow.jsx

@@ -0,0 +1,85 @@
+import { NavLink } from 'react-router-dom'
+
+/**
+ * RailRow — THE L3 rail row. The ladder's bottom rung, owned like the other two.
+ *
+ * WHY IT EXISTS (user ruling 2026-08-01). `.shell-nav-item` was a shared class
+ * name and nothing more: every call site hand-wrote its own utility stack
+ * around it, so ONE row idiom shipped as NINE different strings across five
+ * files —
+ *
+ *   left tree      `shell-nav-item kol-mono-14 ${active ? … }`
+ *   toc rows       `shell-nav-item block kol-mono-14 text-body transition-colors
+ *                   focus-visible:ring-focus hover:text-emphasis`
+ *   related rows   the same minus the focus ring
+ *   quick actions  `shell-nav-item flex items-center gap-2 …`
+ *
+ * — and their containers disagreed too (`space-y-0` against `space-y-4` for the
+ * same list). R1/R2 lock the TYPE class; nothing locked the stack. That is the
+ * eyebrow-box failure exactly, one rung further down, which is why the rails
+ * kept drifting after RailSection fixed L1 and L2.
+ *
+ * The look now lives in `.shell-nav-item` (layout, colour, hover, focus,
+ * active); this component owns the markup. `validate:rails` R4 fails a
+ * hand-written `shell-nav-item` anywhere but here.
+ *
+ * ACTIVE IS BOTH RAILS' (user ruling 2026-08-01). The left tree highlighted the
+ * current page and the right rail highlighted nothing — same rung, one state.
+ * `NavLink` drives it for routes; `active` drives it for hash links and
+ * buttons, which react-router cannot resolve.
+ *
+ * @param {string}   [to]       route → NavLink, active resolved by the router
+ * @param {string}   [href]     plain anchor (hash links: on-this-page)
+ * @param {Function} [onClick]  no `to`/`href` → a <button>
+ * @param {boolean}  [active]   forced active state (hash links, buttons)
+ * @param {node}     [icon]     leading glyph
+ * @param {node}     [trailing] pushed right — a count, a doc number
+ * @param {boolean}  [sub]      nested depth (h3 under h2)
+ */
+export default function RailRow({
+  to,
+  href,
+  onClick,
+  active = false,
+  icon,
+  trailing,
+  sub = false,
+  onNavigate,
+  children,
+  className = '',
+}) {
+  /* ONE string. It is assembled here and nowhere else — that is the entire
+   * point of the component. `kol-mono-14` is the rail's row ramp (R1). */
+  const cls = (isActive) =>
+    ['shell-nav-item', 'kol-mono-14', sub ? 'shell-nav-item-sub' : '', isActive ? 'is-active' : '', className]
+      .filter(Boolean)
+      .join(' ')
+
+  const inner = (
+    <>
+      {icon}
+      <span className="truncate">{children}</span>
+      {trailing != null && <span className="shell-nav-item-trailing kol-mono-14">{trailing}</span>}
+    </>
+  )
+
+  if (to) {
+    return (
+      <NavLink to={to} end className={({ isActive }) => cls(isActive || active)} onClick={onNavigate}>
+        {inner}
+      </NavLink>
+    )
+  }
+  if (href) {
+    return (
+      <a href={href} className={cls(active)} onClick={onNavigate}>
+        {inner}
+      </a>
+    )
+  }
+  return (
+    <button type="button" className={cls(active)} onClick={onClick}>
+      {inner}
+    </button>
+  )
+}

package/src/shell/RailSection.jsx

@@ -0,0 +1,178 @@
+import { useState } from 'react'
+import { Link } from 'react-router-dom'
+
+/**
+ * RailSection — THE rail ladder. One component owns every rail header, at
+ * every rung, in both rails.
+ *
+ * WHY IT EXISTS (user ruling 2026-08-01). The rails already had a class per
+ * rung — `.shell-sidebar-toggle` (L1), `.shell-nav-group-header` (L2),
+ * `.shell-nav-item` (L3) — and drifted anyway, because a class is vocabulary
+ * and not grammar. Nothing declared the three a LADDER, and every affordance
+ * that hangs off a rung (the count, the collapse, the chevron) was hand-typed
+ * at each call site. So the right rail put its count on L1 and the left rail
+ * put its count on L2, and the user had to catch it in a screenshot.
+ *
+ * L3 is the proof of the fix: it is the only rung a component already owned
+ * (`DocsToc`), and it is the only rung that never drifted.
+ *
+ * THE LADDER
+ *
+ *   L1  section  `.shell-sidebar-toggle` + kol-doc-eyebrow    quiet, no chevron
+ *   L2  group    `.shell-nav-group-header` + kol-mono-14      louder, chevron
+ *   L3  row      `.shell-nav-item` + kol-mono-14              leaf, DocsToc/links
+ *
+ * THE RULES THIS COMPONENT ENFORCES BY CONSTRUCTION
+ *
+ *   - A rung's class is chosen here, never at the call site. Same rung in
+ *     either rail is literally the same string.
+ *   - The COUNT is placed by the rung, not by the caller. You cannot put it in
+ *     the wrong place because you never write the span.
+ *   - No chevron at L1 (user ruling 2026-08-01) — the section still collapses
+ *     and expands on click, the glyph is simply not drawn. L2 keeps its
+ *     chevron: it is the rung where a caret means "there is a subtree here".
+ *   - The box (padding + margin) belongs to the rung class alone. Nothing here
+ *     sets y-spacing inline; see the eyebrow-box law in kol-components-workshop.css.
+ *
+ * `pnpm validate:rails` R4 asserts that rail headers come from here.
+ *
+ * @param {1|2}      level        which rung. L3 rows are links, not sections.
+ * @param {string}   label        header text, rendered verbatim (casing is authored)
+ * @param {number}   [count]      leaf rows this section contains — L1 counts the
+ *                                whole subtree, L2 counts its own children
+ * @param {string}   [to]         make the LABEL a link; the rest of the row still toggles
+ * @param {boolean}  [collapsible=true]  false → a static header, no toggle, no aria
+ * @param {boolean}  [collapsed]  controlled state; omit for uncontrolled
+ * @param {Function} [onToggle]   required when `collapsed` is passed
+ * @param {boolean}  [defaultCollapsed=false]  uncontrolled initial state
+ * @param {Function} [onNavigate] click hook on the label link (close a drawer, etc.)
+ * @param {Icon}     [icon]       the chevron renderer, injected — the shell package
+ *                                must not reach into kol-component from here
+ */
+export default function RailSection({
+  level = 1,
+  label,
+  count,
+  to,
+  collapsible = true,
+  collapsed,
+  onToggle,
+  defaultCollapsed = false,
+  onNavigate,
+  icon: IconComponent,
+  children,
+}) {
+  const [internal, setInternal] = useState(defaultCollapsed)
+  const isControlled = collapsed !== undefined
+  const isCollapsed = isControlled ? collapsed : internal
+  const toggle = isControlled ? onToggle : () => setInternal((c) => !c)
+
+  /* The rung decides the class. This is the single line that used to live at
+   * four call sites in two rails, spelled differently at each. */
+  const headerClass = level === 1
+    ? 'shell-sidebar-toggle kol-doc-eyebrow'
+    : 'shell-nav-group-header kol-mono-14 text-body'
+
+  /* A static header is not a button and must not claim to be one. It still
+   * wears the same box — `.shell-sidebar-label` shares L1's rule. */
+  const staticClass = level === 1
+    ? 'shell-sidebar-label kol-doc-eyebrow'
+    : 'shell-nav-group-header kol-mono-14 text-body'
+
+  /* L2 only. At L1 the caret is not drawn (user ruling) — the row is still the
+   * toggle, so the affordance exists, it just isn't a glyph. */
+  const chevron = level === 2 && collapsible && IconComponent ? (
+    <IconComponent
+      name="chevron-right"
+      size={12}
+      className={`transition-transform ${isCollapsed ? '' : 'rotate-90'}`}
+    />
+  ) : null
+
+  /* THE COUNT IS AN L2 AFFORDANCE (user ruling 2026-08-01): "dont list counter
+   * next to eyebrow category, just inside". A category eyebrow names a body of
+   * material; the tally belongs to the groups inside it, not to the label over
+   * them. So L1 drops a `count` on the floor rather than rendering it — the
+   * rung refuses it, so no call site can put one back. */
+  const countNode = level === 2 && count !== undefined && count !== null
+    ? <span className="kol-mono-14 text-subtle">({count})</span>
+    : null
+
+  const labelNode = to ? (
+    /* The label navigates; the rest of the row toggles. stopPropagation keeps
+     * one click from doing both. */
+    <Link
+      to={to}
+      className={level === 1 ? 'kol-doc-eyebrow' : undefined}
+      onClick={(e) => {
+        e.stopPropagation()
+        if (isCollapsed && toggle) toggle()
+        if (onNavigate) onNavigate(e)
+      }}
+    >
+      {label}
+    </Link>
+  ) : (
+    <span>{label}</span>
+  )
+
+  const inner = (
+    <>
+      <span className="flex items-center gap-2">
+        {chevron}
+        {/* L2 rows without a caret keep the caret's width as space, so an
+          * expandable row and a childless one share a left edge. */}
+        {level === 2 && !chevron && <span aria-hidden="true" style={{ width: 12 }} />}
+        {labelNode}
+      </span>
+      {countNode}
+    </>
+  )
+
+  if (!collapsible) {
+    /* A rung with nothing to expand is not a section — it is a row that goes
+     * somewhere. It used to render as a header anyway: a chevron rotating over
+     * an empty body that never navigated, so "Icons" and "Components" did
+     * nothing when clicked. With `to` the WHOLE row is the link (the label
+     * alone would leave the rest of the row dead), and `inner` keeps the caret
+     * column as space so it shares a left edge with its expandable siblings. */
+    if (to) {
+      return (
+        <Link to={to} className={staticClass} onClick={onNavigate}>
+          <span className="flex items-center gap-2">
+            {level === 2 && <span aria-hidden="true" style={{ width: 12 }} />}
+            {label}
+          </span>
+          {countNode}
+        </Link>
+      )
+    }
+    return (
+      <div>
+        <div className={staticClass}>{inner}</div>
+        {children}
+      </div>
+    )
+  }
+
+  /* A div with role=button, not a <button>, because the label may be a Link —
+   * an anchor inside a button is invalid markup. The keyboard handler restores
+   * what the removed chevron button used to provide. */
+  return (
+    <div>
+      <div
+        className={headerClass}
+        role="button"
+        tabIndex={0}
+        aria-expanded={!isCollapsed}
+        onClick={toggle}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); if (toggle) toggle() }
+        }}
+      >
+        {inner}
+      </div>
+      {!isCollapsed && children}
+    </div>
+  )
+}

package/src/shell/ShellLayout.jsx

@@ -1,9 +1,11 @@
 import { createContext, useState, useEffect, Suspense } from 'react'
 import { Outlet, Link, useLocation, useNavigate } from 'react-router-dom'
-import { ShellHeader } from '@kolkrabbi/kol-framework'
+import { ShellHeader, HEADER_ICON } from '@kolkrabbi/kol-framework'
 import ShellSidebar from './ShellSidebar.jsx'
 import { Button, 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,7 @@ 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" />
+        <Button variant="ghost" quiet iconOnly="search" iconSize={HEADER_ICON} onClick={() => setIsSearchOpen(true)} aria-label="Search" />
       </Tooltip>
     </>
   )
@@ -237,10 +283,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 +316,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 +351,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