@vessel-dsp/core 0.5.0

package/src/panel/index.ts

@@ -0,0 +1,39 @@
+export type {
+    ControlState,
+    ControlValue,
+    DeviceInterfaceProvenance,
+    ExternalControlAssignmentHint,
+    ExtractedDeviceInterface,
+    ExtractedDeviceInterfaceControl,
+    JackAudioRole,
+    JackPort,
+    JackRole,
+    Knob,
+    KnobControlMode,
+    KnobStep,
+    KnobTaper,
+    KnobValue,
+    LedIndicator,
+    LedValue,
+    Panel,
+    PanelMessage,
+    SliderControl,
+    SliderOrientation,
+    SliderRange,
+    SliderValue,
+    SwitchControl,
+    SwitchKind,
+    SwitchValue,
+} from './types';
+export { PANEL_PROTOCOL_VERSION } from './types';
+export { extractDeviceInterface, extractPanel } from './extract';
+export { isKnobPositionOnStep, knobStepSize, nearestKnobStep, snapKnobPosition } from './knobs';
+export {
+    applyControlMessage,
+    defaultControlState,
+    isKnob,
+    isLed,
+    isSlider,
+    isSwitch,
+    validateMessage,
+} from './protocol';

package/src/panel/knobs.ts

@@ -0,0 +1,70 @@
+import type { Knob, KnobStep } from './types';
+
+const KNOB_POSITION_EPSILON = 1e-9;
+const POSITION_ROUNDING_FACTOR = 1_000_000_000_000;
+
+export function buildKnobSteps(count: number, labels: readonly string[] = []): readonly KnobStep[] | undefined {
+    if (!Number.isFinite(count)) {
+        return undefined;
+    }
+
+    const normalizedCount = Math.trunc(count);
+    if (normalizedCount < 2) {
+        return undefined;
+    }
+
+    return Array.from({ length: normalizedCount }, (_, index) => {
+        const position = roundPosition(index / (normalizedCount - 1));
+        const label = labels[index];
+        if (label !== undefined && label.length > 0) {
+            return { index, position, label };
+        }
+        return { index, position };
+    });
+}
+
+export function nearestKnobStep(steps: readonly KnobStep[] | undefined, position: number): KnobStep | undefined {
+    if (steps === undefined || steps.length === 0 || !Number.isFinite(position)) {
+        return undefined;
+    }
+
+    let nearest = steps[0];
+    if (nearest === undefined) {
+        return undefined;
+    }
+
+    let nearestDistance = Math.abs(position - nearest.position);
+    for (const step of steps.slice(1)) {
+        const distance = Math.abs(position - step.position);
+        if (distance < nearestDistance) {
+            nearest = step;
+            nearestDistance = distance;
+        }
+    }
+    return nearest;
+}
+
+export function snapKnobPosition(knob: Pick<Knob, 'steps'>, position: number): number {
+    const nearest = nearestKnobStep(knob.steps, position);
+    return nearest?.position ?? position;
+}
+
+export function isKnobPositionOnStep(knob: Pick<Knob, 'steps'>, position: number): boolean {
+    const nearest = nearestKnobStep(knob.steps, position);
+    if (nearest === undefined) {
+        return true;
+    }
+    return Math.abs(position - nearest.position) <= KNOB_POSITION_EPSILON;
+}
+
+export function knobStepSize(knob: Pick<Knob, 'steps'>): number | undefined {
+    const count = knob.steps?.length ?? 0;
+    if (count < 2) {
+        return undefined;
+    }
+    return roundPosition(1 / (count - 1));
+}
+
+function roundPosition(value: number): number {
+    return Math.round(value * POSITION_ROUNDING_FACTOR) / POSITION_ROUNDING_FACTOR;
+}

package/src/panel/protocol.ts

