@audiofab-io/easy-spin-ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Audiofab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @audiofab-io/easy-spin-ui
+
+Shared React components and FV-1 simulation runtime for Audiofab's [Easy Spin](https://audiofab.com/products/easy-spin) pedal. Used by:
+
+- **[easy-spin-web](https://easy-spin.audiofab.com)** — the browser-based effect loader and simulator.
+- **[fv1-vscode](https://github.com/audiofab/fv1-vscode)** — the FV-1 VS Code extension's pedal-shaped simulator and bank editor.
+
+The package keeps the two surfaces visually and behaviourally identical: the skeuomorphic pedal, the rotary knobs, the program-slot grid, and the audio worklet that runs FV-1 programs in real time all live here.
+
+## Installation
+
+```bash
+npm install @audiofab-io/easy-spin-ui
+```
+
+Peer dependencies: `react@^19`, `react-dom@^19`, `@audiofab-io/fv1-core@^0.4`.
+
+## Usage
+
+```tsx
+import '@audiofab-io/easy-spin-ui/styles.css'
+import { PedalFace, useSimulator } from '@audiofab-io/easy-spin-ui'
+import workletUrl  from '@audiofab-io/easy-spin-ui/worklet?url'
+import pedalImage  from '@audiofab-io/easy-spin-ui/assets/pedal.png?url'
+
+function App() {
+  const simulator = useSimulator({ workletUrl })
+  return (
+    <PedalFace
+      pedalImageUrl={pedalImage}
+      pots={[0.5, 0.5, 0.5]}
+      onPotChange={simulator.setPot}
+      potLabels={['Decay', 'Tone', 'Mix']}
+      selectedSlot={0}
+      onSelectSlot={() => {}}
+      selectedClipId={null}
+      onSelectClip={() => {}}
+      playing={simulator.playing}
+      onPlay={simulator.play}
+      onPause={simulator.pause}
+      bypassed={simulator.bypassed}
+      onToggleBypass={() => simulator.setBypass(!simulator.bypassed)}
+      channelMode={simulator.channelMode}
+      onChannelModeChange={simulator.setChannelMode}
+    />
+  )
+}
+```
+
+The hook is intentionally headless — it doesn't know how to fetch effects or audio clips. Consumers compose their own loading conventions on top of `simulator.loadProgram(binary)` and `simulator.loadClipBuffer(arrayBuffer)`.
+
+## Building
+
+```bash
+npm install
+npm run build
+```
+
+The build produces:
+
+- `dist/index.js` — main library entry (ESM)
+- `dist/index.d.ts` — TypeScript declarations
+- `dist/styles.css` — precompiled Tailwind stylesheet
+- `dist/worklet/fv1-processor.js` — self-contained AudioWorklet (IIFE)
+- `dist/assets/pedal.png` — pedal artwork
+
+## Releasing
+
+Releases are published to npm by GitHub Actions when a tag matching `v*` is pushed. The workflow uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers) (no `NPM_TOKEN` required).
+
+```bash
+npm version <patch|minor|major>   # bumps package.json + creates a v* tag
+git push --follow-tags
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/audio/binary.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Converts a compiled FV-1 binary (Uint8Array, big-endian) to an array of
+ * 32-bit machine code words suitable for FV1Simulator.loadProgram().
+ *
+ * An FV-1 program is 128 instructions × 4 bytes = 512 bytes.
+ */
+export declare function binaryToMachineCode(binary: Uint8Array): number[];

package/dist/components/ClipSelector.d.ts

@@ -0,0 +1,20 @@
+export interface ClipInfo {
+    id: string;
+    name: string;
+    description?: string;
+}
+interface ClipSelectorProps {
+    /** List of clips the consumer wants to expose. */
+    clips: ClipInfo[];
+    selectedClipId: string | null;
+    onSelect: (clipId: string) => void;
+    /** When true, the selector is visually disabled (e.g. while a list is loading). */
+    disabled?: boolean;
+}
+/**
+ * Pure presentational dropdown for picking an audio clip. The shared package
+ * has no opinion about where clips come from — consumers fetch / bundle their
+ * own list and pass it in.
+ */
+export declare function ClipSelector({ clips, selectedClipId, onSelect, disabled }: ClipSelectorProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Knob.d.ts

@@ -0,0 +1,11 @@
+interface KnobProps {
+    value: number;
+    label: string;
+    onChange: (value: number) => void;
+    size?: number;
+    /** When true, render without a visible body — just a pointer indicator
+     *  (for overlaying on top of a pre-drawn dial graphic). */
+    overlay?: boolean;
+}
+export declare function Knob({ value, label, onChange, size, overlay }: KnobProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/PedalFace.d.ts

@@ -0,0 +1,47 @@
+import { type ClipInfo } from './ClipSelector';
+export type ChannelMode = 'mono' | 'stereo';
+export interface PedalFaceProps {
+    /** URL of the pedal outline graphic. Required — see assets/pedal.png in
+     *  this package, or bring your own. */
+    pedalImageUrl: string;
+    /** Current values of the three pots, normalised 0..1. */
+    pots: [number, number, number];
+    onPotChange: (index: number, value: number) => void;
+    /** Per-pot display labels — typically the effect's `controls[].name`,
+     *  or `Pot 0/1/2` when the active program is unknown. */
+    potLabels?: [string, string, string];
+    /** Currently selected slot (0-based). */
+    selectedSlot: number;
+    onSelectSlot: (slot: number) => void;
+    /** Display labels for each of the 8 slots. Empty / undefined means empty. */
+    slotLabels?: string[];
+    /** Drop handler for slot N. The data string is the platform-specific
+     *  payload (e.g. an effect id, a file URI). The consumer interprets it. */
+    onAssignSlot?: (slotIndex: number, payload: string) => void;
+    onUnassignSlot?: (slotIndex: number) => void;
+    onUnassignAllSlots?: () => void;
+    /** Called when the user clicks the per-slot "send to pedal" icon. */
+    onProgramSlot?: (slotIndex: number) => void;
+    /** Index of the slot currently being written to the pedal, or null. */
+    programmingSlot?: number | null;
+    /** Audio clip selection — pass an empty array to hide the selector. */
+    clips?: ClipInfo[];
+    selectedClipId: string | null;
+    onSelectClip: (clipId: string) => void;
+    playing: boolean;
+    onPlay: () => void;
+    onPause: () => void;
+    bypassed: boolean;
+    onToggleBypass: () => void;
+    channelMode: ChannelMode;
+    onChannelModeChange: (mode: ChannelMode) => void;
+    /** Pedal connection state — the I/O button cluster only renders when
+     *  these are wired up. */
+    pedalConnected?: boolean;
+    onConnectPedal?: () => void;
+    onReadPedal?: () => void;
+    onWritePedal?: () => void;
+    pedalReading?: boolean;
+    pedalWriting?: boolean;
+}
+export declare function PedalFace({ pedalImageUrl, pots, onPotChange, potLabels, selectedSlot, onSelectSlot, slotLabels, onAssignSlot, onUnassignSlot, onUnassignAllSlots, onProgramSlot, programmingSlot, clips, selectedClipId, onSelectClip, playing, onPlay, onPause, bypassed, onToggleBypass, channelMode, onChannelModeChange, pedalConnected, onConnectPedal, onReadPedal, onWritePedal, pedalReading, pedalWriting, }: PedalFaceProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ProgramSelector.d.ts

@@ -0,0 +1,15 @@
+interface ProgramSelectorProps {
+    selectedSlot: number;
+    onSelectSlot: (slot: number) => void;
+    slotLabels?: string[];
+    /** When true, render as a rotary dial with a pointer indicator (no visible body). */
+    overlay?: boolean;
+}
+/**
+ * Rotary program selector. In overlay mode it renders as a pot-style knob
+ * (black circular outline + pointer) that points at the currently selected
+ * slot. The knob can be dragged to change program — it snaps to the nearest
+ * of the 8 discrete positions.
+ */
+export declare function ProgramSelector({ selectedSlot, onSelectSlot, slotLabels, overlay, }: ProgramSelectorProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @audiofab-io/easy-spin-ui
+ *
+ * Shared React components and FV-1 simulation runtime for Audiofab's
+ * Easy Spin pedal. Used by:
+ *   - easy-spin-web (browser-only)
+ *   - fv1-vscode    (VS Code extension webviews)
+ *
+ * Consumers must:
+ *   1. Import the bundled stylesheet:    import '@audiofab-io/easy-spin-ui/styles.css'
+ *   2. Provide a worklet URL to useSimulator. In Vite consumers:
+ *        import workletUrl from '@audiofab-io/easy-spin-ui/worklet?url'
+ *      In VS Code webviews, copy the file to a webview-accessible path and
+ *      pass the resulting `webview.asWebviewUri(...)`.
+ *   3. Provide a `pedalImageUrl` prop to <PedalFace />. Default asset is
+ *      shipped at `@audiofab-io/easy-spin-ui/assets/pedal.png`.
+ */
+export { Knob } from './components/Knob';
+export { ProgramSelector } from './components/ProgramSelector';
+export { ClipSelector } from './components/ClipSelector';
+export type { ClipInfo } from './components/ClipSelector';
+export { PedalFace } from './components/PedalFace';
+export type { PedalFaceProps, ChannelMode } from './components/PedalFace';
+export { useSimulator } from './simulator/useSimulator';
+export type { SimulatorState, UseSimulatorOptions, AssembleResult, } from './simulator/useSimulator';
+export { binaryToMachineCode } from './audio/binary';
+export { PROGRAM_SLOT_COUNT } from '@audiofab-io/fv1-core/pedal';