@onda-lang/webaudio 0.8.3 → 0.8.5

package/README.md

@@ -84,8 +84,6 @@ for an array.
 
 Controlled `i64` domains use the descriptor's exact binary64 integer range. Full-width unranged
 `i64` values continue to use `bigint` when written directly.
-Event `i64` values accept bigint, safe integers, or decimal integer strings and reject values
-outside the signed 64-bit range.
 
 The artifact must be compiled for exactly `audioContext.sampleRate`; the adapter rejects a mismatch
 before registering the node so sample-rate-derived language semantics cannot silently drift. A Web
@@ -97,6 +95,41 @@ Call `processor.close()` when the adapter is no longer used. Closing is idempote
 rejects pending requests, removes listeners, and makes subsequent operations fail immediately. The
 wrapped `AudioWorkletNode` and `AudioContext` remain caller-owned.
 
+## Events
+
+`trigger(nameOrIndex, values?)` accepts event parameters as an ordered array or an object keyed by
+parameter name. Nominal structs are objects containing exactly their declared fields; tuples, fixed
+arrays, and runtime slices are sequences. The adapter validates and encodes the complete logical
+value on the main thread before transferring its packed bytes to the worklet.
+
+For this Onda declaration:
+
+```onda
+struct Note:
+  frequency = 440.0
+  velocity = 1.0
+
+init:
+  current_note: Note
+
+event note_on(note: Note):
+  current_note = note
+```
+
+the corresponding host call is:
+
+```js
+await processor.trigger("note_on", {
+  note: { frequency: 523.25, velocity: 0.7 },
+});
+```
+
+Fixed arrays must have their declared length. Slice lengths may vary up to the configured event
+payload capacity. `i64` leaves accept `bigint`, exact safe integers, or decimal integer strings and
+reject values outside the signed 64-bit range. Missing top-level arguments use declared defaults;
+structs and struct arrays have no event defaults and must be supplied in full. Input rejected during
+worklet preflight leaves processor state usable and rejects the returned promise.
+
 ## Prints
 
 Authored `print(...)` occurrences leave generated execution as bounded typed records. The worklet

package/api.md

@@ -139,7 +139,8 @@ real-time execution.
 
 `writeDelegateBatch` and `writePrintBatch` initialize reusable batch descriptors.
 `writeExecutionOutput` connects their addresses. Call `resetExecutionOutput` immediately before
-every generated init, process, or event entry. After a successful generated call,
+every generated init or process entry. Generated event entries reset after successful input
+preflight instead, so rejected input preserves existing records. After a successful generated call,
 `readDelegateBatch` or `readPrintBatch` validates the result counters.
 `decodeDelegateRecords` converts delegate payloads using `metadata.delegates`.
 `decodePrintRecords` preserves primitive types and source sites; `formatPrintRecords` and
@@ -296,6 +297,17 @@ validateProcessorModule
 writeDelegateBatch
 writeExecutionOutput
 writePrintBatch
+OndaPayloadType
+OndaPayloadField
+OndaPayloadSchema
+OndaPayloadDefault
+OndaPayloadValue
+OndaPayloadSizes
+PayloadPlan
+canonicalF32Number
+EVENT_INPUT_SIZE_BYTES
+PROCESSOR_EXECUTION_INPUT_REJECTED
+writeEventInput
 <!-- END WEB API onda_processor_abi -->
 
 ### `@onda-lang/binaryen-web`
@@ -410,3 +422,21 @@ paramNormalizedToPlain
 paramPlainToNormalized
 registerOndaAudioWorklet
 <!-- END WEB API onda_webaudio -->
+
+### Structured event and delegate values
+
+`PayloadPlan` prepares a recursive message schema once. `encode(values)` accepts ordered parameter
+arrays or objects keyed by parameter name; structs are objects containing exactly their declared
+own fields, and arrays/tuples are sequences. Unknown named parameters and excess positional values
+are rejected. Missing event arguments use declared constant defaults.
+Supply `i64` as `bigint`, an exact safe integer, or a decimal string. `decode(bytes)` returns named
+nested values with `bigint` for `i64`. Plans own immutable schema snapshots.
+
+`requiredWorkspace(bytes)` preflights packed little-endian input. `sizes(lengths)` reports wire
+and aligned workspace sizes without allocating payload storage. Low-level wasm hosts provision
+both regions and a 16-byte descriptor, then call `writeEventInput` before invoking the event.
+Rejected input returns `PROCESSOR_EXECUTION_INPUT_REJECTED` (2) and leaves processor state usable.
+`OndaAudioProcessor.trigger` performs logical encoding before transferring bytes to the worklet.
+Decoded `f32` leaves use `canonicalF32Number(value)`: the returned JavaScript number has the
+shortest decimal representation that round-trips to the same `f32`, so JSON and controls do not
+expose an irrelevant widened binary tail.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onda-lang/webaudio",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "type": "module",
   "description": "Optional Web Audio adapter for Onda processor WebAssembly artifacts",
   "license": "MIT",
