@kolkrabbi/kol-component 0.195.0 → 0.197.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.195.0",
+  "version": "0.197.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/CropOverlay.jsx

@@ -0,0 +1,211 @@
+import { useContext, useEffect, useState } from 'react'
+import { CanvasZoomContext } from '../hooks/canvasZoom.js'
+
+/**
+ * CropOverlay — crop-mode chrome for a photo layer with an explicit crop
+ * window ({imgX,imgY,imgW,imgH} — the image's draw rect in frame-local px).
+ *
+ *   • drag inside the frame  → pan the image within the frame (clamped)
+ *   • drag a frame handle    → crop: the frame moves/resizes while the
+ *                              image stays FIXED in world space
+ *   • Escape / Enter         → exit crop mode
+ *
+ * The ghost <img> shows the image's full extent at low opacity so the user
+ * can see what they're cropping away. Chrome divides by zoom to stay
+ * screen-constant.
+ *
+ * `SelectionOverlay`'s other sibling, same contract, same zoom division.
+ * Lifted verbatim from kol-fxr (`compose/CropOverlay.jsx`,
+ * `editor-panels-the-held-specs` B2, 2026-09-03), already prop-driven, and it
+ * keeps its transaction-bracketed write path for the reason given on
+ * `PathNodeOverlay`.
+ *
+ * @param {Object} layer - The photo layer: `{ id, x, y, w, h, rotation?, src, imgX, imgY, imgW, imgH }` — the crop window is the image's draw rect in frame-local px
+ * @param {Function} toVirtual - `(clientX, clientY) => { vx, vy }`
+ * @param {Function} updateLayer - `(id, patch) => void` — the live write
+ * @param {Function} beginTransaction - Pointer down: open one undo entry
+ * @param {Function} commitTransaction - Pointer up: close it
+ * @param {Function} onExit - Escape / Enter — leave crop mode
+ */
+
+const HANDLE = 10  /* virtual px */
+
+const DIRS = [
+  { dir: 'NW', cursor: 'nwse-resize', hx: 0,   hy: 0   },
+  { dir: 'N',  cursor: 'ns-resize',   hx: 0.5, hy: 0   },
+  { dir: 'NE', cursor: 'nesw-resize', hx: 1,   hy: 0   },
+  { dir: 'E',  cursor: 'ew-resize',   hx: 1,   hy: 0.5 },
+  { dir: 'SE', cursor: 'nwse-resize', hx: 1,   hy: 1   },
+  { dir: 'S',  cursor: 'ns-resize',   hx: 0.5, hy: 1   },
+  { dir: 'SW', cursor: 'nesw-resize', hx: 0,   hy: 1   },
+  { dir: 'W',  cursor: 'ew-resize',   hx: 0,   hy: 0.5 },
+]
+
+/* Clamp an image offset so the image covers the frame span where it can
+ * (imgSpan ≥ span) or stays inside it where it can't (contain-fit init). */
+function clampOffset(v, span, imgSpan) {
+  const lo = Math.min(0, span - imgSpan)
+  const hi = Math.max(0, span - imgSpan)
+  return Math.min(hi, Math.max(lo, v))
+}
+
+export default function CropOverlay({
+  layer, toVirtual, updateLayer, beginTransaction, commitTransaction, onExit,
+}) {
+  const zoom = useContext(CanvasZoomContext)
+  const hs   = HANDLE / zoom
+  const [drag, setDrag] = useState(null) /* { kind: 'pan'|dir, startVX, startVY, start } */
+
+  useEffect(() => {
+    if (!drag) return
+    const onMove = (e) => {
+      const { vx, vy } = toVirtual(e.clientX, e.clientY)
+      let dvx = vx - drag.startVX
+      let dvy = vy - drag.startVY
+      const st = drag.start
+
+      if (drag.kind === 'pan') {
+        /* Pointer delta into the layer's local frame when rotated. */
+        const rot = (st.rotation * Math.PI) / 180
+        if (rot) {
+          const c = Math.cos(rot)
+          const s = Math.sin(rot)
+          const lx = dvx * c + dvy * s
+          const ly = -dvx * s + dvy * c
+          dvx = lx; dvy = ly
+        }
+        updateLayer(layer.id, {
+          imgX: clampOffset(st.imgX + dvx, st.w, st.imgW),
+          imgY: clampOffset(st.imgY + dvy, st.h, st.imgH),
+        })
+        return
+      }
+
+      /* Crop handle — frame changes, image world-position fixed. Only
+       * offered on unrotated photos (handles hidden otherwise). */
+      const IL = st.x + st.imgX  /* image world left/top */
+      const IT = st.y + st.imgY
+      let x = st.x, y = st.y, w = st.w, h = st.h
+      if (drag.kind.includes('W')) {
+        x = Math.min(Math.max(st.x + dvx, IL), st.x + st.w - 8)
+        w = st.x + st.w - x
+      }
+      if (drag.kind.includes('E')) {
+        const r = Math.max(Math.min(st.x + st.w + dvx, IL + st.imgW), st.x + 8)
+        w = r - st.x
+      }
+      if (drag.kind.includes('N')) {
+        y = Math.min(Math.max(st.y + dvy, IT), st.y + st.h - 8)
+        h = st.y + st.h - y
+      }
+      if (drag.kind.includes('S')) {
+        const b = Math.max(Math.min(st.y + st.h + dvy, IT + st.imgH), st.y + 8)
+        h = b - st.y
+      }
+      updateLayer(layer.id, { x, y, w, h, imgX: IL - x, imgY: IT - y })
+    }
+    const onUp = () => {
+      /* No unconditional write here — commit's reference-diff makes a
+       * click-without-move a history no-op. */
+      commitTransaction()
+      setDrag(null)
+    }
+    window.addEventListener('mousemove', onMove)
+    window.addEventListener('mouseup', onUp)
+    return () => {
+      window.removeEventListener('mousemove', onMove)
+      window.removeEventListener('mouseup', onUp)
+    }
+  }, [drag, layer.id, toVirtual, updateLayer, commitTransaction])
+
+  /* Escape / Enter exit crop mode. Capture phase beats the compose-level
+   * deselect / delete handlers. */
+  useEffect(() => {
+    const onKey = (e) => {
+      if (e.key === 'Escape' || e.key === 'Enter') {
+        e.preventDefault(); e.stopPropagation()
+        onExit()
+      }
+    }
+    window.addEventListener('keydown', onKey, true)
+    return () => window.removeEventListener('keydown', onKey, true)
+  }, [onExit])
+
+  const startDrag = (kind) => (e) => {
+    if (e.button !== 0) return
+    /* Stop the stage router from reading this as an empty-stage marquee
+     * (which would deselect and pop crop mode). */
+    e.preventDefault(); e.stopPropagation()
+    const { vx, vy } = toVirtual(e.clientX, e.clientY)
+    beginTransaction()
+    setDrag({
+      kind, startVX: vx, startVY: vy,
+      start: {
+        x: layer.x, y: layer.y, w: layer.w, h: layer.h,
+        imgX: layer.imgX, imgY: layer.imgY, imgW: layer.imgW, imgH: layer.imgH,
+        rotation: layer.rotation ?? 0,
+      },
+    })
+  }
+
+  const rot    = layer.rotation ?? 0
+  const accent = 'var(--kol-accent-primary)'
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        left: layer.x, top: layer.y,
+        width: layer.w, height: layer.h,
+        transform: rot ? `rotate(${rot}deg)` : undefined,
+        pointerEvents: 'none',
+        zIndex: 110,
+      }}
+    >
+      {/* full-extent ghost — what lies outside the crop. Video sources use a
+          muted <video> (an <img src=blob:video> renders blank). */}
+      {(() => {
+        const ghostStyle = {
+          position: 'absolute',
+          left: layer.imgX, top: layer.imgY,
+          width: layer.imgW, height: layer.imgH,
+          maxWidth: 'none',
+          opacity: 0.35,
+          pointerEvents: 'none',
+        }
+        return layer.srcType === 'video'
+          ? <video src={layer.src} muted playsInline draggable={false} style={ghostStyle} />
+          : <img src={layer.src} alt="" draggable={false} style={ghostStyle} />
+      })()}
+      {/* frame outline + pan surface */}
+      <div
+        onMouseDown={startDrag('pan')}
+        style={{
+          position: 'absolute', inset: 0,
+          outline: `${1 / zoom}px solid ${accent}`,
+          cursor: drag?.kind === 'pan' ? 'grabbing' : 'grab',
+          pointerEvents: 'auto',
+        }}
+      />
+      {/* crop handles — hidden on rotated photos.
+        * ponytail: pan-only when rotated; add rotation-aware crop resize
+        * (world-anchor math like CanvasArea's rotated resize) if needed. */}
+      {rot === 0 && DIRS.map(({ dir, cursor, hx, hy }) => (
+        <div
+          key={dir}
+          onMouseDown={startDrag(dir)}
+          style={{
+            position: 'absolute',
+            left: `calc(${hx * 100}% - ${hs / 2}px)`,
+            top:  `calc(${hy * 100}% - ${hs / 2}px)`,
+            width: hs, height: hs,
+            background: 'white',
+            border: `${1 / zoom}px solid ${accent}`,
+            cursor,
+            pointerEvents: 'auto',
+          }}
+        />
+      ))}
+    </div>
+  )
+}

