@kolkrabbi/kol-component 0.196.0 → 0.198.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.196.0",
+  "version": "0.198.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/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/hooks/layerTree.js

@@ -0,0 +1,92 @@
+/**
+ * layerTree — the labels and the tree walk a layer stack reads.
+ *
+ * Lifted verbatim from kol-fxr's engine (`compose/labels.js` +
+ * `compose/helpers.js`, `editor-panels-the-held-specs` A1, 2026-09-03) as
+ * `LayerStack`'s DEFAULTS. A consumer's layer taxonomy is its own — the stack
+ * takes `labelFor` and `iconFor` seams — and these are what those seams fall
+ * back to when a consumer's layers happen to speak the same `type` vocabulary.
+ * In `src/hooks` for the reason `glyphLadders.js` and `pathMath.js` are: the
+ * taxonomy's one non-component folder.
+ *
+ * Convention: Title Case everywhere. A user-set `layer.name` always wins,
+ * verbatim — no casing applied.
+ */
+
+export const TYPE_LABELS = {
+  background: 'Background',
+  pattern:    'Pattern',
+  photo:      'Photo',
+  shape:      'Shape',
+  text:       'Text',
+  group:      'Group',
+  bool:       'Boolean',
+  loop:       'Loop',
+  kinetic:    'Kinetic type',
+  misc:       'Misc',
+}
+
+export const BOOL_OP_LABELS = {
+  unite:     'Unite',
+  subtract:  'Subtract',
+  intersect: 'Intersect',
+  exclude:   'Exclude',
+}
+
+export const SHAPE_KIND_LABELS = {
+  logo:     'Logo',
+  rect:     'Rectangle',
+  ellipse:  'Ellipse',
+  triangle: 'Triangle',
+  line:     'Line',
+  polygon:  'Polygon',
+  star:     'Star',
+  flatten:  'Flatten',
+}
+
+/* Inspector title — verbose form, e.g. "Shape · Rectangle". */
+export function labelForLayer(layer) {
+  if (layer.type === 'shape') {
+    const kind = SHAPE_KIND_LABELS[layer.kind ?? 'logo'] ?? 'Shape'
+    return `Shape · ${kind}`
+  }
+  if (layer.type === 'bool') {
+    const op = BOOL_OP_LABELS[layer.op]
+    return op ? `Boolean · ${op}` : TYPE_LABELS.bool
+  }
+  if (layer.type === 'loop' && layer.presetLabel) return `Loop · ${layer.presetLabel}`
+  if (layer.type === 'misc' && layer.presetLabel) return `Misc · ${layer.presetLabel}`
+  if (layer.type === 'kinetic' && layer.presetLabel) return `Kinetic · ${layer.presetLabel}`
+  return TYPE_LABELS[layer.type] ?? layer.type
+}
+
+/* Compact label for a layer-stack row. A user-set `layer.name` (inline
+ * rename in the layer stack) always wins, verbatim — no casing applied.
+ * Otherwise shapes show their kind directly (Figma idiom — "Rectangle"
+ * not "Shape · Rectangle"); text rows show the actual content (truncated
+ * by the row's CSS). */
+export function rowLabelForLayer(layer) {
+  if (layer.name) return layer.name
+  if (layer.type === 'text') return layer.text || TYPE_LABELS.text
+  if (layer.type === 'shape') {
+    return SHAPE_KIND_LABELS[layer.kind ?? 'logo'] ?? TYPE_LABELS.shape
+  }
+  if (layer.type === 'bool') return BOOL_OP_LABELS[layer.op] ?? TYPE_LABELS.bool
+  if (layer.type === 'loop' || layer.type === 'misc') return layer.presetLabel || TYPE_LABELS[layer.type]
+  if (layer.type === 'kinetic') return layer.presetLabel || TYPE_LABELS.kinetic
+  return TYPE_LABELS[layer.type] ?? layer.type
+}
+
+/* Walk the layer tree (including group/bool children) and return the layer
+ * with `id`, or null if none. Single source of truth — the engine had four
+ * inline copies drifting independently before this. */
+export function findLayerDeep(layers, id) {
+  for (const l of layers) {
+    if (l.id === id) return l
+    if (Array.isArray(l.children)) {
+      const found = findLayerDeep(l.children, id)
+      if (found) return found
+    }
+  }
+  return null
+}

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