@@ -0,0 +1,117 @@
+import type {
+    ControlState,
+    ControlValue,
+    KnobValue,
+    LedValue,
+    Panel,
+    PanelMessage,
+    SliderValue,
+    SwitchValue,
+} from './types';
+import { isKnobPositionOnStep, snapKnobPosition } from './knobs';
+
+// defaultControlState builds the initial control state from a Panel descriptor.
+// Every knob/switch lands at its declared default; every LED starts off.
+export function defaultControlState(panel: Panel): ControlState {
+    const state: Record<string, ControlValue> = {};
+    for (const knob of panel.knobs) {
+        state[knob.id] = { kind: 'knob', position: snapKnobPosition(knob, knob.defaultPosition) };
+    }
+    for (const slider of panel.sliders ?? []) {
+        state[slider.id] = { kind: 'slider', position: slider.defaultPosition };
+    }
+    for (const sw of panel.switches) {
+        state[sw.id] = { kind: 'switch', position: sw.defaultPosition };
+    }
+    for (const led of panel.leds) {
+        state[led.id] = { kind: 'led', on: false };
+    }
+    return state;
+}
+
+// applyControlMessage is a pure reducer: (state, message) → state. Callers can
+// route the same message in both directions — `control/set` from UI → DSP and
+// `control/changed` from DSP → UI both produce the same state update.
+export function applyControlMessage(state: ControlState, message: PanelMessage): ControlState {
+    switch (message.type) {
+        case 'panel/load':
+            return defaultControlState(message.panel);
+        case 'state/snapshot':
+            return message.state;
+        case 'state/request':
+        case 'control/error':
+            return state;
+        case 'control/set':
+        case 'control/changed':
+            return { ...state, [message.controlId]: message.value };
+    }
+}
+
+// Type guards make it safe for consumers to interrogate ControlValues without
+// reaching into the discriminator manually.
+export function isKnob(value: ControlValue | undefined): value is KnobValue {
+    return value !== undefined && value.kind === 'knob';
+}
+
+export function isSlider(value: ControlValue | undefined): value is SliderValue {
+    return value !== undefined && value.kind === 'slider';
+}
+
+export function isSwitch(value: ControlValue | undefined): value is SwitchValue {
+    return value !== undefined && value.kind === 'switch';
+}
+
+export function isLed(value: ControlValue | undefined): value is LedValue {
+    return value !== undefined && value.kind === 'led';
+}
+
+// Validate a message against a Panel — useful when the UI receives an event
+// from the DSP and needs to ensure the controlId still exists. Returns null on
+// success or a short reason string on failure.
+export function validateMessage(panel: Panel, message: PanelMessage): string | null {
+    if (message.type === 'control/set' || message.type === 'control/changed') {
+        const knob = panel.knobs.find((k) => k.id === message.controlId);
+        if (knob !== undefined) {
+            if (message.value.kind !== 'knob') {
+                return `control "${message.controlId}" is a knob but received ${message.value.kind} value`;
+            }
+            if (!Number.isFinite(message.value.position) || message.value.position < 0 || message.value.position > 1) {
+                return `knob "${message.controlId}" position must be in [0,1]`;
+            }
+            if (!isKnobPositionOnStep(knob, message.value.position)) {
+                const stepCount = knob.steps?.length ?? 0;
+                return `knob "${message.controlId}" position must match one of ${stepCount} stepped positions`;
+            }
+            return null;
+        }
+        const slider = (panel.sliders ?? []).find((s) => s.id === message.controlId);
+        if (slider !== undefined) {
+            if (message.value.kind !== 'slider') {
+                return `control "${message.controlId}" is a slider but received ${message.value.kind} value`;
+            }
+            if (!Number.isFinite(message.value.position) || message.value.position < 0 || message.value.position > 1) {
+                return `slider "${message.controlId}" position must be in [0,1]`;
+            }
+            return null;
+        }
+        const sw = panel.switches.find((s) => s.id === message.controlId);
+        if (sw !== undefined) {
+            if (message.value.kind !== 'switch') {
+                return `control "${message.controlId}" is a switch but received ${message.value.kind} value`;
+            }
+            if (!Number.isInteger(message.value.position) || message.value.position < 0 || message.value.position >= sw.positions) {
+                return `switch "${message.controlId}" position must be in [0,${sw.positions - 1}]`;
+            }
+            return null;
+        }
+        const led = panel.leds.find((l) => l.id === message.controlId);
+        if (led !== undefined) {
+            if (message.value.kind !== 'led') {
+                return `control "${message.controlId}" is an LED but received ${message.value.kind} value`;
+            }
+            return null;
+        }
+        return `unknown control id "${message.controlId}"`;
+    }
+    return null;
+}

