devtools-page: connect to and process webaudio debugger events (#97)

* devtools-page: connect to and process webaudio debugger events

Connect to WebAudio chrome debugger protocol domain and collect events
into a larger AudioContext "graph". This object is collects the events
into a current representation of WebAudio graphs in the inspected
window. A graphlib graph will be derived from this information in a
future change.

- Add and test some internal utilities
  - Observer
  - Observer.throttle
    Used to limit the frequency of WebAudio representations to later
    process steps.
  - invariant
- Add and test some types to process events
  - DevtoolsGraphPanel
    Create a chrome devtools panel and post graph updates to the panel.
  - WebAudioEventObserver
    Attach to chrome debugger api and forward WebAudio domain events.
  - WebAudioGraphIntegrator
    Collect WebAudio events into a current representation.

* fixup! devtools-page: connect to and process webaudio debugger events

* fixup! devtools-page: connect to and process webaudio debugger events

* fixup! devtools-page: connect to and process webaudio debugger events

* fixup! devtools-page: connect to and process webaudio debugger events

* fixup! devtools-page: connect to and process webaudio debugger events

* fixup! devtools-page: connect to and process webaudio debugger events

* fixup! devtools-page: connect to and process webaudio debugger events

* fixup! devtools-page: connect to and process webaudio debugger events

.eslintrc.json

@@ -11,6 +11,8 @@
   },
   "rules": {
     // Indent files with prettier
-    "indent": ["off"]
+    "indent": ["off"],
+    // Allow triple slash comments
+    "spaced-comment": ["error", "always", {"markers": ["/"]}]
   }
 }

.jsdoc.json

@@ -2,14 +2,16 @@
   "source": {
     "include": ["./src/"],
     "includePattern": ".+\\.js(doc)?$",
-    "excludePattern": "(^|\\/|\\\\)_"
+    "excludePattern": "(^|\\/|\\\\)_|\\.test\\.js$"
   },
   "opts": {
     "encoding": "utf8",
     "recurse": true,
     "private": false,
     "lenient": true,
     "destination": "./docs",
-    "template": "./node_modules/@pixi/jsdoc-template"
-  }
+    "template": "./node_modules/@pixi/jsdoc-template",
+    "readme": "README.md"
+  },
+  "plugins": ["plugins/markdown"]
 }

README.md

@@ -1 +1,21 @@
-This is a new branch for the Web Audio DevTools extension V2.
+# Audion: A Web Audio Inpsector
+
+## Development and Installation
+
+#### Build and test the extension
+
+1. Install NodeJS 14 or later.
+2. Install dependencies with `npm ci` or `npm install`.
+3. Run `npm test` to build and test the extension.
+
+#### Install the development copy of the extension
+
+1. Open `chrome://extensions` in Chrome.
+2. Turn on `Developer mode` if it is not already active.
+3. Load an unpacked extension with the `Load unpacked` button. In the file modal that opens, select the `audion` directory inside of the `build` directory under the copy of this repository.
+
+#### Use and make changes to the extension
+
+1. Open the added Web Audio panel in an inspector window with a page that uses the Web Audio api.
+2. Make changes to the extension and rebuild with `npm test` or `npm run build`.
+3. Open `chrome://extensions`, click `Update` to reload the rebuilt extension. Close and reopen any tab and inspector to get the rebuilt extension's panel.

src/.jest.config.json

@@ -3,5 +3,6 @@
   "injectGlobals": false,
   "transform": {
     "\\.[jt]sx?$": "babel-jest"
-  }
+  },
+  "coveragePathIgnorePatterns": ["<rootDir>/chrome/"]
 }

src/build/make-chrome-extension.js

@@ -1,7 +1,8 @@
 /**
  * A nodejs script that copies files, writes a extension manifest, and zips it
  * all up.
- * @module makeChromeExtension
+ *
+ * @namespace makeChromeExtension
  */
 
 const fs = require('fs').promises;
@@ -17,6 +18,8 @@ main();
  * Copy files, generate extension manifest, and zip the unpacked extension.
  *
  * Calls other methods in this script.
