@kolkrabbi/kol-component 0.185.0 → 0.187.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.185.0",
+  "version": "0.187.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",

package/src/hooks/colorMath.js

@@ -104,6 +104,37 @@ export function harmonyColors(hue, harmony, { saturation = 100, lightness = 50 }
   return roleOffsets.map((off) => hslToHex(normHue(hue + off), saturation, lightness))
 }
 
+/**
+ * Re-hue an EXISTING palette to a harmony, preserving each slot's own
+ * saturation and lightness.
+ *
+ * `harmonyColors` builds every role at ONE flat S/L, which is right when a
+ * caller has no palette yet and wrong the moment it does: a Light slot and a
+ * Dark slot both come back at 50% lightness, so the palette flattens on the
+ * first drag of the wheel (kol-fxr, `editor-set-is-behind-its-source`
+ * 2026-09-03 — its own wheel emits a hue and re-hues slot by slot, so the
+ * package's `colors` payload was half-ignorable).
+ *
+ * A slot that is `locked`, empty, or has no hex is passed through untouched —
+ * locking a colour is the one instruction a re-hue must not overrule.
+ *
+ * @param {number} hue base hue, 0–360
+ * @param {string|object} harmony harmony id or object
+ * @param {Array<{hex?: string, locked?: boolean}|string|null>} slots the current palette, in role order
+ * @returns {Array} the same shape back, re-hued — strings stay strings, objects keep every other key
+ */
+export function reHueSlots(hue, harmony, slots = []) {
+  const { roleOffsets } = harmonyById(harmony)
+  return slots.map((slot, i) => {
+    const off = roleOffsets[i % roleOffsets.length]
+    const hex = typeof slot === 'string' ? slot : slot?.hex
+    if (!hex || (typeof slot === 'object' && slot?.locked)) return slot
+    const { s, l } = hexToHsl(hex)
+    const next = hslToHex(normHue(hue + off), s, l)
+    return typeof slot === 'string' ? next : { ...slot, hex: next }
+  })
+}
+
 /**
  * Deterministic role colors derived from a base hex (S/L taken from the hex).
  * Convenience wrapper over `harmonyColors` for callers holding a color, not

package/src/hooks/useDragResize.js

@@ -0,0 +1,319 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+/* THE SAME GRAB AS THE SHELL RAIL (OneGrabGestureBothRails, kol-fxr 2026-08-30 —
+ * user: *"why dont we use the grab animation and other sidenav settings to be
+ * consistent?"*). fxr's /labs shows both rails at once and only the left one
+ * woke as the cursor neared it, because each package had built the gesture
+ * itself. `useGrabEdge` lives in kol-component, the one package both can reach —
+ * kol-shell dropped its framework peer in 0.16.0, so neither could import the
+ * other's.
+ *
+ * THIS HOOK FOLLOWED IT DOWN 2026-09-03 (`editor-set-is-behind-its-source`,
+ * kol-fxr). `EditorShell` is a kol-component export whose rails are fixed-px
+ * and unresizable, and the fix is this hook — but kol-component may not import
+ * kol-framework (ARCHITECTURE §3, no reverse deps), so the shared hook moved to
+ * the tier both sides reach, exactly as its own comment argues for the gesture
+ * it wraps. kol-framework re-exports it under the same name, so `SideNav` and
+ * every consumer import keep working unchanged. */
+import useGrabEdge from './useGrabEdge.js'
+
+/* Grab-edge resize + collapse for SideNav — THE single control since 0.17.0
+ * (user build order 2026-08-09, completing the SideNavGrabResize brief: the
+ * chip Button is gone in both states; the pill-marked edge does everything).
+ * Logic lifted from the hand-tested brand proto (kol-website _tmp
+ * useDragResizeProto.js), which forked this hook's 0.16.0 form.
+ *
+ *  - CLICK TOGGLES expand↔collapse: pointerup with < 3px of travel is a
+ *    click, never a resize — drags only start past the slop, so toggle
+ *    presses can't jitter the rail.
+ *  - DRAG resizes; live width goes to --kol-sidenav-w on :root so the grid,
+ *    shell-header brand block and aside follow one number. Dragging under
+ *    --kol-sidenav-snap stamps :root[data-sidenav="collapsed"].
+ *  - SNAP-TO-DEFAULT: releasing within --kol-sidenav-snap-default of the
+ *    stylesheet default clears the override — you land exactly on default,
+ *    never 249px or 263px.
+ *  - DOUBLE-CLICK RESET IS GONE — it cannot coexist with click-toggle (two
+ *    clicks would toggle-toggle-reset). Home keeps the reset; the snap band
+ *    covers pointer users.
+ *  - Keyboard on the focused separator: arrows resize by --kol-sidenav-step
+ *    (ArrowLeft past the snap collapses), Home resets, Enter/Space toggle.
+ *  - Width + state survive reload ('kol-sidenav' keeps the consumers'
+ *    existing 'collapsed'|'expanded' schema; width under its own key).
+ *
+ * Every value the gesture needs is a --<token>-* custom property in the
+ * consumer's CSS — no literals here except the click slop, which is a
+ * gesture constant, not chrome. Missing tokens leave the gesture inert.
+ *
+ * SIDE-AGNOSTIC since ThreeColumnEditorShell (kol-fxr, 2026-08-15): the name
+ * family and the drag direction are both arguments now, so a right-hand
+ * inspector rail reuses this gesture — pointer, keyboard, snap, collapse and
+ * persistence — instead of reimplementing it. The bullets above describe the
+ * DEFAULT ('kol-sidenav', side 'left'), which is byte-identical to 0.17.0. */
+
+const CLICK_SLOP_PX = 3
+
+const root = () => document.documentElement
+
+/* Every name the gesture touches, derived from ONE token (ThreeColumnEditorShell,
+ * filed from kol-fxr 2026-08-15). The default token reproduces the hardcoded
+ * 0.17.0 names EXACTLY — 'kol-sidenav' → data-sidenav, --kol-sidenav-w,
+ * storage 'kol-sidenav'/'kol-sidenav-w' — so SideNav and every existing caller
+ * are untouched by this generalisation.
+ *
+ * The data-attribute drops the `kol-` prefix because that is what the shipped
+ * CSS already selects (`:root[data-sidenav="collapsed"]`), not a new scheme. */
+export function buildNames(token) {
+  const base = token.replace(/^kol-/, '')
+  return {
+    stateKey: token,
+    widthKey: `${token}-w`,
+    collapsedAttr: `data-${base}`,
+    draggingAttr: `data-${base}-dragging`,
+    wVar: `--${token}-w`,
+    collapsedVar: `--${token}-w-collapsed`,
+    snapVar: `--${token}-snap`,
+    stepVar: `--${token}-step`,
+    snapDefaultVar: `--${token}-snap-default`,
+  }
+}
+
+/* Resolve a length token to px, or null when it is absent/unparsable. */
+function readVarPx(name) {
+  const raw = getComputedStyle(root()).getPropertyValue(name).trim()
+  const n = parseFloat(raw)
+  if (!raw || Number.isNaN(n)) return null
+  return raw.endsWith('rem') ? n * parseFloat(getComputedStyle(root()).fontSize) : n
+}
+
+/* Imperative DOM writes — pointermove must never re-render the nav tree.
+ * React state syncs from the DOM at rest (release / key press / reset). */
+const stampCollapsed = (n, on) => {
+  if (on) root().setAttribute(n.collapsedAttr, 'collapsed')
+  else root().removeAttribute(n.collapsedAttr)
+}
+const writeWidth = (n, px) => {
+  if (px == null) root().style.removeProperty(n.wVar)
+  else root().style.setProperty(n.wVar, `${px}px`)
+}
+const readBack = (n) => {
+  const inline = parseFloat(root().style.getPropertyValue(n.wVar))
+  return {
+    collapsed: root().getAttribute(n.collapsedAttr) === 'collapsed',
+    widthPx: Number.isNaN(inline) ? null : inline,
+  }
+}
+
+/* @param ref      the panel being resized — its measured width seeds the drag
+ * @param options  { token, side }
+ *   token — the CSS/storage name family. Default 'kol-sidenav' (SideNav).
+ *           A right-hand inspector passes its own, e.g. 'kol-rail', so the two
+ *           rails never share one :root variable and drag together.
+ *   side  — which EDGE the grab handle sits on. 'left' (default) is a rail on
+ *           the left of the viewport whose handle is on its right edge, so
+ *           rightward drag = wider. 'right' inverts both the pointer sign and
+ *           the arrow keys.
+ *   persistWidth — remember a dragged WIDTH across sessions. **Default false**
+ *           (sidenav-drag-width-outranks-breakpoints, kol-client-olina
+ *           2026-09-03; user: *"why would you want that in persistent memory?
+ *           and even if you did, shouldnt it be an opt in via prop? off by
+ *           default"*).
+ *
+ *           It used to be unconditional, and the width was replayed on boot as
+ *           an INLINE custom property on `:root` — which outranks every
+ *           stylesheet rule, so one drag on a laptop killed both shipped rungs
+ *           (`--kol-sidenav-w: 264px` and the 320px `min-width:1536px` rule)
+ *           permanently, on every machine, with no UI saying so and no selector
+ *           a consumer could beat. Measured at 1600×900: a stored 210 rendered
+ *           210 and the 1536 rung did nothing. A one-off gesture had become a
+ *           permanent global.
+ *
+ *           Off, a drag still works and lasts the session; the rail follows the
+ *           stylesheet and its breakpoints on the next boot. On, the old
+ *           behaviour returns for an app that genuinely wants the rail
+ *           remembered — and it is still an inline stamp, so an app opting in is
+ *           choosing to outrank its own breakpoints. That precedence is worth
+ *           inverting, but it is a bigger change than this ticket asked for.
+ *
+ *           STATE is untouched: collapsed/expanded still persists via
+ *           `stateKey`, unconditionally, as it always did. The ticket says the
+ *           two are separate questions and only asks about the width. */
+export default function useDragResize(ref, options = {}) {
+  const { token = 'kol-sidenav', side = 'left', defaultCollapsed = false, persistWidth = false } = options
+  /* -1 on a right-hand rail: the same rightward pointer travel that widens a
+   * left rail must NARROW a right one, because its handle faces the canvas. */
+  const dir = side === 'right' ? -1 : 1
+  const names = useMemo(() => buildNames(token), [token])
+
+  /* the handle's own ref, so the shared gesture can find it. Returned in
+   * `grabProps`, so a consumer already spreading those gets the wake, the
+   * travel and the dwell with no change. */
+  const grabRef = useRef(null)
+  useGrabEdge(grabRef)
+  const drag = useRef(null) // { startX, startW, snapPx, maxPx, moved } during a drag
+  const defaultPx = useRef(null)
+  const collapsedPx = useRef(null)
+  const [collapsed, setCollapsed] = useState(false)
+  const [widthPx, setWidthPx] = useState(null) // null = stylesheet default
+
+  const syncAndPersist = () => {
+    const { collapsed: c, widthPx: w } = readBack(names)
+    setCollapsed(c)
+    setWidthPx(w)
+    try {
+      localStorage.setItem(names.stateKey, c ? 'collapsed' : 'expanded')
+      /* width only when asked for; off, the key is not written AND any key a
+       * previous version left behind is cleared, so a consumer that bumps stops
+       * replaying a width it never opted into */
+      if (!persistWidth || w == null) localStorage.removeItem(names.widthKey)
+      else localStorage.setItem(names.widthKey, String(Math.round(w)))
+    } catch { /* storage blocked */ }
+  }
+
+  const toggleCollapsed = () => {
+    const { collapsed: c } = readBack(names)
+    stampCollapsed(names, !c)
+    syncAndPersist()
+  }
+
+  /* Boot: capture the stylesheet defaults BEFORE any inline override lands,
+   * then restore the persisted width/state. */
+  useEffect(() => {
+    defaultPx.current = readVarPx(names.wVar)
+    collapsedPx.current = readVarPx(names.collapsedVar)
+    let w = null
+    let stored = null
+    try {
+      /* off → never read it, and drop a key an earlier version wrote */
+      if (persistWidth) w = parseFloat(localStorage.getItem(names.widthKey)) || null
+      else localStorage.removeItem(names.widthKey)
+      stored = localStorage.getItem(names.stateKey)
+    } catch { /* storage blocked */ }
+    /* nothing stored → the consumer's boot state (RailSideNavPixelParity,
+     * 2026-08-28): an app rail boots collapsed, the brand sidebar boots open;
+     * the first drag or click persists and the default never speaks again */
+    const c = stored ? stored === 'collapsed' : !!defaultCollapsed
+    if (w) { writeWidth(names, w); setWidthPx(w) }
+    if (c) { stampCollapsed(names, true); setCollapsed(true) }
+  }, [names, defaultCollapsed, persistWidth])
+
+  useEffect(() => {
+    const onMove = (e) => {
+      if (!drag.current) return
+      const d = drag.current
+      const dx = e.clientX - d.startX
+      /* Below the slop the pointer is still a CLICK — resizing from the
+       * first pixel would jitter the rail on every toggle press. */
+      if (!d.moved) {
+        if (Math.abs(dx) < CLICK_SLOP_PX) return
+        d.moved = true
+      }
+      const next = d.startW + dx * dir
+      if (next < d.snapPx) {
+        stampCollapsed(names, true)
+      } else {
+        stampCollapsed(names, false)
+        writeWidth(names, Math.min(next, d.maxPx))
+      }
+    }
+    const onUp = () => {
+      if (!drag.current) return
+      const { moved } = drag.current
+      drag.current = null
+      root().removeAttribute(names.draggingAttr)
+      document.body.style.cursor = ''
+      document.body.style.userSelect = ''
+      if (!moved) { toggleCollapsed(); return } // a click, not a drag
+      /* Snap-to-default: release near the stylesheet default clears the
+       * override entirely. */
+      const { collapsed: c, widthPx: w } = readBack(names)
+      const band = readVarPx(names.snapDefaultVar) ?? readVarPx(names.stepVar) ?? 16
+      if (!c && w != null && defaultPx.current != null && Math.abs(w - defaultPx.current) <= band) {
+        writeWidth(names, null)
+      }
+      syncAndPersist()
+    }
+    window.addEventListener('pointermove', onMove)
+    window.addEventListener('pointerup', onUp)
+    return () => {
+      window.removeEventListener('pointermove', onMove)
+      window.removeEventListener('pointerup', onUp)
+    }
+  }, [names, dir])
+
+  const onPointerDown = (e) => {
+    const snapPx = readVarPx(names.snapVar)
+    if (defaultPx.current == null || snapPx == null) return // tokens absent → inert
+    e.preventDefault()
+    drag.current = {
+      startX: e.clientX,
+      startW: ref.current?.getBoundingClientRect().width ?? defaultPx.current,
+      snapPx,
+      /* mirror's ceiling (default × 3), resolved from the token not hardcoded */
+      maxPx: defaultPx.current * 3,
+      moved: false,
+    }
+    /* the grid's grid-template-columns ease would trail the pointer —
+     * kol-framework.css suspends it while this attribute is stamped */
+    root().setAttribute(names.draggingAttr, '')
+    document.body.style.cursor = 'col-resize'
+    document.body.style.userSelect = 'none'
+  }
+
+  const resetToDefault = () => {
+    stampCollapsed(names, false)
+    writeWidth(names, null)
+    syncAndPersist()
+  }
+
+  const onKeyDown = (e) => {
+    const snapPx = readVarPx(names.snapVar)
+    const stepPx = readVarPx(names.stepVar)
+    if (defaultPx.current == null || snapPx == null || stepPx == null) return
+    const { collapsed: c, widthPx: w } = readBack(names)
+    const current = w ?? defaultPx.current
+    /* The arrow that GROWS is the one pointing away from the rail's own edge —
+     * ArrowRight on a left rail, ArrowLeft on a right one. Same inversion the
+     * pointer gets, so keyboard and drag never disagree. */
+    const growKey = dir === 1 ? 'ArrowRight' : 'ArrowLeft'
+    const shrinkKey = dir === 1 ? 'ArrowLeft' : 'ArrowRight'
+    if (e.key === growKey) {
+      e.preventDefault()
+      if (c) stampCollapsed(names, false)
+      else writeWidth(names, Math.min(current + stepPx, defaultPx.current * 3))
+      syncAndPersist()
+    } else if (e.key === shrinkKey) {
+      e.preventDefault()
+      if (c) return
+      const next = current - stepPx
+      if (next < snapPx) stampCollapsed(names, true)
+      else writeWidth(names, next)
+      syncAndPersist()
+    } else if (e.key === 'Home') {
+      e.preventDefault()
+      resetToDefault()
+    } else if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      toggleCollapsed()
+    }
+  }
+
+  return {
+    collapsed,
+    toggleCollapsed,
+    grabProps: {
+      ref: grabRef,
+      /* the pill is drawn by `.kol-rail-grab` (kol-animation.css) — the hook
+       * only supplies `is-near` and `--kol-rail-grab-y`. A consumer's own
+       * className, spread after this, still wins. */
+      className: 'kol-rail-grab',
+      role: 'separator',
+      'aria-orientation': 'vertical',
+      'aria-label': 'Resize navigation',
+      'aria-valuenow': Math.round(collapsed ? collapsedPx.current : (widthPx ?? defaultPx.current)) || undefined,
+      'aria-valuemin': collapsedPx.current == null ? undefined : Math.round(collapsedPx.current),
+      'aria-valuemax': defaultPx.current == null ? undefined : Math.round(defaultPx.current * 3),
+      tabIndex: 0,
+      onPointerDown,
+      onKeyDown,
+    },
+  }
+}

