@kolkrabbi/kol-shell 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "private": false,
   "description": "KOL application shell — fixed 48px NavRail + AppShell layout root, PageShell/PageHeader scaffolds, ContentFilters catalog organism, GridCard, SettingsScaffold, WalkthroughPanel, ShortcutsOverlay. App chrome (kol-framework owns site chrome). Nav items, content, shortcuts and settings are consumer-injected. Sits above @kolkrabbi/kol-{theme,component,framework}.",
   "license": "MIT",
@@ -12,18 +12,18 @@
     "./src/*": "./src/*"
   },
   "peerDependencies": {
-    "@kolkrabbi/kol-component": ">=0.108.0",
-    "@kolkrabbi/kol-framework": ">=0.34.0",
+    "@kolkrabbi/kol-component": ">=0.125.0",
     "@kolkrabbi/kol-icons": ">=0.16.0",
-    "@kolkrabbi/kol-theme": ">=0.80.0",
+    "@kolkrabbi/kol-theme": ">=0.84.0",
+    "gsap": "^3.13.0",
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.119.0",
-    "@kolkrabbi/kol-framework": "^0.34.0",
+    "@kolkrabbi/kol-component": "^0.125.0",
+    "@kolkrabbi/kol-framework": "^0.35.0",
     "@kolkrabbi/kol-icons": "^0.24.0",
-    "@kolkrabbi/kol-theme": "^0.81.0"
+    "@kolkrabbi/kol-theme": "^0.88.0"
   },
   "files": [
     "src",

package/src/AppShell.jsx

@@ -9,21 +9,17 @@ import TouchDeviceOverlay, { useTouchPrimary } from './TouchDeviceOverlay.jsx'
  * children and wire `currentPath`/`onNavigate` from your router at the call
  * site.
  *
- * THE RAIL IS A SIDENAV (RailSideNavPixelParity, kol-fxr 2026-08-28 — user:
- * "same component both states super nice"): since 0.13.0 the root is the
- * brand grid, `.kol-brand-layout` (kol-framework.css — `--kol-sidenav-w` ×
- * `minmax(0, 1fr)`, the collapsed column on the `data-sidenav` stamp, the
- * ≤1024 forced rail and the ≤767 drawer), and `NavRail` mounts kol-framework's
- * `SideNav` collapsed in it. The grab edge opens it to the brand sidebar and
- * the drag is the transition; the content column follows the grid, so the old
- * fixed rail + `margin-left` offset is gone. `--kol-shell-rail-width`
- * (kol-theme ≥0.80.0) is LIVE — the sidenav's width in its current state —
- * for consumers that offset a fixed element by it; hidden rail = `0px`.
- * REQUIRES `@kolkrabbi/kol-framework/kol-framework.css` imported after the
- * theme (kol-mirror's bump, 2026-08-28): the grid, the sidenav's box and
- * collapse rules and its width tokens live there, not in kol-theme — without
- * it the root is `display: block` and the rail is a horizontal bar, with a
- * green build and a clean console.
+ * THE RAIL IS FLAT AGAIN (RailFlatGrabOpen, kol-mirror 2026-08-28 — user: "the
+ * div structure is super simple ok … it's 1 div parent and everything is just
+ * in that container"): 0.13.0 had made it a collapsed kol-framework `SideNav`
+ * inside the brand grid; 0.16.0 reverses that. The root is a plain wrapper, the
+ * rail is `position: fixed`, and the content is offset by
+ * `margin-left: var(--kol-shell-rail-width)` — the ONE variable the rail writes
+ * per pointermove during a grab-drag and tweens on release, so the page is
+ * pushed live through both. Hidden rail = `0px`.
+ *
+ * `kol-framework.css` is no longer required by the shell (it was, for one
+ * grid rule, 0.13–0.15).
  *
  * @param {Array}  props.items         nav items `{ icon, path, label }`
  * @param {Array}  props.bottomItems   items pinned below the theme toggle
@@ -31,11 +27,11 @@ import TouchDeviceOverlay, { useTouchPrimary } from './TouchDeviceOverlay.jsx'
  * @param {string} props.currentPath   the router's current pathname
  * @param {Function} props.onNavigate  `(path) => void`
  * @param {ElementType} props.iconComponent  icon renderer seam (see Button)
- * @param {Object}  props.settings     `{ icon, path, label }` — Settings as a DISCLOSURE in the pinned bottom
- *                                        row (RailSettingsDisclosure, 2026-08-28): click opens a panel above the
- *                                        row with the theme toggle and the settings page as a row; click again,
- *                                        Escape or any navigation closes it. Turns the rail's theme slot off.
- * @param {boolean} props.themeToggle  render the ThemeToggle above bottomItems (default true; false when `settings` is given)
+ * NOTE (0.16.0): `settings` and `themeToggle` left with the SideNav-backed rail
+ * — the flat rail carries neither. Settings is a `bottomItems` rung whose
+ * open/close is the consumer's `onNavigate` (kol-mirror's model: navigating to
+ * `/settings` while already there returns to the last page), and the theme
+ * toggle lives on the settings page, not in the rail (user, 2026-08-28).
  * @param {string}  props.railToggleKey  a key that toggles the rail (e.g. '\\') — ignored while typing in a field;
  *                                        the rail comes back on every `currentPath` change (ShellHomeSystem, 2026-08-27)
  * @param {'shell'|'bare'|'overlay'} props.touch  the touch-primary policy (default 'shell' = the rail regardless):
@@ -66,8 +62,6 @@ export default function AppShell({
   currentPath,
   onNavigate,
   iconComponent,
-  settings,
-  themeToggle,
   railToggleKey,
   touch = 'shell',
   appName,
@@ -120,11 +114,11 @@ export default function AppShell({
   return (
     <NavHiddenContext.Provider value={{ navHidden, setNavHidden }}>
       {/* `kol-app-shell` = the app tier: neutral ::selection (kol-theme).
-        * `kol-brand-layout` = the sidenav grid; a hidden rail collapses the
-        * grid to the content column and zeroes the live width token. */}
+        * A hidden rail zeroes the live width token, so the content's own
+        * margin closes with it — one variable, both sides. */}
       <div
-        className="kol-app-shell kol-brand-layout min-h-dvh bg-surface-primary"
-        style={navHidden ? { gridTemplateColumns: 'minmax(0, 1fr)', '--kol-shell-rail-width': '0px' } : undefined}
+        className="kol-app-shell min-h-dvh bg-surface-primary"
+        style={navHidden ? { '--kol-shell-rail-width': '0px' } : undefined}
       >
       {touch === 'overlay' && <TouchDeviceOverlay appName={appName} />}
       {!navHidden && (
@@ -135,13 +129,13 @@ export default function AppShell({
           currentPath={currentPath}
           onNavigate={onNavigate}
           iconComponent={iconComponent}
-          settings={settings}
-          themeToggle={themeToggle ?? !settings}
         />
       )}
       {/* THE BACK OF THE BACK — surface-primary, always, in every app; the
         * page paints its wash over it (ShellPageWash). */}
-      <div className="bg-surface-primary min-w-0" style={{ '--kol-shell-page-wash': pageWash }}>
+      {/* the margin IS the rail's live width, so the content is pushed
+        * through the drag and the snap (RailFlatGrabOpen) */}
+      <div className="bg-surface-primary min-w-0" style={{ marginLeft: `var(--kol-shell-rail-width)`, '--kol-shell-page-wash': pageWash }}>
         {children}
       </div>
       </div>

package/src/NavRail.jsx

@@ -1,39 +1,204 @@
-import { SideNav, ThemeToggle } from '@kolkrabbi/kol-framework'
+import { useEffect, useRef, useState } from 'react'
+import gsap from 'gsap'
+import { Button } from '@kolkrabbi/kol-component'
+import { GRAB } from '@kolkrabbi/kol-component/utilities/motion'
 import { Icon } from '@kolkrabbi/kol-icons'
 import Logomark from './Logomark.jsx'
 
 /**
- * NavRail — AppShell's rail, which IS kol-framework's `SideNav`
- * (RailSideNavPixelParity, kol-fxr 2026-08-28 — user, on the brand sidebar's
- * drag: "same component both states super nice"). Until 0.13.0 this was its
- * own fixed 48px icon rail, and the first app to run it beside a collapsed
- * SideNav on adjacent routes measured every icon moving on the route change
- * (48 vs 56 wide, 20 vs 16px glyphs, 40 vs 38 pitch, first glyph at y 76 vs
- * 26). There is no second component now: this file maps the shell's flat
- * `{ icon, path, label }` items onto the sidenav's tree and mounts it
- * collapsed — the pill-marked grab edge opens it to the brand sidebar, the
- * drag is the transition, and it stays a rail while it navigates
- * (`expandOnSelect={false}`).
+ * NavRail — the flat rail. ONE fixed column, every child a direct child of it
+ * (RailFlatGrabOpen, kol-mirror 2026-08-28 — user, on the monitor rail he
+ * measured it against: "the div structure is super simple ok … it's 1 div
+ * parent and everything is just in that container", and on the SideNav-backed
+ * rail that had replaced it: it was "impossible" to get this shape out of it).
  *
- * The bottom, specified once: theme slot → `bottomItems` (pinned rows) →
- * no footer (an app rail never carried the site's wordmark link). The
- * `logomark` is the sidenav's `header` — at the TOP, both states, where every
- * rail in the estate has carried it (RailLogomarkAtTop, 2026-08-28 — user, on
- * 0.13.0's footer placement: "why did you move the logo from top to bottom?
- * … I've never seen that before so you are the first"). Its `title` is the
- * label beside the mark in the open rail; collapsed, the mark alone.
+ * This REVERSES RailSideNavPixelParity (0.13.0), which made the rail a collapsed
+ * kol-framework `SideNav`. That ticket's pixel argument is settled the other way:
+ * the rail does not share pixels with the brand sidebar because it never becomes
+ * one. `RailLogomarkAtTop` stands — the mark is at the top in both states.
  *
- * `settings` — SETTINGS IS A DISCLOSURE, NOT A ROUTE (RailSettingsDisclosure,
- * kol-fxr 2026-08-28 — user: "put the settings where the logo is, and logo
- * back on top" · "sidebar setting should open close on click and click again"
- * · "put the theme toggle in the settings and out of the sidebar" · "we make
- * it work here then ship it"): `{ icon, path, label }` renders the gear as the
- * pinned bottom row — a SideNav panel leaf, same pixel as the route row it
- * replaces — whose panel holds the theme toggle (`icon` collapsed /
- * `hop-bare` expanded, the slot's two variants) and the Settings page as a
- * row. The rail's standing theme slot is off when `settings` is given; the
- * toggle exists in the disclosure and on the settings page only.
+ * THE GRAB OPENS IT (user: "when you grab it should not move the icons one
+ * pixel, only reveal the title, and a chevron to see sub categories" · "when it
+ * opens it should push the main content inside"). Closed, every row is the rail
+ * minus its gutter — the 32px rung alone shows and the label and chevron exist
+ * but are clipped by the row's own width. Open, the clip reveals them. Nothing
+ * in the icon column moves between the two states, and the content column
+ * follows because AppShell offsets by the same live variable.
+ *
+ * ONE WIDTH VARIABLE: `--kol-shell-rail-width` on `:root` — this rail is that
+ * wide and AppShell's content is offset by it, written per pointermove during a
+ * drag and tweened on release, so the page is pushed live through both. A drag
+ * writes the DOM, not React state: a pointermove per frame is not a render.
+ *
+ * The pill is kol-r2b2's, verbatim (user: "make it like it is in kol-r2b2, it
+ * has animation and gsap") — `.kol-rail-grab` in kol-theme's kol-animation.css,
+ * its pointer numbers in kol-component's `utilities/motion` (`GRAB`).
+ *
+ * @param {Array}  items        `{ icon, path, label, sub?: [{ path, label }] }`
+ * @param {Array}  bottomItems  pinned below the rule (Settings)
+ * @param {Object} logomark     `{ svgUrl, title }` — the mark, and the app name beside it when open
+ * @param {string} currentPath  active match: '/' exact, else prefix → aria-current="page"
+ * @param {Function} onNavigate `(path) => void` — every click, the mark included
  */
+const RAIL_W = '--kol-shell-rail-width'
+const CLOSED = 48
+
+/* the OPEN width is the sidenav's ladder (kol-framework: 264, 320 from 1536),
+ * read at drag time so the rail lands on whichever rung the window is on */
+const openWidth = () => {
+  const v = getComputedStyle(document.documentElement).getPropertyValue('--kol-sidenav-w').trim()
+  const px = parseFloat(v)
+  return Number.isFinite(px) ? (v.endsWith('rem') ? px * 16 : px) : 264
+}
+
+/* THE GRAB EDGE — proximity, not contact: the pill wakes within `GRAB.near` of
+ * the line and sleeps only past `GRAB.sleep` (hovering the line itself flapped
+ * the class every frame and restarted the fade). Along the line it rests on the
+ * nearest of GRAB.marks and is STICKY — it leaves a mark only within `GRAB.stick`
+ * of the pitch of another (user: "following the mouse a little too much"), so the
+ * middle of each gap is dead. One window listener, rAF-throttled. */
+function useGrabEdge(ref) {
+  useEffect(() => {
+    let raf = 0
+    const onMove = ({ clientX, clientY }) => {
+      if (raf) return
+      raf = requestAnimationFrame(() => {
+        raf = 0
+        const h = ref.current
+        if (!h) return
+        const r = h.getBoundingClientRect()
+        const dist = Math.abs(clientX - (r.left + r.width / 2))
+        const near = dist <= GRAB.near || (h.classList.contains('is-near') && dist <= GRAB.sleep)
+        h.classList.toggle('is-near', near)
+        if (!near) return
+        const frac = Math.min(Math.max((clientY - r.top) / r.height, 0), 1)
+        const mark = GRAB.marks.reduce((a, b) => (Math.abs(b - frac) < Math.abs(a - frac) ? b : a))
+        if (h.dataset.grabSeeded && Math.abs(frac - mark) > GRAB.stick) return
+        const along = mark * r.height
+        if (h.dataset.grabSeeded && along === Number(h.dataset.grabTarget)) return
+        h.dataset.grabTarget = String(along)
+        const vars = { '--kol-rail-grab-y': `${along}px` }
+        /* the CSS fallback is 50%, a percentage — nothing to tween from, so the
+         * first sighting sets and every move after tweens */
+        if (h.dataset.grabSeeded) gsap.to(h, { ...vars, ...GRAB.travel, overwrite: 'auto' })
+        else { gsap.set(h, vars); h.dataset.grabSeeded = '1' }
+      })
+    }
+    window.addEventListener('pointermove', onMove)
+    return () => { window.removeEventListener('pointermove', onMove); cancelAnimationFrame(raf) }
+  }, [ref])
+}
+
+/* THE DRAG — hold the pill and the width follows the pointer between closed and
+ * open; release snaps to the nearer state, a click (no travel past GRAB.slop)
+ * toggles. `onSnap` reports the resting state once — the sub rows render only
+ * while open, because closed they would still take their height and push the
+ * rungs below them. */
+function useRailDrag(railRef, grabRef, onSnap) {
+  useEffect(() => {
+    const strip = grabRef.current, rail = railRef.current, root = document.documentElement
+    if (!strip || !rail) return undefined
+    gsap.set(root, { [RAIL_W]: `${CLOSED}px` })
+    let drag = null
+    const snapTo = (w) => {
+      gsap.to(root, { [RAIL_W]: `${w}px`, ...GRAB.snap, overwrite: 'auto' })
+      onSnap(w !== CLOSED)
+    }
+    const onDown = (e) => {
+      strip.setPointerCapture(e.pointerId)
+      gsap.killTweensOf(root)
+      drag = { x: e.clientX, w: rail.offsetWidth, open: openWidth(), moved: false }
+      strip.classList.add('is-dragging')
+    }
+    const onMove = (e) => {
+      if (!drag) return
+      const dx = e.clientX - drag.x
+      if (Math.abs(dx) > GRAB.slop) drag.moved = true
+      root.style.setProperty(RAIL_W, `${Math.min(Math.max(drag.w + dx, CLOSED), drag.open)}px`)
+    }
+    const onUp = () => {
+      if (!drag) return
+      const w = rail.offsetWidth
+      const open = drag.open
+      snapTo(drag.moved ? (w > (CLOSED + open) / 2 ? open : CLOSED) : (drag.w > CLOSED ? CLOSED : open))
+      drag = null
+      strip.classList.remove('is-dragging')
+    }
+    strip.addEventListener('pointerdown', onDown)
+    strip.addEventListener('pointermove', onMove)
+    strip.addEventListener('pointerup', onUp)
+    strip.addEventListener('pointercancel', onUp)
+    return () => {
+      strip.removeEventListener('pointerdown', onDown)
+      strip.removeEventListener('pointermove', onMove)
+      strip.removeEventListener('pointerup', onUp)
+      strip.removeEventListener('pointercancel', onUp)
+    }
+  }, [railRef, grabRef, onSnap])
+}
+
+/* one row: the rung exactly where the closed rail had it, then the label and
+ * (with `sub`) the chevron — the row clips to the rail's width */
+function RailItem({ icon, path, label, sub, currentPath, onNavigate, iconComponent, railOpen }) {
+  const [open, setOpen] = useState(false)
+  const active = path === '/' ? currentPath === '/' : currentPath.startsWith(path)
+  return (
+    <>
+      <div className="flex items-center gap-3 w-full overflow-hidden shrink-0">
+        <Button
+          iconOnly={icon}
+          iconSize={20}
+          iconComponent={iconComponent}
+          variant="nav"
+          size="md"
+          className="shrink-0"
+          /* nav ACTIVE keys off aria-current="page" (kol-components-atoms.css) —
+           * a brighter glyph, never the pressed fill */
+          aria-current={active ? 'page' : undefined}
+          /* oq-96 on every rung: the nav variant's oq-64 rest is site-nav quiet
+           * and too dim on an icon rail (user: "make the color .96 on every icon
+           * in the rail") */
+          style={{ color: 'var(--kol-oq-96)' }}
+          onClick={() => onNavigate?.(path)}
+          title={label}
+          aria-label={label}
+        />
+        <span
+          className="kol-helper-12 uppercase text-oq-96 flex-1 min-w-0 truncate cursor-pointer"
+          onClick={() => onNavigate?.(path)}
+        >
+          {label}
+        </span>
+        {sub?.length > 0 && (
+          <Button
+            iconOnly={open ? 'chevron-down' : 'chevron-right'}
+            iconSize={16}
+            iconComponent={iconComponent}
+            variant="nav"
+            size="sm"
+            className="shrink-0"
+            style={{ color: 'var(--kol-oq-96)' }}
+            aria-expanded={open}
+            onClick={() => setOpen((v) => !v)}
+            title={label}
+            aria-label={`${label} sub categories`}
+          />
+        )}
+      </div>
+      {railOpen && open && sub.map((s) => (
+        <div key={s.path} className="flex items-center w-full overflow-hidden shrink-0 pl-11">
+          <span
+            className="kol-helper-12 uppercase text-oq-64 hover:text-oq-96 truncate cursor-pointer"
+            onClick={() => onNavigate?.(s.path)}
+          >
+            {s.label}
+          </span>
+        </div>
+      ))}
+    </>
+  )
+}
+
 export default function NavRail({
   items = [],
   bottomItems = [],
@@ -41,66 +206,43 @@ export default function NavRail({
   currentPath = '',
   onNavigate,
   iconComponent,
-  settings,
-  themeToggle = !settings,
   hidden = false,
 }) {
+  const railRef = useRef(null)
+  const grabRef = useRef(null)
+  const [railOpen, setRailOpen] = useState(false)
+  useGrabEdge(grabRef)
+  useRailDrag(railRef, grabRef, setRailOpen)
   if (hidden) return null
-  const node = (item) => ({ id: item.path, label: item.label, icon: item.icon, to: item.path })
-  const Glyph = iconComponent ?? Icon
-  const settingsLeaf = settings && {
-    id: settings.path,
-    label: settings.label,
-    icon: settings.icon,
-    panel: ({ collapsed, close }) => (
-      <>
-        <div className="kol-sidenav-theme-slot flex">
-          <ThemeToggle variant={collapsed ? 'icon' : 'hop-bare'} size="md" />
-        </div>
-        <button
-          type="button"
-          className="kol-sidenav-hop kol-helper-12 text-strong hover:text-emphasis bg-transparent border-0 cursor-pointer text-left"
-          onClick={() => { close(); onNavigate?.(settings.path) }}
-          title={settings.label}
-          aria-label={settings.label}
-        >
-          <span className="kol-sidenav-hop-icon inline-flex items-center justify-center w-5 h-5 shrink-0" aria-hidden="true">
-            <Glyph name="arrow-right" size={16} />
-          </span>
-          <span className="kol-sidenav-hop-label flex-1 min-w-0 truncate">{settings.label}</span>
-        </button>
-      </>
-    ),
-  }
-  /* the shell's route match: '/' exact, anything else by prefix */
-  const isActive = (to) => (to === '/' ? currentPath === '/' : currentPath.startsWith(to))
+  const row = (item) => (
+    <RailItem key={item.path} {...item} currentPath={currentPath} onNavigate={onNavigate} iconComponent={iconComponent} railOpen={railOpen} />
+  )
   return (
-    <SideNav
-      navTree={items.map(node)}
-      bottomItems={[...bottomItems.map(node), ...(settingsLeaf ? [settingsLeaf] : [])]}
-      currentPath={currentPath}
-      isActive={isActive}
-      onNavigate={(e, to) => onNavigate?.(to)}
-      iconComponent={iconComponent}
-      themeToggle={themeToggle}
-      expandOnSelect={false}
-      defaultCollapsed
-      hairline
-      footer={false}
-      header={logomark ? (
-        <button
-          type="button"
-          className="flex items-center gap-3 w-full bg-transparent border-0 p-0 cursor-pointer text-emphasis no-underline text-left"
+    <div
+      ref={railRef}
+      className="kol-shell-rail bg-surface-primary border-r border-fg-08 fixed inset-y-0 left-0 flex flex-col items-start pt-4 pb-4 px-2 gap-2"
+      style={{ width: `var(${RAIL_W})` }}
+    >
+      <div ref={grabRef} className="kol-rail-grab" />
+      {logomark && (
+        /* 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. */
+        <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}
-          aria-label={logomark.title}
         >
-          <span className="kol-sidenav-hop-icon inline-flex items-center justify-center w-5 h-5 shrink-0" aria-hidden="true">
-            <Logomark svgUrl={logomark.svgUrl} size={20} />
-          </span>
-          {logomark.title && <span className="kol-sidenav-hop-label kol-helper-12 flex-1 min-w-0 truncate">{logomark.title}</span>}
-        </button>
-      ) : undefined}
-    />
+          <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>
+      )}
+      {items.map(row)}
+      {/* the spacer IS the layout */}
+      <div className="flex-1" />
+      {/* the rule runs the full rail width, out past the px-2 */}
+      {bottomItems.length > 0 && <div className="self-stretch -mx-2 border-t border-fg-08" />}
+      {bottomItems.map(row)}
+    </div>
   )
 }

package/src/PageHeader.jsx

@@ -29,18 +29,34 @@
  *                    kol-mono-heading-03 · kol-mono-display-03 · kol-mono-display-02
  *                    (kol-theme ≥0.67.0). The subtitle stays kol-mono-14.
  * @param {string}    titleClass  replaces the title role whole (the ContentText seam)
+ * @param {ReactNode} actions   a control cluster on the SUBTITLE's first baseline — on the title's
+ *                    when there is no subtitle (PageHeaderTrailingSlot, kol-website 2026-08-28;
+ *                    kol-r2b2's header is the reference: wordmark left, controls right, on the
+ *                    line). Without it the consumer wrapped the header in a flex row and got the
+ *                    h1's baseline, or re-rendered the subtitle as a bare <p> off copied classes
+ *                    with an `!important` on the margin — a DS text role re-implemented outside.
+ * @param {string}    subtitleMaxWidth  the lede's measure (e.g. '800px' or '60ch'), a prop
+ *                    instead of a consumer selector reaching inside
+ * The bottom rhythm is `--kol-page-header-mb` (default 40px): inline, as before, but through a
+ * variable a consumer can re-point where an inline literal could only be `!important`-ed.
  */
 const TITLE = {
   sans: { sm: 'kol-sans-heading-03', md: 'kol-sans-display-03', lg: 'kol-sans-display-02' },
   mono: { sm: 'kol-mono-heading-03', md: 'kol-mono-display-03', lg: 'kol-mono-display-02' },
 }
 
-export default function PageHeader({ eyebrow, title, subtitle, size = 'md', voice = 'sans', titleClass, className = '' }) {
+export default function PageHeader({ eyebrow, title, subtitle, actions, subtitleMaxWidth, size = 'md', voice = 'sans', titleClass, className = '' }) {
   const roles = TITLE[voice] ?? TITLE.sans
+  const h1 = <h1 className={`text-fg-96 ${titleClass ?? roles[size] ?? roles.md}`}>{title}</h1>
+  const lede = subtitle && <p className="text-oq-64 kol-mono-14 min-w-0" style={{ marginTop: actions ? undefined : 12, maxWidth: subtitleMaxWidth }}>{subtitle}</p>
+  /* the cluster shares a baseline row with the lede (or the title): flexbox
+     exposes a flex item's FIRST baseline, so putting them in one row is the
+     one way to land on the subtitle's line rather than the h1's */
+  const cluster = actions && <div className="flex items-center gap-4 shrink-0">{actions}</div>
   return (
     /* the block owns its own rhythm — margins inline, never in a shared type
        class, which leaks estate-wide (ShellHeaderFilterRefinements, 2026-08-15) */
-    <header className={`flex flex-col ${className}`.trim()} style={{ marginBottom: 40 }}>
+    <header className={`flex flex-col ${className}`.trim()} style={{ marginBottom: 'var(--kol-page-header-mb, 40px)' }}>
       {eyebrow && (
         /* HELPER, not mono (user ruling 2026-08-15). An eyebrow is single-line
            chrome — that is the whole definition of the `kol-helper-*` ramp, and
@@ -54,9 +70,24 @@ export default function PageHeader({ eyebrow, title, subtitle, size = 'md', voic
           {eyebrow}
         </p>
       )}
-      <h1 className={`text-fg-96 ${titleClass ?? roles[size] ?? roles.md}`}>{title}</h1>
-      {subtitle && (
-        <p className="text-oq-64 kol-mono-14" style={{ marginTop: 12 }}>{subtitle}</p>
+      {actions && subtitle ? (
+        <>
+          {h1}
+          <div className="flex items-baseline justify-between gap-6" style={{ marginTop: 12 }}>
+            {lede}
+            {cluster}
+          </div>
+        </>
+      ) : actions ? (
+        <div className="flex items-baseline justify-between gap-6">
+          {h1}
+          {cluster}
+        </div>
+      ) : (
+        <>
+          {h1}
+          {lede}
+        </>
       )}
     </header>
   )