@ilusiv/fyug-js

Browser JavaScript bindings for the Fugue runtime.

Install

npm install @ilusiv/fyug-js

Usage

import { FuguePlayer } from "@ilusiv/fyug-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 wraps the Fugue Rust runtime for the browser. It builds optimized wasm from the core commit the product workspace pins (or FUGUE_CORE_PATH), with core's own lockfile, then runs wasm-bindgen --target web. See Developing against core. From the workspace root, after pnpm bootstrap:

pnpm --filter @ilusiv/fyug-js build
pnpm --filter @ilusiv/fyug-js typecheck
pnpm --filter @ilusiv/fyug-js test

Publishing

The package is published to npm as part of a product release, never from an ordinary push:

1. Release type-checks, tests and builds the package from the pinned core, runs npm pack and checks the tarball. If this package.json version is not on npm yet, it stages the tarball in the draft release with its checksum and provenance. Otherwise it stages nothing, so a product release never forces a player version bump.
2. Promote Release publishes that exact tarball with npm trusted publishing (OIDC). No npm token exists anywhere.

To release a new player version, bump version here and run a product release.

@ilusiv/fyug-js replaces @ilusiv/fugue-js, which stays on npm at 2026.5.2. npm offers trusted publishing settings only for a package that already exists, so publish the first @ilusiv/fyug-js version by hand. Run pnpm --filter @ilusiv/fyug-js build, then npm publish --access public in packages/fugue-js, from an npm account that owns the @ilusiv scope. Then configure trusted publishing and deprecate the old name: npm deprecate @ilusiv/fugue-js "Renamed to @ilusiv/fyug-js".

Trusted publishing is configured on npmjs.com under the package's settings: publisher GitHub Actions, repository gdamron/fyug-product, workflow promote.yml, environment public-release.