@onda-lang/webaudio 0.8.2 → 0.8.4

package/README.md

@@ -75,15 +75,15 @@ const sliderValueFor440Hz = paramPlainToNormalized(cutoff, 440);
 ```
 
 The helpers preserve exact endpoints, clamp and snap consistently with adapter writes, and reject
-arrays or numeric parameters without a host-control domain. `scale`, `curve`, `unit`, `step_repr`,
+numeric parameters without a host-control domain. Select array elements with indexed names such
+as `offsets[0]`, or supply an exact-length array to `setParam("offsets", values)`. `scale`, `curve`, `unit`, `step_repr`,
 and `step_count` remain available on each parameter's descriptor metadata for control construction
 and formatting. For repeated UI conversion, `createParamControl(param)` prepares and validates the
-descriptor once and returns bound conversion methods.
+descriptor once and returns bound conversion methods; pass an element index as its second argument
+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
@@ -95,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

@@ -119,7 +119,11 @@ versions rather than guessing layout compatibility.
 ### Parameter controls
 
 `createParamControl(metadata)` validates one scalar parameter descriptor and returns a reusable
-`OndaPreparedParamControl`. `createParamDomain(domain)` does the same from already-decoded values.
+`OndaPreparedParamControl`. For an array, `createParamControl(metadata, index)` prepares one element;
+`paramElementMetadata(metadata, index)` projects its scalar descriptor, default, and storage offset.
+The Web Audio adapter accepts indexed names such as `offsets[1]` in `setParam` and
+`setParamNormalized`, and exact-length arrays in `setParam("offsets", values)`.
+`createParamDomain(domain)` does the same from already-decoded values.
 Prepared controls expose `constrainPlain`, `normalizedToPlain`, and `plainToNormalized` methods.
 
 The one-shot `constrainParamPlain`, `paramNormalizedToPlain`, and `paramPlainToNormalized`
@@ -135,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
@@ -271,6 +276,7 @@ PROCESSOR_INIT_PRESERVE_PINNED
 PROCESSOR_SNAPSHOT_FORMAT_VERSION
 constrainParamPlain
 createParamControl
+paramElementMetadata
 createParamDomain
 createProcessorArtifactFiles
 decodeDelegateRecords
@@ -291,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`
@@ -405,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.2",
+  "version": "0.8.4",
   "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.2"