package/src/index.js

@@ -193,6 +193,11 @@ export { default as useCoarsePointer } from './hooks/useCoarsePointer.js'
 export { default as useInViewAttention } from './hooks/useInViewAttention.js'
 export { default as useAxisAnimation } from './hooks/useAxisAnimation.js'
 export { useEyedropper, pickFromCanvasElement } from './hooks/useEyedropper.js'
+/* The rail gesture's other half. It lived in kol-framework until 2026-09-03 and
+ * moved here for the same reason `useGrabEdge` did: kol-component's own
+ * `EditorShell` needs resizable rails and cannot import framework. framework
+ * re-exports it, so no consumer specifier changed. */
+export { default as useDragResize } from './hooks/useDragResize.js'
 export { default as usePlaceholders } from './hooks/usePlaceholders.js'
 export { resolveCssVar, resolveCssColor, isLight } from './hooks/cssVar.js'
 

package/src/molecules/Dropdown.jsx

@@ -3,7 +3,7 @@ import { toneClass, TONE_VARS } from '../utilities/tone.js'
 import { Icon } from '@kolkrabbi/kol-icons'
 import { MenuDropdownItem } from './MenuItem.jsx'
 import { PopoverPanel, usePopover } from '../utilities/Popover.jsx'
-import { indicatorSize } from '../hooks/glyphLadders.js'
+import { glyphSize, indicatorSize } from '../hooks/glyphLadders.js'
 
 /**
  * Dropdown — trigger IS button chrome (2026-07-08 chrome law).
@@ -77,6 +77,18 @@ const Dropdown = ({
    * while a row is hovered would otherwise leave the consumer previewing
    * forever. It never fires while closed — a closed dropdown has no rows. */
   onOptionHover,
