@kolkrabbi/kol-hardware 0.5.0 → 0.6.1

package/README.md

@@ -18,7 +18,7 @@ A different TIER from `kol-component`'s app atoms: a `kol-component` Slider is a
 | | `IconButton` | 1px-bordered icon key, momentary pulse |
 | indicators | `LED` | 6 / 8px lamp — red · yellow · green · white · blue, optional hit pad |
 | | `JackSocket`, `LabeledJack` | the 3.5mm jack, presentational: ring, hole, label, a rim that glows with `signalRef`. **Routing stays in the consumer** |
-| | `SignalScope` | the oscilloscope — a trace of any `sample(t)`, the knob range dashed, a live playhead; zoom X/Y, drag to pan, a clock `rate`, `loop` or one-shot on `trigger`, `height="fill"` |
+| | `SignalScope` | the oscilloscope — a trace of any `sample(t)`, the knob range dashed, a live playhead; zoom X/Y, drag to pan, a clock `rate` or a host's `now`, `loop` or one-shot on `trigger`, the played part in the accent, `height="fill"` |
 | panel | `PanelLabel` | label wrapper, four positions |
 | | `ModuleHeader` | Toggle + module name + edit-mode remove dot / bypass dot |
 | | `SignalReference` | an expression / envelope reference — `variant` `panel` (mirror's box) · `tabs` · `popover` (EX / REF) · `sheet` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-hardware",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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.262.0",
-    "@kolkrabbi/kol-icons": "^0.38.0",
-    "@kolkrabbi/kol-theme": "^0.174.0"
+    "@kolkrabbi/kol-component": "^0.290.0",
+    "@kolkrabbi/kol-icons": "^0.41.0",
+    "@kolkrabbi/kol-theme": "^0.183.0"
   },
   "files": [
     "src",

package/src/indicators/SignalScope.jsx

@@ -16,7 +16,13 @@ import { useEffect, useRef } from 'react'
  * THE CLOCK is the scope's: `rate` is time units per second (BPM / 60 for a beat clock), and
  * `playing` stops it where it is. `loop` (default) wraps the playhead over `sec`; off, the
  * playhead runs `0 → sec` once and holds at the end, and every change of `trigger` fires it
- * again — a one-shot envelope's gate.
+ * again — a one-shot envelope's gate. `now` hands the clock to the host instead: a
+ * `() => t` read every frame (mirror's desk transport), and `rate` / `playing` stop applying.
+ *
+ * THE PLAYED PART IS THE ACCENT (SignalScopePlayedTraceAndClock, kol-mirror): while live, the
+ * curve is faint and the trace up to the playhead, the playhead and its dot take
+ * `--kol-slider-playhead` (the accent unless a host overrides it) — where the position is in the
+ * signal, at a glance.
  *
  * @param {(t:number)=>number} sample
  * @param {number} min · max       the view (default 0…100)
@@ -30,20 +36,21 @@ import { useEffect, useRef } from 'react'
  * @param {number}  rate           time units per second (default 1)
  * @param {boolean} loop           wrap the playhead (default true); off = one pass per `trigger`
  * @param {number}  trigger        a counter — each change restarts the pass
+ * @param {()=>number} now         an external clock (time units); overrides the scope's own
  * @param {number|'fill'} height   px (default 320), or `fill` to take the parent's height
  */
 const css = (el, name, fallback) => getComputedStyle(el).getPropertyValue(name).trim() || fallback
 
 export default function SignalScope({
   sample, min = 0, max = 100, sec = 5, ofs = 0, zoomX = 1, zoomY = 1, panY = 0, onPan,
-  refLines = [0, 100], live = true, playing = true, rate = 1, loop = true, trigger = 0,
+  refLines = [0, 100], live = true, playing = true, rate = 1, loop = true, trigger = 0, now,
   height = 320, className = '',
 }) {
   const ref = useRef(null)
   const args = useRef({})
   const drawRef = useRef(null)
   const clock = useRef({ t: 0, last: 0 })
-  args.current = { sample, min, max, sec, ofs, zoomX, zoomY, panY, refLines, live, playing, rate, loop }
+  args.current = { sample, min, max, sec, ofs, zoomX, zoomY, panY, refLines, live, playing, rate, loop, now }
 
   // a trigger restarts the pass
   useEffect(() => { clock.current.t = 0 }, [trigger])
@@ -59,7 +66,8 @@ export default function SignalScope({
       const now = performance.now()
       const dt = (now - clock.current.last) / 1000
       clock.current.last = now
-      if (a.live && a.playing) clock.current.t += dt * a.rate
+      if (a.now) clock.current.t = a.now()
+      else if (a.live && a.playing) clock.current.t += dt * a.rate
       const fn = a.sample
       const dpr = window.devicePixelRatio || 1
       const { width: w, height: h } = canvas.getBoundingClientRect()
@@ -71,6 +79,7 @@ export default function SignalScope({
       ctx.clearRect(0, 0, w, h)
       const ink = css(canvas, '--kol-surface-on-primary', '#e8e4dc')
       const red = css(canvas, '--kol-ctl-led-red', '#e74c3c')
+      const accent = css(canvas, '--kol-slider-playhead', css(canvas, '--kol-accent-primary', ink))
       const pad = 12
       const span = (a.max - a.min) / (a.zoomY || 1) || 1
       const lo = (a.min + a.max) / 2 + a.panY - span / 2
@@ -101,26 +110,35 @@ export default function SignalScope({
       ctx.fillStyle = ink
       ctx.fillText(fmt(hi), 4, pad + 9)
       ctx.fillText(fmt(lo), 4, h - pad - 3)
-      // trace
-      ctx.globalAlpha = 1
-      ctx.strokeStyle = ink
-      ctx.lineWidth = 1.5
-      ctx.beginPath()
-      for (let x = 0; x <= w; x++) {
-        const y = toY(fn ? fn(a.ofs + (x / w) * dur) : lo)
-        if (x === 0) ctx.moveTo(x, y); else ctx.lineTo(x, y)
+      const trace = (to) => {
+        ctx.beginPath()
+        for (let x = 0; x <= to; x++) {
+          const y = toY(fn ? fn(a.ofs + (x / w) * dur) : lo)
+          if (x === 0) ctx.moveTo(x, y); else ctx.lineTo(x, y)
+        }
+        ctx.stroke()
       }
-      ctx.stroke()
+      const played = a.live && fn
+      // trace — faint under a playhead, the played part drawn over it
+      ctx.globalAlpha = played ? 0.15 : 1
+      ctx.strokeStyle = ink
+      ctx.lineWidth = played ? 1 : 1.5
+      trace(w)
+      ctx.globalAlpha = 1
       // playhead — over the base window, whatever the zoom (mirror's)
-      if (a.live && fn) {
-        const t = a.loop ? clock.current.t % a.sec : Math.min(clock.current.t, a.sec)
+      if (played) {
+        const t = a.loop ? ((clock.current.t % a.sec) + a.sec) % a.sec : Math.max(0, Math.min(clock.current.t, a.sec))
         const px = toX(t)
+        ctx.strokeStyle = accent
+        ctx.lineWidth = 2
+        if (px > 0) trace(Math.min(px, w))
         if (px >= 0 && px <= w) {
           const py = toY(fn(t))
-          ctx.globalAlpha = 0.25
+          ctx.globalAlpha = 0.4
+          ctx.lineWidth = 1
           ctx.beginPath(); ctx.moveTo(px, 0); ctx.lineTo(px, h); ctx.stroke()
           ctx.globalAlpha = 1
-          ctx.fillStyle = ink
+          ctx.fillStyle = accent
           ctx.beginPath(); ctx.arc(px, py, 3, 0, Math.PI * 2); ctx.fill()
         }
       }

package/src/value/EnvelopeGenerator.jsx

@@ -27,11 +27,11 @@ const adsrWindow = (adsr) => envelopeLength(adsr) * 1.15
 
 /**
  * useEnvelopeGenerator(options) — the generator's state, for a host that arranges the parts.
- * Takes the component's own options (`default*`, `saved`, `savedAdsr`, `onSave`, `onChange`).
+ * Takes the component's own options (`default*`, `saved`, `savedAdsr`, `onSave`, `onChange`, `now`).
  */
 export function useEnvelopeGenerator({
   defaultMode = 'equation', defaultExpr = 'wave(t)', defaultAdsr = ADSR_DEFAULTS,
-  saved, savedAdsr, onSave, onChange,
+  saved, savedAdsr, onSave, onChange, now,
 } = {}) {
   const [mode, setModeState] = useState(defaultMode)
   const [expr, setExprState] = useState(defaultExpr)
@@ -69,7 +69,7 @@ export function useEnvelopeGenerator({
   return {
     mode, setMode, expr, setExpr, compiled, adsr, setAdsr, view, setView, fit, reset,
     cycle, setCycle, playing, setPlaying, bpm, setBpm, trigger, fire: () => setTrigger((n) => n + 1),
-    heldSec, setHeldSec, save,
+    heldSec, setHeldSec, save, now,
     /* spread into <SignalReference> — the current mode's data, whichever shape it takes. Key the
      * element on `mode` so its open tab resets when the data changes under it. */
     reference: {
@@ -188,7 +188,9 @@ function EnvelopeHandles({ adsr, sec, onDragStart, onDrag, onDragEnd }) {
  * itself.
  *
  * TIME is the scope's clock: `bpm` sets its speed (60 BPM = one unit a second, so `t` reads as
- * seconds at the default and as beats at any other). Play / pause stops it where it is.
+ * seconds at the default and as beats at any other). Play / pause stops it where it is. `now`
+ * (`() => t`) hands the clock to the host — a desk transport — and the scope reads it instead;
+ * Play/Pause, BPM and Trigger are then not drawn, since the host's transport does their jobs.
  *
  * ADSR: four handles on the scope — A (attack time), D (decay time), S (at the end of the hold:
  * sideways = how long the gate holds, up/down = the sustain level), R (release time). The scope
@@ -205,6 +207,7 @@ function EnvelopeHandles({ adsr, sec, onDragStart, onDrag, onDragEnd }) {
  * @param {string}  defaultExpr
  * @param {object}  defaultAdsr        knob values 0…100, `hold` in seconds (`ADSR_DEFAULTS`)
  * @param {Array}   saved · savedAdsr  the host's own rows for each mode's Saved tab
+ * @param {()=>number} now           an external clock for the scope (overrides play / BPM)
  * @param {Function} onSave            `({ mode, code }) => void` — shows a Save button; `code` is the
  *                                     expression, or the envelope as `a10 d30 s70 r50 h1`
  */
@@ -223,14 +226,18 @@ export default function EnvelopeGenerator({ generator, reference = 'panel', clas
   const passSec = mode === 'equation' ? sec : envelopeLength(adsr)
   const panel = reference === true || reference === 'panel'
 
+  /* a host clock (`now`) owns play, speed and restart — the controls for them would do nothing, so
+   * they are not drawn (EnvelopeGeneratorHostClockControls, kol-mirror 2026-10-22). Cycle still
+   * acts: it decides whether the host's time wraps over the pass or holds at its end. */
+  const ownClock = !g.now
   const transport = (
     <div className="flex h-6 shrink-0 items-center gap-3">
-      <Button tone="ghost" size="sm" iconOnly={g.playing ? 'pause' : 'play'} aria-label={g.playing ? 'Pause' : 'Play'} onClick={() => g.setPlaying(!g.playing)} />
-      <Field label="BPM" value={g.bpm} chars={3} onCommit={(v) => g.setBpm(Math.max(1, Math.min(999, num(v, g.bpm))))} />
+      {ownClock && <Button tone="ghost" size="sm" iconOnly={g.playing ? 'pause' : 'play'} aria-label={g.playing ? 'Pause' : 'Play'} onClick={() => g.setPlaying(!g.playing)} />}
+      {ownClock && <Field label="BPM" value={g.bpm} chars={3} onCommit={(v) => g.setBpm(Math.max(1, Math.min(999, num(v, g.bpm))))} />}
       {mode === 'adsr' && (
         <>
           <Toggle value={g.cycle} onChange={g.setCycle} label="cycle" />
-          <Button tone="ghost" size="sm" onClick={g.fire}>Trigger</Button>
+          {ownClock && <Button tone="ghost" size="sm" onClick={g.fire}>Trigger</Button>}
         </>
       )}
       <span className="ml-auto text-fg-48">{mode === 'adsr' ? `${passSec.toFixed(2)} s` : ''}</span>
@@ -270,6 +277,7 @@ export default function EnvelopeGenerator({ generator, reference = 'panel', clas
             rate={g.bpm / 60}
             loop={mode === 'equation' || g.cycle}
             trigger={g.trigger}
+            now={g.now}
             className="absolute inset-0"
           />
           {mode === 'adsr' && (