+    "@onda-lang/processor-abi": "0.8.4"
   },
   "publishConfig": {
     "access": "public"

package/src/index.js

@@ -1,5 +1,8 @@
+import { paramAddress } from "./param-metadata.js";
 import {
+  PayloadPlan,
   createParamControl,
+  paramElementMetadata,
   decodeDelegateRecords,
   formatPrintRecords,
   validateProcessorArtifact,
@@ -152,18 +155,24 @@ function configuredExecutionOutputCapacity(
   return capacity;
 }
 
-function paramInfoFor(paramInfo, selector) {
-  const info = Number.isInteger(selector)
-    ? paramInfo[selector]
-    : paramInfo.find((candidate) => candidate.name === selector);
-  if (!info) {
-    throw new Error(`unknown Onda parameter '${String(selector)}'`);
+function paramElementInfo(info, element, cache = null) {
+  if (!cache) return paramElementMetadata(info, element);
+  let elements = cache.get(info);
+  if (!elements) {
+    elements = new Map();
+    cache.set(info, elements);
   }
-  return info;
+  if (!elements.has(element)) elements.set(element, paramElementMetadata(info, element));
+  return elements.get(element);
+}
+
+function paramInfoFor(params, selector, cache = null) {
+  const { info, element } = paramAddress(params, selector);
+  return element === null ? info : paramElementInfo(info, element, cache);
 }
 
 function preparedParamControl(info, cache = null) {
-  if (Number(info.array_len) !== 1) return null;
+  if (info.type_repr !== info.scalar) return null;
   if (info.scalar !== "bool" && info.param_control === null) return null;
   let control = cache?.get(info);
   if (!control) {
@@ -173,7 +182,15 @@ function preparedParamControl(info, cache = null) {
   return control;
 }
 
-function constrainParamValue(info, value, cache = null) {
+function constrainParamValue(info, value, cache = null, elements = null) {
+  if (info.type_repr !== info.scalar) {
+    if ((!Array.isArray(value) && !ArrayBuffer.isView(value)) || value.length !== info.array_len) {
+      throw new Error(`Onda parameter '${info.name}' requires exactly ${info.array_len} values`);
+    }
+    return Array.from(value, (item, index) => constrainParamValue(
+      paramElementInfo(info, index, elements), item, cache, elements,
+    ));
+  }
   return preparedParamControl(info, cache)?.constrainPlain(value) ?? value;
 }
 
@@ -290,7 +307,9 @@ 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;
     this.pending = new Map();
     this.delegateListeners = new Set();
@@ -580,10 +599,10 @@ export class OndaAudioProcessor {
       if (!Array.isArray(this.paramInfo)) {
         return this.request("set-param", { param, value });
       }
-      const info = paramInfoFor(this.paramInfo ?? [], param);
+      const info = paramInfoFor(this.paramInfo ?? [], param, this.paramElements);
       return this.request("set-param", {
         param,
-        value: constrainParamValue(info, value, this.paramControls),
+        value: constrainParamValue(info, value, this.paramControls, this.paramElements),
       });
     } catch (error) {
       return Promise.reject(error);
@@ -597,7 +616,7 @@ export class OndaAudioProcessor {
           "setParamNormalized requires processor metadata; construct the adapter with createOndaAudioProcessor()",
         );
       }
-      const info = paramInfoFor(this.paramInfo, param);
+      const info = paramInfoFor(this.paramInfo, param, this.paramElements);
       const control = preparedParamControl(info, this.paramControls);
       if (!control) {
         throw new Error(`Onda parameter '${info.name}' has no scalar host-control domain`);
@@ -612,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/param-metadata.js

@@ -0,0 +1,18 @@
+// Shared by the adapter and worklet; keep this module independent of package
+// imports so worklets also load from a plain static HTTP directory.
+export function paramAddress(params, selector) {
+  const direct = Number.isInteger(selector) ? params[selector] : params.find((param) => param.name === selector);
+  if (direct) return { info: direct, element: null };
+  if (typeof selector === "string") {
+    const match = /^(.*)\[(0|[1-9][0-9]*)\]$/.exec(selector);
+    const root = match && params.find((param) => param.name === match[1] && param.type_repr !== param.scalar);
+    if (root) {
+      const element = Number(match[2]);
+      if (!Number.isSafeInteger(element) || element >= root.array_len) {
+        throw new Error(`Onda parameter '${root.name}' element index is out of bounds`);
+      }
+      return { info: root, element };
+    }
+  }
+  throw new Error(`unknown Onda parameter '${String(selector)}'`);
+}

package/src/worklet.js

@@ -1,3 +1,4 @@
+import { paramAddress } from "./param-metadata.js";
 import {
   EXECUTION_OPERATION_EVENT,
   EXECUTION_OPERATION_INIT,
@@ -11,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;
@@ -188,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,
     );
@@ -340,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;
@@ -477,13 +486,7 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
   }
 
   setParam(selector, value) {
-    const paramId = Number.isInteger(selector)
-      ? selector
-      : this.paramInfo.findIndex((param) => param.name === selector);
-    const param = this.paramInfo[paramId];
-    if (!param) {
-      throw new Error(`unknown Onda parameter '${String(selector)}'`);
-    }
+    const { info: param, element } = paramAddress(this.paramInfo, selector);
     if (value === undefined) {
       throw new Error(`Onda parameter '${param.name}' requires a value`);
     }
@@ -502,6 +505,10 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     ) {
       throw new Error(`Onda parameter '${param.name}' has invalid storage metadata`);
     }
+    if (element !== null) {
+      this.writeScalar(this.paramsPtr + offset + element * this.scalarByteSize(param.scalar), param.scalar, value, this.memoryView());
+      return;
+    }
     this.writeStorage(
       this.paramsPtr + offset,
       param,
@@ -711,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") {
@@ -753,7 +760,7 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     }
   }
 
-  dispatchEvent(selector, values) {
+  dispatchEvent(selector, payload) {
     this.requireInitialized("event dispatch");
     const eventId = Number.isInteger(selector)
       ? selector
@@ -762,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,
@@ -825,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,
@@ -832,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(