@kolkrabbi/kol-hardware 0.1.0

package/src/panel/PanelLabel.jsx

@@ -0,0 +1,28 @@
+/**
+ * PanelLabel — wraps any control with the panel's text label (kol-monitor's
+ * rack `LabeledControl`, lifted 2026-09-01; named `PanelLabel` because
+ * `LabeledControl` is kol-component's settings-row control). Matches Knob /
+ * Toggle: `kol-helper-8`, `text-fg-32`, uppercase.
+ *
+ * @param {string}   label
+ * @param {boolean}  horizontal      shorthand for a row
+ * @param {'top'|'bottom'|'left'|'right'} labelPosition  (default bottom)
+ * @param {string}   labelClass      type class (default `kol-helper-8`)
+ * @param {number}   gap
+ * @param {ReactNode} children
+ */
+export default function PanelLabel({ label, horizontal = false, labelPosition = 'bottom', labelClass = 'kol-helper-8', gap = 0, children }) {
+  const isRow = horizontal || labelPosition === 'left' || labelPosition === 'right'
+  const labelEl = label && (
+    <span className={`${labelClass} text-fg-32`} style={{ textTransform: 'uppercase', lineHeight: 1 }}>
+      {label}
+    </span>
+  )
+  return (
+    <div style={{ display: 'inline-flex', flexDirection: isRow ? 'row' : 'column', alignItems: 'center', gap }}>
+      {(labelPosition === 'top' || labelPosition === 'left') && labelEl}
+      {children}
+      {(labelPosition === 'bottom' || labelPosition === 'right') && labelEl}
+    </div>
+  )
+}

package/src/panel/SignalReference.jsx

