@kolkrabbi/kol-hardware 0.6.1 → 0.8.0

package/README.md

@@ -58,4 +58,4 @@ Hardware is theme-INVARIANT — a knob cap is black on a white panel too — so
 ## Consumer requirements
 
 - **CSS** ships in `@kolkrabbi/kol-theme` (`kol-components-controls.css`, in the theme umbrella; a `core` consumer imports it as a domain pack) — this package ships JS only.
-- Tailwind v4 `@source "…/node_modules/@kolkrabbi/kol-hardware/src"` for the utility classes inside — or `@import "@kolkrabbi/kol-theme/kol-sources.css"`, which lists it since kol-theme 0.152.0.
+- Tailwind v4 `@source "…/node_modules/@kolkrabbi/kol-hardware/src"` for the utility classes inside — the explicit line, not kol-theme's `kol-sources.css`, which reaches nothing in a pnpm workspace.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-hardware",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "private": false,
   "description": "Panel controls for instruments",
   "license": "MIT",
@@ -20,9 +20,9 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.290.0",
-    "@kolkrabbi/kol-icons": "^0.41.0",
-    "@kolkrabbi/kol-theme": "^0.183.0"
+    "@kolkrabbi/kol-component": "^0.311.0",
+    "@kolkrabbi/kol-icons": "^0.52.0",
+    "@kolkrabbi/kol-theme": "^0.196.0"
   },
   "files": [
     "src",

package/src/frames/FlipCard.jsx

@@ -4,22 +4,30 @@
  * to its patch panel. The body turns; everything around it holds still, so the back is the same
  * shaped object as the front.
  *
+ * THE FACES SWAP BY BACKFACE, NOT BY A CLOCK (FlipCardFaceSwap, kol-monitor 2026-10-24 — user: *"the card flipps,
+ * but the image snaps in once its landed. not believable."*). It swapped `visibility` at a fixed duration / 2, but
+ * `ease` crosses edge-on at ~a third of the turn, so from there to the swap neither face showed — a blank card for
+ * ~110ms of a 450 — and the back popped in near the end. Both faces hide their backface and the back is pre-rotated
+ * 180° in the preserve-3d turner, so the back shows exactly as the card passes edge-on, whatever the easing. The
+ * face that is away is `inert` (and aria-hidden), which is what the visibility had been for: out of tab order.
+ *
  * @param {boolean}   flipped
  * @param {ReactNode} front · back
  * @param {number|string} width   the card's width (the back is laid over the front at it)
  * @param {number}    duration    ms (default 450, mirror's)
  */
 export default function FlipCard({ flipped = false, front, back, width, duration = 450, className = '' }) {
-  const half = `visibility 0s ${duration / 2}ms`
+  const hidden = { backfaceVisibility: 'hidden', WebkitBackfaceVisibility: 'hidden' }
   return (
     <div className={className} style={{ perspective: 1400, position: 'relative', width }}>
       <div style={{ transition: `transform ${duration}ms ease`, transformStyle: 'preserve-3d', transform: flipped ? 'rotateY(180deg)' : 'none' }}>
-        <div style={{ backfaceVisibility: 'hidden', transition: half, visibility: flipped ? 'hidden' : 'visible' }}>
+        <div aria-hidden={flipped || undefined} inert={flipped || undefined} style={hidden}>
           {front}
         </div>
         <div
-          aria-hidden={!flipped}
-          style={{ position: 'absolute', inset: 0, transform: 'rotateY(180deg)', backfaceVisibility: 'hidden', overflowY: 'auto', scrollbarWidth: 'none', transition: half, visibility: flipped ? 'visible' : 'hidden' }}
+          aria-hidden={!flipped || undefined}
+          inert={!flipped || undefined}
+          style={{ position: 'absolute', inset: 0, transform: 'rotateY(180deg)', overflowY: 'auto', scrollbarWidth: 'none', ...hidden }}
         >
           {back}
         </div>

package/src/frames/useFloating.js

@@ -0,0 +1,70 @@
+// useFloating — a panel you can drag around the stage and scale from a corner.
+//
+// LIFTED FROM TWO COPIES (UseFloatingHook, kol-mirror 2026-10-28 — user: *"seems like DS should tho?"*): kol-monitor's
+// hook (kol-ds-ui apps/rack-hub/src/stage/useFloating.js, monitor's own beside it) and kol-mirror's copy of it
+// (src/hooks/useFloating.js, 2026-10-03), which differed by one line — the cursor test also lets `nwse-resize` through, for
+// a corner grip. That line is in: a grip that declares `cursor: nwse-resize` drags `onResize`, and monitor, which wires no
+// grip, is unchanged by it.
+//
+// Window listeners rather than pointer capture, the same shape RackViewport's
+// pan uses, so a drag survives the pointer leaving the handle. `scale` is CSS
+// `zoom` at the call site: canvases inside re-measure through the shared
+// ResizeObserver instead of being upsampled.
+//
+//   const panel = useFloating({ x: 40, y: 40, scale: 1 })
+//   <div style={{ left: panel.box.x, top: panel.box.y, zoom: panel.box.scale }} onPointerDown={panel.onDrag}>
+//     …<span style={{ cursor: 'nwse-resize' }} onPointerDown={panel.onResize} />
+//   </div>
+
+import { useCallback, useRef, useState } from 'react'
+
+export const FLOATING_MIN_SCALE = 0.35
+export const FLOATING_MAX_SCALE = 2.5
+
+export function useFloating(initial) {
+  const [box, setBox] = useState(initial)
+  const boxRef = useRef(box)
+  boxRef.current = box
+
+  // Both gestures share one shape: capture the start, translate pointer delta,
+  // release on pointerup.
+  const gesture = useCallback((e, onDelta) => {
+    if (e.button !== 0) return
+    /* A press on a CONTROL belongs to that control; anything else drags. The
+       test is the cursor, not a selector list: every control in this repo
+       declares its own (`ns-resize` on knobs and sliders, `pointer` on keys and
+       jacks, `text` on inputs), so one computed read covers them all and a new
+       control needs no entry here. Excluding `[data-module-id]` — the obvious
+       list-based guard — made the whole dock undraggable, since every pixel of
+       it is inside a module. `nwse-resize` passes: it is the corner grip's own. */
+    const cursor = getComputedStyle(e.target).cursor
+    if (cursor !== 'auto' && cursor !== 'default' && cursor !== 'grab' && cursor !== 'nwse-resize') return
+    e.preventDefault()
+    e.stopPropagation()
+    const px = e.clientX
+    const py = e.clientY
+    const start = boxRef.current
+    const move = (ev) => setBox(onDelta(start, ev.clientX - px, ev.clientY - py))
+    const up = () => {
+      window.removeEventListener('pointermove', move)
+      window.removeEventListener('pointerup', up)
+    }
+    window.addEventListener('pointermove', move)
+    window.addEventListener('pointerup', up)
+  }, [])
+
+  const onDrag = useCallback((e) => {
+    gesture(e, (start, dx, dy) => ({ ...start, x: start.x + dx, y: start.y + dy }))
+  }, [gesture])
+
+  // Corner handle: right/down grows. One axis drives it so a diagonal drag
+  // doesn't fight itself — the larger movement wins.
+  const onResize = useCallback((e) => {
+    gesture(e, (start, dx, dy) => {
+      const d = Math.abs(dx) > Math.abs(dy) ? dx : dy
+      return { ...start, scale: Math.min(FLOATING_MAX_SCALE, Math.max(FLOATING_MIN_SCALE, start.scale + d / 400)) }
+    })
+  }, [gesture])
+
+  return { box, onDrag, onResize, setBox }
+}

package/src/index.js

@@ -16,6 +16,9 @@
 // value
 export { default as Knob } from './value/Knob.jsx'
 export { default as Fader } from './value/Fader.jsx'
+/* any value control made patchable — an expression in its readout, a modulation source on right-click (2026-10-28) */
+export { default as Modulatable } from './value/Modulatable.jsx'
+export { default as useExpressionValue } from './value/useExpressionValue.js'
 export { default as ParamSheet } from './value/ParamSheet.jsx'
 /* moved to kol-component with the controls that arm it (2026-10-01); re-exported so imports hold */
 export { armLongPress } from '@kolkrabbi/kol-component'
@@ -35,6 +38,11 @@ export { default as ModuleHeader } from './panel/ModuleHeader.jsx'
 export { default as ModuleFrame } from './frames/ModuleFrame.jsx'
 export { default as ChannelStrip } from './frames/ChannelStrip.jsx'
 export { default as FlipCard } from './frames/FlipCard.jsx'
+/* a panel dragged by its body and scaled from a corner grip — monitor's and mirror's hook, one copy (2026-10-28) */
+export { useFloating, FLOATING_MIN_SCALE, FLOATING_MAX_SCALE } from './frames/useFloating.js'
+/* the transport's face (2026-10-28): the timeline strip and the scrubber over a `createTransport()` clock, and its hooks */
+export { default as TimeStrip, Scrubber } from './panel/TimeStrip.jsx'
+export { useTransport, useTransportPlaying, useTransportNow } from './panel/useTransport.js'
 /* the rack (2026-10-01, user ruling: it comes into the design system) — the case, its 1U/3U rows
  * and the HP slot, lifted from kol-monitor; what mounts where and routing stay in the consumer */
 export { default as RackCase, RackRow, RackSlot } from './frames/Rack.jsx'

package/src/panel/SignalReference.jsx

@@ -73,7 +73,7 @@ function Tabs({ sections, tabs, saved, onPick, onAppend }) {
       <TabsRow tabs={visible} value={current?.id} onChange={setTab} />
       <div className="flex min-h-0 flex-col gap-4 overflow-y-auto">
         {current?.id === 'saved' && !saved?.length
-          ? <div className="kol-helper-10 text-fg-48">Nothing saved yet.</div>
+          ? <div className="kol-mono-10 text-fg-48">Nothing saved yet.</div>
           : list.map((s) => <Section key={s.title} section={s} onPick={onPick} onAppend={onAppend} showTitle={list.length > 1} />)}
       </div>
     </div>
@@ -93,7 +93,7 @@ function Panel({ sections, tabs, saved, onPick, onAppend }) {
       </div>
       <div className="flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto p-4" style={{ scrollbarWidth: 'none' }}>
         {current?.id === 'saved' && !saved?.length
-          ? <div className="kol-helper-10 text-fg-48">Nothing saved yet.</div>
+          ? <div className="kol-mono-10 text-fg-48">Nothing saved yet.</div>
           : list.map((s) => <Section key={s.title} section={s} onPick={onPick} onAppend={onAppend} showTitle={list.length > 1} />)}
       </div>
     </div>

package/src/panel/TimeStrip.jsx

@@ -0,0 +1,121 @@
+import { useRef } from 'react'
+import { seekToSeconds } from '../signal/transport.js'
+import { useTransport, useTransportNow } from './useTransport.js'
+
+/**
+ * TimeStrip — the one clock drawn as a line you can grab (user 2026-10-15:
+ * *"loop section? or timeline preview with scrubber? like |-->----------|"* and
+ * *"a timeline section like fxr labs has, it could be hidden by default but
+ * shown on shortcut"*).
+ *
+ * Two faces over ONE scrubber: `Scrubber` sits on the Transport panel; the
+ * default export is the studio's bottom strip, fxr labs' shape (`docs/
+ * documentation/05-blueprint/_assets/ref-fxr-timeline.png`) — a readout column,
+ * a ruler with the head, and the loop row with its start marked "1" in the
+ * accent (*"a thin yellow or accent color vertical divider with a label showing
+ * where it starts"*).
+ *
+ * Grabbing never starts or stops the clock; it moves the head (`transport.seek`).
+ *
+ * kol-mirror's `components/mirror/TimeStrip.jsx`, carried into kol-hardware (TransportAndTimeline, 2026-10-28): the same
+ * strip and scrubber, reading the clock they are handed (`transport`, from `createTransport()`) instead of mirror's own
+ * module. What an app lays on the strip under the bar — kol-fxr's keyframe lanes — goes in `children`, on the same span.
+ */
+
+/* The visible span: the loop window's far edge, at least four seconds, and on a
+   free-running clock it grows in four-second steps to keep the head on screen. */
+function spanOf(t, now) {
+  const far = Math.max(t.loopIn, t.loopOut, 4)
+  const free = t.mode === 'forward' && !t.looping
+  return free && now > far ? Math.ceil(now / 4) * 4 : far
+}
+
+/* The bar itself — the loop window shaded, IN marked in the accent, the head. */
+function Bar({ transport, t, now, span, height = 14, marker = false }) {
+  const ref = useRef(null)
+  const drag = useRef(false)
+  const at = (e) => {
+    const box = ref.current.getBoundingClientRect()
+    seekToSeconds(transport, Math.max(0, Math.min(1, (e.clientX - box.left) / box.width)) * span)
+  }
+  const a = Math.min(t.loopIn, t.loopOut)
+  const b = Math.max(t.loopIn, t.loopOut)
+  const pct = (x) => `${Math.max(0, Math.min(100, (x / span) * 100))}%`
+  return (
+    <div
+      ref={ref}
+      className="relative w-full cursor-ew-resize select-none"
+      style={{ height, background: 'var(--kol-fg-08)', borderRadius: 2, touchAction: 'none' }}
+      onPointerDown={(e) => { drag.current = true; e.currentTarget.setPointerCapture(e.pointerId); at(e) }}
+      onPointerMove={(e) => { if (drag.current) at(e) }}
+      onPointerUp={() => { drag.current = false }}
+      title="Drag to move the head (↑ start · ↓ end)"
+    >
+      {/* the loop window — lit when the clock wraps inside it */}
+      <div
+        className="absolute top-0 bottom-0"
+        style={{ left: pct(a), width: pct(b - a), background: t.looping || t.mode !== 'forward' ? 'var(--kol-fg-24)' : 'var(--kol-fg-12)' }}
+      />
+      {marker && (
+        <div className="absolute top-0 bottom-0" style={{ left: pct(a), width: 1, background: 'var(--kol-accent-primary)' }}>
+          <span className="absolute kol-helper-10" style={{ left: 3, top: 0, lineHeight: `${height}px`, color: 'var(--kol-accent-primary)' }}>1</span>
+        </div>
+      )}
+      <div className="absolute top-0 bottom-0" style={{ left: pct(b), width: 1, background: 'var(--kol-fg-24)' }} />
+      {/* the head */}
+      <div className="absolute" style={{ left: pct(now), top: -2, bottom: -2, width: 2, marginLeft: -1, background: 'var(--kol-fg-96)' }} />
+    </div>
+  )
+}
+
+/** The Transport panel's strip: `|-->----------|`, IN to OUT, grab to move. */
+export function Scrubber({ transport, width = 232 }) {
+  const t = useTransport(transport)
+  const now = useTransportNow(transport)
+  return (
+    <div style={{ width }}>
+      <Bar transport={transport} t={t} now={now} span={spanOf(t, now)} height={10} />
+    </div>
+  )
+}
+
+/** The studio's bottom strip — hidden by default, `B` shows it. `children` render under the bar, on its span (lanes). */
+export default function TimeStrip({ transport, onClose, children }) {
+  const t = useTransport(transport)
+  const now = useTransportNow(transport)
+  const span = spanOf(t, now)
+  const ticks = Array.from({ length: Math.floor(span) + 1 }, (_, i) => i)
+  return (
+    <div
+      className="absolute left-0 right-0 bottom-0 flex items-stretch gap-4 px-4 py-3 border-t border-fg-08 kol-helper-10 group"
+      style={{ background: 'var(--kol-surface-primary)', zIndex: 'var(--kol-z-overlay)' }}
+    >
+      <div className="flex flex-col justify-between shrink-0 text-fg-64" style={{ width: 112, fontVariantNumeric: 'tabular-nums' }}>
+        <span>{now.toFixed(2)} / {span.toFixed(2)} s</span>
+        <span className="text-fg-96">Loop {t.looping || t.mode !== 'forward' ? 'on' : 'off'}</span>
+      </div>
+      <div className="flex flex-col flex-1 gap-2" style={{ minWidth: 0 }}>
+        {/* the ruler — a tick a second, a number every second until it crowds */}
+        <div className="relative w-full" style={{ height: 12 }}>
+          {ticks.map((s) => (
+            <span key={s} className="absolute text-fg-32" style={{ left: `${(s / span) * 100}%`, transform: s ? 'translateX(-50%)' : undefined }}>
+              {span <= 16 || s % 4 === 0 ? s : ''}
+            </span>
+          ))}
+          <div className="absolute" style={{ left: `${Math.min(100, (now / span) * 100)}%`, top: 0, bottom: -4, width: 1, background: 'var(--kol-fg-96)' }} />
+        </div>
+        <Bar transport={transport} t={t} now={now} span={span} height={16} marker />
+        {typeof children === 'function' ? children({ now, span, state: t }) : children}
+      </div>
+      {onClose && <button
+        type="button"
+        onClick={onClose}
+        className="self-start text-fg-32 hover:text-fg-96 opacity-0 group-hover:opacity-100 cursor-pointer"
+        aria-label="Hide timeline"
+        title="Hide timeline (B)"
+      >
+        ×
+      </button>}
+    </div>
+  )
+}

package/src/panel/useTransport.js

@@ -0,0 +1,34 @@
+// The transport's React side (TransportAndTimeline, 2026-10-28) — the clock itself is plain JS, `createTransport()` in
+// `@kolkrabbi/kol-hardware/signal`. These read one clock: the state snapshot (re-renders on a change, never per frame), the
+// play state alone, and the shaped time per frame for whatever draws it (a head, a readout, a bound value).
+import { useEffect, useState, useSyncExternalStore } from 'react'
+
+const never = () => () => {}
+
+/* the state snapshot — `{ playing, rate, mode, loopIn, loopOut, swing, ease, looping, hold }`; mirror's useTransport */
+export function useTransport(transport) {
+  return useSyncExternalStore(transport ? transport.subscribe : never, () => transport?.state, () => transport?.state)
+}
+
+/* the play state alone — a <video> following play/pause without a per-frame subscription */
+export function useTransportPlaying(transport) {
+  return useSyncExternalStore(transport ? transport.subscribe : never, () => !!transport?.playing, () => !!transport?.playing)
+}
+
+/* the shaped time, sampled each frame at up to `fps` (mirror's TimeStrip `useNow`, 30 by default); `enabled: false` stops it */
+export function useTransportNow(transport, { fps = 30, enabled = true } = {}) {
+  const [now, setNow] = useState(() => transport?.now() ?? 0)
+  useEffect(() => {
+    if (!transport || !enabled) return undefined
+    let raf
+    let last = 0
+    const gap = 1000 / fps
+    const tick = (ts) => {
+      if (ts - last > gap) { last = ts; setNow(transport.now()) }
+      raf = requestAnimationFrame(tick)
+    }
+    raf = requestAnimationFrame(tick)
+    return () => cancelAnimationFrame(raf)
+  }, [transport, fps, enabled])
+  return now
+}

package/src/signal/index.js

@@ -4,3 +4,5 @@
 export { compileExpression, isExpression, fitRange, EXPRESSION_HELPERS } from './expression.js'
 export { envelopeAt, envelopeLength, gateSeconds, createEnvelope, stageSeconds, toRange, ADSR_DEFAULTS } from './adsr.js'
 export { EXPRESSION_SECTIONS, EXPRESSION_TABS, ADSR_PRESETS, ADSR_SECTIONS, ADSR_TABS } from './reference.js'
+// the transport — one clock, its loop window, shaped time (2026-10-28, kol-mirror's + kol-fxr's)
+export { createTransport, seekToSeconds, TRANSPORT_MODES, TRANSPORT_DEFAULTS } from './transport.js'

package/src/signal/signal.test.mjs

@@ -1,6 +1,6 @@
 // The signal engine's check: `node src/signal/signal.test.mjs`
 import assert from 'node:assert/strict'
-import { compileExpression, isExpression, fitRange, envelopeAt, envelopeLength, gateSeconds, createEnvelope, stageSeconds, EXPRESSION_SECTIONS } from './index.js'
+import { createTransport, seekToSeconds, compileExpression, isExpression, fitRange, envelopeAt, envelopeLength, gateSeconds, createEnvelope, stageSeconds, EXPRESSION_SECTIONS } from './index.js'
 
 // helpers span [min, max] — monitor's semantics; min 0 is mirror's / the editor's
 const w = compileExpression('wave(t)')
@@ -50,3 +50,23 @@ assert.equal(lvl, 0)
 assert.equal(env.stage, 'idle')
 
 console.log('signal: ok')
+
+// the transport: paused at boot, shaped time folds over the loop window, phase is 0..1, stop/home bump the epoch
+{
+  const tr = createTransport({ loopIn: 2, loopOut: 6 })
+  assert.equal(tr.playing, false)
+  assert.equal(tr.now(), 0)
+  assert.equal(tr.loopSeconds, 4)
+  tr.seek(5); assert.equal(tr.now(), 5)                 // free-running forward: raw time
+  tr.set({ looping: true }); tr.seek(5); assert.equal(tr.now(), 2 + 1)   // a loop: IN + wrap(5, 4)
+  assert.equal(tr.phase(), 0.25)
+  tr.set({ mode: 'reverse' }); tr.seek(1); assert.equal(tr.now(), 2 + 3)
+  seekToSeconds(tr, 3); assert.equal(tr.now(), 3)       // a scrubber lands where it points
+  const e = tr.epoch; tr.pause(); assert.equal(tr.epoch, e)   // pause never resets
+  tr.home(); assert.equal(tr.epoch, e + 1)
+  tr.stop(); assert.equal(tr.epoch, e + 2); assert.equal(tr.playing, false)
+  tr.setLoopSeconds(10); assert.equal(tr.state.loopOut, 12)
+  tr.set({ hold: true }); const h = tr.now(); tr.seek(0.5); assert.equal(tr.now(), h)  // hold freezes the output
+  tr.reset(); assert.equal(tr.state.mode, 'forward'); assert.equal(tr.state.loopOut, 8)
+}
+console.log('transport: ok')

package/src/signal/transport.js

@@ -0,0 +1,117 @@
+// The transport — one clock for everything time-driven (knob expressions, a scope, an animated stage, a timeline).
+// Plain JS, no React (TransportAndTimeline, kol-mirror 2026-10-28 — user: *"fxr uses the loop from transport controls. so
+// its two components together … this should live in DS"*).
+//
+// kol-mirror's `hooks/transport.js`, verbatim, made a factory: `createTransport()` returns one clock, so an app keeps its
+// own (`export const transport = createTransport()`). Its contract, carried:
+//   `now()` is the SHAPED time in seconds — it stands still while paused, runs at `rate`, and in reverse / ping-pong folds
+//   over the loop window (ease-in-out on the turnarounds by `ease`); `swing` slides each cycle's midpoint; `hold` freezes the
+//   output while time keeps running underneath. The loop is a WINDOW (`loopIn` · `loopOut`, absolute seconds, read
+//   min-first); `looping` arms it for forward, the folding modes always use it. Nothing autoplays.
+//
+// kol-fxr's transport (`editor/params/transport.js`) adds three things, also here:
+//   `phase()` — the position in the loop as 0..1 (fxr's `t`, the loops' `u`): `(now − in) / length`, wrapped
+//   `epoch` — a counter bumped ONLY by stop and home (never pause), so free-running state can key a fresh run on it
+//   `loopSeconds` / `setLoopSeconds(s)` — the window's length; setting it moves OUT, IN stays
+// What stays the app's: fxr's pointer and live sources, its keyframes. The clock reads `performance.now()` lazily and
+// notifies only on a state change; a renderer that needs every frame asks for one (`useTransportFrame`).
+
+export const TRANSPORT_MODES = ['forward', 'reverse', 'pingpong']
+/* NOTHING AUTOPLAYS (mirror, user 2026-08-28): a clock boots paused; `reset()` restores its shape, never its run state */
+export const TRANSPORT_DEFAULTS = { playing: false, rate: 1, mode: 'forward', loopIn: 0, loopOut: 8, swing: 0, ease: 0, looping: false, hold: false }
+
+const nowSec = () => (typeof performance !== 'undefined' ? performance.now() : Date.now()) / 1000
+const easeInOut = (u) => (u < 0.5 ? 2 * u * u : 1 - Math.pow(-2 * u + 2, 2) / 2)
+const wrap = (x, m) => ((x % m) + m) % m
+
+/* SWING — "two ticks on one clock" (mirror, user 2026-08-28). Every loop cycle carries two beats; swing slides the midpoint
+   between them, so the first runs long in wall time and the second catches up — a pure reparameterisation of the cycle. */
+const swingU = (u, s) => {
+  if (!s) return u
+  const m = 0.5 + s * 0.4 // the moved midpoint: 0.5 (straight) → 0.9 (hard shuffle)
+  return u < m ? (u / m) * 0.5 : 0.5 + ((u - m) / (1 - m)) * 0.5
+}
+const swung = (r, L, s) => (s ? (Math.floor(r / L) + swingU(wrap(r, L) / L, s)) * L : r)
+
+export function createTransport(initial = {}) {
+  let state = { ...TRANSPORT_DEFAULTS, ...initial }
+  let base = 0 // rate-scaled seconds banked up to `anchor`
+  let anchor = nowSec()
+  let held = 0
+  let epoch = 0
+  const listeners = new Set()
+  const emit = () => listeners.forEach((l) => l())
+
+  const raw = () => (state.playing ? base + (nowSec() - anchor) * state.rate : base)
+  const windowOf = () => ({ a: Math.min(state.loopIn, state.loopOut), L: Math.max(0.1, Math.abs(state.loopOut - state.loopIn)) })
+
+  function shape(r) {
+    const { mode, swing, ease, looping } = state
+    const { a, L } = windowOf()
+    const s = swing / 100
+    if (mode === 'forward' && !looping) return swung(r, L, s)
+    const t = swung(r, L, s)
+    if (mode === 'forward') return a + wrap(t, L)
+    if (mode === 'reverse') return a + (L - wrap(t, L))
+    const p = wrap(t, 2 * L) / L // 0..2 — out and back
+    const leg = p <= 1 ? p : 2 - p
+    return a + (leg + (easeInOut(leg) - leg) * ease) * L
+  }
+
+  // Bank the elapsed time at the OLD rate before anything changes, so the clock never jumps.
+  const set = (patch) => {
+    // HOLD freezes the OUTPUT, not the clock — releasing it jumps to where the transport actually got to.
+    if (patch.hold === true && !state.hold) held = shape(raw())
+    base = raw()
+    anchor = nowSec()
+    state = { ...state, ...patch }
+    emit()
+  }
+
+  const transport = {
+    now: () => (state.hold ? held : shape(raw())),
+    /* the position in the loop as 0..1 — fxr's `t` */
+    phase() { const { a, L } = windowOf(); return wrap(transport.now() - a, L) / L },
+    get playing() { return state.playing },
+    get state() { return state },
+    get epoch() { return epoch },
+    get loopSeconds() { return windowOf().L },
+    play() { if (!state.playing) set({ playing: true }) },
+    pause() { if (state.playing) set({ playing: false }) },
+    toggle() { if (state.playing) transport.pause(); else transport.play() },
+    /* stop = pause + home + a new epoch (fxr's stop) */
+    stop() { base = 0; anchor = nowSec(); epoch++; state = { ...state, playing: false }; emit() },
+    /* THE HEAD (mirror, user 2026-10-15): START is raw 0 — in a loop or a fold that IS the window's start; END is the window's
+       far edge. Run state is untouched — moving the head never starts or stops the clock. Home is fxr's rewind: a new epoch. */
+    home() { base = 0; anchor = nowSec(); epoch++; emit() },
+    end() {
+      const { L } = windowOf()
+      const free = state.mode === 'forward' && !state.looping
+      base = free ? Math.max(state.loopIn, state.loopOut) : L - 0.001
+      anchor = nowSec()
+      emit()
+    },
+    /* the raw position, for a scrubber: shape(seek) lands on the timeline */
+    seek(r) { base = Math.max(0, r); anchor = nowSec(); emit() },
+    /* a 0..1 position in the loop (fxr's seek) */
+    seekPhase(u) { const { L } = windowOf(); transport.seek(wrap(u, 1) * L) },
+    setLoopSeconds(s) { const n = Math.max(0.1, Number(s) || 0.1); set({ loopOut: Math.min(state.loopIn, state.loopOut) + n }) },
+    /* restores the clock's SHAPE, never its run state */
+    reset() { const { playing, ...shapeDefaults } = TRANSPORT_DEFAULTS; set(shapeDefaults) },
+    set,
+    subscribe(l) { listeners.add(l); return () => listeners.delete(l) },
+  }
+  return transport
+}
+
+/* Timeline seconds → the raw position `seek` takes so `now()` lands there (mirror's TimeStrip `seekTo`).
+   ponytail: a ping-pong seek lands on the OUT leg; the return leg is the same picture mirrored. */
+export function seekToSeconds(transport, sec) {
+  const t = transport.state
+  const a = Math.min(t.loopIn, t.loopOut)
+  const L = Math.max(0.1, Math.abs(t.loopOut - t.loopIn))
+  if (t.mode === 'forward' && !t.looping) return transport.seek(sec)
+  const u = Math.max(0, Math.min(L - 0.001, sec - a))
+  if (t.mode === 'reverse') return transport.seek(L - u)
+  return transport.seek(u)
+}

package/src/value/Modulatable.jsx

@@ -0,0 +1,124 @@
+import { Children, cloneElement, isValidElement, useCallback, useEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import useExpressionValue from './useExpressionValue.js'
+
+/**
+ * Modulatable — any value control, made patchable: an EXPRESSION in its readout and a MODULATION SOURCE on right-click.
+ * kol-mirror's `RotaryDial` adapter and its `ModulationAssign` menu, carried (ModulatableControls, 2026-10-28 — user:
+ * *"expression generator engine lives in DS, rotary dial lives in DS. nothing here is unique to mirror except that it homes
+ * modulation source"*). The app passes its sources and its clock; the behaviour is the DS's.
+ *
+ * A WRAPPER, NOT A PROP ON THE KNOB: the expression compiler is kol-hardware's (`./signal`), and kol-component — where the
+ * panel knob and slider live (kol-component's `Knob` / `Slider` at `variant="panel"`) — cannot import kol-hardware; `Knob` and `Fader` here
+ * are aliases on the retirement ledger, which may not gain behaviour. So the seam wraps the control:
+ *
+ *   <Modulatable label="Gain" value={v} onChange={setV} min={0} max={100} bus={busRef} clock={transport}>
+ *     <Knob variant="panel" size="lg" />
+ *   </Modulatable>
+ *
+ * The child gets `value` · `onChange` · `min` · `max` handed in. Under it, the readout: the label, then the value — click it
+ * and type a number or an expression (`wave(t)`, `A * 0.5`), Enter commits, Escape cancels; alt-click clears a running one,
+ * which reads in the accent. Right-click the control: None, then each source on the bus (`A`–`D` read as Expression A–D);
+ * picking one runs it (the source's name IS the expression) and lights the 5px `--kol-ctl-led-red` dot.
+ *
+ * @param {number}   value · {Function} onChange · {number} min · {number} max   the control's own
+ * @param {string}   label        the readout's label
+ * @param {Object}   bus          the modulation bus — a ref (`{ current: { A, B, … } }`) or the object; its keys are the sources
+ * @param {string[]} sources      the sources to offer, when not every bus key (defaults to the bus's keys)
+ * @param {Object|Function} clock a transport (`createTransport()`) or `() => seconds` — what `t` is
+ * @param {string|null} source    the assigned source, controlled; with `onSourceChange`. Uncontrolled, the wrapper keeps it
+ * @param {'default'|'dense'} density  the readout's type: mirror's 10px mono, or `dense` at 8
+ */
+const sourceLabel = (key) => (/^[A-D]$/.test(key) ? `Expression ${key}` : key)
+
+function ModulationMenu({ x, y, sources, current, onSelect, onClose }) {
+  const ref = useRef(null)
+  useEffect(() => {
+    const handle = (e) => { if (ref.current && !ref.current.contains(e.target)) onClose() }
+    const key = (e) => { if (e.key === 'Escape') onClose() }
+    document.addEventListener('pointerdown', handle)
+    window.addEventListener('keydown', key)
+    return () => { document.removeEventListener('pointerdown', handle); window.removeEventListener('keydown', key) }
+  }, [onClose])
+  return (
+    <div
+      ref={ref}
+      role="menu"
+      aria-label="Modulation"
+      className="flex flex-col bg-surface-secondary border border-fg-16 shadow-lg"
+      style={{ position: 'fixed', left: x, top: y, zIndex: 9999, borderRadius: '4px', minWidth: '100px', padding: '2px 0' }}
+    >
+      <div className="kol-helper-10 text-fg-32 px-2 py-1" style={{ borderBottom: '1px solid var(--kol-fg-08)' }}>Modulation</div>
+      {[{ id: null, label: 'None' }, ...sources.map((k) => ({ id: k, label: sourceLabel(k) }))].map((src) => (
+        <button
+          key={src.id ?? 'none'}
+          type="button"
+          role="menuitemradio"
+          aria-checked={current === src.id}
+          className={`kol-helper-12 px-2 py-1 text-left cursor-pointer bg-transparent border-0 hover:bg-fg-08 ${current === src.id ? 'text-accent-primary' : 'text-fg-96'}`}
+          onClick={() => { onSelect(src.id); onClose() }}
+        >
+          {src.label}
+        </button>
+      ))}
+    </div>
+  )
+}
+
+export default function Modulatable({ children, value = 0, onChange, min = 0, max = 100, label, bus, sources: sourcesProp, clock, source, onSourceChange, density = 'default', className = '' }) {
+  const [ownSource, setOwnSource] = useState(null)
+  const mod = source !== undefined ? source : ownSource
+  const assign = onSourceChange ?? setOwnSource
+  const [editing, setEditing] = useState(false)
+  const [draft, setDraft] = useState('')
+  const [menu, setMenu] = useState(null)
+  const { expr, commit, isAnimating } = useExpressionValue({ onChange, min, max, bus, clock })
+  const busObj = (bus && typeof bus === 'object' && 'current' in bus ? bus.current : bus) ?? {}
+  const sources = sourcesProp ?? Object.keys(busObj)
+
+  const onContextMenu = useCallback((e) => { e.preventDefault(); setMenu({ x: e.clientX, y: e.clientY }) }, [])
+  const select = useCallback((id) => { commit(id ?? ''); assign(id) }, [commit, assign])
+  const done = () => { setEditing(false); commit(draft); if (!String(draft).trim() || !isNaN(parseFloat(draft))) assign(null) }
+
+  const child = Children.only(children)
+  const control = isValidElement(child) ? cloneElement(child, { value, onChange, min, max }) : child
+  const dense = density === 'dense'
+
+  return (
+    <div className={`flex flex-col items-center ${className}`.trim()} data-modulatable>
+      <div className="relative select-none flex items-center justify-center" onContextMenu={onContextMenu}>
+        {control}
+        {mod && <span aria-label={`Modulated by ${sourceLabel(mod)}`} style={{ position: 'absolute', bottom: dense ? 2 : 4, right: 0, width: 5, height: 5, borderRadius: '50%', backgroundColor: 'var(--kol-ctl-led-red)' }} />}
+      </div>
+      {menu && createPortal(<ModulationMenu x={menu.x} y={menu.y} sources={sources} current={mod} onSelect={select} onClose={() => setMenu(null)} />, document.body)}
+      <div className={`flex items-center justify-center gap-1 w-full ${dense ? 'kol-helper-8' : ''}`} style={dense ? {} : { fontSize: '10px', fontFamily: 'var(--kol-font-family-mono)' }}>
+        {label && <span className="text-fg-64 uppercase">{label}</span>}
+        <span className="text-fg-96" style={{ minWidth: 32, textAlign: 'right', display: 'inline-block', overflow: 'hidden' }}>
+          {editing ? (
+            <input
+              type="text"
+              value={draft}
+              aria-label={`${label ?? 'Value'} — a number or an expression`}
+              onChange={(e) => setDraft(e.target.value)}
+              onBlur={done}
+              onKeyDown={(e) => { if (e.key === 'Enter') done(); if (e.key === 'Escape') setEditing(false) }}
+              autoFocus
+              className="bg-surface-tertiary"
+              style={{ width: '100%', height: 15, border: 'none', outline: 'none', color: 'inherit', fontSize: 'inherit', fontFamily: 'inherit', padding: 0, textAlign: 'right', borderRadius: 2, lineHeight: '15px' }}
+            />
+          ) : (
+            <button
+              type="button"
+              data-readout
+              className={`cursor-pointer bg-transparent border-0 p-0 ${isAnimating ? 'text-accent-primary' : ''}`}
+              style={{ font: 'inherit', color: isAnimating ? undefined : 'inherit' }}
+              onClick={(e) => { if (e.altKey && isAnimating) { commit(''); assign(null) } else { setDraft(expr || String(Math.round(value))); setEditing(true) } }}
+            >
+              {expr || `${Math.round(value)}`}
+            </button>
+          )}
+        </span>
+      </div>
+    </div>
+  )
+}

package/src/value/useExpressionValue.js

@@ -0,0 +1,49 @@
+// useExpressionValue — a value that can be an EXPRESSION: commit `wave(t)` and the value runs it every frame, clamped to
+// [min, max], on the clock it is given; commit a number and it is a number again. kol-mirror's `hooks/useExpressionValue.js`,
+// carried (ModulatableControls, 2026-10-28 — user: *"expression generator engine lives in DS, rotary dial lives in DS.
+// nothing here is unique to mirror except that it homes modulation source"*); its clock is a prop now, not mirror's module.
+//
+//   clock   a transport (`createTransport()`, its `now()`) or a `() => seconds`; unset, wall time since the expression began
+//   bus     the modulation bus — `{ current: { A: 0.4, … } }` (a ref the app owns) or the object itself; an expression may
+//           name its keys, and a source is just its name
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { compileExpression, isExpression } from '../signal/expression.js'
+
+const busOf = (bus) => (bus && typeof bus === 'object' && 'current' in bus ? bus.current : bus) ?? {}
+const secondsOf = (clock, t0) => (typeof clock === 'function' ? clock() : clock?.now ? clock.now() : performance.now() / 1000 - t0)
+
+export default function useExpressionValue({ onChange, min = 0, max = 100, bus, clock, initial = null }) {
+  const [expr, setExpr] = useState(initial)
+  const onChangeRef = useRef(onChange)
+  onChangeRef.current = onChange
+  const rafRef = useRef(null)
+  const frameRef = useRef(0)
+
+  useEffect(() => {
+    if (!expr) { frameRef.current = 0; return undefined }
+    const { ok, fn } = compileExpression(expr, { bus: Object.keys(busOf(bus)) })
+    if (!ok) { setExpr(null); return undefined }
+    frameRef.current = 0
+    const t0 = performance.now() / 1000
+    const tick = () => {
+      const f = frameRef.current++
+      try {
+        const raw = fn(secondsOf(clock, t0), f, min, max, busOf(bus))
+        onChangeRef.current?.(Math.max(min, Math.min(max, Math.round(raw))))
+      } catch { /* silent: the engine already holds the last good value */ }
+      rafRef.current = requestAnimationFrame(tick)
+    }
+    rafRef.current = requestAnimationFrame(tick)
+    return () => cancelAnimationFrame(rafRef.current)
+  }, [expr, min, max, bus, clock])
+
+  /* a number commits as a value; anything else is an expression; empty clears */
+  const commit = useCallback((draft) => {
+    const trimmed = String(draft ?? '').trim()
+    if (!trimmed) { setExpr(null); return }
+    const n = parseFloat(trimmed)
+    if (!isNaN(n) && !isExpression(trimmed)) { setExpr(null); onChangeRef.current?.(Math.round(n)) } else setExpr(trimmed)
+  }, [])
+
+  return { expr, commit, isAnimating: expr !== null }
+}