@kolkrabbi/kol-component 0.198.0 → 0.200.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.198.0",
+  "version": "0.200.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/index.js

@@ -75,6 +75,9 @@ 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 { default as CurveEditor, CURVE_KINDS, defaultCurveFor } from './organisms/CurveEditor.jsx'
+export { default as KeyframeEditor, KEYFRAME_EASES, DEFAULT_KEYFRAMES } from './organisms/KeyframeEditor.jsx'
 export { pathD, pathBounds, shiftNode, normalizePath, scalePathNodes, normalizePathRings, rotatePathNodes, dist, nearestSegmentT, splitSegment, smoothNode } from './hooks/pathMath.js'
 
 // molecules

package/src/organisms/CurveEditor.jsx

@@ -0,0 +1,207 @@
+import Button from '../atoms/Button.jsx'
+import Input from '../atoms/Input.jsx'
+import Dropdown from '../molecules/Dropdown.jsx'
+import LabeledControl from '../molecules/LabeledControl.jsx'
+
+/* The six curve kinds the picker offers. A consumer with more passes `kinds`. */
+export const CURVE_KINDS = [
+  { value: 'epicycle', label: 'Epicycle' },
+  { value: 'polar',    label: 'Polar' },
+  { value: 'param2d',  label: 'Parametric 2D' },
+  { value: 'param3d',  label: 'Parametric 3D' },
+  { value: 'points',   label: 'Points' },
+  { value: 'maurer',   label: 'Maurer rose' },
+]
+
+const TAU = Math.PI * 2
+
+/* Fresh per-kind defaults — the engine's `defaultCustomFor`, kept as the
+ * default so a kind switch has somewhere to land. Injectable via `defaultFor`. */
+export function defaultCurveFor(kind) {
+  switch (kind) {
+    case 'epicycle': return { kind, turns: 2, terms: [{ amp: 1, freq: 1, phase: 0 }] }
+    case 'param2d':  return { kind, range: [0, TAU], x: 'sin(3*t)', y: 'sin(2*t + 0.6)' }
+    case 'param3d':  return { kind, range: [0, 6 * TAU], x: 'cos(t)', y: 'sin(t)', z: '0.3*t' }
+    case 'points':   return { kind, count: 1400, a: 'k*TAU/(PHI*PHI)', r: 'sqrt(k)' }
+    case 'maurer':   return { kind, n: 6, d: 71 }
+    default:         return { kind: 'polar', range: [0, 6 * TAU], r: '3*sin(6*th)' }
+  }
+}
+
+const num = (v, fb) => { const n = Number(v); return Number.isFinite(n) ? n : fb }
+
+/* Draft/commit number — `Input onCommit` IS the idiom since 0.196.0. */
+function NumberField({ value, onCommit, ...rest }) {
+  return <Input type="number" variant="filled" size="sm" {...rest} value={String(value)} onCommit={onCommit} />
+}
+
+/* Draft/commit text input for an expression, mono. A string that does not
+ * validate is STILL committed — the renderer keeps its last good function —
+ * and the field shows the hint until it is fixed. That is what makes live
+ * expression editing bearable; keep it. */
+function ExprField({ label, value, args, validate, onCommit }) {
+  const bad = validate && String(value ?? '').trim() !== '' && !validate(value, args)
+  return (
+    <LabeledControl label={label} hint={bad ? 'doesn’t compile — last good kept' : undefined}>
+      <Input
+        variant="filled" size="sm" className="w-full"
+        style={{ fontFamily: 'var(--kol-font-family-mono, monospace)', fontVariantLigatures: 'none' }}
+        value={value ?? ''}
+        onCommit={(v) => { if (v !== value) onCommit(v) }}
+      />
+    </LabeledControl>
+  )
+}
+
+/* Start/end of the curve's parameter range. */
+function RangeFields({ def, commit }) {
+  const [a, b] = def.range || [0, 1]
+  return (
+    <div className="grid grid-cols-2 gap-2">
+      <LabeledControl label="Start">
+        <NumberField value={a} onCommit={(v) => commit({ range: [num(v, a), b] })} />
+      </LabeledControl>
+      <LabeledControl label="End">
+        <NumberField value={b} onCommit={(v) => commit({ range: [a, num(v, b)] })} />
+      </LabeledControl>
+    </div>
+  )
+}
+
+/* Epicycle = a sum of rotating vectors; each term {amp, freq, phase} is one
+ * vector (add/remove terms = the vector array). */
+function TermsEditor({ def, commit }) {
+  const terms = def.terms || []
+  const setTerm = (i, key, v) => commit({ terms: terms.map((tm, j) => (j === i ? { ...tm, [key]: v } : tm)) })
+  const addTerm = () => commit({ terms: [...terms, { amp: 0.5, freq: 2, phase: 0 }] })
+  const removeTerm = (i) => commit({ terms: terms.filter((_, j) => j !== i) })
+  return (
+    <div className="flex flex-col gap-2">
+      <div className="flex items-center justify-between">
+        <span className="kol-helper-10 text-meta">Vectors</span>
+        <Button variant="primary" size="sm" onClick={addTerm}>Add</Button>
+      </div>
+      <div className="grid grid-cols-[1fr_1fr_1fr_auto] gap-1.5 items-center min-w-0 [&>*]:min-w-0">
+        <span className="kol-helper-10 text-fg-48 text-center">amp</span>
+        <span className="kol-helper-10 text-fg-48 text-center">freq</span>
+        <span className="kol-helper-10 text-fg-48 text-center">phase</span>
+        <span />
+        {terms.map((tm, i) => (
+          <TermRow key={i} term={tm} onSet={(k, v) => setTerm(i, k, v)} onRemove={() => removeTerm(i)} canRemove={terms.length > 1} />
+        ))}
+      </div>
+    </div>
+  )
+}
+
+function TermRow({ term, onSet, onRemove, canRemove }) {
+  const cell = (key, fallback) => (
+    <NumberField value={term[key] ?? fallback} onCommit={(v) => onSet(key, num(v, term[key] ?? fallback))} />
+  )
+  return (
+    <>
+      {cell('amp', 1)}
+      {cell('freq', 1)}
+      {cell('phase', 0)}
+      <Button variant="ghost" size="sm" onClick={onRemove} disabled={!canRemove} aria-label="Remove vector">×</Button>
+    </>
+  )
+}
+
+/**
+ * CurveEditor — curve authoring: a kind picker, per-kind ranges and
+ * EXPRESSION fields, and the epicycle term list.
+ *
+ * Lifted from kol-fxr's editor (`compose/inspectors/CurveEditor.jsx`,
+ * `editor-panels-the-held-specs` A4, 2026-09-03) with its two couplings
+ * dropped: the compiler (`loops/math/mathfn`) is the `validate` seam, and the
+ * stock-clip table (`loops/math/curves`) is the `stock` prop.
+ *
+ * FORK-ON-EDIT, kept exactly: while the layer shows a stock clip the editor
+ * displays that clip's definition (`value`), and the FIRST commit forks it —
+ * `onChange` fires with `fork: true` and the extras the fork should seed
+ * (`copies` / `spiral` from the stock clip, unless the caller says they were
+ * already moved). The shared clip table is never mutated; the caller writes
+ * `{ clip: 'custom', custom, ...extras }`. A kind switch replaces the whole
+ * def with that kind's defaults.
+ *
+ * @param {Object} value - The curve def being edited: `{ kind, range?, r?, x?, y?, z?, turns?, terms?, count?, a?, n?, d? }`
+ * @param {Function} onChange - `(nextDef, { fork, extras }) => void` — `fork` is true when this commit leaves a stock clip; `extras` carries what the fork seeds
+ * @param {{label: string, copies?: number, spiral?: number, layerCopies?: number, layerSpiral?: number}} [stock] - Present while the layer still shows a STOCK clip: its label, its authored `copies` / `spiral`, and the layer's current ones so the fork only seeds what the user has not moved. Omit once the curve is custom
+ * @param {Function} [validate] - `(expr, args) => boolean` — the consumer's compiler; omitted, every expression is accepted without a hint
+ * @param {Array<{value: string, label: string}>} [kinds] - The kind picker (default `CURVE_KINDS`)
+ * @param {Function} [defaultFor] - `(kind) => def` for a kind switch (default `defaultCurveFor`)
+ * @param {string} [className] - Extra classes on the editor
+ */
+export default function CurveEditor({ value, onChange, stock = null, validate, kinds = CURVE_KINDS, defaultFor = defaultCurveFor, className = '' }) {
+  const def = value ?? defaultFor('polar')
+  const kind = def.kind || 'polar'
+  const isCustom = stock == null
+
+  /* Any commit forks a stock clip — and seeds the copies/spiral the stock
+   * clip authored, unless the layer already moved them. */
+  const commit = (defPatch) => {
+    const extras = {}
+    if (!isCustom) {
+      if ((stock.layerCopies ?? 1) <= 1 && (stock.copies ?? 0) > 1) extras.copies = stock.copies
+      if (!((stock.layerSpiral ?? 0) > 0) && (stock.spiral ?? 0) > 0) extras.spiral = stock.spiral
+    }
+    onChange?.({ ...def, ...defPatch }, { fork: !isCustom, extras })
+  }
+  const setKind = (k) => {
+    if (k === kind) return
+    onChange?.(defaultFor(k), { fork: !isCustom, extras: {} })
+  }
+
+  return (
+    <div className={`kol-curve-editor flex flex-col gap-3 ${className}`.trim()}>
+      <span className="kol-helper-10 text-meta">Curve</span>
+      <Dropdown size="sm" variant="subtle" className="w-full" options={kinds} value={kind} onChange={setKind} />
+      {!isCustom && (
+        <p className="kol-helper-10 text-meta">Editing “{stock.label}” forks it to a custom curve.</p>
+      )}
+
+      {kind === 'epicycle' && (
+        <>
+          <LabeledControl label="Turns">
+            <NumberField value={def.turns ?? 1} onCommit={(v) => commit({ turns: num(v, def.turns ?? 1) })} />
+          </LabeledControl>
+          <TermsEditor def={def} commit={commit} />
+        </>
+      )}
+
+      {kind === 'polar' && (
+        <>
+          <RangeFields def={def} commit={commit} />
+          <ExprField label="r(th)" value={def.r} args={['th']} validate={validate} onCommit={(v) => commit({ r: v })} />
+        </>
+      )}
+
+      {(kind === 'param2d' || kind === 'param3d') && (
+        <>
+          <RangeFields def={def} commit={commit} />
+          <ExprField label="x(t)" value={def.x} args={['t']} validate={validate} onCommit={(v) => commit({ x: v })} />
+          <ExprField label="y(t)" value={def.y} args={['t']} validate={validate} onCommit={(v) => commit({ y: v })} />
+          {kind === 'param3d' && <ExprField label="z(t)" value={def.z} args={['t']} validate={validate} onCommit={(v) => commit({ z: v })} />}
+        </>
+      )}
+
+      {kind === 'points' && (
+        <>
+          <LabeledControl label="Count">
+            <NumberField value={def.count ?? 1400} onCommit={(v) => commit({ count: Math.max(1, Math.round(num(v, def.count ?? 1400))) })} />
+          </LabeledControl>
+          <ExprField label="a(k)" value={def.a} args={['k']} validate={validate} onCommit={(v) => commit({ a: v })} />
+          <ExprField label="r(k)" value={def.r} args={['k']} validate={validate} onCommit={(v) => commit({ r: v })} />
+        </>
+      )}
+
+      {kind === 'maurer' && (
+        <div className="grid grid-cols-2 gap-2">
+          <LabeledControl label="n"><NumberField value={def.n ?? 6} onCommit={(v) => commit({ n: num(v, def.n ?? 6) })} /></LabeledControl>
+          <LabeledControl label="d°"><NumberField value={def.d ?? 71} onCommit={(v) => commit({ d: num(v, def.d ?? 71) })} /></LabeledControl>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/organisms/KeyframeEditor.jsx

@@ -0,0 +1,136 @@
+import { useState } from 'react'
+import Button from '../atoms/Button.jsx'
+import Dropdown from '../molecules/Dropdown.jsx'
+import LabeledControl from '../molecules/LabeledControl.jsx'
+import Slider from '../molecules/Slider.jsx'
+
+const deg = (r) => Math.round(((r || 0) * 180) / Math.PI)
+const rad = (d) => (d * Math.PI) / 180
+
+/* The engine's easings by name; the curves are the consumer's interpolator's. */
+export const KEYFRAME_EASES = [
+  { value: 'linear', label: 'Linear' },
+  { value: 'in',     label: 'Ease in' },
+  { value: 'out',    label: 'Ease out' },
+  { value: 'inout',  label: 'Ease in-out' },
+]
+
+export const DEFAULT_KEYFRAMES = [
+  { t: 0, rot: [0, 0, 0], pos: [0, 0, 0], scale: 1, ease: 'inout' },
+  { t: 1, rot: [0, Math.PI * 2, 0], pos: [0, 0, 0], scale: 1, ease: 'inout' },
+]
+
+/**
+ * KeyframeEditor — a keyframe list over a pose track, kept sorted by `t`.
+ *
+ *   { t: 0..1, rot: [x, y, z] RADIANS, pos: [x, y, z], scale, ease }
+ *
+ * Rotations are stored in radians (engine-native) and EDITED IN DEGREES here.
+ * Selecting a key pauses the clock and seeks to its `t`, so the live render is
+ * the pose being edited; "Add @ playhead" reads the clock's current `t`.
+ *
+ * Lifted from kol-fxr's editor (`compose/inspectors/KeyframeEditor.jsx`,
+ * `editor-panels-the-held-specs` A5, 2026-09-03) with the transport singleton
+ * and the layer patch path dropped, as the row asked: the track is `keyframes`
+ * + `onChange`, the clock is `t` + `onSeek` + `onPause`. The engine's
+ * cycles arithmetic (a layer's phase runs N loops per transport loop) is the
+ * CONSUMER's — it hands in the layer-local `t` and maps `onSeek`'s local `t`
+ * back to its global playhead. The pose shape stays rot / pos / scale; the
+ * row notes it should be schema-described, and that is a design change
+ * rather than a port, so it is not done here.
+ *
+ * @param {Array<Object>} keyframes - The track; empty falls back to `DEFAULT_KEYFRAMES`
+ * @param {Function} onChange - `(keyframes) => void` — the whole track, sorted
+ * @param {number} t - The clock's current LAYER-LOCAL phase, 0..1 — what "Add @ playhead" stamps
+ * @param {Function} onSeek - `(t) => void` — a key was selected; seek the clock to its local `t`
+ * @param {Function} [onPause] - Called before the seek, so the render holds on the pose
+ * @param {Array<{value: string, label: string}>} [easeOptions] - The Ease menu (default `KEYFRAME_EASES`)
+ * @param {Array<Object>} [defaultKeyframes] - What an empty track shows (default `DEFAULT_KEYFRAMES`)
+ */
+export default function KeyframeEditor({
+  keyframes,
+  onChange,
+  t = 0,
+  onSeek,
+  onPause,
+  easeOptions = KEYFRAME_EASES,
+  defaultKeyframes = DEFAULT_KEYFRAMES,
+}) {
+  const kfs = Array.isArray(keyframes) && keyframes.length ? keyframes : defaultKeyframes
+  const [selected, setSelected] = useState(0)
+  const sel = Math.min(selected, kfs.length - 1)
+  const k = kfs[sel] || { rot: [0, 0, 0], pos: [0, 0, 0], scale: 1 }
+
+  const write = (next) => onChange?.(next)
+
+  const onSelect = (i) => {
+    setSelected(i)
+    onPause?.()
+    onSeek?.(kfs[i].t ?? 0)
+  }
+  const onAdd = () => {
+    const base = kfs[sel] || { rot: [0, 0, 0], pos: [0, 0, 0], scale: 1, ease: 'inout' }
+    const nk = {
+      t: Math.max(0, Math.min(1, t)),
+      rot: [...(base.rot || [0, 0, 0])],
+      pos: [...(base.pos || [0, 0, 0])],
+      scale: base.scale ?? 1,
+      ease: base.ease || 'inout',
+    }
+    const next = [...kfs, nk].sort((a, b) => a.t - b.t)
+    write(next)
+    setSelected(next.indexOf(nk))
+  }
+  const onDelete = () => {
+    if (kfs.length <= 1) return
+    write(kfs.filter((_, i) => i !== sel))
+    setSelected((s) => Math.max(0, s - 1))
+  }
+  const onPatch = (p) => write(kfs.map((kf, i) => (i === sel ? { ...kf, ...p } : kf)))
+
+  const setRot = (axis, d) => { const r = [...(k.rot || [0, 0, 0])]; r[axis] = rad(d); onPatch({ rot: r }) }
+  const setPos = (axis, v) => { const p = [...(k.pos || [0, 0, 0])]; p[axis] = v; onPatch({ pos: p }) }
+
+  const pose = (label, min, max, step, value, onValue) => (
+    <LabeledControl label={label}>
+      <Slider min={min} max={max} step={step} value={value} onChange={onValue} />
+    </LabeledControl>
+  )
+
+  return (
+    <div className="kol-keyframe-editor flex flex-col gap-3">
+      <span className="kol-helper-10 text-meta">Keyframes</span>
+      <div className="flex flex-col gap-1">
+        {kfs.map((kf, i) => (
+          <Button
+            key={i}
+            variant={i === sel ? 'primary' : 'secondary'}
+            size="sm"
+            className="w-full"
+            style={{ justifyContent: 'space-between' }}
+            onClick={() => onSelect(i)}
+          >
+            <span>Key {i + 1}</span>
+            <span className="kol-helper-10 tabular-nums">{Math.round((kf.t ?? 0) * 100)}%</span>
+          </Button>
+        ))}
+      </div>
+      <div className="flex gap-2">
+        <Button variant="primary" size="sm" className="flex-1" onClick={onAdd}>Add @ playhead</Button>
+        <Button variant="ghost" size="sm" title="Delete keyframe" onClick={onDelete} disabled={kfs.length <= 1}>Delete</Button>
+      </div>
+
+      <span className="kol-helper-10 text-meta">Pose</span>
+      {pose('Rotate X', -360, 360, 1, deg(k.rot?.[0]), (v) => setRot(0, v))}
+      {pose('Rotate Y', -360, 360, 1, deg(k.rot?.[1]), (v) => setRot(1, v))}
+      {pose('Rotate Z', -360, 360, 1, deg(k.rot?.[2]), (v) => setRot(2, v))}
+      {pose('Move X', -2, 2, 0.05, k.pos?.[0] || 0, (v) => setPos(0, v))}
+      {pose('Move Y', -2, 2, 0.05, k.pos?.[1] || 0, (v) => setPos(1, v))}
+      {pose('Move Z', -2, 2, 0.05, k.pos?.[2] || 0, (v) => setPos(2, v))}
+      {pose('Scale', 0.2, 2, 0.05, k.scale ?? 1, (v) => onPatch({ scale: v }))}
+      <LabeledControl label="Ease">
+        <Dropdown variant="subtle" size="sm" className="w-full" options={easeOptions} value={k.ease || 'inout'} onChange={(v) => onPatch({ ease: v })} />
+      </LabeledControl>
+    </div>
+  )
+}

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