@kolkrabbi/kol-hardware 0.2.0 → 0.3.0

package/README.md

@@ -11,17 +11,17 @@ A different TIER from `kol-component`'s app atoms: a `kol-component` Slider is a
 | value | `Knob` | SVG rotary — sizes sm 24 · md 32 · lg 40 · xl 64, 270° sweep, drag ns (200px = range), ⌥-click resets, touch long-press → `ParamSheet` |
 | | `Fader` | the rack slider — 2px track + 8px thumb, horizontal (flex-1 + readout) or vertical; long-press → `ParamSheet` |
 | | `ParamSheet`, `armLongPress` | touch: hold a control 500ms → a full-width bottom sheet with the DS `Slider` |
-| | `EnvelopeGenerator` | a value over time — an equation or an ADSR envelope — with the scope, window controls and reference |
+| | `EnvelopeGenerator` | a value over time — an equation or an ADSR envelope — filling its parent: the scope box, its controls and transport (BPM), and the reference panel. `useEnvelopeGenerator()` + `EnvelopeModeToggle` let a host arrange the parts |
 | switches | `Toggle` | LED-dot toggle, sm 8 · md 12 — momentary, blink, long-press, `forceLit` |
 | | `FlipToggle` | 2/3-position rocker, horizontal or vertical |
 | | `RockerSwitch` | I/O rocker, backlit paddle |
 | | `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 |
+| | `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"` |
 | panel | `PanelLabel` | label wrapper, four positions |
 | | `ModuleHeader` | Toggle + module name + edit-mode remove dot / bypass dot |