@@ -34,7 +34,7 @@
     "prepack": "node ../../scripts/stage-web-api-docs.mjs"
   },
   "dependencies": {
-    "@onda-lang/processor-abi": "0.8.3"
+    "@onda-lang/processor-abi": "0.8.5"
   },
   "publishConfig": {
     "access": "public"

package/src/index.js

@@ -1,5 +1,6 @@
 import { paramAddress } from "./param-metadata.js";
 import {
+  PayloadPlan,
   createParamControl,
   paramElementMetadata,
   decodeDelegateRecords,
@@ -306,6 +307,7 @@ export class OndaAudioProcessor {
     this.node = node;
     this.metadata = metadata;
     this.paramInfo = metadata?.metadata?.params ?? null;
+    this.eventPlans = new WeakMap();
     this.paramControls = new WeakMap();
     this.paramElements = new WeakMap();
     this.nextRequestId = 1;
@@ -629,7 +631,16 @@ export class OndaAudioProcessor {
   }
 
   trigger(event, values = {}) {
-    return this.request("event", { event, values });
+    try {
+      this.assertOpen();
+      const events = this.metadata?.metadata?.events;
+      const info = Number.isInteger(event) ? events?.[event] : events?.find((entry) => entry.name === event);
+      if (!info) throw new Error(`unknown Onda event '${String(event)}'`);
+      let plan = this.eventPlans.get(info);
+      if (!plan) { plan = new PayloadPlan(info.schema); this.eventPlans.set(info, plan); }
+      const payload = plan.encode(values);
+      return this.request("event", { event, payload }, [payload.buffer]);
+    } catch (error) { return Promise.reject(error); }
   }
 
   onDelegates(listener) {

package/src/worklet.js

@@ -12,6 +12,7 @@ const ONDA_PROCESS_BEGIN_BLOCK = 1 << 0;
 const ONDA_PROCESS_END_BLOCK = 1 << 1;
 const ONDA_INIT_PRESERVE_PINNED = 0;
 const ONDA_INIT_FULL = 1;
+const PROCESSOR_EXECUTION_INPUT_REJECTED = 2;
 const ONDA_AUDIO_WORKLET_PROCESSOR_NAME = "onda-wasm-processor";
 const DEFAULT_EVENT_PAYLOAD_CAPACITY_BYTES = 64 * 1024;
 const DEFAULT_DELEGATE_CAPACITY_BYTES = 64 * 1024;
@@ -189,6 +190,12 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     this.eventPayloadPtr = this.eventPayloadCapacity
       ? this.alloc(this.eventPayloadCapacity, 8)
       : 0;
+    // Each tensor and dynamic prefix adds at most seven alignment bytes.
+    // Reserve before rendering; dispatch never grows memory for preparation.
+    this.eventWorkspaceCapacity = this.eventPayloadCapacity + 7 * Math.max(0,
+      ...this.eventInfo.map((event) => event.params.length * 2));
+    this.eventWorkspacePtr = this.eventWorkspaceCapacity ? this.alloc(this.eventWorkspaceCapacity, 8) : 0;
+    this.eventInputPtr = this.eventInfo.length ? this.alloc(16, 4) : 0;
     this.delegateCapacity = this.configuredDelegateCapacity(
       processorOptions.delegateCapacityBytes,
     );
@@ -341,6 +348,7 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
         this.outputCapacityFrames,
       );
     });
+    this.eventPayloadView = new Uint8Array(buffer, this.eventPayloadPtr, this.eventPayloadCapacity);
     this.delegateRecordView = this.delegateStoragePtr
       ? new Uint8Array(buffer, this.delegateStoragePtr, this.delegateCapacity)
       : null;
@@ -710,7 +718,7 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
       } else if (message.type === "event") {
         this.dispatchEvent(
           message.event ?? message.name ?? message.index,
-          message.values ?? message.args ?? {},
+          message.payload,
         );
         this.postResponse(message, { type: "onda-ok", operation: message.type });
       } else if (message.type === "read-control-outputs") {
@@ -752,7 +760,7 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     }
   }
 