@@ -0,0 +1,126 @@
+import { useState } from 'react'
+import { 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="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
+ *
+ * Clicking a code loads it (`onPick`); ⌘/Ctrl-click appends it (`onAppend`) — mirror's gestures.
+ *
+ * @param {object} sections   `{ id: { title, rows | tips, grid } }` (EXPRESSION_SECTIONS, ADSR_SECTIONS)
+ * @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)
+ */
+function Code({ text, onPick, onAppend }) {
+  return (
+    <button
+      type="button"
+      className="kol-helper-10 min-w-0 max-w-full truncate rounded-[2px] bg-surface-tertiary px-2 py-1 text-left text-fg-96"
+      onClick={(e) => ((e.metaKey || e.ctrlKey) ? onAppend : onPick)?.(text)}
+    >
+      {text}
+    </button>
+  )
+}
+
+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>}
+      {section.tips
+        ? section.tips.map((tip) => <div key={tip} className="kol-helper-10 text-fg-48" style={{ lineHeight: '150%' }}>{tip}</div>)
+        : (
+          <div className={section.grid ? 'grid grid-cols-2 gap-x-4' : 'flex flex-col'}>
+            {section.rows.map((row) => {
+              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">
+                    {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>
+                </div>
+              )
+            })}
+          </div>
+        )}
+    </div>
+  )
+}
+
+const sectionsOf = (tab, sections, saved = []) =>
+  tab.id === 'saved' ? [{ title: 'Saved', rows: saved }] : tab.sections.map((id) => sections[id]).filter(Boolean)
+
+function Tabs({ 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="flex min-h-0 flex-col gap-4">
+      <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>
+          : 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 }) {
+  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>
+      <PopoverPanel popover={popover} className="w-80 max-h-96 overflow-y-auto p-3">
+        <div className="flex flex-col gap-3">
+          {list.map((s) => (
+            <Section key={s.title} section={s} showTitle
+              onPick={(c) => { onPick?.(c); setOpen(false) }} onAppend={onAppend} />
+          ))}
+        </div>
+      </PopoverPanel>
+    </>
+  )
+}
+
+export default function SignalReference({ sections, tabs, variant = 'tabs', saved, onPick, onAppend, className = '' }) {
+  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} />}
+      </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}`}>
+        {all.map((s) => <Section key={s.title} section={s} onPick={onPick} onAppend={onAppend} showTitle />)}
+      </div>
+    )
+  }
+  return (
+    <div className={className}>
+      <Tabs sections={sections} tabs={tabs} saved={saved} onPick={onPick} onAppend={onAppend} />
+    </div>
+  )
+}

package/src/signal/adsr.js

@@ -0,0 +1,100 @@
+/**
+ * ADSR — the envelope engine (signal engine, 2026-09-27), ported from kol-monitor's
+ * `modules/control/EnvelopeModule.jsx` so the rack module, the envelope generator and any scope
+ * share one curve. Levels are 0…100 like every other signal here; map to a range with `toRange`.
+ *
+ * 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
+ */
+
+export const ADSR_DEFAULTS = Object.freeze({ attack: 10, decay: 30, sustain: 70, release: 50 })
+
+/** knob 0…100 → seconds, 5 ms … 2 s */
+export const stageSeconds = (v) => 0.005 + (Math.max(0, Math.min(100, v)) / 100) * 1.995
+
+/** a 0…100 level → [min, max] */
+export const toRange = (level, min = 0, max = 100) => min + (level / 100) * (max - min)
+
+/**
+ * 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.
+ */
+export function envelopeAt(t, params = ADSR_DEFAULTS, { hold, cycle = false } = {}) {
+  const { attack, decay, sustain, release } = { ...ADSR_DEFAULTS, ...params }
+  const a = stageSeconds(attack)
+  const d = stageSeconds(decay)
+  const r = stageSeconds(release)
+  const s = Math.max(0, Math.min(100, sustain))
+  const gate = hold ?? a + d + 1
+  const length = gate + r
+  let u = t
+  if (cycle) u = ((t % length) + length) % length
+  if (u < 0) return 0
+  const held = (x) => (x < a ? (x / a) * 100 : x < a + d ? 100 - ((x - a) / d) * (100 - s) : s)
+  if (u < gate) return held(u)
+  const from = held(gate)
+  const k = (u - gate) / r
+  return k >= 1 ? 0 : from * (1 - k)
+}
+
+/** 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)
+}
+
+/**
+ * createEnvelope() — the stateful form a rack module runs per frame (monitor's stage machine,
+ * verbatim in behaviour): `step(dt, { gate, trig }, params)` → level 0…100. A rising `gate`
+ * attacks and holds sustain until it drops; a rising `trig` is a one-shot A→D→R (with sustain 0,
+ * D and R fold into one long decay); `cycle` loops.
+ */
+export function createEnvelope() {
+  let stage = 'idle'
+  let level = 0
+  let releaseFrom = 0
+  let oneShot = false
+  let prevGate = false
+  let prevTrig = false
+  return {
+    get stage() { return stage },
+    get level() { return level },
+    step(dt, { gate = false, trig = false } = {}, params = ADSR_DEFAULTS) {
+      const { attack, decay, sustain, release, cycle = false } = { ...ADSR_DEFAULTS, ...params }
+      const aT = stageSeconds(attack)
+      const dT = stageSeconds(decay)
+      const rT = stageSeconds(release)
+      const sL = Math.max(0, Math.min(100, sustain))
+      if (trig && !prevTrig) { stage = 'attack'; oneShot = true }
+      prevTrig = trig
+      if (cycle && stage === 'idle') stage = 'attack'
+      if (gate && !prevGate) { stage = 'attack'; oneShot = false }
+      if (!gate && prevGate && stage !== 'idle') { releaseFrom = level; stage = 'release' }
+      prevGate = gate
+      if (stage === 'attack') {
+        level += (dt / aT) * 100
+        if (level >= 100) { level = 100; stage = 'decay' }
+      } else if (stage === 'decay') {
+        const once = oneShot || (cycle && !gate)
+        const dTime = once && sL <= 0 ? dT + rT : dT
+        level -= (dt / dTime) * (100 - sL)
+        if (level <= sL) {
+          level = sL
+          if (once) {
+            if (sL > 0) { releaseFrom = level; stage = 'release' } else { stage = cycle ? 'attack' : 'idle'; oneShot = false }
+          } else stage = 'sustain'
+        }
+      } else if (stage === 'sustain') {
+        level = sL
+        if (cycle && !gate) { releaseFrom = level; stage = 'release' }
+      } else if (stage === 'release') {
+        level -= (dt / rT) * (releaseFrom || 1)
+        if (level <= 0) { level = 0; stage = cycle ? 'attack' : 'idle'; oneShot = false }
+      }
+      return level
+    },
+    reset() { stage = 'idle'; level = 0; releaseFrom = 0; oneShot = false; prevGate = false; prevTrig = false },
+  }
+}

package/src/signal/expression.js

@@ -0,0 +1,127 @@
+/**
+ * The expression engine — ONE compiler for every scope, expression module and animated value in
+ * the estate (signal engine, 2026-09-27). Before it there were four: kol-monitor's and kol-mirror's
+ * `hooks/useExpressionValue.js`, the design editor's Oscilloscope (`loops/math/expression.js`) and
+ * its modulation DSL (`params/expr.js`) — already drifted (monitor's helpers span [min, max],
+ * mirror's always started at 0), and two of them handed user text straight to `new Function`.
+ *
+ * SEMANTICS — monitor's, the newest: every helper spans the caller's [min, max], so `wave(t)` is
+ * min…max. With min = 0 that is exactly mirror's and the editor's `0…max`; with min 0 max 1 it is
+ * labs' normalized "animate any value". `sin`/`cos` stay raw (−1…1).
+ *
+ * SAFETY — the design editor's two gates, in front of the Function sink: math-only characters,
+ * and an identifier allowlist (the helpers, `t f min max`, and the caller's bus names), so
+ * `sin.constructor(…)` dies at the gate. Browser globals are shadowed inside the body. A compiled
+ * fn never throws and never returns a non-finite value (last good value, labs behaviour).
+ *
+ *   const { ok, fn } = compileExpression('wave(t*2)')
+ *   fn(t, frame, min, max, bus)   // → number
+ */
+
+const HELPERS = `
+  "use strict";
+  var sin=Math.sin,cos=Math.cos,tan=Math.tan,atan2=Math.atan2,abs=Math.abs,floor=Math.floor,
+      ceil=Math.ceil,round=Math.round,sqrt=Math.sqrt,pow=Math.pow,
+      PI=Math.PI,TAU=Math.PI*2,PHI=1.618033988749895,E=Math.E,
+      __span=max-min,
+      __map=function(u){return min+u*__span},
+      __ph=function(x){return((x%1)+1)%1},
+      wave=function(x){return __map(sin(x)*0.5+0.5)},
+      saw=function(x){return __map(__ph(x))},
+      pulse=function(x,w){w=w||0.5;return __ph(x)<w?max:min},
+      rand=function(){return __map(Math.random())},
+      tri=function(x){var p=__ph(x);return __map(p<0.5?p*2:(1-p)*2)},
+      ease=function(x,c){c=c||2;var p=__ph(x);var v=p<0.5?p*2:(1-p)*2;return __map(pow(v,c))},
+      bell=function(x){var p=__ph(x);return __map(Math.exp(-pow((p-0.5)*6,2)))},
+      exp=function(x){var p=__ph(x);return __map((Math.exp(p*3)-1)/(Math.exp(3)-1))},
+      log=function(x){var p=__ph(x);return __map(Math.log(1+p*9)/Math.log(10))},
+      step=function(x,n){n=n||4;return __map(floor(__ph(x)*n)/n)},
+      clamp=function(x,a,b){return x<a?a:x>b?b:x},
+      lerp=function(a,b,u){return a+(b-a)*u},
+      mod=function(a,b){return((a%b)+b)%b},
+      frac=function(x){return x-floor(x)},
+      smooth=function(x){x=clamp(x,0,1);return x*x*(3-2*x)};
+`
+
+export const EXPRESSION_HELPERS = [
+  'sin', 'cos', 'tan', 'atan2', 'abs', 'floor', 'ceil', 'round', 'sqrt', 'pow',
+  'PI', 'TAU', 'PHI', 'E',
+  'wave', 'saw', 'pulse', 'rand', 'tri', 'ease', 'bell', 'exp', 'log', 'step',
+  'clamp', 'lerp', 'mod', 'frac', 'smooth',
+]
+const BASE = new Set([...EXPRESSION_HELPERS, 't', 'f', 'min', 'max'])
+const CHARS = /^[\w\s+\-*/%(),.?:<>=!&|]+$/
+const SHADOWED = [
+  'globalThis', 'window', 'self', 'document', 'fetch', 'XMLHttpRequest', 'localStorage',
+  'sessionStorage', 'indexedDB', 'navigator', 'location', 'top', 'parent', 'frames', 'opener',
+  'Function', 'WebSocket', 'Worker', 'importScripts',
+]
+const IDENT = /^[A-Za-z_$][\w$]*$/
+const FAIL = Object.freeze({ ok: false, fn: () => 0 })
+
+const cache = new Map()
+
+/**
+ * compileExpression(expr, { bus }) → { ok, fn(t, f, min, max, busValues) }
+ * `bus` names extra variables the expression may read (a module's CV inputs: `['a', 'b']`);
+ * their values arrive as the fifth argument, an object. Never throws.
+ */
+export function compileExpression(expr, { bus = [] } = {}) {
+  const src = String(expr ?? '').trim()
+  if (!src) return FAIL
+  const names = bus.filter((b) => IDENT.test(b) && !BASE.has(b))
+  const key = `${names.join(',')}|${src}`
+  const hit = cache.get(key)
+  if (hit) return hit
+  let entry = FAIL
+  try {
+    if (!CHARS.test(src)) throw new Error('chars')
+    const allowed = new Set([...BASE, ...names])
+    for (const m of src.matchAll(/[A-Za-z_$][\w$]*/g)) {
+      if (!allowed.has(m[0])) throw new Error(`ident ${m[0]}`)
+    }
+    const busVars = names.length ? `var ${names.map((n) => `${n}=+(__bus&&__bus.${n})||0`).join(',')};` : ''
+    // eslint-disable-next-line no-new-func
+    const raw = new Function('t', 'f', 'min', 'max', '__bus', ...SHADOWED, `${HELPERS}${busVars}return (${src});`)
+    if (typeof raw(1, 60, 0, 100, {}) !== 'number') throw new Error('not numeric')
+    let last = 0
+    entry = {
+      ok: true,
+      fn: (t, f = 0, min = 0, max = 100, busValues) => {
+        try {
+          const v = raw(t, f, min, max, busValues)
+          if (typeof v === 'number' && Number.isFinite(v)) { last = v; return v }
+          return last
+        } catch { return last }
+      },
+    }
+  } catch { /* FAIL */ }
+  cache.set(key, entry)
+  return entry
+}
+
+/** A typed string is an expression (not a plain number) when it has any letter but `e`
+ *  (so `1e3` stays a number) — the rule monitor's and mirror's slider boxes use. */
+export const isExpression = (str) => /[a-df-zA-DF-Z]/.test(String(str))
+
+/**
+ * Fit — the [min, max] a curve actually covers over a window, with 10% headroom on Y (labs /
+ * mirror's Fit button). Evaluates at min 0 max 100, the helpers' reference scale, so fitting the
+ * view never feeds back into the curve.
+ */
+export function fitRange(expr, { sec = 5, ofs = 0, bus } = {}) {
+  const { ok, fn } = compileExpression(expr, { bus })
+  if (!ok) return null
+  const N = Math.min(20000, Math.max(300, Math.round(sec * 240)))
+  let lo = Infinity
+  let hi = -Infinity
+  for (let i = 0; i <= N; i++) {
+    const t = ofs + (i / N) * sec
+    const v = fn(t, Math.round(t * 60), 0, 100)
+    if (v < lo) lo = v
+    if (v > hi) hi = v
+  }
+  if (!(hi > lo)) { lo -= 1; hi += 1 }
+  const m = (hi - lo) * 0.1
+  return { min: Math.floor(lo - m), max: Math.ceil(hi + m) }
+}

package/src/signal/index.js

@@ -0,0 +1,6 @@
+// @kolkrabbi/kol-hardware/signal — the signal engine: plain JS, no React. One expression compiler
+// 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 { EXPRESSION_SECTIONS, EXPRESSION_TABS, ADSR_PRESETS, ADSR_SECTIONS, ADSR_TABS } from './reference.js'

package/src/signal/reference.js

@@ -0,0 +1,89 @@
+/**
+ * The reference — examples, the language and usage notes for the expression engine, and the
+ * presets and usage for ADSR (signal engine, 2026-09-27). DATA, one copy: before this the same
+ * lists lived in kol-mirror's ExpressionReference, kol-monitor's Scope+ EX/REF popovers and the
+ * design editor's labs shortcuts sheet, and had already drifted (mirror 20 examples, labs 9).
+ * The expression sections are kol-mirror's `SECTIONS`, verbatim; the Functions rows gained the
+ * helpers the engine took from labs (tan · atan2 · clamp · lerp · mod · frac · smooth · TAU · E).
+ *
+ * A row is `[code, label]`, or `{ codes, label }` for a multi-code row. `SignalReference` renders
+ * any of these as tabs, popovers or a sheet.
+ */
+
+export const EXPRESSION_SECTIONS = {
+  examples: { title: 'Examples', rows: [
+    ['wave(t*2)', 'Fast sine'], ['saw(t)*0.8', 'Ramp to 80'], ['tri(t*0.5)', 'Slow bounce'], ['ease(t*2, 4)', 'Fast + punchy'],
+    ['pulse(t*3)', 'Fast toggle'], ['pulse(t, 0.3)', 'PWM 30%'], ['sin(t)*30+50', 'Sine 20–80'], ['abs(sin(t*3))*max', 'Bouncing'],
+    ['rand()', 'Noise'], ['t*20 % max', 'Linear ramp'], ['exp(t)', 'Exponential'], ['log(t)', 'Logarithmic'], ['bell(t)', 'Bell curve'],
+    ['step(t, 4)', '4 steps'], ['step(t, 8)', '8 steps'], ['exp(t)*0.5+25', 'Exp 25–75'], ['bell(t*2)', 'Fast bell'],
+    ['wave(t)+saw(t*2)*0.3', 'Layered'], ['tri(t)*pulse(t*4)', 'Gated bounce'], ['step(t, 6)*0.8+10', 'Steps 10–90'], ['ease(t*0.3, 3)*0.6+20', 'Slow dramatic'],
+  ] },
+  waves: { title: 'Waves', rows: [
+    ['wave(t)', 'Smooth up and down'], ['saw(t)', 'Ramp up, jump back'], ['tri(t)', 'Ramp up, ramp down'], ['pulse(t)', 'Snap on/off'],
+    ['rand()', 'Random every frame'], ['bell(t)', 'Bell curve'], ['exp(t)', 'Exponential ramp'], ['log(t)', 'Logarithmic ramp'], ['step(t, 4)', 'Staircase'],
+  ] },
+  functions: { title: 'Functions', grid: true, rows: [
+    ['sin', '-1 to 1'], ['cos', '-1 to 1'], ['tan', 'Tangent'], ['atan2', 'Angle of y, x'], ['abs', 'Absolute'],
+    ['floor', '↓ Round'], ['ceil', '↑ Round'], ['round', 'Nearest'], ['sqrt', '√'], ['pow', 'Power'],
+    ['clamp', 'Hold in a, b'], ['lerp', 'a → b by u'], ['mod', 'Wrap, never negative'], ['frac', 'Fractional part'], ['smooth', 'Smoothstep 0…1'],
+    ['PI', '3.14159'], ['TAU', '6.28318'], ['PHI', '1.61803'], ['E', '2.71828'],
+  ] },
+  variables: { title: 'Variables', rows: [
+    { codes: ['t', 'f'], label: 'Second / Frame count' }, ['min', 'Knob minimum'], ['max', 'Knob maximum'],
+  ] },
+  curves: { title: 'Curves', rows: [
+    ['ease(t)', 'Gentle breath'], ['ease(t, 1)', 'Linear, no curve'], ['ease(t, 5)', 'Dramatic punch'], ['ease(t, 0.5)', 'Quick flick'],
+  ] },
+  range: { title: 'Range', rows: [
+    ['saw(t)*0.8', '0 to 80'], ['wave(t)*0.5+25', '25 to 75'], ['tri(t)*0.3+70', '70 to 100'], ['ease(t)*0.2', '0 to 20'],
+  ] },
+  speed: { title: 'Speed', rows: [
+    ['wave(t*0.5)', 'Half speed'], ['saw(t*2)', 'Double speed'], ['tri(t*3)', '3x faster'], ['ease(t*5)', '5x faster'], ['pulse(t*0.1)', 'Very slow'],
+  ] },
+  tips: { title: 'Tips', tips: [
+    '→ Click numbers for expression input',
+    '→ Alt+click number to reset',
+    '→ Cmd+click expression to append to oscilloscope',
+  ] },
+}
+
+/* kol-mirror's fold: Examples alone; Language = what the language has; Usage = how to shape it.
+ * `saved` is the host's own list (a library) — the component renders what it is handed. */
+export const EXPRESSION_TABS = [
+  { id: 'examples', label: 'Examples', sections: ['examples'] },
+  { id: 'saved', label: 'Saved', sections: [] },
+  { id: 'language', label: 'Language', sections: ['waves', 'functions', 'variables'] },
+  { id: 'usage', label: 'Usage', sections: ['curves', 'range', 'speed', 'tips'] },
+]
+
+/* ADSR — a preset is `{ id, label, params }`, knob values 0…100. */
+export const ADSR_PRESETS = [
+  { id: 'pluck', label: 'Pluck', params: { attack: 0, decay: 12, sustain: 0, release: 10 } },
+  { id: 'pad', label: 'Pad', params: { attack: 60, decay: 40, sustain: 80, release: 70 } },
+  { id: 'swell', label: 'Swell', params: { attack: 85, decay: 10, sustain: 100, release: 40 } },
+  { id: 'gate', label: 'Gate', params: { attack: 0, decay: 0, sustain: 100, release: 0 } },
+  { id: 'stab', label: 'Stab', params: { attack: 2, decay: 25, sustain: 30, release: 15 } },
+  { id: 'fade', label: 'Slow fade', params: { attack: 5, decay: 90, sustain: 0, release: 90 } },
+]
+
+export const ADSR_SECTIONS = {
+  presets: { title: 'Presets', rows: ADSR_PRESETS.map((p) => [p.id, p.label]) },
+  stages: { title: 'Stages', rows: [
+    ['A', 'Attack — rise to full'], ['D', 'Decay — fall to sustain'], ['S', 'Sustain — held while the gate is open'], ['R', 'Release — fall to zero after the gate'],
+  ] },
+  timing: { title: 'Timing', rows: [
+    ['0', '5 ms'], ['50', '≈ 1 s'], ['100', '2 s'],
+  ] },
+  tips: { title: 'Tips', tips: [
+    '→ Sustain is a level, not a time',
+    '→ Gate holds sustain; a trigger runs A → D → R once',
+    '→ With sustain 0, a trigger folds D and R into one long decay',
+    '→ Cycle loops the whole envelope',
+  ] },
+}
+
+export const ADSR_TABS = [
+  { id: 'presets', label: 'Presets', sections: ['presets'] },
+  { id: 'saved', label: 'Saved', sections: [] },
+  { id: 'usage', label: 'Usage', sections: ['stages', 'timing', 'tips'] },
+]

package/src/signal/signal.test.mjs

@@ -0,0 +1,46 @@
+// 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'
+
+// helpers span [min, max] — monitor's semantics; min 0 is mirror's / the editor's
+const w = compileExpression('wave(t)')
+assert.ok(w.ok)
+assert.equal(Math.round(w.fn(0, 0, 0, 100)), 50)
+assert.equal(Math.round(w.fn(0, 0, -100, 100)), 0)
+assert.equal(compileExpression('pulse(0.25)').fn(0, 0, -100, 100), 100)
+assert.equal(compileExpression('pulse(0.75)').fn(0, 0, -100, 100), -100)
+assert.equal(compileExpression('saw(-0.25)').fn(0, 0, 0, 100), 75)   // wraps, never negative
+// every shipped example compiles
+for (const [code] of EXPRESSION_SECTIONS.examples.rows) assert.ok(compileExpression(code).ok, code)
+// the gates
+for (const bad of ['sin.constructor("return 1")()', 'window.x', 'Math.random()', 'fetch(1)', 'a+1', '"x"'])
+  assert.equal(compileExpression(bad).ok, false, bad)
+// bus names are allowed only when declared
+const b = compileExpression('a*2+b', { bus: ['a', 'b'] })
+assert.ok(b.ok)
+assert.equal(b.fn(0, 0, 0, 100, { a: 3, b: 1 }), 7)
+// never non-finite: last good value
+const inf = compileExpression('1/(t-1)')
+assert.equal(inf.fn(0), -1)
+assert.equal(inf.fn(1), -1)
+assert.ok(isExpression('wave(t)') && !isExpression('1e3') && !isExpression('42'))
+assert.deepEqual(fitRange('wave(t)', { sec: 10 }), { min: -10, max: 110 })
+
+// ADSR
+assert.equal(stageSeconds(0), 0.005)
+assert.equal(stageSeconds(100), 2)
+const p = { attack: 50, decay: 50, sustain: 40, release: 50 }
+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
+const env = createEnvelope()
+let lvl = 0
+for (let i = 0; i < 600; i++) lvl = env.step(1 / 60, { gate: true }, p)
+assert.equal(Math.round(lvl), 40)
+assert.equal(env.stage, 'sustain')
+for (let i = 0; i < 600; i++) lvl = env.step(1 / 60, { gate: false }, p)
+assert.equal(lvl, 0)
+assert.equal(env.stage, 'idle')
+
+console.log('signal: ok')

package/src/switches/FlipToggle.jsx

@@ -0,0 +1,80 @@
+/**
+ * FlipToggle — the eurorack flip switch, two or three positions (kol-monitor's
+ * rack, lifted 2026-09-01). `positions=2`: `value` is a boolean; `positions=3`:
+ * `value` is 0 · 1 · 2 (top, centre, bottom / left, centre, right).
+ *
+ * @param {boolean|number} value · onChange
+ * @param {string}   labelA · labelB · labelC   up to three labels along the switch
+ * @param {'vertical'|'horizontal'} variant   (default vertical)
+ * @param {2|3}      positions
+ */
+export default function FlipToggle({ value, onChange, labelA, labelB, labelC, variant = 'vertical', positions = 2 }) {
+  const isHorizontal = variant === 'horizontal'
+
+  const handleClick = () => {
+    if (positions === 3) {
+      onChange((value + 1) % 3)
+    } else {
+      onChange(!value)
+    }
+  }
+
+  const trackW = isHorizontal ? (positions === 3 ? 24 : 16) : 8
+  const trackH = isHorizontal ? 8 : (positions === 3 ? 24 : 16)
+  const thumbW = isHorizontal ? 8 : 6
+  const thumbH = isHorizontal ? 6 : 8
+
+  let thumbPos
+  if (positions === 3) {
+    const offsets = [0, 8, 15]
+    thumbPos = isHorizontal
+      ? { top: 0, left: offsets[value], transition: 'left 0.1s' }
+      : { left: 0, top: offsets[value], transition: 'top 0.1s' }
+  } else {
+    thumbPos = isHorizontal
+      ? { top: 0, left: value ? 0 : 7, transition: 'left 0.1s' }
+      : { left: 0, top: value ? 0 : 7, transition: 'top 0.1s' }
+  }
+
+  return (
+    <div
+      onClick={handleClick}
+      style={{ display: 'flex', flexDirection: isHorizontal ? 'row' : 'column', alignItems: 'center', gap: 2, cursor: 'pointer', userSelect: 'none' }}
+    >
+      {labelA && (
+        <span className="kol-helper-8 text-fg-32" style={{ textTransform: 'uppercase', lineHeight: 1 }}>
+          {labelA}
+        </span>
+      )}
+      <div style={{
+        width: trackW,
+        height: trackH,
+        borderRadius: 4,
+        backgroundColor: 'var(--kol-ctl-hw-cap)',
+        border: '1px solid var(--kol-ctl-hw-cap-edge)',
+        position: 'relative',
+        boxShadow: 'inset 0 1px 2px rgba(0,0,0,0.5)',
+      }}>
+        <div style={{
+          width: thumbW,
+          height: thumbH,
+          borderRadius: 3,
+          backgroundColor: 'var(--kol-ctl-hw-on-cap)',
+          position: 'absolute',
+          ...thumbPos,
+          boxShadow: '0 1px 2px rgba(0,0,0,0.3)',
+        }} />
+      </div>
+      {labelB && (
+        <span className="kol-helper-8 text-fg-32" style={{ textTransform: 'uppercase', lineHeight: 1 }}>
+          {labelB}
+        </span>
+      )}
+      {labelC && (
+        <span className="kol-helper-8 text-fg-32" style={{ textTransform: 'uppercase', lineHeight: 1 }}>
+          {labelC}
+        </span>
+      )}
+    </div>
+  )
+}

package/src/switches/IconButton.jsx

@@ -0,0 +1,58 @@
+import { useState, useRef } from 'react'
+import { Icon } from '@kolkrabbi/kol-icons'
+
+const PULSE_MS = 100
+
+/**
+ * IconButton — the icon-only panel key (kol-monitor's rack, lifted 2026-09-01):
+ * 1px border, radius 3, `active` lights the LED-red border and a 15% fill;
+ * `momentary` flashes the active style for ~100ms on click — trigger-style
+ * actions. Use with `PanelLabel` for a text label.
+ *
+ * @param {string}   icon         icon name
+ * @param {boolean}  active · disabled · momentary
+ * @param {Function} onClick
+ * @param {string}   title
+ * @param {number}   iconSize     (default 10)
+ * @param {ElementType} iconComponent  icon renderer seam (default kol-icons `Icon`)
+ */
+export default function IconButton({ icon, active, onClick, title, momentary, disabled, iconSize = 10, iconComponent: IconCmp = Icon }) {
+  const [pulse, setPulse] = useState(false)
+  const timeoutRef = useRef(null)
+  const isActive = active || pulse
+
+  const handleClick = (e) => {
+    if (disabled) return
+    if (momentary) {
+      setPulse(true)
+      if (timeoutRef.current) clearTimeout(timeoutRef.current)
+      timeoutRef.current = setTimeout(() => setPulse(false), PULSE_MS)
+    }
+    onClick?.(e)
+  }
+
+  return (
+    <button
+      type="button"
+      title={title}
+      onClick={handleClick}
+      disabled={disabled}
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        padding: 3,
+        borderRadius: 3,
+        border: '1px solid',
+        borderColor: isActive ? 'var(--kol-ctl-led-red)' : 'var(--kol-fg-08)',
+        backgroundColor: isActive ? 'color-mix(in srgb, var(--kol-ctl-led-red) 15%, transparent)' : 'transparent',
+        cursor: disabled ? 'not-allowed' : 'pointer',
+        color: isActive ? 'var(--kol-fg-88)' : 'var(--kol-fg-32)',
+        opacity: disabled ? 0.3 : 1,
+        transition: pulse ? 'none' : `border-color ${PULSE_MS}ms, background-color ${PULSE_MS}ms, color ${PULSE_MS}ms, opacity ${PULSE_MS}ms`,
+      }}
+    >
+      <IconCmp name={icon} size={iconSize} />
+    </button>
+  )
+}