@@ -68,6 +68,14 @@ 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 { default as LayerStack, AddLayerButton, BLEND_MODES } from './organisms/LayerStack.jsx'
+export { TYPE_LABELS, BOOL_OP_LABELS, SHAPE_KIND_LABELS, labelForLayer, rowLabelForLayer, findLayerDeep } from './hooks/layerTree.js'
+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/organisms/LayerStack.jsx

@@ -0,0 +1,504 @@
+import { useRef, useState } from 'react'
+import { Icon } from '@kolkrabbi/kol-icons'
+import Button from '../atoms/Button.jsx'
+import Input from '../atoms/Input.jsx'
+import { MenuDropdownItem, MenuDropdownNest } from '../molecules/MenuItem.jsx'
+import { usePopover, PopoverPanel } from '../utilities/Popover.jsx'
+import { rowLabelForLayer, findLayerDeep } from '../hooks/layerTree.js'
+
+/* DS icon names for the engine's types — every one a shipped v1 glyph. A
+ * consumer's own map goes in through `iconFor`. */
+const DEFAULT_TYPE_ICONS = {
+  background: 'square',
+  pattern:    'ptrn-dot',
+  photo:      'image',
+  shape:      'rectangle',
+  text:       'type',
+  group:      'layers',
+  bool:       'layers',
+  loop:       'refresh',
+  misc:       'refresh',
+  kinetic:    'type',
+}
+const defaultIconFor = (type) => DEFAULT_TYPE_ICONS[type] ?? 'rectangle'
+
+/* Exported — an inspector's Blend dropdown shares this list. */
+export const BLEND_MODES = [
+  { value: 'normal',     label: 'Normal' },
+  { value: 'multiply',   label: 'Multiply' },
+  { value: 'screen',     label: 'Screen' },
+  { value: 'overlay',    label: 'Overlay' },
+  { value: 'soft-light', label: 'Soft light' },
+  { value: 'difference', label: 'Difference' },
+]
+
+/* Shift state captured in mousedown via ref; click reads the ref to decide
+ * single-select vs toggle-select. Avoids relying on the synthetic event's
+ * shiftKey passing through (proved unreliable in the source codebase). */
+function useShiftClickHandlers(onSelect, onShiftSelect) {
+  const shiftRef = useRef(false)
+  const onMouseDown = (e) => { shiftRef.current = !!e.shiftKey }
+  const onClick = () => {
+    if (shiftRef.current) {
+      shiftRef.current = false
+      onShiftSelect?.()
+    } else {
+      onSelect?.()
+    }
+  }
+  return { onMouseDown, onClick }
+}
+
+function Chevron({ IconC, collapsed, onToggle, title }) {
+  return (
+    <button
+      type="button"
+      onClick={onToggle}
+      aria-expanded={!collapsed}
+      title={title}
+      className="kol-layer-stack-collapse"
+    >
+      <IconC
+        name="chevron-down"
+        size={10}
+        style={{ transform: collapsed ? 'rotate(-90deg)' : 'rotate(0deg)', transition: 'transform 150ms' }}
+      />
+    </button>
+  )
+}
+
+function LayerRow({
+  layer, active, tinted, isContainer, IconC, labelFor, iconFor,
+  groupCollapsed, onToggleGroup,
+  onSelect, onShiftSelect, onToggleVisibility, onToggleLock, onRename,
+  draggedId, dropTargetId, dropPosition,
+  onDragStart, onDragOver, onDragLeave, onDrop, onDragEnd,
+  parentId = null,
+}) {
+  const isDragging  = draggedId === layer.id
+  const isDropAbove = dropTargetId === layer.id && dropPosition === 'above'
+  const isDropBelow = dropTargetId === layer.id && dropPosition === 'below'
+
+  const selectHandlers = useShiftClickHandlers(onSelect, onShiftSelect)
+
+  /* Inline rename — double-click the name to edit. Enter/blur commits (the
+   * consumer's write, so undo-safety is theirs); Escape cancels. An emptied
+   * input clears the name so the row falls back to its type label. */
+  const [renaming, setRenaming] = useState(false)
+  const [draft, setDraft]       = useState('')
+  const cancelRef = useRef(false)
+
+  const startRename = () => {
+    setDraft(layer.name ?? '')
+    setRenaming(true)
+  }
+  const commitRename = () => {
+    if (!cancelRef.current) onRename(draft.trim() || null)
+    cancelRef.current = false
+    setRenaming(false)
+  }
+
+  return (
+    <div className="kol-layer-stack-line group">
+      {isContainer ? (
+        <Chevron IconC={IconC} collapsed={groupCollapsed} onToggle={onToggleGroup} title={groupCollapsed ? 'Expand group' : 'Collapse group'} />
+      ) : (
+        <span aria-hidden="true" className="kol-layer-stack-collapse" />
+      )}
+      <div
+        draggable={!renaming}
+        onDragStart={(e) => onDragStart(e, layer.id)}
+        onDragOver={(e) => onDragOver(e, layer.id, parentId)}
+        onDragLeave={(e) => onDragLeave(e, layer.id)}
+        onDrop={(e) => onDrop(e, layer.id, parentId)}
+        onDragEnd={onDragEnd}
+        className={
+          `kol-layer-stack-row${active ? ' is-active' : ''}` +
+          `${tinted && !active ? ' is-tinted' : ''}` +
+          `${!layer.visible ? ' is-hidden' : ''}` +
+          `${isDragging ? ' is-dragging' : ''}` +
+          `${isDropAbove ? ' is-drop-above' : ''}` +
+          `${isDropBelow ? ' is-drop-below' : ''}`
+        }
+        data-layer-id={layer.id}
+      >
+        {renaming ? (
+          <span className="kol-layer-stack-main">
+            <span className="kol-layer-stack-icon" aria-hidden="true">
+              <IconC name={iconFor(layer.type)} size={14} />
+            </span>
+            <Input
+              variant="ghost"
+              size="sm"
+              width="100%"
+              value={draft}
+              onChange={(e) => setDraft(e.target.value)}
+              onFocus={(e) => e.target.select()}
+              onBlur={commitRename}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter') e.currentTarget.blur()
+                else if (e.key === 'Escape') { cancelRef.current = true; e.currentTarget.blur() }
+              }}
+              autoFocus
+              placeholder={labelFor({ ...layer, name: null })}
+              inputClassName="kol-helper-12 text-emphasis"
+            />
+          </span>
+        ) : (
+          <button
+            type="button"
+            onMouseDown={selectHandlers.onMouseDown}
+            onClick={selectHandlers.onClick}
+            onDoubleClick={startRename}
+            className="kol-layer-stack-main"
+          >
+            <span className="kol-layer-stack-icon" aria-hidden="true">
+              <IconC name={iconFor(layer.type)} size={14} />
+            </span>
+            <span className="kol-helper-12 truncate flex-1 text-left">
+              {labelFor(layer)}
+            </span>
+          </button>
+        )}
+        <button
+          type="button"
+          onClick={onToggleVisibility}
+          title={layer.visible ? 'Hide' : 'Show'}
+          aria-pressed={!layer.visible}
+          className={`kol-layer-stack-toggle kol-layer-stack-toggle--eye${active || !layer.visible ? ' is-pinned' : ''}`}
+        >
+          <IconC name={layer.visible ? 'eye-on' : 'eye-off'} size={12} />
+        </button>
+        <button
+          type="button"
+          onClick={onToggleLock}
+          title={layer.locked ? 'Unlock' : 'Lock'}
+          aria-pressed={!!layer.locked}
+          className={`kol-layer-stack-toggle kol-layer-stack-toggle--lock${active || layer.locked ? ' is-pinned' : ''}${layer.locked ? ' is-on' : ''}`}
+        >
+          <IconC name={layer.locked ? 'lock' : 'unlock'} size={12} />
+        </button>
+      </div>
+    </div>
+  )
+}
+
+/* CanvasRow — the container row at the top of the stack (Figma frame model:
+ * everything nests one step inside it). Always present, can't be deleted;
+ * its chevron collapses the contents. */
+function CanvasRow({ IconC, active, collapsed, onToggleCollapse, onSelect }) {
+  return (
+    <div className="kol-layer-stack-line group">
+      <Chevron IconC={IconC} collapsed={collapsed} onToggle={onToggleCollapse} title={collapsed ? 'Expand layers' : 'Collapse layers'} />
+      <div className={`kol-layer-stack-row${active ? ' is-active' : ''}`} data-layer-id="canvas">
+        <button type="button" onClick={onSelect} className="kol-layer-stack-main">
+          <span className="kol-layer-stack-icon" aria-hidden="true">
+            <IconC name="maximize" size={14} />
+          </span>
+          {/* helper-12 like every layer row — mono-12 read heavier than the stack */}
+          <span className="kol-helper-12 truncate flex-1 text-left">Canvas</span>
+        </button>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * LayerStack — the layers panel: a z-stacked tree of rows with HTML5 drag to
+ * reorder AND reparent in one gesture, hover-revealed eye + lock toggles,
+ * inline rename, collapsible containers, and a Canvas root row above it all.
+ *
+ * Lifted from kol-fxr's editor (`compose/LayerStack.jsx`, 583 lines,
+ * `editor-panels-the-held-specs` A1, 2026-09-03) with its ONE coupling
+ * dropped: it read and wrote `useComposeState()` directly. Every store call
+ * is now a prop, and the drag model — the non-trivial part, the drop target
+ * computed against the flattened tree with the cycle guard — is verbatim.
+ *
+ * ANATOMY, per row: `[chevron] [type icon] [name] … [eye] [lock]`. Chevrons
+ * are focus chrome, not resting chrome (Figma model): hidden until the pointer
+ * is inside the stack. Eye and lock reveal on row hover and pin visible when
+ * the layer is hidden or locked. Double-click the name to rename inline —
+ * Enter / blur commits, Escape cancels, an emptied field clears the name so
+ * the row falls back to its type label. The panel renders REVERSED, so the
+ * top row is the top of the z-order.
+ *
+ * THE DRAG. One drop path for every row: `onReorder(id, parentId, index)`
+ * handles same-container reorder, child → top level, and top level → container
+ * alike. `index` is in the target container's order WITHOUT the dragged item.
+ * Dropping a container into its own subtree is refused at every depth (the UI
+ * shows no indicator, so it never promises a drop the consumer would reject).
+ *
+ * SEAMS. `labelFor(layer)` and `iconFor(type)` because a consumer's layer
+ * taxonomy is not ours — the defaults are the engine's own labels
+ * (`hooks/layerTree.js`) and a DS-icon map, and a consumer with its own icon
+ * registry passes `iconComponent` (Button's seam, same shape: `{ name, size,
+ * className, style }`). `containerTypes` says which types have children.
+ *
+ * Chrome is `.kol-layer-stack-*` in kol-theme (organisms) — the states,
+ * the drop indicators and the hover-reveal are pseudo-elements and descendant
+ * rules a utility cannot express.
+ *
+ * @param {Array<Object>} layers - The tree, bottom-of-z-order first: `{ id, type, name?, visible, locked?, children? }` plus whatever the consumer's `labelFor` reads
+ * @param {string[]} selectedIds - Current selection; may include `canvasId`
+ * @param {string} [canvasId='canvas'] - The id that means the canvas root row
+ * @param {Function} onSelect - `(id) => void` — plain click
+ * @param {Function} onToggleSelect - `(id) => void` — shift-click adds / removes
+ * @param {Function} onSelectCanvas - `() => void` — the root row
+ * @param {Function} onToggleVisible - `(id) => void`
+ * @param {Function} onToggleLocked - `(id) => void`
+ * @param {Function} onRename - `(id, name|null) => void` — null clears the name
+ * @param {Function} onReorder - `(id, parentId|null, index) => void` — see THE DRAG
+ * @param {Function} onGroup - `(ids) => void` — the footer's Group action over a multi-selection; omit to hide it
+ * @param {Function} [labelFor] - `(layer) => string` (default: the engine's `rowLabelForLayer`)
+ * @param {Function} [iconFor] - `(type) => iconName` (default: a DS-icon map over the engine's types)
+ * @param {ElementType} [iconComponent] - Icon renderer receiving `{ name, size, className, style }` (default: DS `Icon`)
+ * @param {string[]} [containerTypes=['group','bool']] - Types whose rows collapse and whose `children` nest
+ * @param {string} [className] - Extra classes on the panel
+ */
+export default function LayerStack({
+  layers = [],
+  selectedIds = [],
+  canvasId = 'canvas',
+  onSelect,
+  onToggleSelect,
+  onSelectCanvas,
+  onToggleVisible,
+  onToggleLocked,
+  onRename,
+  onReorder,
+  onGroup,
+  labelFor = rowLabelForLayer,
+  iconFor = defaultIconFor,
+  iconComponent: IconC = Icon,
+  containerTypes = ['group', 'bool'],
+  className = '',
+}) {
+  const isContainer = (l) => containerTypes.includes(l.type)
+
+  /* The canvas is selectable but isn't a layer — exclude it from the group
+   * action's count and payload. */
+  const layerSelectedIds    = selectedIds.filter((id) => id !== canvasId)
+  const layerSelectionCount = layerSelectedIds.length
+
+  const [draggedId, setDraggedId]       = useState(null)
+  const [dropTargetId, setDropTargetId] = useState(null)
+  const [dropPosition, setDropPosition] = useState(null)
+  const [collapsedGroups, setCollapsedGroups] = useState(() => new Set())
+  const [canvasCollapsed, setCanvasCollapsed] = useState(false)
+
+  const toggleGroupCollapse = (id) => setCollapsedGroups((prev) => {
+    const next = new Set(prev)
+    if (next.has(id)) next.delete(id)
+    else next.add(id)
+    return next
+  })
+
+  const onDragStart = (e, id) => {
+    e.dataTransfer.effectAllowed = 'move'
+    e.dataTransfer.setData('text/plain', id)
+    setDraggedId(id)
+  }
+
+  /* True when the drop container sits anywhere inside the dragged layer's own
+   * subtree (group into its own descendant) — a cycle the consumer will
+   * reject, so the UI must not promise the drop. Every depth, not just direct
+   * children. */
+  const isIntoOwnSubtree = (targetParentId) => {
+    if (!draggedId || targetParentId == null) return false
+    const dragged = findLayerDeep(layers, draggedId)
+    return dragged != null && findLayerDeep([dragged], targetParentId) != null
+  }
+
+  const onDragOver = (e, targetId, targetParentId = null) => {
+    e.preventDefault()
+    e.dataTransfer.dropEffect = 'move'
+    if (!draggedId || draggedId === targetId || isIntoOwnSubtree(targetParentId)) {
+      setDropTargetId(null)
+      setDropPosition(null)
+      return
+    }
+    const rect = e.currentTarget.getBoundingClientRect()
+    const isUpper = (e.clientY - rect.top) < rect.height / 2
+    setDropTargetId(targetId)
+    setDropPosition(isUpper ? 'above' : 'below')
+  }
+
+  const onDragLeave = (_e, targetId) => {
+    setDropTargetId((cur) => (cur === targetId ? null : cur))
+  }
+
+  const clearDrag = () => {
+    setDraggedId(null)
+    setDropTargetId(null)
+    setDropPosition(null)
+  }
+
+  /* One drop path for every row. Index is in the target container's order
+   * WITHOUT the dragged item. The panel renders reversed, so visual 'above'
+   * = one past the target. */
+  const onDrop = (e, targetId, targetParentId = null) => {
+    e.preventDefault()
+    if (!draggedId || draggedId === targetId || isIntoOwnSubtree(targetParentId)) {
+      clearDrag()
+      return
+    }
+    const container = targetParentId
+      ? (findLayerDeep(layers, targetParentId)?.children ?? [])
+      : layers
+    const list = container.filter((l) => l.id !== draggedId)
+    const targetIndex = list.findIndex((l) => l.id === targetId)
+    if (targetIndex < 0) {
+      clearDrag()
+      return
+    }
+    const finalIndex = dropPosition === 'above' ? targetIndex + 1 : targetIndex
+    onReorder?.(draggedId, targetParentId, finalIndex)
+    clearDrag()
+  }
+
+  const rowProps = (layer, parentId) => ({
+    layer,
+    parentId,
+    active: selectedIds.includes(layer.id),
+    tinted: selectedIds.includes(parentId ?? canvasId),
+    isContainer: isContainer(layer),
+    IconC, labelFor, iconFor,
+    groupCollapsed: collapsedGroups.has(layer.id),
+    onToggleGroup: () => toggleGroupCollapse(layer.id),
+    onSelect: () => onSelect?.(layer.id),
+    onShiftSelect: () => onToggleSelect?.(layer.id),
+    onToggleVisibility: () => onToggleVisible?.(layer.id),
+    onToggleLock: () => onToggleLocked?.(layer.id),
+    onRename: (name) => onRename?.(layer.id, name),
+    draggedId, dropTargetId, dropPosition,
+    onDragStart, onDragOver, onDragLeave, onDrop, onDragEnd: clearDrag,
+  })
+
+  /* Recursive container contents. Each level wraps in a `-nest` ul, so the
+   * indent compounds one chevron slot per depth; collapse, selection and drag
+   * are id-keyed, so they work identically at every depth. */
+  const renderChildren = (parent) => (
+    <ul className="flex flex-col kol-layer-stack-nest">
+      {[...parent.children].reverse().map((child) => (
+        <li key={child.id}>
+          <LayerRow {...rowProps(child, parent.id)} />
+          {isContainer(child) && !collapsedGroups.has(child.id)
+            && Array.isArray(child.children) && child.children.length > 0
+            && renderChildren(child)}
+        </li>
+      ))}
+    </ul>
+  )
+
+  return (
+    <div className={`kol-layer-stack flex flex-col min-h-[240px] ${className}`.trim()} data-layer-stack="true">
+      {/* Figma frame model: Canvas is the container, every layer nests one
+        * step inside it; container children one more. */}
+      <ul className="flex flex-col pb-3 px-2 pt-3">
+        <li>
+          <CanvasRow
+            IconC={IconC}
+            active={selectedIds.includes(canvasId)}
+            collapsed={canvasCollapsed}
+            onToggleCollapse={() => setCanvasCollapsed((v) => !v)}
+            onSelect={() => onSelectCanvas?.()}
+          />
+        </li>
+        {!canvasCollapsed && [...layers].reverse().map((layer) => (
+          <li key={layer.id} className="kol-layer-stack-nest">
+            <LayerRow {...rowProps(layer, null)} />
+            {isContainer(layer) && !collapsedGroups.has(layer.id)
+              && Array.isArray(layer.children) && layer.children.length > 0
+              && renderChildren(layer)}
+          </li>
+        ))}
+      </ul>
+
+      {/* Footer only exists while a multi-selection can be grouped — add
+        * lives in the panel's tab row (AddLayerButton), delete is the
+        * consumer's keymap. */}
+      {onGroup && layerSelectionCount >= 2 && (
+        <div className="mt-auto flex items-center gap-2 px-3 h-10 border-t border-fg-08">
+          <Button
+            iconComponent={IconC}
+            variant="primary"
+            size="sm"
+            iconLeft="layers"
+            onClick={() => onGroup(layerSelectedIds)}
+            title={`Group ${layerSelectionCount} selected layers`}
+          >
+            Group {layerSelectionCount}
+          </Button>
+        </div>
+      )}
+    </div>
+  )
+}
+
+/**
+ * AddLayerButton — the `+` that opens a menu of layer types. Lives in the
+ * panel's tab row, not the stack footer (the source's placement). One entry
+ * may expand inline to a kind picker so adding "a shape" doesn't silently
+ * default to the first kind.
+ *
+ * @param {Array<{id: string, label: string, icon?: string}>} types - The menu rows
+ * @param {{typeId: string, kinds: Array<{id: string, label: string, icon?: string, extras?: Object}>}} [nested] - One type that opens a sub-menu of kinds; picking one fires `onAdd(typeId, kind.extras)`
+ * @param {Function} onAdd - `(typeId, extras?) => void`
+ * @param {Function} [iconFor] - `(typeId) => iconName` for rows without their own `icon`
+ * @param {ElementType} [iconComponent] - Icon renderer (default: DS `Icon`)
+ * @param {number} [menuWidth=180] - Panel width in px
+ */
+export function AddLayerButton({
+  types = [],
+  nested,
+  onAdd,
+  iconFor = defaultIconFor,
+  iconComponent: IconC = Icon,
+  menuWidth = 180,
+}) {
+  const [open, setOpen] = useState(false)
+  const popover = usePopover({
+    open,
+    onOpenChange: setOpen,
+    placement: 'bottom-start',
+    offset: 4,
+    role: 'menu',
+  })
+  const pick = (id, extras) => { onAdd?.(id, extras); setOpen(false) }
+
+  return (
+    <>
+      <span ref={popover.refs.setReference} {...popover.getReferenceProps()} className="inline-flex">
+        <Button
+          iconComponent={IconC}
+          variant="primary"
+          size="sm"
+          quiet
+          iconOnly="plus"
+          aria-label="Add layer"
+          title="Add layer"
+        />
+      </span>
+      <PopoverPanel popover={popover} className="py-1" style={{ width: menuWidth }}>
+        {types.map((t) => {
+          if (nested && t.id === nested.typeId) {
+            return (
+              <MenuDropdownNest key={t.id} iconLeft={<IconC name={t.icon ?? iconFor(t.id)} size={12} />} label={t.label}>
+                {nested.kinds.map((k) => (
+                  <MenuDropdownItem key={k.id} iconLeft={<IconC name={k.icon ?? iconFor(t.id)} size={12} />} onClick={() => pick(t.id, k.extras)}>
+                    {k.label}
+                  </MenuDropdownItem>
+                ))}
+              </MenuDropdownNest>
+            )
+          }
+          return (
+            <MenuDropdownItem key={t.id} iconLeft={<IconC name={t.icon ?? iconFor(t.id)} size={12} />} onClick={() => pick(t.id)}>
+              {t.label}
+            </MenuDropdownItem>
+          )
+        })}
+      </PopoverPanel>
+    </>
+  )
+}