@kolkrabbi/kol-component 0.197.0 → 0.199.0

package/package.json

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

package/src/hooks/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/index.js

@@ -73,6 +73,9 @@ export { default as InspectorRail } from './molecules/InspectorRail.jsx'
  * 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 { default as TimelineDock, sampleTrack, TIMELINE_EASINGS } from './organisms/TimelineDock.jsx'
 export { pathD, pathBounds, shiftNode, normalizePath, scalePathNodes, normalizePathRings, rotatePathNodes, dist, nearestSegmentT, splitSegment, smoothNode } from './hooks/pathMath.js'
 
 // molecules

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

package/src/organisms/TimelineDock.jsx

@@ -0,0 +1,258 @@
+import { useRef, useState } from 'react'
+import Input from '../atoms/Input.jsx'
+import Dropdown from '../molecules/Dropdown.jsx'
+
+/* The six easings the key editor offers. The CURVES stay the consumer's
+ * (its interpolator resolves the name); this is the menu, not the math. */
+export const TIMELINE_EASINGS = [
+  { value: 'linear', label: 'Linear' },
+  { value: 'ease',   label: 'Ease' },
+  { value: 'in',     label: 'Ease in' },
+  { value: 'out',    label: 'Ease out' },
+  { value: 'in-out', label: 'Ease in-out' },
+  { value: 'hold',   label: 'Hold' },
+]
+
+/* Sample a track's value at t (linear across the segment — good enough for
+ * the "add key without a jump" affordance). Exported: a consumer's renderer
+ * wants the same answer the dock used when it placed the key. */
+export function sampleTrack(keys, t) {
+  if (keys.length === 0) return 0
+  if (t <= keys[0].t) return keys[0].v
+  const last = keys[keys.length - 1]
+  if (t >= last.t) return last.v
+  let i = 0
+  while (i < keys.length - 1 && keys[i + 1].t <= t) i++
+  const a = keys[i], b = keys[i + 1]
+  if (typeof a.v !== 'number' || typeof b.v !== 'number') return a.v
+  const span = b.t - a.t || 1
+  return a.v + (b.v - a.v) * ((t - a.t) / span)
+}
+
+/* Click/drag to seek. */
+function ScrubRuler({ t, onSeek }) {
+  const ref = useRef(null)
+  const fracFromEvent = (e) => {
+    const r = ref.current.getBoundingClientRect()
+    return Math.min(1, Math.max(0, (e.clientX - r.left) / r.width))
+  }
+  const onPointerDown = (e) => {
+    e.currentTarget.setPointerCapture(e.pointerId)
+    onSeek?.(fracFromEvent(e))
+  }
+  const onPointerMove = (e) => {
+    if (e.buttons & 1) onSeek?.(fracFromEvent(e))
+  }
+  return (
+    <div className="flex items-center gap-3">
+      <span className="kol-mono-12 text-meta tabular-nums shrink-0 text-right" style={{ width: 120 }}>{t.toFixed(2)}</span>
+      <div
+        ref={ref}
+        className="relative flex-1 h-4 cursor-ew-resize rounded"
+        style={{ background: 'var(--kol-fg-04)' }}
+        onPointerDown={onPointerDown}
+        onPointerMove={onPointerMove}
+      >
+        <Playhead t={t} />
+      </div>
+    </div>
+  )
+}
+
+function Playhead({ t }) {
+  return (
+    <span
+      aria-hidden="true"
+      className="absolute top-0 bottom-0"
+      style={{ left: `${t * 100}%`, width: 1.5, background: 'var(--kol-accent-primary)' }}
+    />
+  )
+}
+
+function TrackRow({ track, t, selected, setSelected, writeKeys }) {
+  const laneRef = useRef(null)
+  /* Local drag state — committed once on pointer-up. */
+  const drag = useRef(null)
+  const [, force] = useState(0)
+
+  const fracFromEvent = (e) => {
+    const r = laneRef.current.getBoundingClientRect()
+    return Math.min(1, Math.max(0, (e.clientX - r.left) / r.width))
+  }
+
+  const isSel = (i) => selected && selected.trackId === track.id && selected.index === i
+
+  const onLanePointerDown = (e) => {
+    if (e.target.dataset.diamond !== undefined) return
+    /* Add a key at the click position, valued at the track's current value
+     * there (no visual jump), then select it. */
+    const clickT = fracFromEvent(e)
+    const v = sampleTrack(track.keys, clickT)
+    const next = [...track.keys, { t: clickT, v, easing: 'linear' }].sort((a, b) => a.t - b.t)
+    writeKeys(track, next)
+    setSelected({ trackId: track.id, index: next.findIndex((k) => k.t === clickT) })
+  }
+
+  const onDiamondPointerDown = (i) => (e) => {
+    e.stopPropagation()
+    if (e.altKey) {
+      /* alt-click deletes (min 1 key stays — an empty track is a broken binding) */
+      if (track.keys.length > 1) {
+        writeKeys(track, track.keys.filter((_, j) => j !== i))
+        setSelected(null)
+      }
+      return
+    }
+    e.currentTarget.setPointerCapture(e.pointerId)
+    drag.current = { index: i, t: track.keys[i].t }
+    setSelected({ trackId: track.id, index: i })
+  }
+  const onDiamondPointerMove = (i) => (e) => {
+    if (!drag.current || drag.current.index !== i) return
+    drag.current.t = fracFromEvent(e)
+    force((n) => n + 1)
+  }
+  const onDiamondPointerUp = (i) => () => {
+    if (!drag.current || drag.current.index !== i) return
+    const moved = { ...track.keys[i], t: drag.current.t }
+    const next = track.keys.map((k, j) => (j === i ? moved : k))
+    drag.current = null
+    writeKeys(track, next)
+    setSelected(null)
+  }
+
+  return (
+    <div className="flex items-center gap-3">
+      <span className="kol-helper-10 text-meta truncate shrink-0 text-right" style={{ width: 120 }} title={track.label}>
+        {track.label}
+      </span>
+      <div
+        ref={laneRef}
+        className="relative flex-1 h-5 rounded cursor-copy"
+        style={{ background: 'var(--kol-fg-04)' }}
+        onPointerDown={onLanePointerDown}
+      >
+        <Playhead t={t} />
+        {track.keys.map((k, i) => {
+          const kt = drag.current?.index === i ? drag.current.t : k.t
+          return (
+            <span
+              key={i}
+              data-diamond=""
+              onPointerDown={onDiamondPointerDown(i)}
+              onPointerMove={onDiamondPointerMove(i)}
+              onPointerUp={onDiamondPointerUp(i)}
+              title={`t=${kt.toFixed(2)} v=${typeof k.v === 'number' ? Math.round(k.v * 100) / 100 : k.v} (alt-click deletes)`}
+              className="absolute top-1/2 cursor-grab"
+              style={{
+                left: `${kt * 100}%`,
+                width: 9, height: 9,
+                transform: 'translate(-50%, -50%) rotate(45deg)',
+                background: isSel(i) ? 'var(--kol-accent-primary)' : 'var(--kol-fg-emphasis)',
+                borderRadius: 1.5,
+              }}
+            />
+          )
+        })}
+      </div>
+    </div>
+  )
+}
+
+function SelectedKeyEditor({ tracks, selected, setSelected, writeKeys, easingOptions }) {
+  if (!selected) return null
+  const track = tracks.find((tr) => tr.id === selected.trackId)
+  const key = track?.keys[selected.index]
+  if (!key) return null
+
+  const patchKey = (patch) => {
+    writeKeys(track, track.keys.map((k, i) => (i === selected.index ? { ...k, ...patch } : k)))
+  }
+  const isNum = typeof key.v === 'number'
+
+  return (
+    <div className="flex items-center gap-2 pt-1">
+      <span className="kol-helper-10 text-meta shrink-0">key @ {key.t.toFixed(2)}</span>
+      <Input
+        variant="ghost" size="sm" chars={7}
+        type={isNum ? 'number' : 'text'}
+        value={String(key.v)}
+        onChange={(e) => patchKey({ v: isNum ? Number(e.target.value) || 0 : e.target.value })}
+      />
+      <Dropdown
+        variant="subtle" size="sm"
+        options={easingOptions}
+        value={Array.isArray(key.easing) ? 'linear' : (key.easing ?? 'linear')}
+        onChange={(v) => patchKey({ easing: v })}
+      />
+      <button
+        type="button"
+        className="kol-helper-10 text-meta hover:text-emphasis px-2"
+        style={{ background: 'transparent', border: 'none', cursor: 'pointer' }}
+        onClick={() => {
+          if (track.keys.length > 1) writeKeys(track, track.keys.filter((_, i) => i !== selected.index))
+          setSelected(null)
+        }}
+      >
+        Delete key
+      </button>
+      <button
+        type="button"
+        className="kol-helper-10 text-meta hover:text-emphasis px-2 ml-auto"
+        style={{ background: 'transparent', border: 'none', cursor: 'pointer' }}
+        onClick={() => setSelected(null)}
+      >
+        Close
+      </button>
+    </div>
+  )
+}
+
+/**
+ * TimelineDock — the keyframe timeline, docked below a canvas.
+ *
+ *   [t readout] [scrub ruler ................................ playhead]
+ *   [track label] [lane: ◆ diamonds at t · click adds · drag moves · alt-click deletes]
+ *   [selected key: value · easing · delete]
+ *
+ * Collapses to NOTHING while there are no tracks, so a static editor pays
+ * zero chrome. Drags commit on pointer-up — one `onChange` per gesture, so a
+ * consumer's undo gets one entry instead of a flood.
+ *
+ * Lifted from kol-fxr's editor (`params/TimelineDock.jsx`,
+ * `editor-panels-the-held-specs` B3, 2026-09-03) with its couplings dropped
+ * exactly as the row asked: `collectTracks`, which walked fxr's layer tree
+ * for `{ bind: 'track' }` bindings, is the CONSUMER's — it hands in a flat
+ * `tracks` array; `updateLayer` is `onChange(trackId, keys)`; and the clock
+ * is two props, `t` and `onSeek`, so any clock drives it. fxr's `transport` is
+ * an external store precisely so 60fps ticks re-render only bound renderers;
+ * a consumer keeps that property by wrapping this in the one component that
+ * subscribes to its clock. The clock itself does not ship.
+ *
+ * @param {Array<{id: string, label: string, keys: Array<{t: number, v: any, easing?: string}>}>} tracks - One lane each, `t` in 0..1; empty renders nothing
+ * @param {number} t - The clock, 0..1
+ * @param {Function} onSeek - `(t) => void` — the ruler scrubbed
+ * @param {Function} onChange - `(trackId, keys) => void` — a track's keys after an add, move, edit or delete; already sorted by `t`
+ * @param {Array<{value: string, label: string}>} [easingOptions] - The key editor's easing menu (default: `TIMELINE_EASINGS`)
+ * @param {string} [className] - Extra classes on the dock
+ */
+export default function TimelineDock({ tracks = [], t = 0, onSeek, onChange, easingOptions = TIMELINE_EASINGS, className = '' }) {
+  const [selected, setSelected] = useState(null)   /* { trackId, index } */
+
+  if (tracks.length === 0) return null
+
+  const writeKeys = (track, nextKeys) => {
+    const sorted = [...nextKeys].sort((a, b) => a.t - b.t)
+    onChange?.(track.id, sorted)
+  }
+
+  return (
+    <div className={`kol-timeline-dock border-t border-fg-08 px-4 py-2 flex flex-col gap-1 select-none ${className}`.trim()} style={{ background: 'var(--kol-surface-primary)' }}>
+      <ScrubRuler t={t} onSeek={onSeek} />
+      {tracks.map((track) => (
+        <TrackRow key={track.id} track={track} t={t} selected={selected} setSelected={setSelected} writeKeys={writeKeys} />
+      ))}
+      <SelectedKeyEditor tracks={tracks} selected={selected} setSelected={setSelected} writeKeys={writeKeys} easingOptions={easingOptions} />
+    </div>
+  )
+}