+ *
+ * @memberof makeChromeExtension
  */
 async function main() {
   await Promise.all([
@@ -38,7 +41,9 @@ async function main() {
 
 /**
  * Copy file paths from a src directory to a dest directory.
+ *
  * @param {object} options
+ * @memberof makeChromeExtension
  */
 async function copyFiles({src, dest, files, cwd = __dirname}) {
   await Promise.all(
@@ -54,7 +59,9 @@ async function copyFiles({src, dest, files, cwd = __dirname}) {
 
 /**
  * Generate a extension manifest from a template file.
+ *
  * @param {object} options
+ * @memberof makeChromeExtension
  */
 async function generateManifest({
   view,
@@ -77,7 +84,9 @@ async function generateManifest({
 
 /**
  * Zip the unpacked chrome extension.
+ *
  * @param {object} options
+ * @memberof makeChromeExtension
  */
 async function zipChromeExtension({
   src,
@@ -104,7 +113,8 @@ async function zipChromeExtension({
 /**
  * Read entry names in a directory recursively.
  * @param {string} dir directory to recursively read
- * @return {Array<string>} array of paths relative to `dir`
+ * @return {Promise<Array<string>>} array of paths relative to `dir`
+ * @memberof makeChromeExtension
  */
 async function readdirRecursive(dir) {
   return (
@@ -129,7 +139,9 @@ async function readdirRecursive(dir) {
 
 /**
  * Create a directory if it does not already exist.
+ *
  * @param {string} dirpath directory to create
+ * @memberof makeChromeExtension
  */
 async function mkdir(dirpath) {
   try {
@@ -144,7 +156,9 @@ async function mkdir(dirpath) {
 
 /**
  * Unlink a file from the filesystem if it exists.
+ *
  * @param {string} filepath file to unlink
+ * @memberof makeChromeExtension
  */
 async function unlink(filepath) {
   try {

src/build/manifest.json.mustache

@@ -6,5 +6,8 @@
   "background": {
     "service_worker": "background.js"
   },
-  "devtools_page": "devtools.html"
+  "devtools_page": "devtools.html",
+  "permissions": [
+    "debugger"
+  ]
 }

src/chrome/API.js

@@ -0,0 +1,13 @@
+/// <reference path="./Debugger.js" />
+/// <reference path="./DevTools.js" />
+/// <reference path="./Runtime.js" />
+
+/**
+ * Top level chrome extension API type. Contains references of each accessible
+ * extension api.
+ *
+ * @typedef Chrome.API
+ * @property {Chrome.Debugger} debugger
+ * @property {Chrome.DevTools} devtools
+ * @property {Chrome.Runtime} runtime
+ */

src/chrome/Debugger.js

@@ -0,0 +1,43 @@
+/// <reference path="Types.js" />
+
+/**
+ * [Chrome extension api][1] to the [Chrome Debugger Protocol][2]. Used by this
+ * extension to access the [Web Audio domain][3].
+ *
+ * [1]: https://developer.chrome.com/docs/extensions/reference/debugger/
+ * [2]: https://chromedevtools.github.io/devtools-protocol/
+ * [3]: ChromeDebuggerWebAudioDomain.html
+ *
+ * @typedef Chrome.Debugger
+ * @property {function(
+ *   Chrome.DebuggerDebuggee, string, function(): void
+ * ): void} attach
+ * @property {function(Chrome.DebuggerDebuggee, function(): void): void} detach
+ * @property {Chrome.Event<function(): void>} onDetach
+ * @property {Chrome.Event<Chrome.DebuggerOnEventListener>} onEvent
+ * @property {function(Chrome.DebuggerDebuggee, string): void} sendCommand
+ * @see https://developer.chrome.com/docs/extensions/reference/debugger/
+ * @see https://chromedevtools.github.io/devtools-protocol/
+ */
+
+/**
+ * A debuggee identifier.
+ *
+ * Either tabId or extensionId must be specified.
+ *
+ * @typedef Chrome.DebuggerDebuggee
+ * @property {string} [extensionId]
+ * @property {string} [tabId]
+ * @property {string} [targetId]
+ * @see https://developer.chrome.com/docs/extensions/reference/debugger/#type-Debuggee
+ */
+
+/**
+ * Arguments passed to Debugger onEvent listeners.
+ *
+ * @callback Chrome.DebuggerOnEventListener
+ * @param {Chrome.DebuggerDebuggee} source
+ * @param {string} method
+ * @param {*} [params]
+ * @return {void}
+ */