@kolkrabbi/kol-component 0.184.0 → 0.186.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.184.0",
+  "version": "0.186.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/atoms/SelectionOverlay.jsx

@@ -1,3 +1,6 @@
+import { useContext } from 'react'
+import { CanvasZoomContext } from '../hooks/canvasZoom.js'
+
 /* taxonomy-ok: presentational transform-chrome overlay. It nests no KOL
  * component (pure inline-styled squares + label), so by the letter of the
  * molecule test it reads as an atom — but the lobby spec places it as a
@@ -7,23 +10,40 @@
 /**
  * SelectionOverlay — pure transform chrome for a selected box.
  *
- * Renders a dashed outline, 8 named resize handles, and a `W × H` dimension
- * label, all positioned in the **same 1080-virtual coordinate space** the
- * target lives in (pairs with Canvas's scale layer — place it as a sibling of
- * the box inside the same scale layer). Each handle carries a
- * `data-handle="NW|N|NE|E|SE|S|SW|W"` attribute so a parent's pointer router
- * can start the right resize mode. No interaction logic of its own — the drag
- * math lives in the consumer, which reads `e.target.dataset.handle`.
+ * Renders a dashed outline, 8 named resize handles, a rotate handle and a
+ * `W × H` dimension label, all positioned in the **same 1080-virtual
+ * coordinate space** the target lives in (pairs with Canvas's scale layer —
+ * place it as a sibling of the box inside the same scale layer). Each handle
+ * carries a `data-handle="NW|N|NE|E|SE|S|SW|W|ROT"` attribute so a parent's
+ * pointer router can start the right drag mode. No interaction logic of its
+ * own — the drag math lives in the consumer, which reads
+ * `e.target.dataset.handle`.
  *
- * Ported from the brand editor with the `layer` model reduced to a flat `box`
+ * Ported from kol-fxr's editor with the `layer` model reduced to a flat `box`
  * (per lobby spec): renders nothing when there's no positional box.
  *
- * @param {{x:number,y:number,w:number,h:number}} box  virtual-coord position + size; null/x==null → renders nothing
+ * ZOOM COMPENSATION IS THE POINT (restored 2026-09-03,
+ * `editor-set-is-behind-its-source`). The chrome renders in virtual px INSIDE
+ * the canvas's zoomed transform, so every screen-constant dimension — handle
+ * size, outline width, the rotate handle's offset, the label — divides by the
+ * live zoom from `CanvasZoomContext`. The first port hardcoded `1px` / `10px`
+ * / `marginTop: 6`, so at 3× the handles drew 30px and the label ballooned;
+ * kol-fxr measured it and reverted the adoption. Outside a `PanZoomViewport`
+ * the context is 1 and every division is a no-op, so a static canvas is
+ * unaffected.
+ *
+ * The label also counter-SCALES rather than just re-sizing: `scale(1/zoom)`
+ * with a top-left origin keeps its padding, radius and letter-spacing
+ * screen-constant too, which a font-size alone does not.
+ *
+ * @param {{x:number,y:number,w:number,h:number,rotation?:number}} box  virtual-coord position + size; null/x==null → renders nothing. `rotation` in degrees turns the chrome with the box about its centre
  * @param {boolean}  showHandles  render the 8 resize handles (default true)
+ * @param {boolean}  showRotate   render the rotate handle (default: follows `showHandles`) — independent because a path hides the resize handles, node-edit owning their geometry, and still rotates
  * @param {boolean}  showLabel    render the `W × H` dimension label (default true)
- * @param {number}   handleSize   handle square size in virtual px (default 10)
+ * @param {number}   handleSize   handle square size in virtual px BEFORE zoom compensation (default 10)
  * @param {string}   accentColor  outline + handle + label color (default var(--kol-accent-primary))
  * @param {Function} labelFormatter (box) => string — dimension readout (default `${round(w)} × ${round(h)}`)
+ * @param {string}   rotateTitle  tooltip on the rotate handle (default 'Rotate')
  */
 const HANDLE_DIRS = [
   { dir: 'NW', cursor: 'nwse-resize', x: 0,    y: 0    },
@@ -36,17 +56,35 @@ const HANDLE_DIRS = [
   { dir: 'W',  cursor: 'ew-resize',   x: 0,    y: 0.5  },
 ]
 
+/* The rotate handle's float above the top edge, in virtual px before zoom
+ * compensation — fxr's number. */
+const ROTATE_OFFSET = 22
+
 export default function SelectionOverlay({
   box,
   showHandles = true,
+  showRotate,
   showLabel = true,
   handleSize = 10,
   accentColor = 'var(--kol-accent-primary)',
   labelFormatter = (b) => `${Math.round(b.w)} × ${Math.round(b.h)}`,
+  rotateTitle = 'Rotate',
 }) {
+  /* Chrome renders in virtual px inside the zoomed transform — divide by zoom
+   * so handles / outline / label stay screen-constant at any zoom. 1 outside a
+   * PanZoomViewport, which makes every division below a no-op. */
+  const zoom = useContext(CanvasZoomContext)
+
   if (!box || box.x == null) return null  /* no positional box → no chrome */
 
   const { x, y, w, h } = box
+  const size = handleSize / zoom
+  const hairline = 1 / zoom
+  const rotate = showRotate ?? showHandles
+  /* `rotation` may arrive as a BINDING OBJECT on an animated prop; chrome uses
+   * the base 0 rather than throwing on `${{…}}deg` — editing chrome over
+   * animated transforms is a consumer-side v1 limitation, and fxr's guard. */
+  const rot = typeof box.rotation === 'number' ? box.rotation : 0
 
   return (
     <div
@@ -54,6 +92,9 @@ export default function SelectionOverlay({
         position: 'absolute',
         left: x, top: y,
         width: w, height: h,
+        /* the chrome rotates WITH the box (centre origin) so the wireframe and
+         * the handles hug the actually-rendered box, not its unrotated slot */
+        transform: rot ? `rotate(${rot}deg)` : undefined,
         pointerEvents: 'none',
         zIndex: 100,
       }}
@@ -61,22 +102,43 @@ export default function SelectionOverlay({
       <div
         style={{
           position: 'absolute', inset: 0,
-          outline: `1px dashed ${accentColor}`,
+          outline: `${hairline}px dashed ${accentColor}`,
           outlineOffset: 0,
         }}
       />
+      {/* rotate handle — a circle floating above the top edge; a drag rotates
+        * the box about its centre. Independent of the resize handles: a path
+        * hides those (node-edit owns their geometry) and still rotates. */}
+      {rotate && (
+        <div
+          data-handle="ROT"
+          title={rotateTitle}
+          style={{
+            position: 'absolute',
+            left: `calc(50% - ${size / 2}px)`,
+            top: -(ROTATE_OFFSET / zoom),
+            width: size,
+            height: size,
+            borderRadius: '50%',
+            background: 'white',
+            border: `${hairline}px solid ${accentColor}`,
+            cursor: 'grab',
+            pointerEvents: 'auto',
+          }}
+        />
+      )}
       {showHandles && HANDLE_DIRS.map(({ dir, cursor, x: hx, y: hy }) => (
         <div
           key={dir}
           data-handle={dir}
           style={{
             position: 'absolute',
-            left:   `calc(${hx * 100}% - ${handleSize / 2}px)`,
-            top:    `calc(${hy * 100}% - ${handleSize / 2}px)`,
-            width:  handleSize,
-            height: handleSize,
+            left:   `calc(${hx * 100}% - ${size / 2}px)`,
+            top:    `calc(${hy * 100}% - ${size / 2}px)`,
+            width:  size,
+            height: size,
             background: 'white',
-            border: `1px solid ${accentColor}`,
+            border: `${hairline}px solid ${accentColor}`,
             cursor,
             pointerEvents: 'auto',
           }}
@@ -88,7 +150,11 @@ export default function SelectionOverlay({
             position: 'absolute',
             left: 0,
             top: '100%',
-            marginTop: 6,
+            marginTop: 6 / zoom,
+            /* counter-scale, not just a smaller font: padding, radius and
+             * tracking have to stay screen-constant too */
+            transform: `scale(${1 / zoom})`,
+            transformOrigin: 'top left',
             fontFamily: 'var(--kol-font-family-mono)',
             fontSize: 10,
             letterSpacing: '0.04em',

package/src/hooks/canvasZoom.js

@@ -0,0 +1,19 @@
+import { createContext } from 'react'
+
+/**
+ * CanvasZoomContext — the canvas viewport's live zoom factor.
+ *
+ * Lives in `src/hooks` rather than beside `Canvas` because BOTH tiers need it:
+ * the organism publishes it (`PanZoomViewport`) and the atoms consume it
+ * (`SelectionOverlay` divides every screen-constant dimension by it). An atom
+ * importing `../organisms/Canvas.jsx` is an upward import and the taxonomy
+ * gate is right to refuse it — so the shared value moves down to the tier
+ * neither side owns, the same reason `glyphLadders.js` sits here.
+ *
+ * Defaults to 1, so a consumer reads it unconditionally and a canvas without a
+ * pan-zoom viewport turns every `/ zoom` into a no-op.
+ *
+ * `@kolkrabbi/kol-component` exports it from the barrel as `CanvasZoomContext`,
+ * and `Canvas.jsx` re-exports it under the same name it always had.
+ */
+export const CanvasZoomContext = createContext(1)

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

@@ -111,7 +111,11 @@ export { default as TabsRow } from './molecules/TabsRow.jsx'
 /* monorepo sets (P6–P10) — organism members. Foundry members live in the
    standalone @kolkrabbi/kol-foundry package (with the type-specimen kit +
    live-font effects moved there 2026-07-09) — never re-exported here. */
-export { default as Canvas, CanvasFrame, PanViewport, CANVAS_VIRTUAL_W, DEFAULT_ASPECTS, CANVAS_DEFAULTS } from './organisms/Canvas.jsx'
+/* `CanvasZoomContext` and `PanZoomViewport` are the load-bearing pair for an
+ * editor: the viewport publishes the zoom, every piece of editing chrome reads
+ * it. Absent from this barrel until 0.185.0, which is why the first port of
+ * this set could not keep its chrome screen-constant. */
+export { default as Canvas, CanvasFrame, PanViewport, PanZoomViewport, CanvasZoomContext, useFps, CANVAS_VIRTUAL_W, DEFAULT_ASPECTS, CANVAS_DEFAULTS } from './organisms/Canvas.jsx'
 export { default as EditorShell } from './utilities/EditorShell.jsx'
 export { default as GalleryCarousel } from './organisms/GalleryCarousel.jsx'
 export { default as AsciiCursor } from './utilities/AsciiCursor.jsx'
@@ -189,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/organisms/Canvas.jsx

@@ -1,4 +1,5 @@
-import { createContext, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { useCallback, useContext, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { CanvasZoomContext } from '../hooks/canvasZoom.js'
 
 /**
  * Canvas — the editor's aspect-ratio stage.
@@ -31,11 +32,13 @@ import { createContext, useCallback, useEffect, useLayoutEffect, useRef, useStat
  * pan-only viewport is not this component, it is a third of it.
  */
 
-/* Current viewport zoom factor — consumed by editing chrome (selection
- * handles, path nodes) to render at a screen-constant size by dividing their
- * virtual-px dimensions by the zoom. Defaults to 1 for canvases without a
- * PanZoomViewport, so a consumer can read it unconditionally. */
-export const CanvasZoomContext = createContext(1)
+/* The viewport's live zoom factor — editing chrome divides its virtual-px
+ * dimensions by it to stay screen-constant. Defined in `hooks/canvasZoom.js`
+ * because the atoms consume it and an atom may not import an organism (the
+ * taxonomy gate, correctly); re-exported here under the name it has always
+ * had, so `import { CanvasZoomContext } from '@kolkrabbi/kol-component'` and
+ * every existing deep import keep working. */
+export { CanvasZoomContext }
 
 /* Fixed virtual canvas width — children render in this pixel space and the
  * outer rect scales to fit the viewport via CSS transform. Height is derived

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>
   )
 }