+  /* ICON-ONLY TRIGGER — an icon name, or a pre-rendered node dropped in where
+   * the glyph goes. The trigger becomes the pinned square (`kol-btn-icon`) at
+   * the current size, with no label, no ghost widths and no caret; the panel
+   * still sizes to its own rows rather than the trigger. This is what a tool
+   * rail needs, and its absence is why kol-fxr's ToolPalette hand-rolls a
+   * trigger out of `PopoverPanel` + `usePopover` at a bespoke 36/22 instead of
+   * importing anything (`editor-set-is-behind-its-source`, 2026-09-03). */
+  iconOnly,
+  /* A mark drawn INSIDE the trigger box, over the glyph — the tool-palette
+   * corner fold is the case. Kept a slot rather than a boolean so the square
+   * has one implementation and the drawing stays the caller's. */
+  triggerAdornment,
   defaultOpen = false,
   className = ''
 }) => {
@@ -163,6 +175,12 @@ const Dropdown = ({
     `kol-btn-${resolvedSize}`,
     SIZE_TYPE[resolvedSize],
     'kol-dd-trigger',
+    /* ICON-ONLY: the pinned square from Button's own class, so a tool-rail
+     * dropdown is the same box as the icon button beside it at every rung
+     * (editor-set-is-behind-its-source, kol-fxr 2026-09-03 — its ToolPalette
+     * hand-rolls a trigger out of PopoverPanel + usePopover precisely because
+     * this mode did not exist). No label, no ghost widths, no caret. */
+    iconOnly && 'kol-btn-icon kol-dd-trigger--icon',
     isOpen && 'kol-dd-trigger--open',
     /* the dark chip on a washed plane; the panel continues it (ControlToneInverse, 2026-08-27) */
     toneClass(tone),
@@ -179,20 +197,33 @@ const Dropdown = ({
         aria-expanded={isOpen}
         data-state={isOpen ? 'open' : 'closed'}
       >
-        {/* every option's label rides along hidden so the trigger is as wide
-          * as its widest value — the panel matches the trigger's width, so
-          * trigger and list stay one piece at every selection */}
-        <span className="kol-dd-label">
-          <span>{currentOption?.label}</span>
-          {options.map((option) => (
-            <span key={option.value} className="kol-dd-ghost" aria-hidden="true">
-              {option.label}
+        {iconOnly ? (
+          /* the glyph comes from the SOLO ladder — an icon alone in a pinned
+           * square — never from a call-site number */
+          typeof iconOnly === 'string'
+            ? <Icon name={iconOnly} size={glyphSize(resolvedSize, true)} />
+            : iconOnly
+        ) : (
+          <>
+            {/* every option's label rides along hidden so the trigger is as wide
+              * as its widest value — the panel matches the trigger's width, so
+              * trigger and list stay one piece at every selection */}
+            <span className="kol-dd-label">
+              <span>{currentOption?.label}</span>
+              {options.map((option) => (
+                <span key={option.value} className="kol-dd-ghost" aria-hidden="true">
+                  {option.label}
+                </span>
+              ))}
             </span>
-          ))}
-        </span>
-        {/* chrome lives in .kol-dd-caret (trailing edge + open-state flip) —
-          * keyed off the trigger's data-state, no inline styles */}
-        <Icon name="chevron-down" size={indicatorSize(resolvedSize)} className="kol-dd-caret" />
+            {/* chrome lives in .kol-dd-caret (trailing edge + open-state flip) —
+              * keyed off the trigger's data-state, no inline styles */}
+            <Icon name="chevron-down" size={indicatorSize(resolvedSize)} className="kol-dd-caret" />
+          </>
+        )}
+        {/* a consumer's own trigger mark — the tool-palette corner fold rides
+            here so the square keeps ONE implementation */}
+        {triggerAdornment}
       </button>
 
       <PopoverPanel

package/src/molecules/PaletteHarmonyWheel.jsx

@@ -1,5 +1,5 @@
 import { useEffect, useRef } from 'react'
-import { HARMONIES, harmonyById, harmonyColors, normHue } from '../hooks/colorMath.js'
+import { HARMONIES, harmonyById, harmonyColors, normHue, reHueSlots } from '../hooks/colorMath.js'
 
 /* taxonomy-ok: a pure-canvas hue + harmony picker in the SpectrumControls
  * color-picker family. It nests no KOL component — its only import is the
@@ -20,6 +20,16 @@ import { HARMONIES, harmonyById, harmonyColors, normHue } from '../hooks/colorMa
  * arrow keys. `colors` is one hex per role offset of the active harmony
  * (see colorMath.harmonyColors), matching the satellite markers 1:1.
  *
+ * PASS `slots` IF YOU ALREADY HAVE A PALETTE (2026-09-03,
+ * `editor-set-is-behind-its-source`). Without it, `colors` is built at ONE
+ * flat `saturation`/`lightness`, so a Light role and a Dark role both come
+ * back at 50% — the palette flattens on the first drag, and kol-fxr's editor
+ * had to ignore half the payload because its own wheel re-hues slot by slot.
+ * With `slots`, every entry keeps its own S/L and only its hue moves, and a
+ * `locked` or empty slot is passed through untouched. `onHueChange(hue)` is
+ * the same seam with no payload at all, for a caller that owns the derivation
+ * outright — which is what fxr's wheel emits.
+ *
  * The ring hues, marker outlines and handle halo are literal color math
  * (hsl / #FFFFFF / rgba) on purpose — a spectrum is not themeable, and the
  * markers sit on fully-saturated ring hues, not on the surface (same
@@ -31,7 +41,9 @@ import { HARMONIES, harmonyById, harmonyColors, normHue } from '../hooks/colorMa
  * @param {number}        saturation  base saturation for emitted colors, 0–100 (default 100)
  * @param {number}        lightness   base lightness for emitted colors, 0–100 (default 50)
  * @param {Array}         harmonies   injectable scheme table (default HARMONIES)
+ * @param {Array}         slots       the CURRENT palette in role order (`{hex, locked}` objects or plain hex strings). Given, `colors` re-hues these — each slot keeps its own S/L, locked and empty entries pass through — instead of generating flat ones
  * @param {Function}      onChange    ({ hue, colors }) => void
+ * @param {Function}      onHueChange (hue) => void — the payload-free seam, for a caller that derives its own colours
  */
 
 /* Marker outline — white for contrast against the fully-saturated ring hues
@@ -44,8 +56,10 @@ export default function PaletteHarmonyWheel({
   harmony = 'analogous',
   saturation = 100,
   lightness = 50,
+  slots,
   harmonies = HARMONIES,
   onChange,
+  onHueChange,
 }) {
   const canvasRef   = useRef(null)
   const draggingRef = useRef(false)
@@ -58,10 +72,18 @@ export default function PaletteHarmonyWheel({
   )
 
   /* Emit next hue + its harmony colors. Held in a ref so the pointer/key
-   * handlers stay stable while always seeing the latest props. */
+   * handlers stay stable while always seeing the latest props.
+   *
+   * With `slots`, the colours are the CALLER'S palette re-hued — each slot
+   * keeping its own saturation and lightness — rather than a fresh flat set.
+   * Both fire, so a caller can take the hue and ignore the colours. */
   emitRef.current = (nextHue) => {
     const h = normHue(nextHue)
-    onChange?.({ hue: h, colors: harmonyColors(h, active, { saturation, lightness }) })
+    const colors = slots?.length
+      ? reHueSlots(h, active, slots)
+      : harmonyColors(h, active, { saturation, lightness })
+    onChange?.({ hue: h, colors })
+    onHueChange?.(h)
   }
 
   const outerR = size / 2 - 8

package/src/utilities/EditorShell.jsx

@@ -1,4 +1,6 @@
+import { useRef } from 'react'
 import Divider from '../atoms/Divider.jsx'
+import useDragResize from '../hooks/useDragResize.js'
 
 /**
  * EditorShell — the two-rail editor layout frame.
@@ -7,33 +9,56 @@ import Divider from '../atoms/Divider.jsx'
  *   ├────────┬──────────────────────────┬──────────┤
  *   │  left  │  [canvasHeader]          │  right   │
  *   │  rail  │  children (canvas)       │  rail    │
+ *   │        │  [canvasFooter]          │          │
  *   └────────┴──────────────────────────┴──────────┘
  *
- * Fixed-width rails flank a fluid canvas column, all under an optional topbar.
- * Hairlines between regions are composed from the DS `Divider` (vertical
- * between rails/canvas, horizontal under the topbar and rail/canvas headers).
- * Headers render only when their slot is filled, so an unused header
- * contributes no border or gap (the source's `:empty` collapse, expressed as a
- * conditional render instead of a CSS rule).
+ * Rails flank a fluid canvas column, all under an optional topbar. Hairlines
+ * between regions are composed from the DS `Divider`. Headers and footers
+ * render only when their slot is filled, so an unused one contributes no
+ * border or gap (the source's `:empty` collapse, expressed as a conditional
+ * render instead of a CSS rule).
  *
- * Ported from the brand editor with the app couplings dropped (per lobby
+ * Ported from kol-fxr's editor with the app couplings dropped (per lobby
  * spec): the panel-registry + `panelsForSlot`/`SLOTS` indirection is replaced
- * by plain ReactNode slots (`left` / `right` / `children` + optional headers,
- * topbar, overlays); the `MenuTop` / `ShortcutsOverlay` imports become the
- * `topbar` / `overlays` slots; the editor stylesheet import is gone (layout is
- * Tailwind + composed Divider); the `#0E0E11` dark canvas is a `canvasBg` prop.
- * `data-editor-keep-selection` stays as an opt-in click-away hook, not baked
- * behavior.
+ * by plain ReactNode slots; the `MenuTop` / `ShortcutsOverlay` imports become
+ * the `topbar` / `overlays` slots; the editor stylesheet import is gone; the
+ * `#0E0E11` dark canvas is a `canvasBg` prop. `data-editor-keep-selection`
+ * stays as an opt-in click-away hook, not baked behavior.
+ *
+ * THREE GAPS CLOSED 2026-09-03 (`editor-set-is-behind-its-source`, kol-fxr,
+ * which adopted this and reverted):
+ *
+ * 1. **The rails are CSS-width now.** `railWidth` was a px number written
+ *    straight onto the element, so a consumer stylesheet had nothing to target
+ *    and the rail could not follow a breakpoint. Each rail's width now reads
+ *    `var(--kol-editor-{side}-w, {railWidth}px)`, so the prop is the default
+ *    and CSS — a media query, a consumer's own rule, a drag — wins over it.
+ * 2. **`resizable` gives both rails the estate's grab gesture** through
+ *    `useDragResize`, the same hook `SideNav` and kol-shell's `NavRail` wear
+ *    (that hook moved from kol-framework to kol-component in this same pass —
+ *    a component-tier shell cannot import framework, ARCHITECTURE §3). Each
+ *    rail owns its own token, so the two never drag together.
+ * 3. **The `.kol-editor-*` class hooks are emitted**, which is what a
+ *    consumer's stylesheet targets (fxr's `kol-labs.css` styles this frame by
+ *    name). They are HOOKS, not styling: the layout stays here in Tailwind, so
+ *    a consumer without those rules renders identically.
+ *
+ * Footer slots (`leftFooter`, `rightFooter`, `canvasFooter`) also came back —
+ * the source fills all three and the port had none.
  *
  * @param {ReactNode} topbar       top bar spanning the full width (optional)
  * @param {ReactNode} leftHeader   left rail header (optional; renders a hairline when set)
  * @param {ReactNode} left         left rail body (scrolls independently)
+ * @param {ReactNode} leftFooter   left rail footer, pinned under the scrolling body (optional)
  * @param {ReactNode} canvasHeader sub-bar spanning only the canvas column, e.g. a tool palette (optional)
  * @param {ReactNode} children     the canvas region (fills the fluid column)
+ * @param {ReactNode} canvasFooter bar under the canvas, e.g. a timeline or a status line (optional)
  * @param {ReactNode} rightHeader  right rail header (optional)
  * @param {ReactNode} right        right rail body (scrolls independently)
+ * @param {ReactNode} rightFooter  right rail footer (optional)
  * @param {ReactNode} overlays     floating overlays rendered above the frame (optional)
- * @param {number}    railWidth    rail column width in px (default 320)
+ * @param {number}    railWidth    DEFAULT rail width in px (default 320) — the fallback in `var(--kol-editor-{side}-w, …)`, so CSS and a drag both outrank it
+ * @param {boolean}   resizable    give both rails the drag-resize grab edge (default false)
  * @param {string}    canvasBg     canvas column background (default var(--kol-surface-primary))
  * @param {string|number} height   shell height (default '100dvh'; pass a bounded value to embed)
  * @param {string}    className    extra classes merged onto the shell root
@@ -42,12 +67,16 @@ export default function EditorShell({
   topbar,
   leftHeader,
   left,
+  leftFooter,
   canvasHeader,
   children,
+  canvasFooter,
   rightHeader,
   right,
+  rightFooter,
   overlays,
   railWidth = 320,
+  resizable = false,
   canvasBg = 'var(--kol-surface-primary)',
   height = '100dvh',
   className = '',
@@ -55,7 +84,7 @@ export default function EditorShell({
   return (
     <div
       data-editor-keep-selection
-      className={`flex flex-col overflow-hidden bg-surface-primary ${className}`.trim()}
+      className={`kol-editor-shell flex flex-col overflow-hidden bg-surface-primary ${className}`.trim()}
       style={{ height }}
     >
       {topbar && (
@@ -65,27 +94,37 @@ export default function EditorShell({
         </>
       )}
 
-      <div className="flex flex-1 min-h-0">
-        <Rail header={leftHeader} width={railWidth}>{left}</Rail>
+      <div className="kol-editor-grid flex flex-1 min-h-0">
+        <Rail side="left" header={leftHeader} footer={leftFooter} width={railWidth} resizable={resizable}>
+          {left}
+        </Rail>
         <Divider variant="vertical" />
 
-        <div className="flex flex-col flex-1 min-w-0 min-h-0">
+        <div className="kol-editor-canvas-column flex flex-col flex-1 min-w-0 min-h-0">
           {canvasHeader && (
             <>
-              <div className="shrink-0">{canvasHeader}</div>
+              <div className="kol-editor-canvas-header shrink-0">{canvasHeader}</div>
               <Divider />
             </>
           )}
           <main
-            className="flex-1 min-h-0 select-none"
+            className="kol-editor-canvas flex-1 min-h-0 select-none"
             style={{ background: canvasBg }}
           >
             {children}
           </main>
+          {canvasFooter && (
+            <>
+              <Divider />
+              <div className="kol-editor-canvas-footer shrink-0">{canvasFooter}</div>
+            </>
+          )}
         </div>
 
         <Divider variant="vertical" />
-        <Rail header={rightHeader} width={railWidth}>{right}</Rail>
+        <Rail side="right" header={rightHeader} footer={rightFooter} width={railWidth} resizable={resizable}>
+          {right}
+        </Rail>
       </div>
 
       {overlays}
@@ -93,19 +132,50 @@ export default function EditorShell({
   )
 }
 
-/* Rail — fixed-width aside with an optional header (+ hairline) over a
- * scrolling body. `min-h-0` lets the body's overflow scroll instead of
- * stretching the whole shell. */
-function Rail({ header, width, children }) {
+/* Rail — an aside with an optional header (+ hairline) over a scrolling body,
+ * and an optional footer pinned under it. `min-h-0` lets the body's overflow
+ * scroll instead of stretching the whole shell.
+ *
+ * The width is a CSS custom property with the prop as its fallback, so the
+ * cascade can move it; `useDragResize` writes that same property while
+ * dragging. Each side carries its own token — `kol-editor-left` /
+ * `kol-editor-right` — because two rails sharing one `:root` variable drag
+ * together, which is the bug the hook's own docs record. */
+function Rail({ side, header, footer, width, resizable, children }) {
+  /* The hook measures the rail it resizes (`ref.current.getBoundingClientRect`
+   * seeds the drag), so this is the element ref, not the handle's — the handle
+   * gets its own from `grabProps`. */
+  const railRef = useRef(null)
+  const { grabProps } = useDragResize(railRef, {
+    token: `kol-editor-${side}`,
+    /* which EDGE the handle sits on: a left rail's handle faces the canvas on
+     * its right, so rightward drag widens; a right rail inverts both. */
+    side,
+  })
+
   return (
-    <aside className="flex flex-col min-h-0 shrink-0" style={{ width }}>
+    <aside
+      ref={railRef}
+      className={`kol-editor-${side} relative flex flex-col min-h-0 shrink-0`}
+      style={{ width: `var(--kol-editor-${side}-w, ${typeof width === 'number' ? `${width}px` : width})` }}
+    >
       {header && (
         <>
-          <div className="shrink-0">{header}</div>
+          <div className="kol-editor-rail-header shrink-0">{header}</div>
+          <Divider />
+        </>
+      )}
+      <div className="kol-editor-rail-body flex-1 min-h-0 overflow-y-auto">{children}</div>
+      {footer && (
+        <>
           <Divider />
+          <div className="kol-editor-rail-footer shrink-0">{footer}</div>
         </>
       )}
-      <div className="flex-1 min-h-0 overflow-y-auto">{children}</div>
+      {/* `.kol-rail-grab` is the drawing (kol-animation.css); the hook supplies
+          the proximity wake and the travel. Rendered only when asked, so a
+          static shell has no extra hit area over its rail edge. */}
+      {resizable && <div {...grabProps} className={`kol-rail-grab kol-rail-grab--${side}`} />}
     </aside>
   )
 }