-| | `SignalReference` | an expression / envelope reference — `variant` `tabs` · `popover` (EX / REF) · `sheet` |
+| | `SignalReference` | an expression / envelope reference — `variant` `panel` (mirror's box) · `tabs` · `popover` (EX / REF) · `sheet` |
 | frames | `ModuleFrame` | a module's front panel — header pinned, body below |
 | | `ChannelStrip` | a mixer channel's face — power · control grid · action column · faders · footer, as slots |
 | | `FlipCard` | a face that turns over in place to its back |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-hardware",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "description": "KOL hardware — panel controls for instruments (mixers, synths, racks, decks), in five groups: value (knob, fader, the touch ParamSheet), switches (toggle, flip, rocker, icon button), indicators (LED, jacks), panel (label, module header), frames (module frame, channel strip, flip card). Plus the signal engine (./signal): one expression compiler and ADSR for every scope and envelope in the estate. Renamed from @kolkrabbi/kol-controls. Sits above @kolkrabbi/kol-{theme,icons,component}.",
   "license": "MIT",
@@ -20,9 +20,9 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-theme": "^0.152.0",
-    "@kolkrabbi/kol-icons": "^0.27.1",
-    "@kolkrabbi/kol-component": "^0.225.0"
+    "@kolkrabbi/kol-component": "^0.226.0",
+    "@kolkrabbi/kol-icons": "^0.28.0",
+    "@kolkrabbi/kol-theme": "^0.153.0"
   },
   "files": [
     "src",

package/src/index.js

@@ -35,4 +35,4 @@ export { default as FlipCard } from './frames/FlipCard.jsx'
 // signal — the components over the signal engine (the engine itself, React-free, is `./signal`)
 export { default as SignalScope } from './indicators/SignalScope.jsx'
 export { default as SignalReference } from './panel/SignalReference.jsx'
-export { default as EnvelopeGenerator } from './value/EnvelopeGenerator.jsx'
+export { default as EnvelopeGenerator, useEnvelopeGenerator, EnvelopeModeToggle, adsrCode } from './value/EnvelopeGenerator.jsx'

package/src/indicators/SignalScope.jsx

@@ -8,31 +8,59 @@ import { useEffect, useRef } from 'react'
  *
  * Presentational: pass any `sample(t) → number` — a compiled expression, an envelope, a bus.
  *
+ * THE VIEW IS MIRROR'S (app frame and curves, 2026-09-27): `zoomX` narrows the window to
+ * `sec / zoomX` seconds starting at `ofs`; `zoomY` narrows the value span around the centre of
+ * `min…max`, shifted by `panY`. `onPan` makes the trace draggable — it reports the new
+ * `{ ofs, panY }` and the host keeps them, as mirror's Oscilloscope did with its own state.
+ *
+ * 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.
+ *
  * @param {(t:number)=>number} sample
  * @param {number} min · max       the view (default 0…100)
- * @param {number} sec · ofs       the window: `sec` seconds starting at `ofs`
+ * @param {number} sec · ofs       the window: `sec` time units starting at `ofs`
+ * @param {number} zoomX · zoomY   view zoom (default 1)
+ * @param {number} panY            value pan (default 0)
+ * @param {Function} onPan         `({ ofs, panY }) => void` — drag the trace to pan
  * @param {number[]} refLines      values drawn dashed (default the knob range 0 and 100)
- * @param {boolean} live           sweep a playhead and redraw every frame (default true)
- * @param {number|string} height   (default 320)
+ * @param {boolean} live           redraw every frame and sweep a playhead (default true)
+ * @param {boolean} playing        the clock runs (default true)
+ * @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|'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, refLines = [0, 100], live = true, height = 320, className = '',
+  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,
+  height = 320, className = '',
 }) {
   const ref = useRef(null)
   const args = useRef({})
   const drawRef = useRef(null)
-  args.current = { sample, min, max, sec, ofs, refLines, live }
+  const clock = useRef({ t: 0, last: 0 })
+  args.current = { sample, min, max, sec, ofs, zoomX, zoomY, panY, refLines, live, playing, rate, loop }
+
+  // a trigger restarts the pass
+  useEffect(() => { clock.current.t = 0 }, [trigger])
 
   useEffect(() => {
     const canvas = ref.current
     if (!canvas) return undefined
     const ctx = canvas.getContext('2d')
-    const start = performance.now()
+    clock.current.last = performance.now()
     let raf = 0
     const draw = () => {
-      const { sample: fn, min: lo, max: hi, sec: s, ofs: o, refLines: lines, live: on } = args.current
+      const a = args.current
+      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
+      const fn = a.sample
       const dpr = window.devicePixelRatio || 1
       const { width: w, height: h } = canvas.getBoundingClientRect()
       if (canvas.width !== Math.round(w * dpr) || canvas.height !== Math.round(h * dpr)) {
@@ -44,8 +72,13 @@ export default function SignalScope({
       const ink = css(canvas, '--kol-surface-on-primary', '#e8e4dc')
       const red = css(canvas, '--kol-ctl-led-red', '#e74c3c')
       const pad = 12
-      const span = hi - lo || 1
+      const span = (a.max - a.min) / (a.zoomY || 1) || 1
+      const lo = (a.min + a.max) / 2 + a.panY - span / 2
+      const hi = lo + span
+      const dur = a.sec / (a.zoomX || 1)
       const toY = (v) => pad + (h - pad * 2) * (1 - (v - lo) / span)
+      const toX = (t) => ((t - a.ofs) / dur) * w
+      const fmt = (v) => String(Math.round(v * 10) / 10)
       ctx.font = '9px var(--kol-font-family-mono), monospace'
       // midline
       ctx.globalAlpha = 0.12
@@ -57,7 +90,7 @@ export default function SignalScope({
       ctx.strokeStyle = red
       ctx.fillStyle = red
       ctx.setLineDash([4, 4])
-      for (const v of lines) {
+      for (const v of a.refLines) {
         const y = toY(v)
         ctx.beginPath(); ctx.moveTo(0, y); ctx.lineTo(w, y); ctx.stroke()
         ctx.fillText(String(v), w - 4 - ctx.measureText(String(v)).width, y - 3)
@@ -66,30 +99,32 @@ export default function SignalScope({
       // axis labels
       ctx.globalAlpha = 0.4
       ctx.fillStyle = ink
-      ctx.fillText(String(hi), 4, pad + 9)
-      ctx.fillText(String(lo), 4, h - pad - 3)
+      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(o + (x / w) * s) : lo)
+        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()
-      // playhead
-      if (on && fn) {
-        const u = (((performance.now() - start) / 1000) % s) / s
-        const px = u * w
-        const py = toY(fn(o + u * s))
-        ctx.globalAlpha = 0.25
-        ctx.beginPath(); ctx.moveTo(px, 0); ctx.lineTo(px, h); ctx.stroke()
-        ctx.globalAlpha = 1
-        ctx.fillStyle = ink
-        ctx.beginPath(); ctx.arc(px, py, 3, 0, Math.PI * 2); ctx.fill()
+      // 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)
+        const px = toX(t)
+        if (px >= 0 && px <= w) {
+          const py = toY(fn(t))
+          ctx.globalAlpha = 0.25
+          ctx.beginPath(); ctx.moveTo(px, 0); ctx.lineTo(px, h); ctx.stroke()
+          ctx.globalAlpha = 1
+          ctx.fillStyle = ink
+          ctx.beginPath(); ctx.arc(px, py, 3, 0, Math.PI * 2); ctx.fill()
+        }
       }
-      if (on) raf = requestAnimationFrame(draw)
+      if (a.live) raf = requestAnimationFrame(draw)
     }
     drawRef.current = draw
     draw()
@@ -101,5 +136,32 @@ export default function SignalScope({
   // a static scope redraws when its inputs change; a live one is already redrawing every frame
   useEffect(() => { if (!live) drawRef.current?.() })
 
-  return <canvas ref={ref} className={`block w-full rounded-[4px] bg-surface-primary ${className}`} style={{ height }} />
+  /* drag to pan — mirror's gesture, reported rather than kept */
+  const pan = onPan ? {
+    onPointerDown: (e) => {
+      const canvas = ref.current
+      const box = canvas.getBoundingClientRect()
+      const start = { x: e.clientX, y: e.clientY, ofs, panY }
+      const dur = sec / (zoomX || 1)
+      const span = (max - min) / (zoomY || 1)
+      canvas.setPointerCapture(e.pointerId)
+      const move = (ev) => onPan({
+        ofs: start.ofs - ((ev.clientX - start.x) / box.width) * dur,
+        panY: start.panY + ((ev.clientY - start.y) / box.height) * span,
+      })
+      const up = () => { canvas.removeEventListener('pointermove', move); canvas.removeEventListener('pointerup', up) }
+      canvas.addEventListener('pointermove', move)
+      canvas.addEventListener('pointerup', up)
+    },
+  } : {}
+
+  const fill = height === 'fill'
+  return (
+    <canvas
+      ref={ref}
+      {...pan}
+      className={`block w-full rounded-[4px] bg-surface-primary ${fill ? 'h-full min-h-0' : ''} ${onPan ? 'cursor-grab touch-none active:cursor-grabbing' : ''} ${className}`}
+      style={fill ? undefined : { height }}
+    />
+  )
 }

package/src/panel/SignalReference.jsx

@@ -1,14 +1,17 @@
 import { useState } from 'react'
-import { TabsRow, usePopover, PopoverPanel } from '@kolkrabbi/kol-component'
+import { Button, TabsRow, usePopover, PopoverPanel } from '@kolkrabbi/kol-component'
 
 /**
  * SignalReference — the reference an expression or envelope tool is explained with (signal
  * engine, 2026-09-27). ONE component over the reference DATA in `@kolkrabbi/kol-hardware/signal`,
  * in the three shapes the estate already used:
  *
- *   variant="tabs"     kol-mirror's /expressions panel — Examples · Saved · Language · Usage
+ *   variant="tabs"     the tabs and their sections, bare — for a host that draws its own box
+ *   variant="panel"    kol-mirror's /expressions fold, class for class: a box the height of its
+ *                      parent, TabsRow in its head (`px-4 border-b`), the body `p-4` scrolling
+ *                      inside, sub-eyebrows only when a tab holds more than one section
  *   variant="popover"  kol-monitor's Scope+ face — an EX and a REF button, each a popover
- *   variant="sheet"    the design editor's labs shortcuts sheet — every section, stacked
+ *   variant="sheet"    the design editor's labs shortcuts sheet — every section, in columns
  *
  * Clicking a code loads it (`onPick`); ⌘/Ctrl-click appends it (`onAppend`) — mirror's gestures.
  *
@@ -16,6 +19,7 @@ import { TabsRow, usePopover, PopoverPanel } from '@kolkrabbi/kol-component'
  * @param {Array}  tabs       `[{ id, label, sections }]` (EXPRESSION_TABS, ADSR_TABS); a tab with
  *                            id `saved` renders the host's `saved` rows, and is hidden without them
  * @param {Array}  saved      `[code, label]` rows the host keeps (its library)
+ * @param {'xs'|'sm'|'md'} size  the popover buttons' rung (default sm) — match the row they sit in
  */
 function Code({ text, onPick, onAppend }) {
   return (
@@ -31,8 +35,8 @@ function Code({ text, onPick, onAppend }) {
 
 function Section({ section, onPick, onAppend, showTitle }) {
   return (
-    <div className="flex flex-col gap-1">
-      {showTitle && <div className="kol-helper-10 uppercase text-fg-48">{section.title}</div>}
+    <div className="flex shrink-0 flex-col">
+      {showTitle && <div className="kol-helper-12 flex h-6 shrink-0 items-center uppercase text-fg-48">{section.title}</div>}
       {section.tips
         ? section.tips.map((tip) => <div key={tip} className="kol-helper-10 text-fg-48" style={{ lineHeight: '150%' }}>{tip}</div>)
         : (
@@ -41,11 +45,12 @@ function Section({ section, onPick, onAppend, showTitle }) {
               const codes = Array.isArray(row) ? [row[0]] : row.codes
               const label = Array.isArray(row) ? row[1] : row.label
               return (
-                <div key={codes.join()} className="flex h-6 items-center justify-between gap-3">
-                  <span className="flex min-w-0 items-center gap-2">
+                <div key={codes.join()} className="flex h-6 min-w-0 items-center justify-between gap-3">
+                  {/* in the two-column grid the CODE is the thing to read — the label yields */}
+                  <span className={`flex items-center gap-2 ${section.grid ? 'shrink-0' : 'min-w-0'}`}>
                     {codes.map((c) => <Code key={c} text={c} onPick={onPick} onAppend={onAppend} />)}
                   </span>
-                  <span className="kol-helper-10 shrink-0 text-fg-48">{label}</span>
+                  <span className={`kol-helper-10 text-fg-48 ${section.grid ? 'min-w-0 truncate' : 'shrink-0'}`}>{label}</span>
                 </div>
               )
             })}
@@ -75,19 +80,35 @@ function Tabs({ sections, tabs, saved, onPick, onAppend }) {
   )
 }
 
-function PopButton({ label, list, onPick, onAppend }) {
+/* THE FOLD — kol-mirror's /expressions reference box (ExpressionReference, `scopeFill`) */
+function Panel({ sections, tabs, saved, onPick, onAppend }) {
+  const visible = tabs.filter((t) => t.id !== 'saved' || saved)
+  const [tab, setTab] = useState(visible[0]?.id)
+  const current = visible.find((t) => t.id === tab) ?? visible[0]
+  const list = current ? sectionsOf(current, sections, saved) : []
+  return (
+    <div className="kol-helper-12 flex h-full min-h-0 flex-col overflow-hidden rounded-[4px] border border-oq-08 bg-surface-secondary">
+      <div className="shrink-0 border-b border-oq-08 px-4">
+        <TabsRow tabs={visible} value={current?.id} onChange={setTab} />
+      </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>
+          : list.map((s) => <Section key={s.title} section={s} onPick={onPick} onAppend={onAppend} showTitle={list.length > 1} />)}
+      </div>
+    </div>
+  )
+}
+
+function PopButton({ label, list, onPick, onAppend, size }) {
   const [open, setOpen] = useState(false)
   const popover = usePopover({ open, onOpenChange: setOpen, placement: 'bottom-end' })
   return (
     <>
-      <button
-        type="button"
-        ref={popover.refs.setReference}
-        {...popover.getReferenceProps()}
-        className="kol-helper-10 h-7 rounded-[2px] bg-surface-tertiary px-2 text-fg-96"
-      >
-        {label}
-      </button>
+      {/* Button takes no ref — the wrapper is the anchor, and the click reaches it by bubbling */}
+      <span ref={popover.refs.setReference} {...popover.getReferenceProps()} className="inline-flex">
+        <Button variant="grey" size={size} pressed={open}>{label}</Button>
+      </span>
       <PopoverPanel popover={popover} className="w-80 max-h-96 overflow-y-auto p-3">
         <div className="flex flex-col gap-3">
           {list.map((s) => (
@@ -100,20 +121,27 @@ function PopButton({ label, list, onPick, onAppend }) {
   )
 }
 
-export default function SignalReference({ sections, tabs, variant = 'tabs', saved, onPick, onAppend, className = '' }) {
+export default function SignalReference({ sections, tabs, variant = 'tabs', saved, onPick, onAppend, size = 'sm', className = '' }) {
+  if (variant === 'panel') {
+    return (
+      <div className={`h-full min-h-0 ${className}`}>
+        <Panel sections={sections} tabs={tabs} saved={saved} onPick={onPick} onAppend={onAppend} />
+      </div>
+    )
+  }
   if (variant === 'popover') {
     const [first, ...rest] = tabs.filter((t) => t.id !== 'saved')
     return (
       <div className={`flex gap-1 ${className}`}>
-        {first && <PopButton label="EX" list={sectionsOf(first, sections)} onPick={onPick} onAppend={onAppend} />}
-        {rest.length > 0 && <PopButton label="REF" list={rest.flatMap((t) => sectionsOf(t, sections))} onPick={onPick} onAppend={onAppend} />}
+        {first && <PopButton label="EX" size={size} list={sectionsOf(first, sections)} onPick={onPick} onAppend={onAppend} />}
+        {rest.length > 0 && <PopButton label="REF" size={size} list={rest.flatMap((t) => sectionsOf(t, sections))} onPick={onPick} onAppend={onAppend} />}
       </div>
     )
   }
   if (variant === 'sheet') {
     const all = tabs.filter((t) => t.id !== 'saved').flatMap((t) => sectionsOf(t, sections))
     return (
-      <div className={`grid gap-6 sm:grid-cols-2 ${className}`}>
+      <div className={`grid content-start gap-x-6 gap-y-4 ${className}`} style={{ gridTemplateColumns: 'repeat(auto-fill, minmax(280px, 1fr))' }}>
         {all.map((s) => <Section key={s.title} section={s} onPick={onPick} onAppend={onAppend} showTitle />)}
       </div>
     )

package/src/signal/adsr.js

@@ -6,9 +6,13 @@
  * Params are the knob values, 0…100:
  *   attack · decay · release   → seconds via `stageSeconds` (0 → 5 ms, 100 → 2 s, linear — monitor's)
  *   sustain                    → the held level, 0…100
+ *
+ * `hold` is SECONDS, not a knob (app frame and curves, 2026-09-27): how long the gate stays open
+ * once the envelope has reached sustain. Default 1 — the gate the engine always assumed
+ * (`a + d + 1`), so an envelope without it draws exactly as before.
  */
 
-export const ADSR_DEFAULTS = Object.freeze({ attack: 10, decay: 30, sustain: 70, release: 50 })
+export const ADSR_DEFAULTS = Object.freeze({ attack: 10, decay: 30, sustain: 70, release: 50, hold: 1 })
 
 /** knob 0…100 → seconds, 5 ms … 2 s */
 export const stageSeconds = (v) => 0.005 + (Math.max(0, Math.min(100, v)) / 100) * 1.995
@@ -16,10 +20,16 @@ export const stageSeconds = (v) => 0.005 + (Math.max(0, Math.min(100, v)) / 100)
 /** a 0…100 level → [min, max] */
 export const toRange = (level, min = 0, max = 100) => min + (level / 100) * (max - min)
 
+/** Seconds the gate stays open: attack + decay + the sustain hold. */
+export const gateSeconds = (params = ADSR_DEFAULTS) => {
+  const p = { ...ADSR_DEFAULTS, ...params }
+  return stageSeconds(p.attack) + stageSeconds(p.decay) + Math.max(0, p.hold)
+}
+
 /**
- * envelopeAt(t, params, { hold, cycle }) — the level at `t` seconds after a gate that stays
- * open for `hold` seconds (default: until sustain is reached, plus 1 s). Pure, so a scope can
- * draw it and a timeline can scrub it. `cycle` repeats the whole envelope.
+ * envelopeAt(t, params, { hold, cycle }) — the level at `t` seconds after the gate opens. The
+ * gate stays open for `gateSeconds(params)`; the `hold` option (total gate seconds) overrides it.
+ * Pure, so a scope can draw it and a timeline can scrub it. `cycle` repeats the whole envelope.
  */
 export function envelopeAt(t, params = ADSR_DEFAULTS, { hold, cycle = false } = {}) {
   const { attack, decay, sustain, release } = { ...ADSR_DEFAULTS, ...params }
@@ -27,7 +37,7 @@ export function envelopeAt(t, params = ADSR_DEFAULTS, { hold, cycle = false } =
   const d = stageSeconds(decay)
   const r = stageSeconds(release)
   const s = Math.max(0, Math.min(100, sustain))
-  const gate = hold ?? a + d + 1
+  const gate = hold ?? gateSeconds(params)
   const length = gate + r
   let u = t
   if (cycle) u = ((t % length) + length) % length
@@ -42,7 +52,7 @@ export function envelopeAt(t, params = ADSR_DEFAULTS, { hold, cycle = false } =
 /** Total seconds of one envelope pass — for sizing a scope window. */
 export const envelopeLength = (params = ADSR_DEFAULTS, { hold } = {}) => {
   const p = { ...ADSR_DEFAULTS, ...params }
-  return (hold ?? stageSeconds(p.attack) + stageSeconds(p.decay) + 1) + stageSeconds(p.release)
+  return (hold ?? gateSeconds(p)) + stageSeconds(p.release)
 }
 
 /**

package/src/signal/index.js

@@ -2,5 +2,5 @@
 // and one ADSR for every scope, envelope and animated value in the estate, plus the reference
 // they are explained with.
 export { compileExpression, isExpression, fitRange, EXPRESSION_HELPERS } from './expression.js'
-export { envelopeAt, envelopeLength, createEnvelope, stageSeconds, toRange, ADSR_DEFAULTS } from './adsr.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'

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, createEnvelope, stageSeconds, EXPRESSION_SECTIONS } from './index.js'
+import { 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)')
@@ -34,6 +34,12 @@ const a = stageSeconds(50)
 assert.equal(Math.round(envelopeAt(a, p)), 100)                       // top of attack
 assert.equal(Math.round(envelopeAt(a * 2 + 0.5, p)), 40)              // holding sustain
 assert.equal(envelopeAt(100, p), 0)                                   // long after release
+// hold — seconds at sustain; 1 by default, so the old gate (a + d + 1) is unchanged
+assert.equal(gateSeconds(p), a * 2 + 1)
+const held = { ...p, hold: 3 }
+assert.equal(Math.round(envelopeAt(a * 2 + 2.5, held)), 40)           // still holding at 2.5 s in
+assert.ok(envelopeAt(a * 2 + 3 + a / 2, held) < 40)                   // released after 3 s
+assert.equal(envelopeLength(held), a * 2 + 3 + a)
 const env = createEnvelope()
 let lvl = 0
 for (let i = 0; i < 600; i++) lvl = env.step(1 / 60, { gate: true }, p)

package/src/value/EnvelopeGenerator.jsx

@@ -1,59 +1,138 @@
 import { useMemo, useRef, useState } from 'react'
-import { Button, Input, SegmentedToggle } from '@kolkrabbi/kol-component'
+import { Button, Divider, Input, SegmentedToggle, Slider } from '@kolkrabbi/kol-component'
 import Knob from './Knob.jsx'
 import Toggle from '../switches/Toggle.jsx'
 import SignalScope from '../indicators/SignalScope.jsx'
 import SignalReference from '../panel/SignalReference.jsx'
 import { compileExpression, fitRange } from '../signal/expression.js'
-import { envelopeAt, envelopeLength, stageSeconds, ADSR_DEFAULTS } from '../signal/adsr.js'
+import { envelopeAt, envelopeLength, gateSeconds, stageSeconds, ADSR_DEFAULTS } from '../signal/adsr.js'
 import { EXPRESSION_SECTIONS, EXPRESSION_TABS, ADSR_SECTIONS, ADSR_TABS, ADSR_PRESETS } from '../signal/reference.js'
 
-/**
- * EnvelopeGenerator — a value over time, typed as an equation or shaped as an ADSR envelope
- * (signal engine, 2026-09-27). One tool for what kol-mirror's /expressions page, kol-monitor's
- * Scope+ and Env modules and the design editor's Oscilloscope each built alone: the scope in the
- * middle, the window controls under it, the reference beside it — mirror's layout.
- *
- * Uncontrolled: `default*` seeds it, `onChange` reports every change as
- * `{ mode, expr, adsr, min, max, sec, ofs }` — hand it to a store, a module, a layer.
- *
- * @param {'equation'|'adsr'} defaultMode
- * @param {string}  defaultExpr
- * @param {object}  defaultAdsr        knob values 0…100 (`ADSR_DEFAULTS`)
- * @param {Array}   saved · savedAdsr  the host's own rows for each mode's Saved tab
- * @param {Function} onSave            `({ mode, code }) => void` — shows a Save button; `code` is the
- *                                     expression, or the envelope as `a10 d30 s70 r50` (pick loads it back)
- * @param {boolean} reference          show the reference panel (default true)
- *
- * In ADSR mode the envelope's three corners drag on the scope — attack peak (A), decay → sustain
- * (D and S), release end (R) — and the knobs follow; the window holds still while you drag.
- */
 const MODES = [{ value: 'equation', label: 'Equation' }, { value: 'adsr', label: 'ADSR' }]
+const VIEW = { min: 0, max: 100, sec: 5, ofs: 0, zoomX: 1, zoomY: 1, panY: 0 }
 const num = (s, fallback) => { const n = parseFloat(s); return Number.isFinite(n) ? n : fallback }
+const r2 = (v) => Math.round(v * 100) / 100
 
 /* an envelope as text and back — what the Saved rows carry */
-export const adsrCode = (p) => `a${Math.round(p.attack)} d${Math.round(p.decay)} s${Math.round(p.sustain)} r${Math.round(p.release)}`
+export const adsrCode = (p) =>
+  `a${Math.round(p.attack)} d${Math.round(p.decay)} s${Math.round(p.sustain)} r${Math.round(p.release)} h${r2(p.hold ?? ADSR_DEFAULTS.hold)}`
 const parseAdsr = (code) => {
-  const m = /^a(\d+) d(\d+) s(\d+) r(\d+)$/.exec(String(code))
-  return m ? { attack: +m[1], decay: +m[2], sustain: +m[3], release: +m[4] } : null
+  const m = /^a(\d+) d(\d+) s(\d+) r(\d+)(?: h([\d.]+))?$/.exec(String(code))
+  return m ? { attack: +m[1], decay: +m[2], sustain: +m[3], release: +m[4], hold: m[5] ? +m[5] : ADSR_DEFAULTS.hold } : null
 }
 /* seconds → the knob value that gives them (inverse of stageSeconds) */
 const knobFor = (seconds) => Math.max(0, Math.min(100, ((seconds - 0.005) / 1.995) * 100))
+/* the ADSR window: one pass, and room past it to drag R into */
+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`).
+ */
+export function useEnvelopeGenerator({
+  defaultMode = 'equation', defaultExpr = 'wave(t)', defaultAdsr = ADSR_DEFAULTS,
+  saved, savedAdsr, onSave, onChange,
+} = {}) {
+  const [mode, setModeState] = useState(defaultMode)
+  const [expr, setExprState] = useState(defaultExpr)
+  const [adsr, setAdsrState] = useState({ ...ADSR_DEFAULTS, ...defaultAdsr })
+  const [view, setViewState] = useState(VIEW)
+  const [cycle, setCycle] = useState(true)
+  const [playing, setPlaying] = useState(true)
+  const [bpm, setBpm] = useState(60)
+  const [trigger, setTrigger] = useState(0)
+  const [heldSec, setHeldSec] = useState(null)   // the ADSR window, frozen while a handle drags
+
+  const compiled = useMemo(() => compileExpression(expr), [expr])
+  const emit = (patch) => onChange?.({ mode, expr, adsr, min: view.min, max: view.max, sec: view.sec, ofs: view.ofs, ...patch })
+  const setMode = (m) => { setModeState(m); emit({ mode: m }) }
+  const setExpr = (e) => { setExprState(e); emit({ expr: e }) }
+  const setAdsr = (p) => { const next = { ...adsr, ...p }; setAdsrState(next); emit({ adsr: next }) }
+  const setView = (p) => { const next = { ...view, ...p }; setViewState(next); emit(next) }
+
+  const fit = () => { const r = fitRange(expr, { sec: view.sec, ofs: view.ofs }); if (r) setView({ ...r, zoomY: 1, panY: 0 }) }
+  const reset = () => setView(VIEW)
+  /* a load replaces the expression and fits the scope to it — mirror's */
+  const pick = (code) => {
+    if (mode === 'equation') {
+      setExpr(code)
+      const r = fitRange(code, { sec: view.sec, ofs: view.ofs })
+      if (r) setView({ ...r, zoomY: 1, panY: 0 })
+      return
+    }
+    const params = ADSR_PRESETS.find((p) => p.id === code)?.params ?? parseAdsr(code)
+    if (params) setAdsr(params)
+  }
+  const append = mode === 'equation' ? (code) => setExpr(`${expr}+${code}`) : undefined
+  const save = onSave ? () => onSave({ mode, code: mode === 'equation' ? expr : adsrCode(adsr) }) : undefined
+
+  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,
+    /* 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: {
+      sections: mode === 'equation' ? EXPRESSION_SECTIONS : ADSR_SECTIONS,
+      tabs: mode === 'equation' ? EXPRESSION_TABS : ADSR_TABS,
+      saved: mode === 'equation' ? saved : savedAdsr,
+      onPick: pick,
+      onAppend: append,
+    },
+  }
+}
+
+/** The Equation | ADSR toggle, for a host that puts it in its own masthead. */
+export function EnvelopeModeToggle({ generator, size = 'sm', className = '' }) {
+  return <SegmentedToggle value={generator.mode} onChange={generator.setMode} options={MODES} size={size} ariaLabel="Mode" className={className} />
+}
+
+/* mirror's Eyebrow — the box's name above it. `bare` when the child draws its own box. */
+function Box({ title, className = '', bodyClass = '', bare = false, children }) {
+  return (
+    <div className={`flex min-h-0 flex-col ${className}`}>
+      <div className="kol-helper-12 flex h-6 shrink-0 items-start uppercase text-fg-48">{title}</div>
+      {bare
+        ? <div className="min-h-0 flex-1">{children}</div>
+        : (
+          <div className={`kol-helper-12 flex min-h-0 flex-1 flex-col overflow-hidden rounded-[4px] border border-oq-08 bg-surface-secondary p-4 ${bodyClass}`}>
+            {children}
+          </div>
+        )}
+    </div>
+  )
+}
+
+function Field({ label, value, onCommit, chars = 4 }) {
+  return (
+    <label className="flex items-center gap-2">
+      <span className="uppercase text-fg-48">{label}</span>
+      <Input size="sm" chars={chars} value={String(value)} onCommit={onCommit} />
+    </label>
+  )
+}
+
+function ZoomRow({ label, value, onChange }) {
+  return (
+    <Slider label={label} min={0.1} max={10} step={0.1} value={value} onChange={onChange} defaultValue={1} displayWidth={4} className="h-6" />
+  )
+}
 
-const PAD = 12   // SignalScope's inner padding — the handles sit on its grid
-const HEIGHT = 320
+/* the handles sit on SignalScope's grid: 12px inner padding, the level across the rest */
+const PAD = 12
+const top = (level) => `calc(${PAD}px + (100% - ${PAD * 2}px) * ${1 - level / 100})`
 
 function EnvelopeHandles({ adsr, sec, onDragStart, onDrag, onDragEnd }) {
   const ref = useRef(null)
   const a = stageSeconds(adsr.attack)
   const d = stageSeconds(adsr.decay)
-  const gate = a + d + 1
+  const gate = gateSeconds(adsr)
   const r = stageSeconds(adsr.release)
-  const y = (level) => PAD + (HEIGHT - PAD * 2) * (1 - level / 100)
   const pts = [
-    { id: 'a', x: a / sec, y: y(100), label: 'A' },
-    { id: 'ds', x: (a + d) / sec, y: y(adsr.sustain), label: 'D · S' },
-    { id: 'r', x: (gate + r) / sec, y: y(0), label: 'R' },
+    { id: 'a', t: a, level: 100, label: 'A' },
+    { id: 'd', t: a + d, level: adsr.sustain, label: 'D' },
+    { id: 's', t: gate, level: adsr.sustain, label: 'S' },
+    { id: 'r', t: gate + r, level: 0, label: 'R' },
   ]
   const drag = (id) => (e) => {
     e.preventDefault()
@@ -62,9 +141,10 @@ function EnvelopeHandles({ adsr, sec, onDragStart, onDrag, onDragEnd }) {
     const move = (ev) => {
       const box = ref.current.getBoundingClientRect()
       const t = Math.max(0, ((ev.clientX - box.left) / box.width) * sec)
-      const level = Math.max(0, Math.min(100, (1 - (ev.clientY - box.top - PAD) / (HEIGHT - PAD * 2)) * 100))
+      const level = Math.max(0, Math.min(100, (1 - (ev.clientY - box.top - PAD) / (box.height - PAD * 2)) * 100))
       if (id === 'a') onDrag({ attack: knobFor(t) })
-      else if (id === 'ds') onDrag({ decay: knobFor(t - a), sustain: level })
+      else if (id === 'd') onDrag({ decay: knobFor(t - a) })
+      else if (id === 's') onDrag({ hold: r2(Math.max(0, t - a - d)), sustain: level })
       else onDrag({ release: knobFor(t - gate) })
     }
     const up = () => { window.removeEventListener('pointermove', move); window.removeEventListener('pointerup', up); onDragEnd() }
@@ -72,123 +152,173 @@ function EnvelopeHandles({ adsr, sec, onDragStart, onDrag, onDragEnd }) {
     window.addEventListener('pointerup', up)
   }
   return (
-    <div ref={ref} className="pointer-events-none absolute inset-x-0 top-0" style={{ height: HEIGHT }}>
+    <div ref={ref} className="pointer-events-none absolute inset-0">
       {pts.map((pt) => (
         <button
           key={pt.id}
           type="button"
           aria-label={`Drag ${pt.label}`}
           onPointerDown={drag(pt.id)}
-          className="pointer-events-auto absolute flex h-5 w-5 -translate-x-1/2 -translate-y-1/2 cursor-grab touch-none items-center justify-center rounded-full"
-          style={{ left: `${Math.min(1, pt.x) * 100}%`, top: pt.y }}
+          className="pointer-events-auto absolute flex h-6 w-6 -translate-x-1/2 -translate-y-1/2 cursor-grab touch-none items-center justify-center rounded-full"
+          style={{ left: `${Math.min(1, pt.t / sec) * 100}%`, top: top(pt.level) }}
         >
           <span className="block h-2.5 w-2.5 rounded-full border border-oq-64 bg-surface-primary" />
+          <span className="kol-helper-10 absolute -top-3 text-fg-48">{pt.label}</span>
         </button>
       ))}
     </div>
   )
 }
 
-function Field({ label, value, onCommit }) {
-  return (
-    <label className="flex items-center gap-2">
-      <span className="kol-helper-10 uppercase text-fg-48">{label}</span>
-      <Input size="xs" chars={4} value={String(value)} onCommit={onCommit} />
-    </label>
-  )
-}
-
-export default function EnvelopeGenerator({
-  defaultMode = 'equation', defaultExpr = 'wave(t)', defaultAdsr = ADSR_DEFAULTS,
-  saved, savedAdsr, onSave, reference = true, onChange, className = '',
-}) {
-  const [mode, setMode] = useState(defaultMode)
-  const [expr, setExpr] = useState(defaultExpr)
-  const [adsr, setAdsr] = useState({ ...ADSR_DEFAULTS, ...defaultAdsr })
-  const [cycle, setCycle] = useState(true)
-  const [view, setView] = useState({ min: 0, max: 100, sec: 5, ofs: 0 })
-  const [heldSec, setHeldSec] = useState(null)   // the ADSR window, frozen while a handle drags
+/**
+ * EnvelopeGenerator — a value over time, typed as an equation or shaped as an ADSR envelope
+ * (signal engine, 2026-09-27). One tool for what kol-mirror's /expressions page, kol-monitor's
+ * Scope+ and Env modules and the design editor's Oscilloscope each built alone.
+ *
+ * MIRROR'S PAGE, CLASS FOR CLASS (app frame and curves, 2026-09-27): it fills its parent — the
+ * OSCILLOSCOPE box takes every pixel the REFERENCE panel (320px) leaves, the scope takes every
+ * pixel its controls leave. Each box is an eyebrow over `bg-surface-secondary border-oq-08
+ * rounded-4`; the scope box is `kol-tone-sunken`, so its fields sit in mirror's dark wells. Collapse narrows the scope to 320px and the reference spreads into the rest as the
+ * desk (every section at once) — mirror's Collapse.
+ *
+ * THE PARTS ARE THE HOST'S TO ARRANGE. `useEnvelopeGenerator()` holds the state; pass it as
+ * `generator` and the host can put the mode toggle (`EnvelopeModeToggle`) and the reference
+ * (`generator.reference`, spread into `SignalReference`) wherever its page wants them — a tool
+ * frame's masthead, say. Without `generator` the component keeps its own and draws the toggle
+ * 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.
+ *
+ * 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
+ * draws one pass and never wraps; the window holds still while a handle drags and refits on
+ * release. Cycle on loops the playhead; off, it runs once and Trigger fires it again.
+ *
+ * `onChange` reports every change as `{ mode, expr, adsr, min, max, sec, ofs }`.
+ *
+ * @param {object}  generator          state from `useEnvelopeGenerator()` (else it keeps its own)
+ * @param {'panel'|'none'} reference   the reference panel beside the scope (default panel; `false` = none)
+ *
+ * It FILLS its parent's height — give it one (a tool frame's body, or a fixed-height box).
+ * @param {'equation'|'adsr'} defaultMode
+ * @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 {Function} onSave            `({ mode, code }) => void` — shows a Save button; `code` is the
+ *                                     expression, or the envelope as `a10 d30 s70 r50 h1`
+ */
+export default function EnvelopeGenerator({ generator, reference = 'panel', className = '', ...options }) {
+  const own = useEnvelopeGenerator(options)
+  const g = generator ?? own
+  const [collapsed, setCollapsed] = useState(false)
+  const { mode, adsr, view } = g
 
-  const compiled = useMemo(() => compileExpression(expr), [expr])
-  const adsrSec = envelopeLength(adsr)
   const sample = mode === 'equation'
-    ? (t) => compiled.fn(t, Math.round(t * 60), 0, 100)
-    : (t) => envelopeAt(t, adsr, { cycle })
-  const sec = mode === 'equation' ? view.sec : (heldSec ?? adsrSec)
-  const ofs = mode === 'equation' ? view.ofs : 0
-
-  const emit = (patch) => onChange?.({ mode, expr, adsr, ...view, ...patch })
-  const change = {
-    mode: (m) => { setMode(m); emit({ mode: m }) },
-    expr: (e) => { setExpr(e); emit({ expr: e }) },
-    adsr: (p) => { const next = { ...adsr, ...p }; setAdsr(next); emit({ adsr: next }) },
-    view: (p) => { const next = { ...view, ...p }; setView(next); emit(next) },
-  }
-  const fit = () => { const r = fitRange(expr, { sec: view.sec, ofs: view.ofs }); if (r) change.view(r) }
-  const reset = () => change.view({ min: 0, max: 100, sec: 5, ofs: 0 })
-  const pick = (code) => {
-    if (mode === 'equation') { change.expr(code); return }
-    const params = ADSR_PRESETS.find((p) => p.id === code)?.params ?? parseAdsr(code)
-    if (params) change.adsr(params)
-  }
+    ? (t) => g.compiled.fn(t, Math.round(t * 60), 0, 100)
+    : (t) => envelopeAt(t, adsr)
+  const sec = mode === 'equation' ? view.sec : (g.heldSec ?? adsrWindow(adsr))
+  const passSec = mode === 'equation' ? sec : envelopeLength(adsr)
+  const panel = reference === true || reference === 'panel'
+
+  const transport = (
+    <div className="flex h-6 shrink-0 items-center gap-3">
+      <Button variant="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))))} />
+      {mode === 'adsr' && (
+        <>
+          <Toggle value={g.cycle} onChange={g.setCycle} label="cycle" />
+          <Button variant="ghost" size="sm" onClick={g.fire}>Trigger</Button>
+        </>
+      )}
+      <span className="ml-auto text-fg-48">{mode === 'adsr' ? `${passSec.toFixed(2)} s` : ''}</span>
+    </div>
+  )
 
   return (
-    <div className={`flex flex-col gap-4 ${className}`}>
-      <SegmentedToggle value={mode} onChange={change.mode} options={MODES} size="sm" />
-      <div className={`grid gap-6 ${reference ? 'lg:grid-cols-[minmax(0,1fr)_320px]' : ''}`}>
-        <div className="flex min-w-0 flex-col gap-3">
-          {mode === 'equation' && (
-            <Input
-              value={expr}
-              onCommit={(v) => change.expr(v || 'wave(t)')}
-              aria-label="Expression"
-              className={compiled.ok ? '' : 'text-[var(--kol-ctl-led-red)]'}
-            />
-          )}
-          <div className="relative">
-            <SignalScope sample={sample} min={mode === 'equation' ? view.min : 0} max={mode === 'equation' ? view.max : 100} sec={sec} ofs={ofs} height={HEIGHT} />
-            {mode === 'adsr' && (
-              <EnvelopeHandles adsr={adsr} sec={sec}
-                onDragStart={() => setHeldSec(adsrSec)} onDrag={change.adsr} onDragEnd={() => setHeldSec(null)} />
-            )}
-          </div>
-          {mode === 'equation' ? (
-            <>
-              <div className="flex items-center justify-between">
-                <Button variant="ghost" size="sm" iconLeft="maximize" onClick={fit}>Fit</Button>
-                {onSave && <Button variant="ghost" size="sm" iconLeft="save" onClick={() => onSave({ mode, code: expr })}>Save</Button>}
-                <Button variant="ghost" size="sm" iconLeft="refresh" onClick={reset}>Reset</Button>
-              </div>
-              <div className="flex flex-wrap items-center justify-between gap-3">
-                <Field label="Min" value={view.min} onCommit={(v) => change.view({ min: num(v, view.min) })} />
-                <Field label="Max" value={view.max} onCommit={(v) => change.view({ max: num(v, view.max) })} />
-                <Field label="Sec" value={view.sec} onCommit={(v) => change.view({ sec: Math.max(0.1, num(v, view.sec)) })} />
-                <Field label="Ofs" value={view.ofs} onCommit={(v) => change.view({ ofs: num(v, view.ofs) })} />
-              </div>
-            </>
-          ) : (
-            <div className="flex flex-wrap items-end justify-center gap-6 py-2">
-              {[['attack', 'A'], ['decay', 'D'], ['sustain', 'S'], ['release', 'R']].map(([key, label]) => (
-                <Knob key={key} value={adsr[key]} onChange={(v) => change.adsr({ [key]: v })} label={label} size="lg" defaultValue={ADSR_DEFAULTS[key]} />
-              ))}
-              <Toggle value={cycle} onChange={setCycle} label="cycle" />
-              <span className="kol-helper-10 text-fg-48">{adsrSec.toFixed(2)} s</span>
-              {onSave && <Button variant="ghost" size="sm" iconLeft="save" onClick={() => onSave({ mode, code: adsrCode(adsr) })}>Save</Button>}
-            </div>
+    <div className={`flex h-full min-h-0 flex-col gap-4 lg:flex-row ${className}`}>
+      <Box
+        title="Oscilloscope"
+        className={collapsed && panel ? 'shrink-0 lg:w-[320px]' : 'min-w-0 flex-1'}
+        bodyClass="kol-tone-sunken gap-2"
+      >
+        {!generator && <EnvelopeModeToggle generator={g} className="self-start" />}
+        {mode === 'equation' && (
+          <Input
+            size="sm"
+            value={g.expr}
+            onCommit={(v) => g.setExpr(v || 'wave(t)')}
+            aria-label="Expression"
+            className={`shrink-0 ${g.compiled.ok ? '' : 'text-[var(--kol-ctl-led-red)]'}`}
+          />
+        )}
+        <div className="relative min-h-[160px] flex-1">
+          <SignalScope
+            sample={sample}
+            height="fill"
+            min={mode === 'equation' ? view.min : 0}
+            max={mode === 'equation' ? view.max : 100}
+            sec={mode === 'equation' ? view.sec : sec}
+            ofs={mode === 'equation' ? view.ofs : 0}
+            zoomX={mode === 'equation' ? view.zoomX : 1}
+            zoomY={mode === 'equation' ? view.zoomY : 1}
+            panY={mode === 'equation' ? view.panY : 0}
+            onPan={mode === 'equation' ? g.setView : undefined}
+            playing={g.playing}
+            rate={g.bpm / 60}
+            loop={mode === 'equation' || g.cycle}
+            trigger={g.trigger}
+            className="absolute inset-0"
+          />
+          {mode === 'adsr' && (
+            <EnvelopeHandles adsr={adsr} sec={sec}
+              onDragStart={() => g.setHeldSec(adsrWindow(adsr))} onDrag={g.setAdsr} onDragEnd={() => g.setHeldSec(null)} />
           )}
         </div>
-        {reference && (
-          <SignalReference
-            className="rounded-[4px] border border-oq-08 p-4"
-            sections={mode === 'equation' ? EXPRESSION_SECTIONS : ADSR_SECTIONS}
-            tabs={mode === 'equation' ? EXPRESSION_TABS : ADSR_TABS}
-            saved={mode === 'equation' ? saved : savedAdsr}
-            onPick={pick}
-            onAppend={mode === 'equation' ? (code) => change.expr(`${expr}+${code}`) : undefined}
-            key={mode}
-          />
+        <div className="flex min-h-6 shrink-0 flex-wrap items-center justify-between gap-x-2">
+          {mode === 'equation' && <Button variant="ghost" size="sm" iconLeft="maximize" onClick={g.fit}>Fit</Button>}
+          {panel && <Button variant="ghost" size="sm" iconLeft="columns" onClick={() => setCollapsed(!collapsed)} className="hidden lg:inline-flex">{collapsed ? 'Expand' : 'Collapse'}</Button>}
+          {g.save && <Button variant="ghost" size="sm" iconLeft="save" onClick={g.save}>Save</Button>}
+          <Button variant="ghost" size="sm" iconLeft="refresh" onClick={mode === 'equation' ? g.reset : () => g.setAdsr(ADSR_DEFAULTS)}>Reset</Button>
+        </div>
+        <Divider className="shrink-0 py-1" />
+        {mode === 'equation' ? (
+          <>
+            <div className="flex shrink-0 flex-wrap items-center justify-between gap-x-3 gap-y-2">
+              <Field label="Min" value={view.min} onCommit={(v) => g.setView({ min: num(v, view.min) })} />
+              <Field label="Max" value={view.max} onCommit={(v) => g.setView({ max: num(v, view.max) })} />
+              <Field label="Sec" value={view.sec} onCommit={(v) => g.setView({ sec: Math.max(0.1, num(v, view.sec)) })} />
+              <Field label="Ofs" value={r2(view.ofs)} onCommit={(v) => g.setView({ ofs: num(v, view.ofs) })} />
+            </div>
+            <div className="flex shrink-0 flex-col">
+              <ZoomRow label="X" value={view.zoomX} onChange={(v) => g.setView({ zoomX: v })} />
+              <ZoomRow label="Y" value={view.zoomY} onChange={(v) => g.setView({ zoomY: v })} />
+              <ZoomRow label="Scale" value={r2((view.zoomX + view.zoomY) / 2)} onChange={(v) => g.setView({ zoomX: v, zoomY: v })} />
+            </div>
+          </>
+        ) : (
+          <div className="flex shrink-0 flex-wrap items-end justify-between gap-4">
+            {[['attack', 'A'], ['decay', 'D'], ['sustain', 'S'], ['release', 'R']].map(([key, label]) => (
+              <Knob key={key} value={adsr[key]} onChange={(v) => g.setAdsr({ [key]: v })} label={label} size="md" defaultValue={ADSR_DEFAULTS[key]} />
+            ))}
+            <Field label="Hold" value={r2(adsr.hold)} onCommit={(v) => g.setAdsr({ hold: Math.max(0, num(v, adsr.hold)) })} />
+          </div>
         )}
-      </div>
+        <Divider className="shrink-0 py-1" />
+        {transport}
+      </Box>
+      {panel && (
+        <Box
+          title="Reference"
+          className={`hidden lg:flex ${collapsed ? 'min-w-0 flex-1' : 'w-[320px] shrink-0'}`}
+          bodyClass="overflow-y-auto"
+          bare={!collapsed}
+        >
+          {collapsed
+            ? <SignalReference key={mode} {...g.reference} variant="sheet" />
+            : <SignalReference key={mode} {...g.reference} variant="panel" />}
+        </Box>
+      )}
     </div>
   )
 }