@ilusiv/fugue-js

Browser JavaScript bindings for the Fugue runtime.

Install

npm install @ilusiv/fugue-js

Usage

import { FuguePlayer } from "@ilusiv/fugue-js";

const invention = await fetch("/invention.json").then((response) =>
  response.text(),
);
const player = await FuguePlayer.create();

await player.loadInvention(invention);
await player.play();

player.stop();
await player.dispose();

play() must be called from a browser user gesture such as a click handler. By default, FuguePlayer is self-contained: it loads its AudioWorklet from a temporary Blob URL and initializes wasm from bytes embedded in the package. Apps do not need to copy Fugue runtime files into public/.

Advanced hosts can still provide explicit asset URLs:

const player = await FuguePlayer.create({
  wasmUrl: "/fugue/fugue_bg.wasm",
  workletUrl: "/fugue/fugue-audio-worklet.js",
});

Custom Audio Routing

Pass an existing AudioContext and destination node when an app needs to route Fugue through its own Web Audio graph:

const player = await FuguePlayer.create({
  audioContext,
  destination,
});

Development

This package is a thin npm wrapper around the sibling Fugue Rust runtime. Build commands expect a Fugue checkout at ../fugue, or a custom path via FUGUE_ROOT.

npm install
npm run build
npm run typecheck
npm test

The package builds optimized wasm with cargo build --release --target wasm32-unknown-unknown, then runs wasm-bindgen --target web.

Publishing

Publishing uses npm trusted publishing, not a long-lived npm token. Configure the package on npmjs.com with:

• Publisher: GitHub Actions
• Repository owner/name: gdamron/fugue-js
• Workflow filename: publish.yml
• Allowed action: npm publish

The publish workflow validates the package on every push to main, compares the local package.json version to the published npm version, and runs npm publish --access public only when the version differs.