package/src/panel/types.ts

@@ -0,0 +1,180 @@
+import type {
+    ControlContext,
+    ControlGroup,
+    ControlInterfaceAssignmentHint,
+    ControlInterfaceBinding,
+    ControlInterfaceConnector,
+    ControlInterfacePolarity,
+    DeviceInterfaceBinding,
+    DeviceInterfaceControl,
+    PanelPlacementMetadata,
+    ParsedQuantity,
+    Warning,
+} from '../model/types';
+
+// ---------- Static panel descriptor (extracted from a CircuitDocument) ----------
+
+export type KnobTaper = 'linear' | 'log' | 'reverse-log' | 'unknown';
+export type KnobControlMode = 'continuous' | 'stepped';
+
+export type KnobStep = Readonly<{
+    index: number;
+    position: number;
+    label?: string;
+}>;
+
+export type Knob = Readonly<{
+    id: string;
+    name: string;
+    taper: KnobTaper;
+    controlMode?: KnobControlMode;
+    defaultPosition: number;
+    steps?: readonly KnobStep[];
+    resistance?: ParsedQuantity;
+    gangGroup?: string;
+    description?: string;
+}>;
+
+export type SliderOrientation = 'vertical' | 'horizontal';
+
+export type SliderRange = Readonly<{
+    min: number;
+    max: number;
+    unit?: string;
+    center?: number;
+}>;
+
+export type SliderControl = Readonly<{
+    id: string;
+    name: string;
+    defaultPosition: number;
+    orientation: SliderOrientation;
+    range?: SliderRange;
+    gangGroup?: string;
+    description?: string;
+}>;
+
+export type SwitchKind = 'spst' | 'spdt' | 'sp3t' | 'sp4t' | '3pdt' | 'toggle' | 'rotary' | 'unknown';
+
+export type SwitchControl = Readonly<{
+    id: string;
+    name: string;
+    switchKind: SwitchKind;
+    poles: number;
+    positions: number;
+    defaultPosition: number;
+    gangGroup?: string;
+    partNumber?: string;
+    description?: string;
+}>;
+
+export type LedIndicator = Readonly<{
+    id: string;
+    name: string;
+    color?: string;
+    partNumber?: string;
+    description?: string;
+}>;
+
+export type JackRole =
+    | 'input'
+    | 'output'
+    | 'direct-output'
+    | 'send'
+    | 'return'
+    | 'expression'
+    | 'tempo-tap'
+    | 'external-control'
+    | 'unknown';
+
+export type JackAudioRole =
+    | 'guitar-input'
+    | 'bass-input'
+    | 'main-output'
+    | 'mono-output'
+    | 'output-a'
+    | 'output-a-mono'
+    | 'output-b'
+    | 'stereo-output-b'
+    | 'direct-output'
+    | 'dry-output'
+    | 'wet-output'
+    | (string & {});
+
+export type ExternalControlAssignmentHint = ControlInterfaceAssignmentHint;
+
+export type JackPort = Readonly<{
+    id: string;
+    name: string;
+    role: JackRole;
+    audioRole?: JackAudioRole;
+    impedance?: ParsedQuantity;
+    sourceTypeName?: string;
+    sourceComponentId?: string;
+    controlRole?: string;
+    interface?: string;
+    connector?: ControlInterfaceConnector;
+    assignmentHint?: ExternalControlAssignmentHint;
+    polarity?: ControlInterfacePolarity;
+    binding?: ControlInterfaceBinding;
+    description?: string;
+}>;
+
+export type Panel = Readonly<{
+    placement?: PanelPlacementMetadata;
+    knobs: readonly Knob[];
+    sliders?: readonly SliderControl[];
+    switches: readonly SwitchControl[];
+    leds: readonly LedIndicator[];
+    jacks: readonly JackPort[];
+}>;
+
+export type DeviceInterfaceProvenance =
+    | 'vdsp-declared'
+    | 'source-inferred'
+    | 'runtime-descriptor-inferred'
+    | 'control-interface-declared';
+
+export type ExtractedDeviceInterfaceControl = DeviceInterfaceControl & Readonly<{
+    provenance: DeviceInterfaceProvenance;
+    inferredBinding?: DeviceInterfaceBinding;
+}>;
+
+export type ExtractedDeviceInterface = Readonly<{
+    groups: readonly ControlGroup[];
+    contexts: readonly ControlContext[];
+    controls: readonly ExtractedDeviceInterfaceControl[];
+    placement?: PanelPlacementMetadata;
+    diagnostics: readonly Warning[];
+}>;
+
+// ---------- Runtime control state (UI ↔ DSP wire protocol) ----------
+
+// Every control reports its value through a tagged-union ControlValue.
+// The same shape is used in messages going UI → DSP (`control/set`) and DSP → UI
+// (`control/changed`, e.g. LED illumination from a level detector).
+export type KnobValue = Readonly<{ kind: 'knob'; position: number }>;
+export type SliderValue = Readonly<{ kind: 'slider'; position: number }>;
+export type SwitchValue = Readonly<{ kind: 'switch'; position: number }>;
+export type LedValue = Readonly<{ kind: 'led'; on: boolean; intensity?: number }>;
+
+export type ControlValue = KnobValue | SliderValue | SwitchValue | LedValue;
+
+export type ControlState = Readonly<Record<string, ControlValue>>;
+
+// ---------- Wire protocol ----------
+
+// Message envelope — JSON serializable. Implementations can put this on top of
+// any transport (postMessage, WebSocket, MIDI sysex, OSC bundle, FFI marshalling).
+// The `requestId` field is optional and lets a caller correlate request/response
+// when the transport doesn't already preserve ordering.
+
+export type PanelMessage =
+    | Readonly<{ type: 'panel/load'; panel: Panel; requestId?: string }>
+    | Readonly<{ type: 'state/snapshot'; state: ControlState; requestId?: string }>
+    | Readonly<{ type: 'state/request'; requestId?: string }>
+    | Readonly<{ type: 'control/set'; controlId: string; value: ControlValue; requestId?: string }>
+    | Readonly<{ type: 'control/changed'; controlId: string; value: ControlValue; requestId?: string }>
+    | Readonly<{ type: 'control/error'; controlId: string; reason: string; requestId?: string }>;
+
+export const PANEL_PROTOCOL_VERSION = 1 as const;