package/src/atoms/Input.jsx

@@ -20,6 +20,12 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  *                                scope expression, not every keystroke. With it
  *                                the field keeps a local draft seeded from
  *                                `value`; `onChange` still fires live if given.
+ *                                After the commit the draft RE-SNAPS to `value`,
+ *                                so a rejected commit falls back to the last
+ *                                good value rather than lingering — which makes
+ *                                `type="number"` + `onCommit` the draft/commit
+ *                                number idiom outright (parse and clamp at the
+ *                                call site; fxr's NumberField, retired 2026-09-03).
  *   variant="ghost"            — legacy alias, resolves to outline
  *   variant="property"         — the Figma property field (PropertyField,
  *                                2026-08-12): filled chrome, dim `affordance`
@@ -123,7 +129,17 @@ export default function Input({
     ? {
         value: draft,
         onChange: (e) => { draftRef.current = e.target.value; setDraft(e.target.value); onChange?.(e) },
-        onBlur: () => onCommit(String(draftRef.current).trim()),
+        /* RE-SNAP AFTER EVERY COMMIT, not only when `value` changes. The
+         * effect above re-syncs the draft on a value change — so a commit the
+         * caller REJECTED (invalid input, value kept) left the bad draft on
+         * screen, and `1` → `19` → `19x` showed `19x` after blur. kol-fxr's
+         * `NumberField` existed for exactly this line (34 lines wrapping this
+         * atom: commit, then `setDraft(String(value))`); with the re-snap here
+         * it is `<Input type="number" onCommit>` and no component
+         * (editor-panels-the-held-specs A8, 2026-09-03). The order matters —
+         * commit first, so a caller that DOES accept the value re-renders
+         * with the new prop and the effect wins over this fallback. */
+        onBlur: () => { onCommit(String(draftRef.current).trim()); draftRef.current = value ?? ''; setDraft(value ?? '') },
         onKeyDown: (e) => {
           if (e.key === 'Enter') e.currentTarget.blur()
           if (e.key === 'Escape') { draftRef.current = value ?? ''; setDraft(value ?? ''); e.currentTarget.blur() }

package/src/atoms/PathNodeOverlay.jsx

@@ -0,0 +1,294 @@
+import { useContext, useEffect, useRef, useState } from 'react'
+import { CanvasZoomContext } from '../hooks/canvasZoom.js'
+import { normalizePathRings, pathD, nearestSegmentT, splitSegment, smoothNode } from '../hooks/pathMath.js'
+
+/**
+ * PathNodeOverlay — node/bezier editing chrome for a selected `path` layer.
+ *
+ * Draws each anchor (square) and its in/out bezier handles (round knobs on a
+ * thin leash) in the 1080-virtual coord space, over the stage. Interaction:
+ *
+ *   • drag anchor  → moves the node + both handles together
+ *   • drag handle  → adjusts that handle; the opposite handle mirrors it
+ *                    (smooth) unless Alt is held (independent / break tangent)
+ *   • click anchor → selects it; Delete/Backspace removes it (min 2 kept)
+ *   • click FIRST anchor of an open path → closes it (the pen-tool gesture)
+ *   • dbl-click anchor  → corner ↔ smooth toggle
+ *   • dbl-click segment → insert an anchor at that curve point (split)
+ *   • Escape       → exit node-edit mode
+ *
+ * Nodes are layer-local; on drag-commit we renormalize so the anchor bbox
+ * re-origins to (0,0) and the layer's {x,y,w,h} stay in sync. Live drag
+ * skips renormalization to avoid origin jitter under the cursor.
+ *
+ * `SelectionOverlay`'s sibling on the same 1080-virtual contract and the same
+ * zoom division. Lifted verbatim from kol-fxr (`compose/PathNodeOverlay.jsx`,
+ * `editor-panels-the-held-specs` B2, 2026-09-03). It was ALREADY prop-driven —
+ * no store hook — and the contract it had is the one it keeps: live writes go
+ * through `updateLayer`, bracketed by `beginTransaction` / `commitTransaction`
+ * so a drag is ONE undo entry. The ticket suggested `value` + `onChange`; that
+ * would have lost the transaction bracket, and the bracket is the part a
+ * consumer cannot reconstruct from a stream of values.
+ *
+ * @param {Object} layer - The path layer: `{ id, x, y, w, h, nodes, holes?, closed? }` in virtual px, nodes layer-local
+ * @param {number} viewW - The stage's virtual width (the SVG viewBox)
+ * @param {number} viewH - The stage's virtual height
+ * @param {Function} toVirtual - `(clientX, clientY) => { vx, vy }` — the consumer's screen→virtual mapping
+ * @param {Function} updateLayer - `(id, patch) => void` — the live write, called on every move
+ * @param {Function} beginTransaction - Called on pointer down; the consumer opens one undo entry
+ * @param {Function} commitTransaction - Called on pointer up; the consumer closes it (a no-move drag still brackets)
+ * @param {Function} onExit - Escape — leave node-edit mode
+ */
+
+const ANCHOR = 10  /* virtual px */
+const KNOB   = 5    /* virtual px radius */
+
+export default function PathNodeOverlay({
+  layer, viewW, viewH, toVirtual,
+  updateLayer, beginTransaction, commitTransaction, onExit,
+}) {
+  const [selNode, setSelNode] = useState(null)
+  const [drag, setDrag]       = useState(null) /* { type:'anchor'|'in'|'out', index } */
+  const movedRef              = useRef(false)  /* did this drag actually move? */
+
+  /* Chrome renders in virtual px inside the zoomed transform — divide by
+   * zoom so anchors/knobs stay screen-constant instead of vanishing at 25%
+   * and ballooning at 400%. */
+  const zoom   = useContext(CanvasZoomContext)
+  const anchor = ANCHOR / zoom
+  const knob   = KNOB / zoom
+
+  /* Latest layer geometry for the window drag listeners (which close over a
+   * render snapshot otherwise). */
+  const nodesRef = useRef(layer.nodes)
+  const holesRef = useRef(layer.holes)
+  const posRef   = useRef({ x: layer.x, y: layer.y })
+  nodesRef.current = layer.nodes
+  holesRef.current = layer.holes
+  posRef.current   = { x: layer.x, y: layer.y }
+
+  const nodes = layer.nodes ?? []
+
+  useEffect(() => {
+    if (!drag) return
+    const onMove = (e) => {
+      movedRef.current = true
+      const { vx, vy } = toVirtual(e.clientX, e.clientY)
+      const lx = vx - posRef.current.x
+      const ly = vy - posRef.current.y
+      const cur = nodesRef.current
+      const next = cur.map((n, i) => {
+        if (i !== drag.index) return n
+        if (drag.type === 'anchor') {
+          const dx = lx - n.x
+          const dy = ly - n.y
+          return {
+            x: lx, y: ly,
+            in:  n.in  ? { x: n.in.x  + dx, y: n.in.y  + dy } : null,
+            out: n.out ? { x: n.out.x + dx, y: n.out.y + dy } : null,
+          }
+        }
+        /* extract — pull symmetric handles out of a corner anchor (the anchor
+         * itself stays put). Gives endpoints / corners bezier handles. */
+        if (drag.type === 'extract') {
+          return { ...n, out: { x: lx, y: ly }, in: { x: 2 * n.x - lx, y: 2 * n.y - ly } }
+        }
+        /* handle drag — set the dragged side; mirror the other around the
+         * anchor unless Alt breaks the tangent. */
+        const mirror = { x: 2 * n.x - lx, y: 2 * n.y - ly }
+        if (drag.type === 'out') {
+          return { ...n, out: { x: lx, y: ly }, in: e.altKey ? n.in : mirror }
+        }
+        return { ...n, in: { x: lx, y: ly }, out: e.altKey ? n.out : mirror }
+      })
+      updateLayer(layer.id, { nodes: next })
+    }
+    const onUp = () => {
+      /* Only renormalize if the drag actually moved — a bare click (select)
+       * must not write, or the commit's reference-diff sees a "change" and
+       * pushes a junk undo entry. */
+      if (movedRef.current) {
+        const norm = normalizePathRings(nodesRef.current, holesRef.current)
+        updateLayer(layer.id, {
+          nodes: norm.nodes, holes: norm.holes,
+          x: posRef.current.x + norm.dx,
+          y: posRef.current.y + norm.dy,
+          w: norm.w, h: norm.h,
+        })
+      } else if (drag.type === 'anchor' && drag.index === 0 && !layer.closed && nodesRef.current.length >= 2) {
+        /* Plain click on the FIRST anchor of an open path closes it — the
+         * same gesture that closes a draft under the pen tool (≥2 nodes,
+         * matching the pen's close threshold). A real write, so the open
+         * transaction commits it as one history entry. */
+        updateLayer(layer.id, { closed: true })
+      }
+      commitTransaction()
+      setDrag(null)
+    }
+    window.addEventListener('mousemove', onMove)
+    window.addEventListener('mouseup', onUp)
+    return () => {
+      window.removeEventListener('mousemove', onMove)
+      window.removeEventListener('mouseup', onUp)
+    }
+  }, [drag, layer.id, layer.closed, toVirtual, updateLayer, commitTransaction])
+
+  /* Delete removes the selected node; Escape exits. Capture phase so we beat
+   * the compose-level delete-layer / deselect handlers. */
+  useEffect(() => {
+    const onKey = (e) => {
+      if (e.key === 'Escape') {
+        e.preventDefault(); e.stopPropagation()
+        onExit()
+        return
+      }
+      if ((e.key === 'Delete' || e.key === 'Backspace') && selNode != null) {
+        e.preventDefault(); e.stopPropagation()
+        const cur = nodesRef.current
+        if (cur.length <= 2) return  /* keep a drawable minimum */
+        const kept = cur.filter((_, i) => i !== selNode)
+        const norm = normalizePathRings(kept, holesRef.current)
+        beginTransaction()
+        updateLayer(layer.id, {
+          nodes: norm.nodes, holes: norm.holes,
+          x: posRef.current.x + norm.dx,
+          y: posRef.current.y + norm.dy,
+          w: norm.w, h: norm.h,
+        })
+        commitTransaction()
+        setSelNode(null)
+      }
+    }
+    window.addEventListener('keydown', onKey, true)
+    return () => window.removeEventListener('keydown', onKey, true)
+  }, [selNode, layer.id, updateLayer, beginTransaction, commitTransaction, onExit])
+
+  const startDrag = (type, index) => (e) => {
+    e.preventDefault(); e.stopPropagation()
+    setSelNode(index)
+    movedRef.current = false
+    beginTransaction()
+    /* Alt-drag on an anchor extracts fresh handles instead of moving it. */
+    const t = type === 'anchor' && e.altKey ? 'extract' : type
+    setDrag({ type: t, index })
+  }
+
+  /* Renormalize + write a node-list change as ONE history entry. */
+  const commitNodes = (nextNodes) => {
+    const norm = normalizePathRings(nextNodes, holesRef.current)
+    beginTransaction()
+    updateLayer(layer.id, {
+      nodes: norm.nodes, holes: norm.holes,
+      x: posRef.current.x + norm.dx,
+      y: posRef.current.y + norm.dy,
+      w: norm.w, h: norm.h,
+    })
+    commitTransaction()
+  }
+
+  /* Double-click a segment → insert an anchor at the clicked curve point
+   * via de Casteljau split (shape-preserving: the new node takes the split
+   * handles, neighbors' handles trim to the half-curves). Straight segments
+   * insert a handle-less corner node. */
+  const onSegmentDoubleClick = (e) => {
+    e.preventDefault(); e.stopPropagation()
+    const { vx, vy } = toVirtual(e.clientX, e.clientY)
+    const lx = vx - posRef.current.x
+    const ly = vy - posRef.current.y
+    const cur = nodesRef.current
+    const segCount = cur.length - 1 + (layer.closed ? 1 : 0)
+    let best = null
+    for (let i = 0; i < segCount; i++) {
+      const hit = nearestSegmentT(cur[i], cur[(i + 1) % cur.length], lx, ly)
+      if (!best || hit.dist < best.dist) best = { index: i, ...hit }
+    }
+    if (!best) return
+    const { a, mid, b } = splitSegment(cur[best.index], cur[(best.index + 1) % cur.length], best.t)
+    const next = [...cur]
+    next[best.index] = a
+    next[(best.index + 1) % cur.length] = b
+    next.splice(best.index + 1, 0, mid)
+    commitNodes(next)
+    setSelNode(best.index + 1)
+  }
+
+  /* Double-click an anchor → corner ↔ smooth. Corner drops both handles;
+   * smooth derives mirrored handles from the neighbor chord (~1/3 of each
+   * adjacent segment — same tangent model the mirror-by-default handle drag
+   * maintains). Anchors never move, so bounds are untouched (anchor-only). */
+  const onAnchorDoubleClick = (i) => (e) => {
+    e.preventDefault(); e.stopPropagation()
+    const cur = nodesRef.current
+    const n = cur[i]
+    const toggled = (n.in || n.out)
+      ? { ...n, in: null, out: null }
+      : smoothNode(cur, i, !!layer.closed)
+    if (toggled === n) return
+    beginTransaction()
+    updateLayer(layer.id, { nodes: cur.map((m, j) => (j === i ? toggled : m)) })
+    commitTransaction()
+  }
+
+  const accent = 'var(--kol-accent-primary)'
+
+  return (
+    <svg
+      width="100%" height="100%"
+      viewBox={`0 0 ${viewW} ${viewH}`}
+      preserveAspectRatio="none"
+      style={{ position: 'absolute', inset: 0, zIndex: 120, pointerEvents: 'none' }}
+    >
+      <g transform={`translate(${layer.x} ${layer.y})`}>
+        {/* invisible fat stroke = segment hit area (~12 screen px, on par
+          * with the anchor hit size). Rendered first so anchors/knobs win
+          * overlapping hits; mousedown swallowed so the stage router doesn't
+          * treat the click as empty-stage (deselect). */}
+        <path
+          d={pathD(nodes, !!layer.closed)}
+          fill="none"
+          stroke="transparent"
+          strokeWidth={12 / zoom}
+          style={{ pointerEvents: 'stroke' }}
+          onMouseDown={(e) => { e.preventDefault(); e.stopPropagation() }}
+          onDoubleClick={onSegmentDoubleClick}
+        />
+        {/* handle leashes + knobs */}
+        {nodes.map((n, i) => (
+          <g key={`h${i}`}>
+            {n.in && (
+              <>
+                <line x1={n.x} y1={n.y} x2={n.in.x} y2={n.in.y}
+                  stroke={accent} strokeWidth={1} vectorEffect="non-scaling-stroke" opacity={0.7} />
+                <circle cx={n.in.x} cy={n.in.y} r={knob} fill="white" stroke={accent}
+                  strokeWidth={1} vectorEffect="non-scaling-stroke"
+                  style={{ pointerEvents: 'auto', cursor: 'move' }}
+                  onMouseDown={startDrag('in', i)} />
+              </>
+            )}
+            {n.out && (
+              <>
+                <line x1={n.x} y1={n.y} x2={n.out.x} y2={n.out.y}
+                  stroke={accent} strokeWidth={1} vectorEffect="non-scaling-stroke" opacity={0.7} />
+                <circle cx={n.out.x} cy={n.out.y} r={knob} fill="white" stroke={accent}
+                  strokeWidth={1} vectorEffect="non-scaling-stroke"
+                  style={{ pointerEvents: 'auto', cursor: 'move' }}
+                  onMouseDown={startDrag('out', i)} />
+              </>
+            )}
+          </g>
+        ))}
+        {/* anchors */}
+        {nodes.map((n, i) => (
+          <rect key={`a${i}`}
+            x={n.x - anchor / 2} y={n.y - anchor / 2}
+            width={anchor} height={anchor}
+            fill={i === selNode ? accent : 'white'}
+            stroke={accent} strokeWidth={1} vectorEffect="non-scaling-stroke"
+            style={{ pointerEvents: 'auto', cursor: 'move' }}
+            onMouseDown={startDrag('anchor', i)}
+            onDoubleClick={onAnchorDoubleClick(i)} />
+        ))}
+      </g>
+    </svg>
+  )
+}

package/src/atoms/XYPad.jsx

@@ -0,0 +1,92 @@
+import { useRef } from 'react'
+
+/**
+ * XYPad — a two-axis control pad: drag one puck to vary two values at once.
+ *
+ * Lifted verbatim from kol-fxr's editor (`compose/inspectors/XYPad.jsx`,
+ * `editor-panels-the-held-specs` A6, 2026-09-03 — the row the filer marked
+ * "portable as-is", and it was: presentation-only, no store coupling). Its own
+ * lineage runs back through kol-labs-single's para-type lab to Font Playground.
+ *
+ * Axis meaning, ranges and the write path belong to the caller. It fills its
+ * container's width and is square via `aspect-ratio`; the puck is positioned
+ * in %, so there is no `size` prop and a rail of any width takes it. `y` is
+ * inverted — top is high — because that is how every axis pad reads.
+ *
+ * No `useCallback` on the handlers, on purpose: the labs original memoized
+ * them with `[]` deps and froze the first render's axis ranges into the drag
+ * math, so a pad whose range changed kept mapping to the old one.
+ *
+ *   <XYPad xValue={wdth} yValue={wght} xMin={50} xMax={200} yMin={100} yMax={900}
+ *          xLabel="Width" yLabel="Weight" onChange={(x, y) => set({ wdth: x, wght: y })} />
+ *
+ * @param {number} xValue - Current x, in the x range
+ * @param {number} yValue - Current y, in the y range
+ * @param {number} [xMin=0] - x at the left edge
+ * @param {number} [xMax=1] - x at the right edge
+ * @param {number} [yMin=0] - y at the BOTTOM edge
+ * @param {number} [yMax=1] - y at the top edge
+ * @param {Function} onChange - `(x, y) => void` on pointer down and on every move while a button is held — the caller coalesces if it wants one patch per gesture
+ * @param {ReactNode} xLabel - Left label above the pad
+ * @param {ReactNode} yLabel - Right label above the pad
+ * @param {string} [className] - Extra classes on the wrapper
+ */
+export default function XYPad({
+  xValue, yValue,
+  xMin = 0, xMax = 1,
+  yMin = 0, yMax = 1,
+  onChange,
+  xLabel,
+  yLabel,
+  className = '',
+}) {
+  const ref = useRef(null)
+
+  const handlePos = (e) => {
+    const el = ref.current
+    if (!el) return
+    const rect = el.getBoundingClientRect()
+    const px = Math.max(0, Math.min(1, (e.clientX - rect.left) / rect.width))
+    const py = Math.max(0, Math.min(1, (e.clientY - rect.top) / rect.height))
+    const x = xMin + px * (xMax - xMin)
+    const y = yMax - py * (yMax - yMin) /* invert: top = high */
+    onChange?.(x, y)
+  }
+
+  const onPointerDown = (e) => {
+    e.target.setPointerCapture?.(e.pointerId)
+    handlePos(e)
+  }
+  const onPointerMove = (e) => {
+    if (e.buttons === 0) return
+    handlePos(e)
+  }
+
+  const span = (max, min) => (max - min) || 1
+  const puckX = ((xValue - xMin) / span(xMax, xMin)) * 100
+  const puckY = (1 - (yValue - yMin) / span(yMax, yMin)) * 100
+
+  return (
+    <div className={`flex flex-col gap-1 ${className}`.trim()}>
+      <div className="flex justify-between kol-helper-10 tracking-widest text-meta">
+        <span>{xLabel}</span>
+        <span>{yLabel}</span>
+      </div>
+      <div
+        ref={ref}
+        onPointerDown={onPointerDown}
+        onPointerMove={onPointerMove}
+        className="relative w-full aspect-square border border-fg-16 bg-fg-04 rounded cursor-crosshair touch-none"
+      >
+        {/* crosshair guides */}
+        <div className="absolute inset-x-0 top-1/2 border-t border-fg-08" />
+        <div className="absolute inset-y-0 left-1/2 border-l border-fg-08" />
+        {/* puck */}
+        <div
+          className="absolute w-3 h-3 -ml-1.5 -mt-1.5 rounded-full bg-fg-96 border border-fg-04 pointer-events-none"
+          style={{ left: `${puckX}%`, top: `${puckY}%` }}
+        />
+      </div>
+    </div>
+  )
+}

package/src/hooks/pathMath.js

@@ -0,0 +1,242 @@
+/**
+ * pathMath — bezier path geometry: the `d` string, bounds, normalisation,
+ * scale/rotate, nearest-point-on-segment, split and smooth.
+ *
+ * Lifted verbatim from kol-fxr's engine (`compose/path-math.js`,
+ * `editor-panels-the-held-specs` B2, 2026-09-03) because `PathNodeOverlay`
+ * needs five of these and a second copy of pure geometry is a drift waiting
+ * to happen. It lives in `src/hooks` for the reason `glyphLadders.js` and
+ * `colorMath.js` do — the taxonomy's one non-component folder — and
+ * `@kolkrabbi/design-editor`'s own `path-math.js` is now a re-export of this
+ * file, so the engine and the overlay compute the same curve.
+ */
+/**
+ * path-math — pure geometry for the vector `path` layer type.
+ *
+ * A path node: `{ x, y, in, out }` where `x,y` is the anchor and `in`/`out`
+ * are the incoming/outgoing cubic-bezier control points (absolute, same
+ * coord space as the anchor) or `null` for a corner (control collapses to
+ * the anchor → that side renders as a straight segment).
+ *
+ * Node coords are LOCAL to the layer's `{x, y}` translation. Keeping them
+ * layer-local means a whole-path move is just an `{x, y}` update — the same
+ * gesture every other positioned layer already uses — with no per-node math.
+ */
+
+/* Build an SVG path `d`. Every segment is emitted as a cubic `C`; a corner
+ * node (null handle) uses its anchor as the control, degenerating the cubic
+ * into the straight line we want. Uniform command stream = one code path. */
+export function pathD(nodes, closed = false) {
+  if (!nodes || nodes.length === 0) return ''
+  if (nodes.length === 1) return `M ${nodes[0].x} ${nodes[0].y}`
+  const seg = (p, c) => {
+    const c1 = p.out ?? p
+    const c2 = c.in ?? c
+    return `C ${c1.x} ${c1.y} ${c2.x} ${c2.y} ${c.x} ${c.y}`
+  }
+  let d = `M ${nodes[0].x} ${nodes[0].y}`
+  for (let i = 1; i < nodes.length; i++) d += ` ${seg(nodes[i - 1], nodes[i])}`
+  if (closed) d += ` ${seg(nodes[nodes.length - 1], nodes[0])} Z`
+  return d
+}
+
+/* Anchor-only bounding box. Handles are intentionally excluded so the
+ * selection wireframe doesn't jump when a handle is pulled far out.
+ * ponytail: anchor bbox, not the true curve extent — a selection hint, not
+ * a clip. Swap to a de Casteljau extent solve if tight bounds are needed. */
+export function pathBounds(nodes) {
+  if (!nodes || nodes.length === 0) return { minX: 0, minY: 0, w: 1, h: 1 }
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity
+  for (const n of nodes) {
+    if (n.x < minX) minX = n.x
+    if (n.y < minY) minY = n.y
+    if (n.x > maxX) maxX = n.x
+    if (n.y > maxY) maxY = n.y
+  }
+  return { minX, minY, w: Math.max(1, maxX - minX), h: Math.max(1, maxY - minY) }
+}
+
+/* Translate a node (anchor + both handles) by (dx, dy). */
+export function shiftNode(n, dx, dy) {
+  return {
+    x: n.x + dx,
+    y: n.y + dy,
+    in:  n.in  ? { x: n.in.x  + dx, y: n.in.y  + dy } : null,
+    out: n.out ? { x: n.out.x + dx, y: n.out.y + dy } : null,
+  }
+}
+
+/* Re-origin a node list so its anchor bbox starts at (0,0). Returns the
+ * shifted nodes plus the (dx, dy) that must be ADDED to the layer's {x,y}
+ * to keep the path visually fixed. Called after create + after any node
+ * edit so nodes stay layer-local and {x,y,w,h} stay in sync. */
+export function normalizePath(nodes) {
+  const { minX, minY, w, h } = pathBounds(nodes)
+  return {
+    nodes: nodes.map((n) => shiftNode(n, -minX, -minY)),
+    dx: minX,
+    dy: minY,
+    w,
+    h,
+  }
+}
+
+/* Scale a node list (anchors + handles) around the local origin. Used when
+ * the layer's {w,h} bbox is resized so the geometry tracks the box. Nodes
+ * are normalized (bbox origin at 0,0), so plain multiplication preserves
+ * normalization: min stays 0, max becomes the new w/h. */
+export function scalePathNodes(nodes, sx, sy) {
+  const s = (p) => (p ? { x: p.x * sx, y: p.y * sy } : null)
+  return nodes.map((n) => ({ x: n.x * sx, y: n.y * sy, in: s(n.in), out: s(n.out) }))
+}
+
+/* Re-origin a MULTI-RING path (outer nodes + optional hole rings, both
+ * introduced by boolean ops) so the combined anchor bbox starts at (0,0).
+ * Same contract as normalizePath, but bounds span every ring and holes
+ * shift in lockstep with the outer ring. `holes` may be null/empty. */
+export function normalizePathRings(nodes, holes) {
+  const rings = [nodes, ...(holes ?? [])]
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity
+  for (const ring of rings) for (const n of ring) {
+    if (n.x < minX) minX = n.x
+    if (n.y < minY) minY = n.y
+    if (n.x > maxX) maxX = n.x
+    if (n.y > maxY) maxY = n.y
+  }
+  if (!Number.isFinite(minX)) return { nodes, holes: holes ?? null, dx: 0, dy: 0, w: 1, h: 1 }
+  return {
+    nodes: nodes.map((n) => shiftNode(n, -minX, -minY)),
+    holes: holes?.length ? holes.map((ring) => ring.map((n) => shiftNode(n, -minX, -minY))) : null,
+    dx: minX,
+    dy: minY,
+    w: Math.max(1, maxX - minX),
+    h: Math.max(1, maxY - minY),
+  }
+}
+
+/* Rotate a node list by `deg` (clockwise, y-down) about (cx, cy). Used to
+ * BAKE a layer's live `rotation` into path geometry when entering node-edit
+ * mode — node editing always operates on rotation-free geometry, mirroring
+ * how flips are baked. */
+export function rotatePathNodes(nodes, deg, cx, cy) {
+  const rad = (deg * Math.PI) / 180
+  const cos = Math.cos(rad)
+  const sin = Math.sin(rad)
+  const r = (p) => (p ? {
+    x: cx + (p.x - cx) * cos - (p.y - cy) * sin,
+    y: cy + (p.x - cx) * sin + (p.y - cy) * cos,
+  } : null)
+  return nodes.map((n) => ({ ...r(n), in: r(n.in), out: r(n.out) }))
+}
+
+export function dist(ax, ay, bx, by) {
+  return Math.hypot(ax - bx, ay - by)
+}
+
+/* Point on the segment a→b at parameter t. Corner nodes collapse their
+ * control to the anchor — same degenerate-cubic convention as pathD, so
+ * this evaluates straight segments correctly too. */
+function segPoint(a, b, t) {
+  const p1 = a.out ?? a
+  const p2 = b.in ?? b
+  const u = 1 - t
+  return {
+    x: u * u * u * a.x + 3 * u * u * t * p1.x + 3 * u * t * t * p2.x + t * t * t * b.x,
+    y: u * u * u * a.y + 3 * u * u * t * p1.y + 3 * u * t * t * p2.y + t * t * t * b.y,
+  }
+}
+
+/* Nearest parameter on the segment a→b to (px, py): coarse 32-step scan +
+ * a fine pass around the winner. Click-time hit-testing only, not a hot
+ * path — and the split lands wherever the user perceived the click, so
+ * sub-pixel exactness buys nothing. */
+export function nearestSegmentT(a, b, px, py) {
+  let bestT = 0
+  let bestD = Infinity
+  const scan = (from, to, steps) => {
+    for (let i = 0; i <= steps; i++) {
+      const t = from + ((to - from) * i) / steps
+      const p = segPoint(a, b, t)
+      const d = (p.x - px) ** 2 + (p.y - py) ** 2
+      if (d < bestD) { bestD = d; bestT = t }
+    }
+  }
+  scan(0, 1, 32)
+  scan(Math.max(0, bestT - 1 / 32), Math.min(1, bestT + 1 / 32), 16)
+  return { t: bestT, dist: Math.sqrt(bestD) }
+}
+
+/* de Casteljau split of the segment a→b at t. Returns replacement nodes
+ * { a, mid, b } — shape-preserving: the two half-cubics retrace the original
+ * curve exactly (the new node takes the interior split handles; a/b keep
+ * their far handles and get their near handles trimmed). A straight segment
+ * (both controls null) yields a handle-less mid so corners stay corners. */
+export function splitSegment(a, b, t) {
+  if (!a.out && !b.in) {
+    return {
+      a, b,
+      mid: { x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t, in: null, out: null },
+    }
+  }
+  const p1 = a.out ?? a
+  const p2 = b.in ?? b
+  const lerp = (p, q) => ({ x: p.x + (q.x - p.x) * t, y: p.y + (q.y - p.y) * t })
+  const q0 = lerp(a, p1)
+  const q1 = lerp(p1, p2)
+  const q2 = lerp(p2, b)
+  const r0 = lerp(q0, q1)
+  const r1 = lerp(q1, q2)
+  const s  = lerp(r0, r1)
+  /* A null (corner) side stays null: its split control degenerates to the
+   * anchor anyway, and a zero-length handle would just put a dead knob on
+   * top of the anchor square. */
+  return {
+    a:   { ...a, out: a.out ? q0 : null },
+    mid: { x: s.x, y: s.y, in: r0, out: r1 },
+    b:   { ...b, in: b.in ? q2 : null },
+  }
+}
+
+/* Smooth a corner anchor: mirrored handles along the neighbor chord
+ * (Illustrator convention), each sized to ~1/3 of its adjacent segment
+ * length. Open-path endpoints get a single handle toward their only
+ * neighbor. The anchor itself never moves. Returns a new node (or the
+ * original when there are no neighbors to derive a tangent from). */
+export function smoothNode(nodes, i, closed) {
+  const n = nodes[i]
+  const len = nodes.length
+  const prev = (closed || i > 0)       ? nodes[(i - 1 + len) % len] : null
+  const next = (closed || i < len - 1) ? nodes[(i + 1) % len]       : null
+  if (!prev && !next) return n
+  const dPrev = prev ? dist(n.x, n.y, prev.x, prev.y) : 0
+  const dNext = next ? dist(n.x, n.y, next.x, next.y) : 0
+  let tx = (next ?? n).x - (prev ?? n).x
+  let ty = (next ?? n).y - (prev ?? n).y
+  const tl = Math.hypot(tx, ty) || 1
+  tx /= tl
+  ty /= tl
+  return {
+    ...n,
+    in:  prev ? { x: n.x - tx * (dPrev / 3), y: n.y - ty * (dPrev / 3) } : null,
+    out: next ? { x: n.x + tx * (dNext / 3), y: n.y + ty * (dNext / 3) } : null,
+  }
+}
+
+/* ── dev self-check ─────────────────────────────────────────────────── */
+if (import.meta.env?.DEV) {
+  const sq = [
+    { x: 10, y: 10, in: null, out: null },
+    { x: 30, y: 10, in: null, out: null },
+    { x: 30, y: 40, in: null, out: null },
+  ]
+  const b = pathBounds(sq)
+  console.assert(b.minX === 10 && b.minY === 10 && b.w === 20 && b.h === 30, 'pathBounds')
+  const n = normalizePath(sq)
+  console.assert(n.dx === 10 && n.dy === 10 && n.nodes[0].x === 0 && n.nodes[0].y === 0, 'normalizePath origin')
+  console.assert(pathD(sq).startsWith('M 10 10 C'), 'pathD corner→cubic')
+  console.assert(pathD(sq, true).endsWith('Z'), 'pathD closed')
+  const sp = splitSegment(sq[0], sq[1], 0.5)
+  console.assert(sp.mid.x === 20 && sp.mid.y === 10 && sp.mid.in === null, 'splitSegment straight → corner mid')
+  const sm = smoothNode(sq, 1, false)
+  console.assert(sm.in && sm.out && sm.x === 30 && sm.y === 10, 'smoothNode handles, anchor fixed')
+}

package/src/index.js

@@ -65,6 +65,15 @@ export { default as ToggleSwitch } from './atoms/ToggleSwitch.jsx'
 export { default as TiltCard } from './utilities/TiltCard.jsx'
 export { default as TransparentX } from './utilities/TransparentX.jsx'
 export { default as ViewToggle } from './atoms/ViewToggle.jsx'
+/* the design-editor parts, taken per row from editor-panels-the-held-specs (2026-09-03) */
+export { default as XYPad } from './atoms/XYPad.jsx'
+export { default as InspectorRail } from './molecules/InspectorRail.jsx'
+/* SelectionOverlay's two siblings — same 1080-virtual contract, same zoom
+ * division (editor-panels-the-held-specs B2). `pathMath` is their geometry,
+ * exported because the editor engine re-exports it rather than keep a copy. */
+export { default as PathNodeOverlay } from './atoms/PathNodeOverlay.jsx'
+export { default as CropOverlay } from './atoms/CropOverlay.jsx'
+export { pathD, pathBounds, shiftNode, normalizePath, scalePathNodes, normalizePathRings, rotatePathNodes, dist, nearestSegmentT, splitSegment, smoothNode } from './hooks/pathMath.js'
 
 // molecules
 export { Accordion, AccordionPanel } from './molecules/Accordion.jsx'

package/src/molecules/InspectorRail.jsx

@@ -0,0 +1,59 @@
+/**
+ * InspectorRail — the selection-routing shell of an inspector panel.
+ *
+ * Lifted from kol-fxr's editor (`compose/InspectorRail.jsx`,
+ * `editor-panels-the-held-specs` A7, 2026-09-03) with ALL of its coupling
+ * dropped: it read the compose store and imported three concrete panels. What
+ * is left is the one piece of logic the filer said everyone gets wrong — the
+ * precedence — and it is the thing that makes an inspector rail a component
+ * rather than a `<div>`:
+ *
+ *   nothing selected       → renders NOTHING (user ruling 2026-08-12: no dummy
+ *                            empty-state copy; selection must visibly spawn
+ *                            its controls)
+ *   the canvas is selected → `renderers.canvas`, and it WINS over multi-select.
+ *                            Selecting the canvas selects every layer with it,
+ *                            so without this precedence "inspect the canvas"
+ *                            with two layers in frame fell into the multi
+ *                            branch and hid the fill / opacity controls
+ *   exactly one id         → `renderers.single(id)`
+ *   two or more ids        → `renderers.multi(ids)` — the canvas id excluded
+ *                            from the count; it is selectable but not a layer
+ *
+ * The panels themselves are the consumer's — a layer inspector delegating by
+ * type, a canvas inspector, a multi-select summary with a Group action — and
+ * they arrive as render functions so this file imports none of them.
+ *
+ *   <InspectorRail
+ *     selectedIds={selectedIds}
+ *     canvasId="canvas"
+ *     renderers={{
+ *       canvas: () => <CanvasInspector />,
+ *       single: (id) => <LayerInspector layer={find(id)} />,
+ *       multi:  (ids) => <MultiSummary ids={ids} onGroup={group} />,
+ *     }}
+ *   />
+ *
+ * @param {string[]} selectedIds - The current selection, in selection order; may include `canvasId`
+ * @param {string} [canvasId='canvas'] - The id that means "the canvas itself" — precedence, and excluded from the multi count
+ * @param {{canvas?: Function, single?: Function, multi?: Function}} renderers - `canvas()`, `single(id)`, `multi(ids)` — each returns the node for that state; a missing renderer renders nothing for it
+ * @param {string} [className] - Extra classes on the rail
+ */
+export default function InspectorRail({ selectedIds = [], canvasId = 'canvas', renderers = {}, className = '' }) {
+  const isCanvas = selectedIds.includes(canvasId)
+  const layerIds = selectedIds.filter((id) => id !== canvasId)
+
+  const body = isCanvas
+    ? renderers.canvas?.()
+    : layerIds.length >= 2
+      ? renderers.multi?.(layerIds)
+      : layerIds.length === 1
+        ? renderers.single?.(layerIds[0])
+        : null
+
+  return (
+    <div className={`kol-inspector-rail ${className}`.trim()}>
+      {body && <div className="kol-inspector-rail-body">{body}</div>}
+    </div>
+  )
+}