@kolkrabbi/kol-hardware 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @kolkrabbi/kol-hardware
+
+The KOL **hardware** — panel controls for instruments: mixers, synths, racks, decks. Lifted out of kol-monitor's rack on 2026-09-01 as `@kolkrabbi/kol-controls` (user: *"make a controls package in the ds … it's mainly about mixer strips, knobs and stuff specific to modules, mixers and synth hardware"*); renamed `kol-hardware` on 2026-09-27. `@kolkrabbi/kol-controls` 0.4.0 is a deprecated re-export of this package.
+
+A different TIER from `kol-component`'s app atoms: a `kol-component` Slider is app chrome, a `Fader` is a 2px track on a 24px-tall eurorack panel. They coexist on purpose.
+
+## What's in the box — five groups
+
+| Group | Import | What |
+| --- | --- | --- |
+| 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 |
+| 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 |
+| 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` |
+| 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 |
+
+```js
+import { Knob, Fader, LED, ModuleFrame, EnvelopeGenerator } from '@kolkrabbi/kol-hardware'
+import { compileExpression, envelopeAt } from '@kolkrabbi/kol-hardware/signal'
+```
+
+**Not here, on purpose:** the panel's text field, select and ‹ value › stepper are `kol-component`'s `Input size="xs" onCommit`, `Dropdown size="xs"` and `Stepper size="xs" options` — the `xs` rung is what let them collapse (ControlsXsRung, kol-controls 0.3.0). `IconButton` stays: the lit border + momentary pulse are hardware semantics. **Frames are shapes, not modules** — routing, the rack and the render loop stay in the consumer.
+
+## The signal engine — `./signal`
+
+Plain JS, no React: one expression compiler (`compileExpression` — every helper spans `[min, max]`, two gates in front of the Function sink, never throws) and one ADSR (`envelopeAt` for drawing, `createEnvelope` for a per-frame module), plus the reference as data (`EXPRESSION_SECTIONS` / `_TABS`, `ADSR_PRESETS` / `_SECTIONS` / `_TABS`). `pnpm test` runs its check.
+
+## Tokens — `kol-components-controls.css` (ships in kol-theme)
+
+Hardware is theme-INVARIANT — a knob cap is black on a white panel too — so the caps derive from `--kol-color-ab-black` / `-white`, not the flipping `oq-ab` tiers. LEDs are the set's own emitters, deliberately not `--kol-palette-*` (user ruling).
+
+```
+--kol-ctl-hw-cap · -well · -shade · -cap-edge · -on-cap · -rail · -case · -cable
+--kol-ctl-led-red · -green · -yellow · -blue
+--kol-ctl-signal-input · --kol-ctl-cv-attenuate
+```
+
+`JackSocket` reads its colour role as a HEX off `:root` (it appends a hex alpha for the glow), so a consumer overriding a role binds a hex, never a `var()`.
+
+## Seams
+
+- **Icons** through `iconComponent` (`IconButton`, `LabeledJack`) — the seam the DS Button uses; default is kol-icons' `Icon`.
+- **Power** — `ModuleHeader powered` (default true); the consumer's case-power context decides.
+- **Routing** — `JackSocket` takes `active` · `pending` · `dimPending` · `cablesHidden` · `color` · `onPointerDown`; drag-to-patch, the registry and the pending cable are the consumer's.
+
+## Consumer requirements
+
+- **CSS** ships in `@kolkrabbi/kol-theme` (`kol-components-controls.css`, in the theme umbrella; a `core` consumer imports it as a domain pack) — this package ships JS only.
+- Tailwind v4 `@source "…/node_modules/@kolkrabbi/kol-hardware/src"` for the utility classes inside — or `@import "@kolkrabbi/kol-theme/kol-sources.css"`, which lists it since kol-theme 0.152.0.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@kolkrabbi/kol-hardware",
+  "version": "0.1.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",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./signal": "./src/signal/index.js",
+    "./*": "./src/*"
+  },
+  "peerDependencies": {
+    "@kolkrabbi/kol-component": ">=0.156.0",
+    "@kolkrabbi/kol-icons": ">=0.25.0",
+    "@kolkrabbi/kol-theme": ">=0.124.0",
+    "react": "^18.3.0 || ^19.0.0",
+    "react-dom": "^18.3.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@kolkrabbi/kol-component": "^0.225.0",
+    "@kolkrabbi/kol-icons": "^0.27.1",
+    "@kolkrabbi/kol-theme": "^0.152.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "kol",
+    "kolkrabbi",
+    "design-system",
+    "hardware",
+    "knob",
+    "fader",
+    "eurorack",
+    "mixer",
+    "synth",
+    "envelope",
+    "adsr",
+    "oscilloscope"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Tor-Grimsson/kol-ds.git",
+    "directory": "packages/hardware"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node src/signal/signal.test.mjs"
+  }
+}

package/src/frames/ChannelStrip.jsx

@@ -0,0 +1,31 @@
+/**
+ * ChannelStrip — a mixer channel's face (frames group, 2026-09-27). Lifted from kol-mirror's
+ * SymphonyMixer strip: a plate one rung below the desk, a top row of controls beside a column of
+ * actions, then the channel's sliders, then a footer. Slots only — which controls, which
+ * actions, what they do, all stay in the consumer.
+ *
+ * @param {ReactNode} power     the power control, top-left (e.g. a hardware Toggle)
+ * @param {ReactNode} controls  the control grid beside it (e.g. six dials, `grid-cols-3`)
+ * @param {ReactNode} actions   the right-hand column (e.g. IconButtons)
+ * @param {ReactNode} faders    the slider stack under the top row
+ * @param {ReactNode} footer    the bottom row, under a hairline
+ * @param {number}    width     plate width in px (default 320, mirror's)
+ */
+export default function ChannelStrip({ power, controls, actions, faders, footer, width = 320, className = '' }) {
+  return (
+    <div
+      className={`flex flex-col items-center gap-4 border border-oq-08 p-4 ${className}`}
+      style={{ background: 'var(--kol-oq-04)', borderRadius: 4, width }}
+    >
+      <div className="flex w-full items-stretch gap-4">
+        <div className="flex flex-1 flex-col gap-2">
+          {power && <div className="self-start">{power}</div>}
+          {controls}
+        </div>
+        {actions && <div className="flex flex-col gap-2">{actions}</div>}
+      </div>
+      {faders && <div className="flex w-full flex-col gap-1">{faders}</div>}
+      {footer && <div className="w-full border-t border-oq-08 pt-2">{footer}</div>}
+    </div>
+  )
+}

package/src/frames/FlipCard.jsx

@@ -0,0 +1,29 @@
+/**
+ * FlipCard — a face that turns over in place to show its back (frames group, 2026-09-27). Lifted
+ * from kol-mirror's channel flip (`styles/components.css` .mirror-flip-*), where a strip turns
+ * to its patch panel. The body turns; everything around it holds still, so the back is the same
+ * shaped object as the front.
+ *
+ * @param {boolean}   flipped
+ * @param {ReactNode} front · back
+ * @param {number|string} width   the card's width (the back is laid over the front at it)
+ * @param {number}    duration    ms (default 450, mirror's)
+ */
+export default function FlipCard({ flipped = false, front, back, width, duration = 450, className = '' }) {
+  const half = `visibility 0s ${duration / 2}ms`
+  return (
+    <div className={className} style={{ perspective: 1400, position: 'relative', width }}>
+      <div style={{ transition: `transform ${duration}ms ease`, transformStyle: 'preserve-3d', transform: flipped ? 'rotateY(180deg)' : 'none' }}>
+        <div style={{ backfaceVisibility: 'hidden', transition: half, visibility: flipped ? 'hidden' : 'visible' }}>
+          {front}
+        </div>
+        <div
+          aria-hidden={!flipped}
+          style={{ position: 'absolute', inset: 0, transform: 'rotateY(180deg)', backfaceVisibility: 'hidden', overflowY: 'auto', scrollbarWidth: 'none', transition: half, visibility: flipped ? 'visible' : 'hidden' }}
+        >
+          {back}
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/frames/ModuleFrame.jsx

@@ -0,0 +1,43 @@
+import ModuleHeader from '../panel/ModuleHeader.jsx'
+
+/**
+ * ModuleFrame — the front panel a module is built in: the header pinned at the top, the body
+ * below it (frames group, 2026-09-27). Lifted from kol-monitor's `modules/utility/Module.jsx`,
+ * where every rack module sits in it; kol-mirror's modules and the controls reference compose
+ * the same shape. Presentational — the rack's edit context, power and routing stay in the
+ * consumer and arrive as props.
+ *
+ * @param {string}   label        module name — omit for a headerless frame
+ * @param {boolean}  enabled · onToggle   the header's power toggle
+ * @param {boolean}  powered      the case's power (default true)
+ * @param {boolean}  editMode · onRemove  edit-mode remove dot
+ * @param {boolean}  bypass · onBypass    bypass dot
+ * @param {number}   u            rack height in U — a 1U module tightens its padding
+ * @param {string}   className    the plate (default bg-surface-secondary)
+ */
+const PAD = 12
+
+export default function ModuleFrame({
+  label, enabled, onToggle, powered = true, editMode, onRemove, bypass, onBypass,
+  u = 3, className = 'bg-surface-secondary', style, children,
+}) {
+  return (
+    <div
+      className={className}
+      style={{
+        width: '100%', height: '100%', display: 'flex', flexDirection: 'column',
+        padding: `${PAD}px 0 ${u === 1 ? 8 : PAD}px`, userSelect: 'none', ...style,
+      }}
+    >
+      {label && (
+        <div style={{ flexShrink: 0, padding: `0 4px ${u === 1 ? 8 : 16}px` }}>
+          <ModuleHeader label={label} enabled={enabled} onToggle={onToggle} powered={powered}
+            editMode={editMode} onRemove={onRemove} bypass={bypass} onBypass={onBypass} />
+        </div>
+      )}
+      <div style={{ flex: 1, overflow: 'hidden', padding: '0 4px', minHeight: 0 }}>
+        {children}
+      </div>
+    </div>
+  )
+}

package/src/index.js

@@ -0,0 +1,38 @@
+// @kolkrabbi/kol-hardware — hardware panel controls for instruments: everything drawn as hardware
+// (mixers, synths, racks, decks). Renamed from kol-controls 2026-09-27 (user ruling: "hardware"
+// says what it is — `controls` also meant the app atoms). Five groups:
+//
+//   value        things you turn or slide — Knob · Fader · the touch ParamSheet
+//   switches     hardware switches and buttons — Toggle · FlipToggle · RockerSwitch · IconButton
+//   indicators   lights and patching — LED · JackSocket · LabeledJack
+//   panel        panel furniture — PanelLabel · ModuleHeader
+//   frames       the shells a module is built in — ModuleFrame · ChannelStrip · FlipCard
+//
+// App-scale inputs are kol-component's (Dropdown · Input · Stepper at size="xs"); the panel copies
+// retired in kol-controls 0.3.0 (ControlsXsRung).
+
+// value
+export { default as Knob } from './value/Knob.jsx'
+export { default as Fader } from './value/Fader.jsx'
+export { default as ParamSheet } from './value/ParamSheet.jsx'
+export { armLongPress } from './value/armLongPress.js'
+// switches
+export { default as Toggle } from './switches/Toggle.jsx'
+export { default as FlipToggle } from './switches/FlipToggle.jsx'
+export { default as RockerSwitch } from './switches/RockerSwitch.jsx'
+export { default as IconButton } from './switches/IconButton.jsx'
+// indicators
+export { default as LED } from './indicators/LED.jsx'
+export { default as JackSocket } from './indicators/JackSocket.jsx'
+export { default as LabeledJack } from './indicators/LabeledJack.jsx'
+// panel
+export { default as PanelLabel } from './panel/PanelLabel.jsx'
+export { default as ModuleHeader } from './panel/ModuleHeader.jsx'
+// frames
+export { default as ModuleFrame } from './frames/ModuleFrame.jsx'
+export { default as ChannelStrip } from './frames/ChannelStrip.jsx'
+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'

package/src/indicators/JackSocket.jsx

@@ -0,0 +1,161 @@
+import { useRef, useEffect } from 'react'
+
+/* Read a colour binding once, lazily — the roles live in kol-theme's
+ * kol-components-controls.css. HEX is required here: the ring appends a hex
+ * alpha (`${color}${aa}`), so these must resolve to hex on :root, never var(). */
+const _hex = {}
+function token(name) {
+  if (!_hex[name]) _hex[name] = getComputedStyle(document.documentElement).getPropertyValue(name).trim()
+  return _hex[name]
+}
+
+/* Shared jack animation loop — single rAF, throttled to ~15fps, dirty-checked */
+const jackCallbacks = new Set()
+let jackRafId = null
+let jackFrame = 0
+function jackTick() {
+  jackFrame++
+  if (jackFrame % 4 === 0) {
+    for (const cb of jackCallbacks) cb()
+  }
+  jackRafId = requestAnimationFrame(jackTick)
+}
+function startJackLoop() {
+  if (jackRafId == null) jackRafId = requestAnimationFrame(jackTick)
+}
+function stopJackLoop() {
+  if (jackRafId != null) { cancelAnimationFrame(jackRafId); jackRafId = null }
+}
+
+/**
+ * JackSocket — the 3.5mm eurorack jack, PRESENTATIONAL (kol-monitor's rack,
+ * lifted 2026-09-01): ring (well) + hole + label, and a rim that glows with the
+ * signal — `signalRef.current` is `{ type: 'scalar'|'color'|'points', value, … }`,
+ * read on a shared rAF at ~15fps, dirty-checked. Drag-to-patch, the registry and
+ * the pending cable are the CONSUMER'S: they arrive as the props below and
+ * `onPointerDown`. Colour role: `color` is a HEX (the glow appends a hex alpha);
+ * default is the LED red; the consumer passes `--kol-ctl-signal-input` /
+ * `--kol-ctl-cv-attenuate` for its primary / attenuate inputs.
+ *
+ * @param {'in'|'out'} type
+ * @param {'sm'|'md'}  size         12 · 16 (default md)
+ * @param {string}     label · {string} labelSize  (`kol-helper-${labelSize}`, default `xxs`)
+ * @param {boolean}    active       a cable is connected here
+ * @param {boolean}    pending      this output is the pending cable's source
+ * @param {boolean}    dimPending   a cable is pending elsewhere (an input shows a dim ring)
+ * @param {boolean}    cablesHidden the consumer hides cables — a connected hole fills solid
+ * @param {string}     color        HEX role colour (default `--kol-ctl-led-red`)
+ * @param {object}     signalRef    `{ current }` — the live signal for the glow
+ * @param {boolean}    bg           the fg-04 plate behind the ring (default: outputs only)
+ * @param {Function}   onPointerDown  the consumer's routing gesture
+ * @param {string}     title
+ * @param {object|Function} ringRef  the RING element (ControlsJackSeams, kol-monitor 2026-09-01) — the
+ *                                consumer's drag-to-patch registers it for hit-testing (pointerup finds
+ *                                the nearest input ring centre); a ref object or a callback
+ */
+export default function JackSocket({
+  type = 'out',
+  size = 'md',
+  label,
+  labelSize = 'xxs',
+  active = false,
+  pending = false,
+  dimPending = false,
+  cablesHidden = false,
+  color,
+  signalRef,
+  bg,
+  onPointerDown,
+  title,
+  ringRef: ringRefProp,
+}) {
+  const ringRef = useRef(null)
+  /* one element, two refs: the glow loop's and the consumer's */
+  const setRing = (el) => {
+    ringRef.current = el
+    if (typeof ringRefProp === 'function') ringRefProp(el)
+    else if (ringRefProp) ringRefProp.current = el
+  }
+  const catColor = color || token('--kol-ctl-led-red')
+  const isConnected = active
+
+  // Animate ring glow proportional to signal value (shared rAF, ~15fps, dirty-checked)
+  useEffect(() => {
+    if (!signalRef || !ringRef.current) return
+    let prevNorm = -1
+    const cb = () => {
+      const signal = signalRef.current
+      let val = 0
+      if (!signal) val = 0
+      else if (signal.type === 'scalar') val = signal.value
+      else if (signal.type === 'color') { const c = signal.value; val = Math.max(c.r, c.g, c.b) * 100 }
+      else if (signal.type === 'points') val = signal.value?.length > 0 ? (signal.opacity ?? 1) * 100 : 0
+      const norm = Math.min(1, val / 100)
+      if (norm === prevNorm) return
+      prevNorm = norm
+      const ring = ringRef.current
+      if (ring) {
+        const alpha = Math.round(norm * 255).toString(16).padStart(2, '0')
+        ring.style.borderColor = norm > 0.01 ? `${catColor}${alpha}` : 'var(--kol-fg-24)'
+        ring.style.boxShadow = norm > 0.01 ? `0 0 ${2 + norm * 6}px ${catColor}${alpha}` : 'inset 0 1px 2px rgba(0,0,0,0.5)'
+      }
+    }
+    jackCallbacks.add(cb)
+    startJackLoop()
+    return () => {
+      jackCallbacks.delete(cb)
+      if (jackCallbacks.size === 0) stopJackLoop()
+    }
+  }, [signalRef, catColor])
+
+  const s = size === 'sm' ? 12 : 16
+  const hole = size === 'sm' ? 4 : 6
+
+  return (
+    <div
+      className="inline-flex flex-col items-center gap-0.5 select-none"
+      style={{ cursor: type === 'out' ? 'grab' : (dimPending ? 'pointer' : 'default'), touchAction: 'none' }}
+      onPointerDown={onPointerDown}
+      title={title ?? label}
+    >
+      <div
+        className={(bg ?? type === 'out') ? 'bg-fg-04' : ''}
+        style={{ width: `${s + 4}px`, height: `${s + 4}px`, display: 'flex', alignItems: 'center', justifyContent: 'center', borderRadius: 3 }}
+      >
+        <div
+          ref={setRing}
+          style={{
+            width: `${s}px`,
+            height: `${s}px`,
+            borderRadius: '50%',
+            backgroundColor: 'var(--kol-ctl-hw-well)',
+            border: `1.5px solid ${
+              pending ? catColor
+              : active ? catColor
+              : dimPending && type === 'in' ? `${catColor}66`
+              : 'var(--kol-fg-24)'
+            }`,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            boxShadow: 'inset 0 1px 2px rgba(0,0,0,0.5)',
+            transition: 'border-color 0.1s',
+          }}
+        >
+          <div style={{
+            width: `${hole}px`,
+            height: `${hole}px`,
+            borderRadius: '50%',
+            backgroundColor: cablesHidden && isConnected ? catColor : isConnected || pending ? `${catColor}66` : 'var(--kol-ctl-hw-well)',
+            border: type === 'in' ? '1px solid var(--kol-ctl-hw-cap-edge)' : '0.5px solid var(--kol-ctl-hw-shade)',
+          }} />
+        </div>
+      </div>
+      {label && (
+        <span className={`kol-helper-${labelSize} text-fg-32`} style={{ textTransform: 'uppercase', lineHeight: 1 }}>
+          {label}
+        </span>
+      )}
+    </div>
+  )
+}

package/src/indicators/LED.jsx

@@ -0,0 +1,45 @@
+/* The set's own LED colours (`--kol-ctl-led-*`) — a module that needs a
+ * red/green/yellow uses <LED color="…"> or the same token, never a hex. */
+const COLORS = {
+  red: 'var(--kol-ctl-led-red)',
+  yellow: 'var(--kol-ctl-led-yellow)',
+  green: 'var(--kol-ctl-led-green)',
+  white: 'var(--kol-fg-88)',
+  blue: 'var(--kol-ctl-led-blue)',
+}
+
+const SIZES = { sm: 6, md: 8 }
+const HIT_PAD = 5
+
+/**
+ * LED — the indicator lamp (kol-monitor's rack, lifted 2026-09-01). Sizes sm 6 ·
+ * md 8; colours red · yellow · green · white · blue, or any CSS colour. With
+ * `onClick` an invisible hit pad (+5px each side) overlays the lamp.
+ *
+ * @param {boolean}  active
+ * @param {string}   color   a name above or a CSS colour (default red)
+ * @param {'sm'|'md'|number} size
+ * @param {Function} onClick
+ */
+export default function LED({ active = false, color = 'red', size = 'sm', onClick }) {
+  const s = SIZES[size] || size
+  const c = COLORS[color] || color
+  return (
+    <div style={{ width: s, height: s, flexShrink: 0, position: 'relative' }}>
+      <div style={{
+        width: s,
+        height: s,
+        borderRadius: '50%',
+        backgroundColor: active ? c : 'var(--kol-fg-16)',
+        boxShadow: active ? `0 0 4px color-mix(in srgb, ${c} 40%, transparent)` : 'none',
+        transition: 'background-color 0.1s, box-shadow 0.1s',
+      }} />
+      {onClick && (
+        <div
+          onClick={onClick}
+          style={{ position: 'absolute', top: -HIT_PAD, left: -HIT_PAD, width: s + HIT_PAD * 2, height: s + HIT_PAD * 2, cursor: 'pointer' }}
+        />
+      )}
+    </div>
+  )
+}

package/src/indicators/LabeledJack.jsx

@@ -0,0 +1,35 @@
+import { Icon } from '@kolkrabbi/kol-icons'
+import JackSocket from './JackSocket.jsx'
+
+/**
+ * LabeledJack — a `JackSocket` with an 8px label or a dim icon beside it
+ * (kol-monitor's rack, lifted 2026-09-01). Use instead of the socket's own
+ * `label` when the label should sit left / right / above.
+ *
+ * @param {string}   label · {string} icon · {number} iconSize (8)
+ * @param {'top'|'bottom'|'left'|'right'} labelPosition  (default bottom)
+ * @param {boolean}  dim          the whole jack at 30%
+ * @param {ElementType} iconComponent  icon renderer seam (default kol-icons `Icon`)
+ * @param {ElementType} jackComponent  the jack to label (ControlsJackSeams, kol-monitor 2026-09-01):
+ *                                     a consumer whose jack is WIRED — routing props computed from its
+ *                                     own context — passes it here and keeps no copy of this layout;
+ *                                     default the package's presentational `JackSocket`
+ * @param {...*}     jackProps    everything else goes to the jack
+ */
+export default function LabeledJack({ label, icon, iconSize = 8, labelPosition = 'bottom', dim = false, iconComponent: IconCmp = Icon, jackComponent: Jack = JackSocket, ...jackProps }) {
+  const labelEl = icon
+    ? <IconCmp name={icon} size={iconSize} style={{ opacity: 0.35 }} />
+    : label && (
+      <span className="kol-helper-8 text-fg-32" style={{ textTransform: 'uppercase', lineHeight: 1 }}>
+        {label}
+      </span>
+    )
+  const isRow = labelPosition === 'left' || labelPosition === 'right'
+  return (
+    <div style={{ display: 'flex', flexDirection: isRow ? 'row' : 'column', alignItems: 'center', gap: 2, opacity: dim ? 0.3 : 1 }}>
+      {(labelPosition === 'top' || labelPosition === 'left') && labelEl}
+      <Jack {...jackProps} />
+      {(labelPosition === 'bottom' || labelPosition === 'right') && labelEl}
+    </div>
+  )
+}

package/src/indicators/SignalScope.jsx

@@ -0,0 +1,105 @@
+import { useEffect, useRef } from 'react'
+
+/**
+ * SignalScope — the oscilloscope every expression tool draws (signal engine, 2026-09-27): a
+ * trace of `sample(t)` over a window, the knob range as dashed reference lines, a midline, and
+ * a playhead that sweeps the window live. kol-mirror's /expressions scope, kol-monitor's
+ * Scope / Scope+ and the design editor's Oscilloscope loop each drew their own.
+ *
+ * Presentational: pass any `sample(t) → number` — a compiled expression, an envelope, a bus.
+ *
+ * @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[]} 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)
+ */
+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 = '',
+}) {
+  const ref = useRef(null)
+  const args = useRef({})
+  const drawRef = useRef(null)
+  args.current = { sample, min, max, sec, ofs, refLines, live }
+
+  useEffect(() => {
+    const canvas = ref.current
+    if (!canvas) return undefined
+    const ctx = canvas.getContext('2d')
+    const start = 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 dpr = window.devicePixelRatio || 1
+      const { width: w, height: h } = canvas.getBoundingClientRect()
+      if (canvas.width !== Math.round(w * dpr) || canvas.height !== Math.round(h * dpr)) {
+        canvas.width = Math.round(w * dpr)
+        canvas.height = Math.round(h * dpr)
+      }
+      ctx.setTransform(dpr, 0, 0, dpr, 0, 0)
+      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 pad = 12
+      const span = hi - lo || 1
+      const toY = (v) => pad + (h - pad * 2) * (1 - (v - lo) / span)
+      ctx.font = '9px var(--kol-font-family-mono), monospace'
+      // midline
+      ctx.globalAlpha = 0.12
+      ctx.strokeStyle = ink
+      ctx.lineWidth = 1
+      ctx.beginPath(); ctx.moveTo(0, toY((lo + hi) / 2)); ctx.lineTo(w, toY((lo + hi) / 2)); ctx.stroke()
+      // the knob range, dashed
+      ctx.globalAlpha = 0.35
+      ctx.strokeStyle = red
+      ctx.fillStyle = red
+      ctx.setLineDash([4, 4])
+      for (const v of lines) {
+        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)
+      }
+      ctx.setLineDash([])
+      // axis labels
+      ctx.globalAlpha = 0.4
+      ctx.fillStyle = ink
+      ctx.fillText(String(hi), 4, pad + 9)
+      ctx.fillText(String(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)
+        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()
+      }
+      if (on) raf = requestAnimationFrame(draw)
+    }
+    drawRef.current = draw
+    draw()
+    const ro = new ResizeObserver(() => { if (!args.current.live) draw() })
+    ro.observe(canvas)
+    return () => { cancelAnimationFrame(raf); ro.disconnect() }
+  }, [live])
+
+  // 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 }} />
+}

package/src/panel/ModuleHeader.jsx

@@ -0,0 +1,39 @@
+import Toggle from '../switches/Toggle.jsx'
+
+/**
+ * ModuleHeader — the enable dot + module name, left-aligned (kol-monitor's rack,
+ * lifted 2026-09-01). In edit mode the yellow dot removes the module; otherwise
+ * an optional bypass dot. The consumer's case-power context became `powered`:
+ * when the case is off the dot shows off whatever `enabled` says.
+ *
+ * @param {string}   label
+ * @param {boolean}  enabled · onToggle
+ * @param {boolean}  powered      the case's power (default true)
+ * @param {boolean}  editMode · {Function} onRemove
+ * @param {boolean}  bypass · {Function} onBypass
+ */
+export default function ModuleHeader({ label, enabled, onToggle, powered = true, editMode, onRemove, bypass, onBypass }) {
+  const isOn = powered && enabled
+
+  return (
+    <div onClick={() => onToggle?.()} style={{ display: 'flex', alignItems: 'center', gap: 6, width: '100%', padding: '0 2px', flexShrink: 0, cursor: 'pointer', userSelect: 'none' }}>
+      <Toggle value={isOn} size="sm" onChange={() => {}} padding={0} />
+      <span className="kol-helper-10 text-fg-48" style={{ textTransform: 'uppercase', letterSpacing: '0.5px', flex: 1 }}>
+        {label}
+      </span>
+      {editMode && onRemove ? (
+        <div
+          onClick={(e) => { e.stopPropagation(); onRemove() }}
+          title="Send module to workbench"
+          style={{ width: 8, height: 8, borderRadius: '50%', backgroundColor: 'var(--kol-ctl-led-yellow)', cursor: 'pointer', flexShrink: 0 }}
+        />
+      ) : onBypass ? (
+        <div
+          onClick={(e) => { e.stopPropagation(); onBypass() }}
+          title={bypass ? 'Bypassed — click to re-engage' : 'Bypass'}
+          style={{ width: 8, height: 8, borderRadius: '50%', backgroundColor: 'var(--kol-ctl-cv-attenuate)', opacity: bypass ? 0.25 : 1, cursor: 'pointer', flexShrink: 0 }}
+        />
+      ) : null}
+    </div>
+  )
+}