package/src/preview/bounds.ts

@@ -0,0 +1,85 @@
+import { propertyStringValue } from '../model/properties';
+import type { CircuitDocument, Point, PropertyValue } from '../model/types';
+import { computeLabelTextBoxLayout, shouldRenderLabelTextBox } from './label-layout';
+
+export type Bounds = Readonly<{
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+    width: number;
+    height: number;
+}>;
+
+const DEFAULT_PADDING = 60;
+const FALLBACK_HALF = 160;
+
+export function computeDocumentBounds(doc: CircuitDocument, padding: number = DEFAULT_PADDING): Bounds {
+    const points: Point[] = [];
+
+    for (const component of doc.components) {
+        points.push(component.origin);
+        if (component.kind === 'label') {
+            const text = stringValue(component.properties.Text) ?? component.name;
+            const subtext = stringValue(component.properties.Subtext);
+            if (shouldRenderLabelTextBox(text, subtext)) {
+                const box = computeLabelTextBoxLayout(text, subtext);
+                points.push({
+                    x: component.origin.x + box.width,
+                    y: component.origin.y + box.height,
+                });
+            }
+        }
+        for (const terminal of component.terminals) {
+            points.push(terminal.position);
+        }
+    }
+    for (const wire of doc.wires) {
+        points.push(wire.endpoints[0], wire.endpoints[1]);
+    }
+
+    if (points.length === 0) {
+        const width = FALLBACK_HALF * 2;
+        return {
+            minX: -FALLBACK_HALF,
+            minY: -FALLBACK_HALF,
+            maxX: FALLBACK_HALF,
+            maxY: FALLBACK_HALF,
+            width,
+            height: width,
+        };
+    }
+
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    for (const p of points) {
+        if (p.x < minX) minX = p.x;
+        if (p.y < minY) minY = p.y;
+        if (p.x > maxX) maxX = p.x;
+        if (p.y > maxY) maxY = p.y;
+    }
+
+    const paddedMinX = minX - padding;
+    const paddedMinY = minY - padding;
+    const paddedMaxX = maxX + padding;
+    const paddedMaxY = maxY + padding;
+
+    return {
+        minX: paddedMinX,
+        minY: paddedMinY,
+        maxX: paddedMaxX,
+        maxY: paddedMaxY,
+        width: paddedMaxX - paddedMinX,
+        height: paddedMaxY - paddedMinY,
+    };
+}
+
+export function viewBoxString(bounds: Bounds): string {
+    return `${bounds.minX} ${bounds.minY} ${bounds.width} ${bounds.height}`;
+}
+
+function stringValue(value: PropertyValue | undefined): string | null {
+    return propertyStringValue(value);
+}

