supersonic-scsynth 0.66.0 → 0.67.2

package/README.npm.md

@@ -1,4 +1,4 @@
-# SuperSonic 0.66.0
+# SuperSonic 0.67.2
 
 > SuperCollider's scsynth in the browser as an AudioWorklet.
 >
@@ -124,6 +124,18 @@ The arguments are:
 
 The synth parameters control the sound. Here we set `note` to 28 (a low E), `release` to 8 seconds, and `cutoff` to 70 (filter brightness). Each synthdef has its own parameters - see the synthdef documentation for available options.
 
+We used `-1` for the node ID here to let scsynth pick one for us. That's fine for fire-and-forget sounds, but if you need to control a synth after creating it - change its parameters, stop it, query it - you need to know its ID. That's where `nextNodeId()` comes in:
+
+```javascript
+const id = supersonic.nextNodeId();
+supersonic.send("/s_new", "sonic-pi-prophet", id, 0, 0, "note", 28, "release", 8, "cutoff", 70);
+
+// Later — change the cutoff while it's playing
+supersonic.send("/n_set", id, "cutoff", 100);
+```
+
+`nextNodeId()` is thread-safe - if you have multiple Web Workers sending OSC (see the [Workers Guide](https://github.com/samaaron/supersonic/blob/main/docs/WORKERS.md)), each one can allocate IDs independently, guaranteed unique with no clashes.
+
 
 ## Working Example
 
@@ -239,18 +251,20 @@ scsynth with low latency inside a web page.
 
 **Advanced**
 
-| Member                                    | Description                                                  |
-| ----------------------------------------- | ------------------------------------------------------------ |
-| [`bufferConstants`](#bufferconstants)     | Buffer layout constants from the WASM build.                 |
-| [`initTime`](#inittime)                   | NTP time (seconds since 1900) when the AudioContext started. |
-| [`mode`](#mode)                           | Active transport mode ('sab' or 'postMessage').              |
-| [`ringBufferBase`](#ringbufferbase)       | Ring buffer base offset in SharedArrayBuffer.                |
-| [`sharedBuffer`](#sharedbuffer)           | The SharedArrayBuffer (SAB mode) or null (postMessage mode). |
-| [`getLoadedBuffers()`](#getloadedbuffers) | Get info about all loaded audio buffers.                     |
-| [`getSystemReport()`](#getsystemreport)   | Get a comprehensive system performance report.               |
-| [`nextNodeId()`](#nextnodeid)             | Get the next unique node ID.                                 |
-| [`getRawTreeSchema()`](#getrawtreeschema) | Get schema describing the raw flat node tree structure.      |
-| [`getTreeSchema()`](#gettreeschema)       | Get schema describing the hierarchical node tree structure.  |
+| Member                                    | Description                                                                                |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------ |
+| [`bufferConstants`](#bufferconstants)     | Buffer layout constants from the WASM build.                                               |
+| [`initTime`](#inittime)                   | NTP time (seconds since 1900) when the AudioContext started.                               |
+| [`mode`](#mode)                           | Active transport mode ('sab' or 'postMessage').                                            |
+| [`ringBufferBase`](#ringbufferbase)       | Ring buffer base offset in SharedArrayBuffer.                                              |
+| [`sharedBuffer`](#sharedbuffer)           | The SharedArrayBuffer (SAB mode) or null (postMessage mode).                               |
+| [`getEngineState()`](#getenginestate)     | Returns the current engine lifecycle state.                                                |
+| [`getLoadedBuffers()`](#getloadedbuffers) | Get info about all loaded audio buffers.                                                   |
+| [`getSystemReport()`](#getsystemreport)   | Get a comprehensive system performance report.                                             |
+| [`isRunning()`](#isrunning)               | Returns true if the engine has finished booting and is ready to send and receive messages. |
+| [`nextNodeId()`](#nextnodeid)             | Get the next unique node ID.                                                               |
+| [`getRawTreeSchema()`](#getrawtreeschema) | Get schema describing the raw flat node tree structure.                                    |
+| [`getTreeSchema()`](#gettreeschema)       | Get schema describing the hierarchical node tree structure.                                |
 
 ### OscChannel
 
@@ -259,21 +273,27 @@ OscChannel — unified dispatch for sending OSC to the AudioWorklet.
 Obtain a channel via [SuperSonic.createOscChannel](#createoscchannel) on the main thread,
 then transfer it to a Web Worker for direct communication with the AudioWorklet.
 
-| Member                                        | Description                                                                     |
-| --------------------------------------------- | ------------------------------------------------------------------------------- |
-| [`getCurrentNTP`](#getcurrentntp)             | Set the NTP time source for classification (used in AudioWorklet context).      |
-| [`mode`](#mode)                               | Transport mode this channel is using.                                           |
-| [`transferable`](#transferable)               | Serializable config for transferring this channel to a worker via postMessage.  |
-| [`transferList`](#transferlist)               | Array of transferable objects (MessagePorts) for the postMessage transfer list. |
-| [`classify()`](#classify)                     | Classify an OSC message to determine its routing.                               |
-| [`close()`](#close)                           | Close the channel and release its ports.                                        |
-| [`getAndResetMetrics()`](#getandresetmetrics) | Get and reset local metrics (for periodic reporting).                           |
-| [`getMetrics()`](#getmetrics)                 | Get current metrics snapshot.                                                   |
-| [`nextNodeId()`](#nextnodeid)                 | Get the next unique node ID.                                                    |
-| [`send()`](#send)                             | Send an OSC message with automatic routing.                                     |
-| [`sendDirect()`](#senddirect)                 | Send directly to worklet without classification or metrics tracking.            |
-| [`sendToPrescheduler()`](#sendtoprescheduler) | Send to prescheduler without classification.                                    |
-| [`fromTransferable()`](#fromtransferable)     | Reconstruct an OscChannel from data received via postMessage in a worker.       |
+| Member                                        | Description                                                                                             |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| [`getCurrentNTP`](#getcurrentntp)             | Set the NTP time source for classification (used in AudioWorklet context).                              |
+| [`mode`](#mode)                               | Transport mode this channel is using.                                                                   |
+| [`replyDrops`](#replydrops)                   | Number of reply messages dropped because the reply buffer was full.                                     |
+| [`transferable`](#transferable)               | Serializable config for transferring this channel to a worker via postMessage.                          |
+| [`transferList`](#transferlist)               | Array of transferable objects (MessagePorts) for the postMessage transfer list.                         |
+| [`activateReplies()`](#activatereplies)       | Activate the reply slot without registering a handler.                                                  |
+| [`classify()`](#classify)                     | Classify an OSC message to determine its routing.                                                       |
+| [`clearReplyHandler()`](#clearreplyhandler)   | Clear the reply handler and release the reply channel.                                                  |
+| [`close()`](#close)                           | Close the channel and release its ports.                                                                |
+| [`deactivateReplies()`](#deactivatereplies)   | Release the reply slot.                                                                                 |
+| [`getAndResetMetrics()`](#getandresetmetrics) | Get and reset local metrics (for periodic reporting).                                                   |
+| [`getMetrics()`](#getmetrics)                 | Get current metrics snapshot.                                                                           |
+| [`nextNodeId()`](#nextnodeid)                 | Get the next unique node ID.                                                                            |
+| [`pollReplies()`](#pollreplies)               | Drain pending replies, calling the registered handler (or handler argument, if given) once per message. |
+| [`send()`](#send)                             | Send an OSC message with automatic routing.                                                             |
+| [`sendDirect()`](#senddirect)                 | Send directly to worklet without classification or metrics tracking.                                    |
+| [`sendToPrescheduler()`](#sendtoprescheduler) | Send to prescheduler without classification.                                                            |
+| [`setReplyHandler()`](#setreplyhandler)       | Register a handler for OSC replies from scsynth.                                                        |
+| [`fromTransferable()`](#fromtransferable)     | Reconstruct an OscChannel from data received via postMessage in a worker.                               |
 
 #### Example
 
@@ -337,6 +357,20 @@ Transport mode this channel is using.
 
 [`TransportMode`](#transportmode)
 
+##### replyDrops
+
+###### Get Signature
+
+> **get** **replyDrops**(): `number`
+
+Number of reply messages dropped because the reply buffer was full.
+SAB mode only — undefined in PM mode or before [activateReplies](#activatereplies).
+Counter resets each time the slot is (re)claimed.
+
+###### Returns
+
+`number`
+
 ##### transferable
 
 ###### Get Signature
@@ -377,6 +411,19 @@ worker.postMessage({ ch: channel.transferable }, channel.transferList);
 
 #### Methods
 
+##### activateReplies()
+
+> **activateReplies**(): `void`
+
+Activate the reply slot without registering a handler. Usually called
+for you by [setReplyHandler](#setreplyhandler); only call directly if you want to
+claim the slot before installing a handler (or to use the optional
+one-shot handler argument of [pollReplies](#pollreplies)).
+
+###### Returns
+
+`void`
+
 ##### classify()
 
 > **classify**(`oscData`): [`OscCategory`](#osccategory)
@@ -393,6 +440,16 @@ Classify an OSC message to determine its routing.
 
 [`OscCategory`](#osccategory)
 
+##### clearReplyHandler()
+
+> **clearReplyHandler**(): `void`
+
+Clear the reply handler and release the reply channel. Idempotent.
+
+###### Returns
+
+`void`
+
 ##### close()
 
 > **close**(): `void`
@@ -403,6 +460,16 @@ Close the channel and release its ports.
 
 `void`
 
+##### deactivateReplies()
+
+> **deactivateReplies**(): `void`
+
+Release the reply slot. Usually called for you by [clearReplyHandler](#clearreplyhandler).
+
+###### Returns
+
+`void`
+
 ##### getAndResetMetrics()
 
 > **getAndResetMetrics**(): [`OscChannelMetrics`](#oscchannelmetrics)
@@ -439,6 +506,30 @@ the root group, 1 is the default group, 2–999 are reserved for manual use).
 
 A unique node ID (>= 1000)
 
+##### pollReplies()
+
+> **pollReplies**(`handler?`): `number`
+
+Drain pending replies, calling the registered handler (or `handler`
+argument, if given) once per message. Returns the number of messages
+processed. Zero-allocation on the hot path.
+
+Call from an AudioWorklet's `process()` method to receive replies on
+the audio thread. In other contexts automatic delivery already calls
+this for you.
+
+###### Parameters
+
+| Parameter  | Type                                                                                        | Description                          |
+| ---------- | ------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `handler?` | ((`view`, `offset`, `length`, `sequence`) => `void`) \| ((`oscData`, `sequence`) => `void`) | Optional override for this call only |
+
+###### Returns
+
+`number`
+
+Number of messages drained
+
 ##### send()
 
 > **send**(`oscData`): `boolean`
@@ -498,6 +589,40 @@ Send to prescheduler without classification.
 
 true if sent successfully
 
+##### setReplyHandler()
+
+> **setReplyHandler**(`handler`): `void`
+
+Register a handler for OSC replies from scsynth. Idempotent — replaces
+any previously-registered handler. In AudioWorklet contexts the worklet
+must call [pollReplies](#pollreplies) from `process()` to drain; in all other
+contexts delivery is automatic. All registered channels receive all
+replies (broadcast); filter locally if you only need specific addresses.
+
+SAB mode: handler receives `(view, offset, length, sequence)` — zero-copy
+into the shared buffer. Read bytes from `view[offset..offset+length]`.
+Data is valid only for the duration of the handler call.
+
+PM mode: handler receives `(oscData, sequence)` where `oscData` is a copy.
+
+###### Parameters
+
+| Parameter | Type                                                                                        |
+| --------- | ------------------------------------------------------------------------------------------- |
+| `handler` | ((`view`, `offset`, `length`, `sequence`) => `void`) \| ((`oscData`, `sequence`) => `void`) |
+
+###### Returns
+
+`void`
+
+###### Example
+
+```ts
+channel.setReplyHandler((view, offset, length, sequence) => {
+  // SAB: read raw OSC bytes from view[offset..offset+length]
+});
+```
+
 ##### fromTransferable()
 
 > `static` **fromTransferable**(`data`): [`OscChannel`](#oscchannel)
@@ -1216,6 +1341,27 @@ Get number of audio frames captured so far.
 
 `number`
 
+##### getEngineState()
+
+> **getEngineState**(): `"running"` | `"stopped"` | `"booting"`
+
+Returns the current engine lifecycle state.
+
+One of:
+
+* `'stopped'` — before `init()` or after `shutdown()`/`destroy()`.
+* `'booting'` — while `init()` is in progress.
+* `'running'` — after `init()` resolves and before any teardown.
+
+Mirrors the C++ `SupersonicEngine::engineState()` accessor. The C++
+enum also has `'restarting'` and `'error'` states that the web runtime
+does not currently distinguish — `recover()` and `resume()` do not
+surface a `'restarting'` state from JS.
+
+###### Returns
+
+`"running"` | `"stopped"` | `"booting"`
+
 ##### getInfo()
 
 > **getInfo**(): [`SuperSonicInfo`](#supersonicinfo)
@@ -1421,6 +1567,21 @@ Check if audio capture is currently enabled.
 
 `boolean`
 
+##### isRunning()
+
+> **isRunning**(): `boolean`
+
+Returns true if the engine has finished booting and is ready to send
+and receive messages.
+
+Mirrors the C++ `SupersonicEngine::isRunning()` accessor; returns the
+same value as the existing `initialized` getter, exposed as a method
+to match the C++ API shape.
+
+###### Returns
+
+`boolean`
+
 ##### loadSample()
 
 > **loadSample**(`bufnum`, `source`, `startFrame?`, `numFrames?`): `Promise`<[`LoadSampleResult`](#loadsampleresult)>
@@ -2141,9 +2302,9 @@ Create a new synth from a loaded synthdef. addAction: 0=head, 1=tail, 2=before,
 | ------------- | ------------------------- |
 | `address`     | `"/s_new"`                |
 | `defName`     | `string`                  |
-| `nodeID`      | [`NodeID`](#nodeid)       |
+| `nodeID`      | `number`                  |
 | `addAction`   | [`AddAction`](#addaction) |
-| `targetID`    | [`NodeID`](#nodeid)       |
+| `targetID`    | `number`                  |
 | ...`controls` | (`string` \| `number`)\[] |
 
 ###### Returns
@@ -2161,7 +2322,7 @@ Get synth control values. Controls can be indices or names. Replies with `/n_set
 | Parameter     | Type                      |
 | ------------- | ------------------------- |
 | `address`     | `"/s_get"`                |
-| `nodeID`      | [`NodeID`](#nodeid)       |
+| `nodeID`      | `number`                  |
 | ...`controls` | (`string` \| `number`)\[] |
 
 ###### Returns
@@ -2179,7 +2340,7 @@ Get sequential synth control values. Control can be an index or name. Replies wi
 | Parameter | Type                 |
 | --------- | -------------------- |
 | `address` | `"/s_getn"`          |
-| `nodeID`  | [`NodeID`](#nodeid)  |
+| `nodeID`  | `number`             |
 | `control` | `string` \| `number` |
 | `count`   | `number`             |
 
@@ -2195,10 +2356,10 @@ Release client-side synth ID tracking. Synths continue running but are reassigne
 
 ###### Parameters
 
-| Parameter    | Type                                  |
-| ------------ | ------------------------------------- |
-| `address`    | `"/s_noid"`                           |
-| ...`nodeIDs` | \[[`NodeID`](#nodeid), `...NodeID[]`] |
+| Parameter    | Type                       |
+| ------------ | -------------------------- |
+| `address`    | `"/s_noid"`                |
+| ...`nodeIDs` | \[`number`, `...number[]`] |
 
 ###### Returns
 
@@ -2212,10 +2373,10 @@ Free (delete) one or more nodes.
 
 ###### Parameters
 
-| Parameter    | Type                                  |
-| ------------ | ------------------------------------- |
-| `address`    | `"/n_free"`                           |
-| ...`nodeIDs` | \[[`NodeID`](#nodeid), `...NodeID[]`] |
+| Parameter    | Type                       |
+| ------------ | -------------------------- |
+| `address`    | `"/n_free"`                |
+| ...`nodeIDs` | \[`number`, `...number[]`] |
 
 ###### Returns
 
@@ -2232,7 +2393,7 @@ Set node control values. Controls are alternating name/index and value pairs. If
 | Parameter     | Type                      |
 | ------------- | ------------------------- |
 | `address`     | `"/n_set"`                |
-| `nodeID`      | [`NodeID`](#nodeid)       |
+| `nodeID`      | `number`                  |
 | ...`controls` | (`string` \| `number`)\[] |
 
 ###### Returns
@@ -2250,7 +2411,7 @@ Set sequential control values starting at the given control index/name. For mult
 | Parameter   | Type                 |
 | ----------- | -------------------- |
 | `address`   | `"/n_setn"`          |
-| `nodeID`    | [`NodeID`](#nodeid)  |
+| `nodeID`    | `number`             |
 | `control`   | `string` \| `number` |
 | `count`     | `number`             |
 | ...`values` | `number`\[]          |
@@ -2270,7 +2431,7 @@ Fill sequential controls with a single value. For multiple ranges, use the catch
 | Parameter | Type                 |
 | --------- | -------------------- |
 | `address` | `"/n_fill"`          |
-| `nodeID`  | [`NodeID`](#nodeid)  |
+| `nodeID`  | `number`             |
 | `control` | `string` \| `number` |
 | `count`   | `number`             |
 | `value`   | `number`             |
@@ -2287,10 +2448,10 @@ Turn nodes on (1) or off (0). Args are repeating \[nodeID, flag] pairs.
 
 ###### Parameters
 
-| Parameter  | Type                                              |
-| ---------- | ------------------------------------------------- |
-| `address`  | `"/n_run"`                                        |
-| ...`pairs` | \[[`NodeID`](#nodeid), `0` \| `1`, `...NodeID[]`] |
+| Parameter  | Type                                   |
+| ---------- | -------------------------------------- |
+| `address`  | `"/n_run"`                             |
+| ...`pairs` | \[`number`, `0` \| `1`, `...number[]`] |
 
 ###### Returns
 
@@ -2304,10 +2465,10 @@ Move nodeA to execute immediately before nodeB. Args are repeating \[nodeA, node
 
 ###### Parameters
 
-| Parameter  | Type                                                       |
-| ---------- | ---------------------------------------------------------- |
-| `address`  | `"/n_before"`                                              |
-| ...`pairs` | \[[`NodeID`](#nodeid), [`NodeID`](#nodeid), `...NodeID[]`] |
+| Parameter  | Type                                 |
+| ---------- | ------------------------------------ |
+| `address`  | `"/n_before"`                        |
+| ...`pairs` | \[`number`, `number`, `...number[]`] |
 
 ###### Returns
 
@@ -2321,10 +2482,10 @@ Move nodeA to execute immediately after nodeB. Args are repeating \[nodeA, nodeB
 
 ###### Parameters
 
-| Parameter  | Type                                                       |
-| ---------- | ---------------------------------------------------------- |
-| `address`  | `"/n_after"`                                               |
-| ...`pairs` | \[[`NodeID`](#nodeid), [`NodeID`](#nodeid), `...NodeID[]`] |
+| Parameter  | Type                                 |
+| ---------- | ------------------------------------ |
+| `address`  | `"/n_after"`                         |
+| ...`pairs` | \[`number`, `number`, `...number[]`] |
 
 ###### Returns
 
@@ -2338,12 +2499,12 @@ Reorder nodes within a group. addAction: 0=head, 1=tail, 2=before target, 3=afte
 
 ###### Parameters
 
-| Parameter    | Type                                  |
-| ------------ | ------------------------------------- |
-| `address`    | `"/n_order"`                          |
-| `addAction`  | `0` \| `1` \| `2` \| `3`              |
-| `targetID`   | [`NodeID`](#nodeid)                   |
-| ...`nodeIDs` | \[[`NodeID`](#nodeid), `...NodeID[]`] |
+| Parameter    | Type                       |
+| ------------ | -------------------------- |
+| `address`    | `"/n_order"`               |
+| `addAction`  | `0` \| `1` \| `2` \| `3`   |
+| `targetID`   | `number`                   |
+| ...`nodeIDs` | \[`number`, `...number[]`] |
 
 ###### Returns
 
@@ -2357,10 +2518,10 @@ Query node info. Replies with `/n_info` for each node: nodeID, parentGroupID, pr
 
 ###### Parameters
 
-| Parameter    | Type                                  |
-| ------------ | ------------------------------------- |
-| `address`    | `"/n_query"`                          |
-| ...`nodeIDs` | \[[`NodeID`](#nodeid), `...NodeID[]`] |
+| Parameter    | Type                       |
+| ------------ | -------------------------- |
+| `address`    | `"/n_query"`               |
+| ...`nodeIDs` | \[`number`, `...number[]`] |
 
 ###### Returns
 
@@ -2374,10 +2535,10 @@ Print control values and calculation rates for each node to debug output. No rep
 
 ###### Parameters
 
-| Parameter    | Type                                  |
-| ------------ | ------------------------------------- |
-| `address`    | `"/n_trace"`                          |
-| ...`nodeIDs` | \[[`NodeID`](#nodeid), `...NodeID[]`] |
+| Parameter    | Type                       |
+| ------------ | -------------------------- |
+| `address`    | `"/n_trace"`               |
+| ...`nodeIDs` | \[`number`, `...number[]`] |
 
 ###### Returns
 
@@ -2394,7 +2555,7 @@ Map controls to read from control buses. Mappings are repeating \[control, busIn
 | Parameter     | Type                      |
 | ------------- | ------------------------- |
 | `address`     | `"/n_map"`                |
-| `nodeID`      | [`NodeID`](#nodeid)       |
+| `nodeID`      | `number`                  |
 | ...`mappings` | (`string` \| `number`)\[] |
 
 ###### Returns
@@ -2412,7 +2573,7 @@ Map a range of sequential controls to sequential control buses. Mappings are rep
 | Parameter     | Type                      |
 | ------------- | ------------------------- |
 | `address`     | `"/n_mapn"`               |
-| `nodeID`      | [`NodeID`](#nodeid)       |
+| `nodeID`      | `number`                  |
 | ...`mappings` | (`string` \| `number`)\[] |
 
 ###### Returns
@@ -2430,7 +2591,7 @@ Map controls to read from audio buses. Mappings are repeating \[control, busInde
 | Parameter     | Type                      |
 | ------------- | ------------------------- |
 | `address`     | `"/n_mapa"`               |
-| `nodeID`      | [`NodeID`](#nodeid)       |
+| `nodeID`      | `number`                  |
 | ...`mappings` | (`string` \| `number`)\[] |
 
 ###### Returns
@@ -2448,7 +2609,7 @@ Map a range of sequential controls to sequential audio buses. Mappings are repea
 | Parameter     | Type                      |
 | ------------- | ------------------------- |
 | `address`     | `"/n_mapan"`              |
-| `nodeID`      | [`NodeID`](#nodeid)       |
+| `nodeID`      | `number`                  |
 | ...`mappings` | (`string` \| `number`)\[] |
 
 ###### Returns
@@ -2463,10 +2624,10 @@ Create new groups. Args are repeating \[groupID, addAction, targetID] triplets.
 
 ###### Parameters
 
-| Parameter | Type                                                                                           |
-| --------- | ---------------------------------------------------------------------------------------------- |
-| `address` | `"/g_new"`                                                                                     |
-| ...`args` | \[[`NodeID`](#nodeid), [`AddAction`](#addaction), [`NodeID`](#nodeid), ...(number \| UUID)\[]] |
+| Parameter | Type                                                            |
+| --------- | --------------------------------------------------------------- |
+| `address` | `"/g_new"`                                                      |
+| ...`args` | \[`number`, [`AddAction`](#addaction), `number`, `...number[]`] |
 
 ###### Returns
 
@@ -2480,10 +2641,10 @@ Create new parallel groups (children evaluated in unspecified order). Same signa
 
 ###### Parameters
 
-| Parameter | Type                                                                                           |
-| --------- | ---------------------------------------------------------------------------------------------- |
-| `address` | `"/p_new"`                                                                                     |
-| ...`args` | \[[`NodeID`](#nodeid), [`AddAction`](#addaction), [`NodeID`](#nodeid), ...(number \| UUID)\[]] |
+| Parameter | Type                                                            |
+| --------- | --------------------------------------------------------------- |
+| `address` | `"/p_new"`                                                      |
+| ...`args` | \[`number`, [`AddAction`](#addaction), `number`, `...number[]`] |
 
 ###### Returns
 
@@ -2497,10 +2658,10 @@ Free all immediate children of one or more groups (groups themselves remain).
 
 ###### Parameters
 
-| Parameter     | Type                                  |
-| ------------- | ------------------------------------- |
-| `address`     | `"/g_freeAll"`                        |
-| ...`groupIDs` | \[[`NodeID`](#nodeid), `...NodeID[]`] |
+| Parameter     | Type                       |
+| ------------- | -------------------------- |
+| `address`     | `"/g_freeAll"`             |
+| ...`groupIDs` | \[`number`, `...number[]`] |
 
 ###### Returns
 
@@ -2514,10 +2675,10 @@ Recursively free all synths inside one or more groups and their nested sub-group
 
 ###### Parameters
 
-| Parameter     | Type                                  |
-| ------------- | ------------------------------------- |
-| `address`     | `"/g_deepFree"`                       |
-| ...`groupIDs` | \[[`NodeID`](#nodeid), `...NodeID[]`] |
+| Parameter     | Type                       |
+| ------------- | -------------------------- |
+| `address`     | `"/g_deepFree"`            |
+| ...`groupIDs` | \[`number`, `...number[]`] |
 
 ###### Returns
 
@@ -2531,10 +2692,10 @@ Move node to head of group. Args are repeating \[groupID, nodeID] pairs.
 
 ###### Parameters
 
-| Parameter  | Type                                                       |
-| ---------- | ---------------------------------------------------------- |
-| `address`  | `"/g_head"`                                                |
-| ...`pairs` | \[[`NodeID`](#nodeid), [`NodeID`](#nodeid), `...NodeID[]`] |
+| Parameter  | Type                                 |
+| ---------- | ------------------------------------ |
+| `address`  | `"/g_head"`                          |
+| ...`pairs` | \[`number`, `number`, `...number[]`] |
 
 ###### Returns
 
@@ -2548,10 +2709,10 @@ Move node to tail of group. Args are repeating \[groupID, nodeID] pairs.
 
 ###### Parameters
 
-| Parameter  | Type                                                       |
-| ---------- | ---------------------------------------------------------- |
-| `address`  | `"/g_tail"`                                                |
-| ...`pairs` | \[[`NodeID`](#nodeid), [`NodeID`](#nodeid), `...NodeID[]`] |
+| Parameter  | Type                                 |
+| ---------- | ------------------------------------ |
+| `address`  | `"/g_tail"`                          |
+| ...`pairs` | \[`number`, `number`, `...number[]`] |
 
 ###### Returns
 
@@ -2565,10 +2726,10 @@ Print group's node tree to debug output. Args are repeating \[groupID, flag] pai
 
 ###### Parameters
 
-| Parameter           | Type                                            |
-| ------------------- | ----------------------------------------------- |
-| `address`           | `"/g_dumpTree"`                                 |
-| ...`groupFlagPairs` | \[[`NodeID`](#nodeid), `number`, `...NodeID[]`] |
+| Parameter           | Type                                 |
+| ------------------- | ------------------------------------ |
+| `address`           | `"/g_dumpTree"`                      |
+| ...`groupFlagPairs` | \[`number`, `number`, `...number[]`] |
 
 ###### Returns
 
@@ -2582,10 +2743,10 @@ Query group tree structure. Args are repeating \[groupID, flag] pairs. flag: 0=s
 
 ###### Parameters
 
-| Parameter           | Type                                            |
-| ------------------- | ----------------------------------------------- |
-| `address`           | `"/g_queryTree"`                                |
-| ...`groupFlagPairs` | \[[`NodeID`](#nodeid), `number`, `...NodeID[]`] |
+| Parameter           | Type                                 |
+| ------------------- | ------------------------------------ |
+| `address`           | `"/g_queryTree"`                     |
+| ...`groupFlagPairs` | \[`number`, `number`, `...number[]`] |
 
 ###### Returns
 
@@ -2602,7 +2763,7 @@ Send a command to a specific UGen instance within a synth. The command name and
 | Parameter   | Type                   |
 | ----------- | ---------------------- |
 | `address`   | `"/u_cmd"`             |
-| `nodeID`    | [`NodeID`](#nodeid)    |
+| `nodeID`    | `number`               |
 | `ugenIndex` | `number`               |
 | `command`   | `string`               |
 | ...`args`   | [`OscArg`](#oscarg)\[] |
@@ -2978,7 +3139,7 @@ Plain JS values are mapped to OSC types automatically:
 * `boolean` → `T` / `F`
 * `Uint8Array` / `ArrayBuffer` → `b` (blob)
 
-For 64-bit, timetag, or UUID types, use the tagged object form:
+For 64-bit or timetag types, use the tagged object form:
 
 ```ts
 { type: 'int', value: 42 }
@@ -2989,7 +3150,6 @@ For 64-bit, timetag, or UUID types, use the tagged object form:
 { type: 'int64', value: 9007199254740992n }
 { type: 'double', value: 3.141592653589793 }
 { type: 'timetag', value: ntpTimestamp }
-{ type: 'uuid', value: new Uint8Array(16) }
 ```
 
 ##### sendOSC()
@@ -3179,21 +3339,27 @@ OscChannel — unified dispatch for sending OSC to the AudioWorklet.
 Obtain a channel via [SuperSonic.createOscChannel](#createoscchannel) on the main thread,
 then transfer it to a Web Worker for direct communication with the AudioWorklet.
 
-| Member                                        | Description                                                                     |
-| --------------------------------------------- | ------------------------------------------------------------------------------- |
-| [`getCurrentNTP`](#getcurrentntp)             | Set the NTP time source for classification (used in AudioWorklet context).      |
-| [`mode`](#mode)                               | Transport mode this channel is using.                                           |
-| [`transferable`](#transferable)               | Serializable config for transferring this channel to a worker via postMessage.  |
-| [`transferList`](#transferlist)               | Array of transferable objects (MessagePorts) for the postMessage transfer list. |
-| [`classify()`](#classify)                     | Classify an OSC message to determine its routing.                               |
-| [`close()`](#close)                           | Close the channel and release its ports.                                        |
-| [`getAndResetMetrics()`](#getandresetmetrics) | Get and reset local metrics (for periodic reporting).                           |
-| [`getMetrics()`](#getmetrics)                 | Get current metrics snapshot.                                                   |
-| [`nextNodeId()`](#nextnodeid)                 | Get the next unique node ID.                                                    |
-| [`send()`](#send)                             | Send an OSC message with automatic routing.                                     |
-| [`sendDirect()`](#senddirect)                 | Send directly to worklet without classification or metrics tracking.            |
-| [`sendToPrescheduler()`](#sendtoprescheduler) | Send to prescheduler without classification.                                    |
-| [`fromTransferable()`](#fromtransferable)     | Reconstruct an OscChannel from data received via postMessage in a worker.       |
+| Member                                        | Description                                                                                             |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| [`getCurrentNTP`](#getcurrentntp)             | Set the NTP time source for classification (used in AudioWorklet context).                              |
+| [`mode`](#mode)                               | Transport mode this channel is using.                                                                   |
+| [`replyDrops`](#replydrops)                   | Number of reply messages dropped because the reply buffer was full.                                     |
+| [`transferable`](#transferable)               | Serializable config for transferring this channel to a worker via postMessage.                          |
+| [`transferList`](#transferlist)               | Array of transferable objects (MessagePorts) for the postMessage transfer list.                         |
+| [`activateReplies()`](#activatereplies)       | Activate the reply slot without registering a handler.                                                  |
+| [`classify()`](#classify)                     | Classify an OSC message to determine its routing.                                                       |
+| [`clearReplyHandler()`](#clearreplyhandler)   | Clear the reply handler and release the reply channel.                                                  |
+| [`close()`](#close)                           | Close the channel and release its ports.                                                                |
+| [`deactivateReplies()`](#deactivatereplies)   | Release the reply slot.                                                                                 |
+| [`getAndResetMetrics()`](#getandresetmetrics) | Get and reset local metrics (for periodic reporting).                                                   |
+| [`getMetrics()`](#getmetrics)                 | Get current metrics snapshot.                                                                           |
+| [`nextNodeId()`](#nextnodeid)                 | Get the next unique node ID.                                                                            |
+| [`pollReplies()`](#pollreplies)               | Drain pending replies, calling the registered handler (or handler argument, if given) once per message. |
+| [`send()`](#send)                             | Send an OSC message with automatic routing.                                                             |
+| [`sendDirect()`](#senddirect)                 | Send directly to worklet without classification or metrics tracking.                                    |
+| [`sendToPrescheduler()`](#sendtoprescheduler) | Send to prescheduler without classification.                                                            |
+| [`setReplyHandler()`](#setreplyhandler)       | Register a handler for OSC replies from scsynth.                                                        |
+| [`fromTransferable()`](#fromtransferable)     | Reconstruct an OscChannel from data received via postMessage in a worker.                               |
 
 #### Example
 
@@ -3257,6 +3423,20 @@ Transport mode this channel is using.
 
 [`TransportMode`](#transportmode)
 
+##### replyDrops
+
+###### Get Signature
+
+> **get** **replyDrops**(): `number`
+
+Number of reply messages dropped because the reply buffer was full.
+SAB mode only — undefined in PM mode or before [activateReplies](#activatereplies).
+Counter resets each time the slot is (re)claimed.
+
+###### Returns
+
+`number`
+
 ##### transferable
 
 ###### Get Signature
@@ -3297,6 +3477,19 @@ worker.postMessage({ ch: channel.transferable }, channel.transferList);
 
 #### Methods
 
+##### activateReplies()
+
+> **activateReplies**(): `void`
+
+Activate the reply slot without registering a handler. Usually called
+for you by [setReplyHandler](#setreplyhandler); only call directly if you want to
+claim the slot before installing a handler (or to use the optional
+one-shot handler argument of [pollReplies](#pollreplies)).
+
+###### Returns
+
+`void`
+
 ##### classify()
 
 > **classify**(`oscData`): [`OscCategory`](#osccategory)
@@ -3313,6 +3506,16 @@ Classify an OSC message to determine its routing.
 
 [`OscCategory`](#osccategory)
 
+##### clearReplyHandler()
+
+> **clearReplyHandler**(): `void`
+
+Clear the reply handler and release the reply channel. Idempotent.
+
+###### Returns
+
+`void`
+
 ##### close()
 
 > **close**(): `void`
@@ -3323,6 +3526,16 @@ Close the channel and release its ports.
 
 `void`
 
+##### deactivateReplies()
+
+> **deactivateReplies**(): `void`
+
+Release the reply slot. Usually called for you by [clearReplyHandler](#clearreplyhandler).
+
+###### Returns
+
+`void`
+
 ##### getAndResetMetrics()
 
 > **getAndResetMetrics**(): [`OscChannelMetrics`](#oscchannelmetrics)
@@ -3359,6 +3572,30 @@ the root group, 1 is the default group, 2–999 are reserved for manual use).
 
 A unique node ID (>= 1000)
 
+##### pollReplies()
+
+> **pollReplies**(`handler?`): `number`
+
+Drain pending replies, calling the registered handler (or `handler`
+argument, if given) once per message. Returns the number of messages
+processed. Zero-allocation on the hot path.
+
+Call from an AudioWorklet's `process()` method to receive replies on
+the audio thread. In other contexts automatic delivery already calls
+this for you.
+
+###### Parameters
+
+| Parameter  | Type                                                                                        | Description                          |
+| ---------- | ------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `handler?` | ((`view`, `offset`, `length`, `sequence`) => `void`) \| ((`oscData`, `sequence`) => `void`) | Optional override for this call only |
+
+###### Returns
+
+`number`
+
+Number of messages drained
+
 ##### send()
 
 > **send**(`oscData`): `boolean`
@@ -3418,6 +3655,40 @@ Send to prescheduler without classification.
 
 true if sent successfully
 
+##### setReplyHandler()
+
+> **setReplyHandler**(`handler`): `void`
+
+Register a handler for OSC replies from scsynth. Idempotent — replaces
+any previously-registered handler. In AudioWorklet contexts the worklet
+must call [pollReplies](#pollreplies) from `process()` to drain; in all other
+contexts delivery is automatic. All registered channels receive all
+replies (broadcast); filter locally if you only need specific addresses.
+
+SAB mode: handler receives `(view, offset, length, sequence)` — zero-copy
+into the shared buffer. Read bytes from `view[offset..offset+length]`.
+Data is valid only for the duration of the handler call.
+
+PM mode: handler receives `(oscData, sequence)` where `oscData` is a copy.
+
+###### Parameters
+
+| Parameter | Type                                                                                        |
+| --------- | ------------------------------------------------------------------------------------------- |
+| `handler` | ((`view`, `offset`, `length`, `sequence`) => `void`) \| ((`oscData`, `sequence`) => `void`) |
+
+###### Returns
+
+`void`
+
+###### Example
+
+```ts
+channel.setReplyHandler((view, offset, length, sequence) => {
+  // SAB: read raw OSC bytes from view[offset..offset+length]
+});
+```
+
 ##### fromTransferable()
 
 > `static` **fromTransferable**(`data`): [`OscChannel`](#oscchannel)