-  dispatchEvent(selector, values) {
+  dispatchEvent(selector, payload) {
     this.requireInitialized("event dispatch");
     const eventId = Number.isInteger(selector)
       ? selector
@@ -761,61 +769,23 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     if (!event) {
       throw new Error(`unknown Onda event '${String(selector)}'`);
     }
-    let payloadSize = 0;
-    for (let paramId = 0; paramId < event.params.length; paramId += 1) {
-      const param = event.params[paramId];
-      const value = this.eventValue(event, param, paramId, values);
-      if (param.is_slice) {
-        const length = this.sequenceLength(
-          value,
-          `event '${event.name}' slice '${param.name}'`,
-        );
-        payloadSize = this.checkedEventPayloadSize(
-          payloadSize,
-          4 + length * this.scalarByteSize(param.scalar),
-          event.name,
-        );
-      } else {
-        this.validateStorageValue(param, value);
-        payloadSize = this.checkedEventPayloadSize(
-          payloadSize,
-          Number(param.byte_size ?? 0),
-          event.name,
-        );
-      }
-    }
+    if (!(payload instanceof Uint8Array)) throw new TypeError("event payload must be encoded bytes");
+    const payloadSize = payload.byteLength;
     if (payloadSize > this.eventPayloadCapacity) {
-      throw new Error(
-        `event '${event.name}' requires ${payloadSize} payload bytes; configured capacity is ${this.eventPayloadCapacity}`,
-      );
+      throw new Error(`event '${event.name}' requires ${payloadSize} payload bytes; configured capacity is ${this.eventPayloadCapacity}`);
     }
-
-    let offset = 0;
     const view = this.memoryView();
-    for (let paramId = 0; paramId < event.params.length; paramId += 1) {
-      const param = event.params[paramId];
-      const value = this.eventValue(event, param, paramId, values);
-      const address = this.eventPayloadPtr + offset;
-      if (param.is_slice) {
-        const length = this.sequenceLength(
-          value,
-          `event '${event.name}' slice '${param.name}'`,
-        );
-        view.setInt32(address, length, true);
-        this.writeScalarValues(address + 4, param.scalar, value, length, view);
-        offset += 4 + length * this.scalarByteSize(param.scalar);
-      } else {
-        this.writeStorage(address, param, value, view);
-        offset += Number(param.byte_size ?? 0);
-      }
-    }
+    this.eventPayloadView.set(payload);
     const handler = this.exports[event.export];
     if (typeof handler !== "function") {
       throw new Error(`missing WebAssembly export '${event.export}'`);
     }
-    this.prepareExecutionOutput();
+    view.setUint32(this.eventInputPtr, this.eventPayloadPtr, true);
+    view.setUint32(this.eventInputPtr + 4, payloadSize, true);
+    view.setUint32(this.eventInputPtr + 8, this.eventWorkspacePtr, true);
+    view.setUint32(this.eventInputPtr + 12, this.eventWorkspaceCapacity, true);
     const status = handler(
-      this.eventPayloadPtr,
+      this.eventInputPtr,
       this.paramsPtr,
       this.statePtr,
       this.bufferPointersPtr,
@@ -824,6 +794,7 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
       this.bufferSampleRatesPtr,
       this.executionOutputPtr,
     );
+    if (status === PROCESSOR_EXECUTION_INPUT_REJECTED) throw new Error(`event '${event.name}' input rejected: invalid payload or insufficient workspace`);
     this.publishExecutionOutput(
       EXECUTION_OPERATION_EVENT,
       eventId,
@@ -831,34 +802,6 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     this.checkExecutionStatus(status, `event '${event.name}'`);
   }
 
-  eventValue(event, param, paramId, values) {
-    const supplied = Array.isArray(values)
-      ? values[paramId]
-      : values?.[param.name];
-    const value = supplied === undefined
-      ? this.metadataDefaultValue(param)
-      : supplied;
-    if (value === undefined) {
-      throw new Error(
-        `event '${event.name}' requires parameter '${param.name}'`,
-      );
-    }
-    return value;
-  }
-
-  checkedEventPayloadSize(current, additional, eventName) {
-    const next = current + additional;
-    if (
-      !Number.isSafeInteger(additional)
-      || additional < 0
-      || !Number.isSafeInteger(next)
-      || next > 0x7fff_ffff
-    ) {
-      throw new Error(`event '${eventName}' payload exceeds the 32-bit ABI limit`);
-    }
-    return next;
-  }
-
   readControlOutputs() {
     this.requireInitialized("reading control outputs");
     return Object.fromEntries(