package/src/preview/box-layout.ts

@@ -0,0 +1,24 @@
+import type { Bounds } from './bounds';
+import type { Component } from '../model/types';
+
+// Every component renders in a uniform square container centered on its origin.
+// HALF_SIZE=20 matches the symbol viewBox (−25..25 with body content within ±20).
+// Lead axes that extend beyond ±20 (potentiometer ±40, op-amp ±30) intentionally
+// reach OUT of the container — they're connection lines to wires, not symbol body.
+const HALF_SIZE = 20;
+
+export function computeComponentBox(component: Component): Bounds {
+    const minX = component.origin.x - HALF_SIZE;
+    const minY = component.origin.y - HALF_SIZE;
+    const maxX = component.origin.x + HALF_SIZE;
+    const maxY = component.origin.y + HALF_SIZE;
+
+    return {
+        minX,
+        minY,
+        maxX,
+        maxY,
+        width: maxX - minX,
+        height: maxY - minY,
+    };
+}

package/src/preview/colors.ts

@@ -0,0 +1,43 @@
+import type { ComponentKind } from '../model/types';
+
+const KIND_COLOR: Readonly<Record<ComponentKind, string>> = {
+    resistor: '#3b82f6',
+    capacitor: '#3b82f6',
+    inductor: '#3b82f6',
+    potentiometer: '#3b82f6',
+    'variable-resistor': '#3b82f6',
+    transformer: '#14b8a6',
+    diode: '#ef4444',
+    led: '#ef4444',
+    bjt: '#ef4444',
+    jfet: '#ef4444',
+    mosfet: '#ef4444',
+    opamp: '#14b8a6',
+    ota: '#14b8a6',
+    optocoupler: '#14b8a6',
+    bbd: '#14b8a6',
+    'delay-ic': '#14b8a6',
+    'power-amp': '#14b8a6',
+    regulator: '#f97316',
+    'analog-switch': '#eab308',
+    flipflop: '#a855f7',
+    ic: '#14b8a6',
+    triode: '#a855f7',
+    pentode: '#a855f7',
+    'tube-diode': '#a855f7',
+    'voltage-source': '#f97316',
+    'current-source': '#f97316',
+    battery: '#f97316',
+    rail: '#f97316',
+    ground: '#64748b',
+    switch: '#eab308',
+    jack: '#ec4899',
+    label: '#64748b',
+    'named-wire': '#64748b',
+    port: '#64748b',
+    unsupported: '#94a3b8',
+};
+
+export function colorForKind(kind: ComponentKind): string {
+    return KIND_COLOR[kind];
+}

package/src/preview/hanging.ts

@@ -0,0 +1,94 @@
+import type { CircuitDocument, Point, Wire } from '../model/types';
+
+export type HangingEndpoint = Readonly<{
+    wireId: string;
+    point: Point;
+    // 0 = first endpoint (A), 1 = second endpoint (B)
+    endpointIndex: 0 | 1;
+}>;
+
+// A wire endpoint is "hanging" when it doesn't actually connect to anything:
+// - It doesn't coincide with any component terminal position
+// - It doesn't coincide with another wire's endpoint
+// - It doesn't lie on another wire's body (T-junction)
+// These show up as floating dots in the schematic view and almost always
+// indicate a fixture data bug.
+export function findHangingEndpoints(doc: CircuitDocument): readonly HangingEndpoint[] {
+    const terminalSet = new Set<string>();
+    for (const component of doc.components) {
+        for (const terminal of component.terminals) {
+            terminalSet.add(pointKey(terminal.position));
+        }
+    }
+
+    const endpointCounts = new Map<string, number>();
+    for (const wire of doc.wires) {
+        endpointCounts.set(pointKey(wire.endpoints[0]), (endpointCounts.get(pointKey(wire.endpoints[0])) ?? 0) + 1);
+        endpointCounts.set(pointKey(wire.endpoints[1]), (endpointCounts.get(pointKey(wire.endpoints[1])) ?? 0) + 1);
+    }
+
+    const hanging: HangingEndpoint[] = [];
+    for (const wire of doc.wires) {
+        for (const [endpointIndex, point] of [[0, wire.endpoints[0]] as const, [1, wire.endpoints[1]] as const]) {
+            if (isConnected(point, wire, doc.wires, terminalSet, endpointCounts)) {
+                continue;
+            }
+            hanging.push({ wireId: wire.id, point, endpointIndex });
+        }
+    }
+    return hanging;
+}
+
+function isConnected(
+    point: Point,
+    owningWire: Wire,
+    allWires: readonly Wire[],
+    terminalSet: ReadonlySet<string>,
+    endpointCounts: ReadonlyMap<string, number>,
+): boolean {
+    if (terminalSet.has(pointKey(point))) {
+        return true;
+    }
+    // Shared with another wire's endpoint?
+    const count = endpointCounts.get(pointKey(point)) ?? 0;
+    if (count > 1) {
+        return true;
+    }
+    // Lies on another wire's body (T-junction)?
+    for (const other of allWires) {
+        if (other.id === owningWire.id) {
+            continue;
+        }
+        if (pointOnSegmentInterior(point, other.endpoints[0], other.endpoints[1])) {
+            return true;
+        }
+    }
+    return false;
+}
+
+function pointOnSegmentInterior(p: Point, a: Point, b: Point): boolean {
+    const cross = (p.x - a.x) * (b.y - a.y) - (p.y - a.y) * (b.x - a.x);
+    if (cross !== 0) {
+        return false;
+    }
+    const minX = Math.min(a.x, b.x);
+    const maxX = Math.max(a.x, b.x);
+    const minY = Math.min(a.y, b.y);
+    const maxY = Math.max(a.y, b.y);
+    if (minX === maxX && minY === maxY) {
+        return false;
+    }
+    const inXRange = p.x > minX && p.x < maxX;
+    const inYRange = p.y > minY && p.y < maxY;
+    if (minX === maxX) {
+        return inYRange;
+    }
+    if (minY === maxY) {
+        return inXRange;
+    }
+    return inXRange && inYRange;
+}
+
+function pointKey(p: Point): string {
+    return `${p.x},${p.y}`;
+}