@onda-lang/webaudio 0.8.6 → 0.8.8

package/README.md

@@ -57,8 +57,13 @@ write to the worklet. Boolean normalized values use the `0.5` threshold. For exa
 ```js
 await processor.setParam("cutoff", 440);          // exactly 440 Hz
 await processor.setParamNormalized("cutoff", 0.5); // midpoint in its declared control scale
+await processor.setParamElement("offsets", 1, 12); // one fixed-array element
+await processor.setParamElementNormalized("offsets", 1, 0.5);
 ```
 
+The element methods also accept scalar parameters with element index zero. Indexed names such as
+`offsets[1]` remain available through `setParam()` and `setParamNormalized()`.
+
 The same synchronous conversion helpers are re-exported for UI display and typed entry:
 
 ```js
@@ -128,7 +133,9 @@ Fixed arrays must have their declared length. Slice lengths may vary up to the c
 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.
+worklet preflight leaves processor state usable and rejects the returned promise. Unknown
+nonnegative numeric event indices are successful no-ops, matching native dispatch; unknown names
+and negative indices reject the promise.
 
 ## Prints
 
@@ -249,23 +256,28 @@ const processor = await createOndaAudioProcessorInitialized(context, artifact, {
 Hosts may instead pass a flat array in physical descriptor order or key individual physical names
 such as `"bank[1]"`. Logical group metadata determines the contiguous slot range; no sample data is
 copied when Onda selects a slot while processing. Initial descriptors are installed before the
-initialized constructor runs full initialization, so authored top-level and proc init code can
+initialized factory awaits full initialization, so authored top-level and proc init code can
 preprocess the supplied samples once before rendering begins.
 
 Artifact descriptors and module exports are validated by the shared, compiler-free
 `@onda-lang/processor-abi` package before anything reaches the rendering thread.
-If generated init or event code returns a nonzero execution status, the adapter reports the error
-to the caller. A failing process call reports an `onda-error` and emits silence. Any generated-code
-failure invalidates the live state, so later callbacks remain silent and stateful operations are
-rejected until full initialization or snapshot restoration succeeds.
+If generated init or event code returns a nonzero execution status, the adapter rejects with
+`OndaExecutionError`; its `operation` and `status` fields preserve the raw processor result. Event
+input rejection preserves live state. The package re-exports the `PROCESSOR_EXECUTION_*` constants
+for direct status comparisons. Runtime-safety failure invalidates the processor, so later callbacks
+remain silent and stateful operations are rejected until full initialization or snapshot
+restoration succeeds. Subscribe with `onExecutionError(listener)` to receive the same typed error
+when a render-time process call fails; the failed callback emits silence.
 `init(ONDA_INIT_PRESERVE_PINNED)` reruns generated initialization
 while preserving pinned roots and task continuations; `init(ONDA_INIT_FULL)` initializes the
 complete physical state and is required before processing an instance returned by
-`createOndaAudioProcessor`. The initialized convenience constructor performs full initialization
-during worklet construction. Neither mode allocates on the successful path, and a
+`createOndaAudioProcessor`. The initialized convenience factory installs its response and output
+handling before requesting full initialization, then resolves only after initialization succeeds.
+Neither mode allocates on the successful path, and a
 failure returns the processor to its silent pending state until full initialization or snapshot
 restore succeeds. Suspend or disconnect playback before initialization that performs substantial
-work.
+work. Snapshot restoration performs its internal full initialization silently and does not deliver
+init prints or delegates.
 
 Dynamic event storage is also allocated before rendering. Its default capacity is 64 KiB per
 processor with dynamic events and can be changed explicitly:

package/api.md

@@ -121,8 +121,10 @@ versions rather than guessing layout compatibility.
 `createParamControl(metadata)` validates one scalar parameter descriptor and returns a reusable
 `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)`.
+The Web Audio adapter exposes `setParamElement(nameOrIndex, element, value)` and
+`setParamElementNormalized(nameOrIndex, element, normalized)` for individual scalar or fixed-array
+elements. Indexed names such as `offsets[1]` remain accepted by `setParam` and
+`setParamNormalized`; exact-length arrays use `setParam("offsets", values)`.
 `createParamDomain(domain)` does the same from already-decoded values.
 Prepared controls expose `constrainPlain`, `normalizedToPlain`, and `plainToNormalized` methods.
 
@@ -144,7 +146,8 @@ contract.
 every generated init or process entry. Generated event entries reset before input preflight, so
 rejected input returns empty batches. After a successful generated call,
 `readDelegateBatch` or `readPrintBatch` validates the result counters.
-`decodeDelegateRecords` converts delegate payloads using `metadata.delegates`.
+`decodeDelegateBatch` validates and decodes a complete delegate batch in one call;
+`decodeDelegateRecords` decodes an already-isolated storage region using `metadata.delegates`.
 `decodePrintRecords` preserves primitive types and source sites; `formatPrintRecords` and
 `formatPrintBatch` add canonical text formatting. Both decoded record types expose a `sequence` from
 the host-reset call-local counter; merge that call's two arrays by this field when presenting one
@@ -186,27 +189,36 @@ The package root re-exports the common artifact validation and file helpers. The
 - `compileOndaProcessorModule(artifact)` validates and compiles a reusable module off the render thread.
 - `ondaAudioWorkletNodeOptions(artifact, options?)` builds low-level node options.
 - `createOndaAudioProcessor(context, artifact, options?)` allocates an uninitialized adapter.
-- `createOndaAudioProcessorInitialized(context, artifact, options?)` allocates and fully initializes it.
+- `createOndaAudioProcessorInitialized(context, artifact, options?)` allocates it, requests full
+  initialization through the status-bearing control protocol, and resolves only on success.
 - `flattenedAudioChannelCount(ports?)` totals declared physical channels with validation.
 
 `OndaAudioProcessorOptions` accepts initial plain parameter values, external buffers, event,
 delegate, and print capacities, an optional construction-time `onPrint` listener, a precompiled
 module, custom node options, and an `AudioWorkletNode` constructor. Pass `onPrint` when using the
-initialized constructor if initialization output must be observed; registering a listener after
+initialized factory if initialization output must be observed; registering a listener after
 construction cannot replay output from an execution that has already completed. The artifact sample
 rate must equal the context sample rate and it must expose at least one audio input or output.
 Print and delegate delivery uses a bounded `SharedArrayBuffer` ring and requires cross-origin
 isolation in browsers; ordinary audio processing remains available when shared memory is absent.
 Low-level callers that manually pair the returned node options with `OndaAudioProcessor` must pass
-`processorOptions.executionOutputRing` as the adapter constructor's fourth argument.
+the artifact metadata as the adapter constructor's second argument and
+`processorOptions.executionOutputRing` as its fourth argument. Event encoding and numeric
+unknown-index classification require that metadata.
 
 ### `OndaAudioProcessor`
 
 The adapter exposes its `node` and validated `metadata`, plus these operations:
 
-- `setParam(nameOrIndex, plain)` and `setParamNormalized(nameOrIndex, normalized)`.
-- `trigger(nameOrIndex, values?)` for input events.
-- `onDelegates(listener)` and `onPrint(listener)`, each returning an unsubscribe function.
+- `setParam(nameOrIndex, plain)` and `setParamNormalized(nameOrIndex, normalized)` for whole
+  parameters.
+- `setParamElement(nameOrIndex, element, plain)` and
+  `setParamElementNormalized(nameOrIndex, element, normalized)` for one scalar or fixed-array
+  element.
+- `trigger(nameOrIndex, values?)` for input events. Unknown nonnegative numeric indices are
+  successful no-ops, matching native dispatch; unknown names and negative indices are rejected.
+- `onExecutionError(listener)`, `onDelegates(listener)`, and `onPrint(listener)`, each returning an
+  unsubscribe function.
 - `init(mode)`, `snapshot()`, and `restoreSnapshot(bytes)`.
 - `readControlOutputs()` and `readBuffer(nameOrIndex)`.
 - `request(type, fields?, transfer?)` for adapter protocol extensions.
@@ -224,7 +236,24 @@ each init, event, or process segment.
 
 `ONDA_INIT_FULL` clears and initializes all physical state. `ONDA_INIT_PRESERVE_PINNED` retains
 pinned state according to the processor ABI. The package also re-exports the prepared and one-shot
-parameter conversion helpers.
+parameter conversion helpers. Snapshot restoration performs its internal full initialization
+silently, without delivering init prints or delegates.
+
+Raw WebAssembly exports use the same generated status values as native processor objects:
+`PROCESSOR_EXECUTION_OK` (`0`), `PROCESSOR_EXECUTION_RUNTIME_SAFETY_FAILURE` (`1`), and event-only
+`PROCESSOR_EXECUTION_INPUT_REJECTED` (`2`). The Web Audio adapter translates host-side validation
+problems into rejected promises before generated execution. It also rejects init and event promises
+when generated code returns a nonzero status: status `1` invalidates the live processor, while event
+status `2` preserves it. These generated failures use `OndaExecutionError`, whose `operation` and
+`status` fields retain the machine-readable failure. The Web Audio root re-exports all three
+`PROCESSOR_EXECUTION_*` constants for direct comparison. Render-time process failure invalidates the
+processor and silences subsequent callbacks. `onExecutionError(listener)` receives its typed
+`OndaExecutionError`; requested init and event failures remain on their promise rejection path and
+are not reported twice.
+The raw `@onda-lang/processor-abi` package exposes `PROCESSOR_BEGIN_BLOCK`,
+`PROCESSOR_END_BLOCK`, and `PROCESSOR_FULL_BLOCK` for native and direct WebAssembly hosts that use
+segmented processing. Web Audio schedules render quanta internally and has no segmented-process
+method.
 
 `@onda-lang/webaudio/worklet` is the side-effect-only AudioWorklet registration module and has no
 named exports.
@@ -271,8 +300,11 @@ PRINT_RECORD_HEADER_SIZE_BYTES
 PROCESSOR_ABI_VERSION
 PROCESSOR_ARTIFACT_FORMAT
 PROCESSOR_ARTIFACT_FORMAT_VERSION
+PROCESSOR_BEGIN_BLOCK
+PROCESSOR_END_BLOCK
 PROCESSOR_EXECUTION_OK
 PROCESSOR_EXECUTION_RUNTIME_SAFETY_FAILURE
+PROCESSOR_FULL_BLOCK
 PROCESSOR_INIT_FULL
 PROCESSOR_INIT_PRESERVE_PINNED
 PROCESSOR_SNAPSHOT_FORMAT_VERSION
@@ -281,6 +313,7 @@ createParamControl
 paramElementMetadata
 createParamDomain
 createProcessorArtifactFiles
+decodeDelegateBatch
 decodeDelegateRecords
 decodePrintRecords
 formatPrintBatch
@@ -320,12 +353,19 @@ OndaArtifactError
 OndaBinaryenError
 OndaBinaryenOptions
 OndaProcessorArtifact
+OndaProcessorInitMode
 OndaProcessorMetadata
 PROCESSOR_ABI_VERSION
 PROCESSOR_ARTIFACT_FORMAT
 PROCESSOR_ARTIFACT_FORMAT_VERSION
+PROCESSOR_BEGIN_BLOCK
+PROCESSOR_END_BLOCK
+PROCESSOR_EXECUTION_INPUT_REJECTED
 PROCESSOR_EXECUTION_OK
 PROCESSOR_EXECUTION_RUNTIME_SAFETY_FAILURE
+PROCESSOR_FULL_BLOCK
+PROCESSOR_INIT_FULL
+PROCESSOR_INIT_PRESERVE_PINNED
 PROCESSOR_SNAPSHOT_FORMAT_VERSION
 SUPPORTED_MIR_SCHEMA_VERSION
 compileTrustedMir
@@ -366,6 +406,7 @@ OndaLspAnalysisOptions
 OndaLspMessage
 OndaMaterializedProjectFile
 OndaProcessorArtifact
+OndaProcessorInitMode
 OndaProcessorMetadata
 OndaProjectBufferInfo
 OndaProjectCapabilities
@@ -383,8 +424,14 @@ OndaWorkerLike
 PROCESSOR_ABI_VERSION
 PROCESSOR_ARTIFACT_FORMAT
 PROCESSOR_ARTIFACT_FORMAT_VERSION
+PROCESSOR_BEGIN_BLOCK
+PROCESSOR_END_BLOCK
+PROCESSOR_EXECUTION_INPUT_REJECTED
 PROCESSOR_EXECUTION_OK
 PROCESSOR_EXECUTION_RUNTIME_SAFETY_FAILURE
+PROCESSOR_FULL_BLOCK
+PROCESSOR_INIT_FULL
+PROCESSOR_INIT_PRESERVE_PINNED
 PROCESSOR_SNAPSHOT_FORMAT_VERSION
 WorkerCompilerOptions
 createCompiler
@@ -408,11 +455,16 @@ OndaAudioProcessor
 OndaAudioProcessorOptions
 OndaAudioPrintBatch
 OndaAudioPrintListener
+OndaExecutionError
+OndaExecutionErrorListener
 OndaInitMode
 OndaParamDomain
 OndaPreparedParamControl
 OndaProcessorArtifact
 OndaProcessorMetadata
+PROCESSOR_EXECUTION_INPUT_REJECTED
+PROCESSOR_EXECUTION_OK
+PROCESSOR_EXECUTION_RUNTIME_SAFETY_FAILURE
 compileOndaProcessorModule
 constrainParamPlain
 createOndaAudioProcessor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onda-lang/webaudio",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "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.6"
+    "@onda-lang/processor-abi": "0.8.8"
   },
   "publishConfig": {
     "access": "public"

package/src/index.d.ts

@@ -3,6 +3,21 @@ export const ONDA_INIT_PRESERVE_PINNED: 0;
 export const ONDA_INIT_FULL: 1;
 export type OndaInitMode = 0 | 1;
 
+export {
+  PROCESSOR_EXECUTION_INPUT_REJECTED,
+  PROCESSOR_EXECUTION_OK,
+  PROCESSOR_EXECUTION_RUNTIME_SAFETY_FAILURE,
+} from "@onda-lang/processor-abi";
+
+/** A nonzero status returned by generated processor execution. */
+export class OndaExecutionError extends Error {
+  constructor(message: string, operation: string, status: number);
+  readonly operation: string;
+  readonly status: number;
+}
+
+export type OndaExecutionErrorListener = (error: OndaExecutionError) => void;
+
 export type {
   OndaParamDomain,
   OndaPreparedParamControl,
@@ -88,6 +103,7 @@ export function createOndaAudioProcessor(
   artifact: OndaProcessorArtifact,
   options?: OndaAudioProcessorOptions,
 ): Promise<OndaAudioProcessor>;
+/** Resolves after full initialization succeeds; generated failures reject with OndaExecutionError. */
 export function createOndaAudioProcessorInitialized(
   context: BaseAudioContext,
   artifact: OndaProcessorArtifact,
@@ -110,9 +126,20 @@ export class OndaAudioProcessor {
   request(type: string, fields?: Record<string, unknown>, transfer?: Transferable[]): Promise<any>;
   /** Set a plain Onda value; ranged scalar values are clamped and snapped. */
   setParam(param: string | number, value: unknown): Promise<any>;
+  /** Set one scalar or fixed-array parameter element without modifying its siblings. */
+  setParamElement(param: string | number, element: number, value: unknown): Promise<any>;
   /** Map a host value in [0, 1] through the descriptor and set the resulting plain value. */
   setParamNormalized(param: string | number, value: number): Promise<any>;
+  /** Normalized form of setParamElement(). */
+  setParamElementNormalized(
+    param: string | number,
+    element: number,
+    value: number,
+  ): Promise<any>;
+  /** Unknown nonnegative numeric event indices are successful no-ops; unknown names are rejected. */
   trigger(event: string | number, values?: Record<string, unknown> | unknown[]): Promise<any>;
+  /** Subscribe to asynchronous render-time generated failures. */
+  onExecutionError(listener: OndaExecutionErrorListener): () => boolean;
   /**
    * Subscribe to batches decoded after generated execution. Collection is active only while at
    * least one listener is registered. overflowCount reports configured-capacity loss and

package/src/index.js

@@ -1,4 +1,4 @@
-import { paramAddress } from "./param-metadata.js";
+import { paramAddress, paramElementAddress } from "./param-metadata.js";
 import {
   PayloadPlan,
   createParamControl,
@@ -18,6 +18,10 @@ import {
   drainExecutionOutputRing,
   openExecutionOutputRing,
 } from "./execution-output-ring.js";
+import {
+  PROCESSOR_INIT_FULL,
+  PROCESSOR_INIT_PRESERVE_PINNED,
+} from "./processor-constants.js";
 
 export {
   createParamDomain,
@@ -25,11 +29,23 @@ export {
   constrainParamPlain,
   paramNormalizedToPlain,
   paramPlainToNormalized,
+  PROCESSOR_EXECUTION_INPUT_REJECTED,
+  PROCESSOR_EXECUTION_OK,
+  PROCESSOR_EXECUTION_RUNTIME_SAFETY_FAILURE,
 } from "@onda-lang/processor-abi";
 
 export const ONDA_AUDIO_WORKLET_PROCESSOR_NAME = "onda-wasm-processor";
-export const ONDA_INIT_PRESERVE_PINNED = 0;
-export const ONDA_INIT_FULL = 1;
+export const ONDA_INIT_PRESERVE_PINNED = PROCESSOR_INIT_PRESERVE_PINNED;
+export const ONDA_INIT_FULL = PROCESSOR_INIT_FULL;
+
+export class OndaExecutionError extends Error {
+  constructor(message, operation, status) {
+    super(message);
+    this.name = "OndaExecutionError";
+    this.operation = operation;
+    this.status = status;
+  }
+}
 
 const registrationByContext = new WeakMap();
 const DEFAULT_DELEGATE_CAPACITY_BYTES = 64 * 1024;
@@ -171,6 +187,11 @@ function paramInfoFor(params, selector, cache = null) {
   return element === null ? info : paramElementInfo(info, element, cache);
 }
 
+function paramElementInfoFor(params, selector, element, cache = null) {
+  const address = paramElementAddress(params, selector, element);
+  return paramElementInfo(address.info, address.element, cache);
+}
+
 function preparedParamControl(info, cache = null) {
   if (info.type_repr !== info.scalar) return null;
   if (info.scalar !== "bool" && info.param_control === null) return null;
@@ -263,7 +284,7 @@ async function createOndaAudioProcessorImpl(context, artifact, options, initiali
   }
   const nodeOptions = audioWorkletNodeOptionsFromValidated(
     validated,
-    { ...options, compiledModule, initialize },
+    { ...options, compiledModule, initialize: false },
     false,
   );
   const node = new NodeConstructor(
@@ -271,12 +292,32 @@ async function createOndaAudioProcessorImpl(context, artifact, options, initiali
     ONDA_AUDIO_WORKLET_PROCESSOR_NAME,
     nodeOptions,
   );
-  return new OndaAudioProcessor(
+  const processor = new OndaAudioProcessor(
     node,
     validated.metadata,
     options.onPrint,
     nodeOptions.processorOptions.executionOutputRing,
   );
+  if (!initialize) return processor;
+  try {
+    await processor.init(ONDA_INIT_FULL);
+    return processor;
+  } catch (error) {
+    // Initialization publishes diagnostic prints before reporting its status. Consume any
+    // already-published records while the construction-time listener is still installed.
+    try {
+      processor.drainExecutionOutput();
+    } catch {
+      // Preserve the initialization failure if consuming its diagnostics also fails.
+    }
+    processor.close(error);
+    try {
+      node.disconnect?.();
+    } catch {
+      // Preserve the initialization failure if node teardown also fails.
+    }
+    throw error;
+  }
 }
 
 export async function compileOndaProcessorModule(artifact) {
@@ -312,6 +353,7 @@ export class OndaAudioProcessor {
     this.paramElements = new WeakMap();
     this.nextRequestId = 1;
     this.pending = new Map();
+    this.executionErrorListeners = new Set();
     this.delegateListeners = new Set();
     this.delegateSubscriptionId = 0;
     this.printListeners = new Set(
@@ -333,15 +375,22 @@ export class OndaAudioProcessor {
     this.closeReason = null;
     this.handleMessage = (event) => {
       const message = event.data ?? {};
-      if (message.requestId === undefined) return;
+      const error = message.type === "onda-error"
+        ? Number.isInteger(message.status)
+          ? new OndaExecutionError(message.error, message.operation, message.status)
+          : new Error(message.error)
+        : null;
+      if (message.requestId === undefined) {
+        if (error instanceof OndaExecutionError) {
+          this.notifyListeners(this.executionErrorListeners, error);
+        }
+        return;
+      }
       const pending = this.pending.get(message.requestId);
       if (!pending) return;
       this.pending.delete(message.requestId);
-      if (message.type === "onda-error") {
-        pending.reject(new Error(message.error));
-      } else {
-        pending.resolve(message);
-      }
+      if (error) pending.reject(error);
+      else pending.resolve(message);
     };
     node.port.addEventListener("message", this.handleMessage);
     node.port.start?.();
@@ -375,7 +424,7 @@ export class OndaAudioProcessor {
         if (result.async) await result.value;
       }
     };
-    void wait().catch((error) => this.reportExecutionOutputError(error));
+    void wait().catch((error) => this.reportListenerError(error));
   }
 
   stopExecutionOutputDrain() {
@@ -398,18 +447,18 @@ export class OndaAudioProcessor {
     );
   }
 
-  reportExecutionOutputError(error) {
+  reportListenerError(error) {
     queueMicrotask(() => {
       throw error;
     });
   }
 
-  notifyExecutionOutputListeners(listeners, batch) {
+  notifyListeners(listeners, value) {
     for (const listener of listeners) {
       try {
-        listener(batch);
+        listener(value);
       } catch (error) {
-        this.reportExecutionOutputError(error);
+        this.reportListenerError(error);
       }
     }
   }
@@ -422,7 +471,7 @@ export class OndaAudioProcessor {
         try {
           this.consumeExecutionOutput(entry);
         } catch (error) {
-          this.reportExecutionOutputError(error);
+          this.reportListenerError(error);
         }
       },
     );
@@ -540,7 +589,7 @@ export class OndaAudioProcessor {
           entries: batchRecords.map((record) => record.entry),
           ...meta,
         };
-        this.notifyExecutionOutputListeners(this.printListeners, batch);
+        this.notifyListeners(this.printListeners, batch);
       } else {
         const meta = delegate ?? { overflowCount: 0, transportDropCount: 0 };
         delegate = null;
@@ -550,7 +599,7 @@ export class OndaAudioProcessor {
           occurrences: batchRecords.map((record) => record.occurrence),
           ...meta,
         };
-        this.notifyExecutionOutputListeners(this.delegateListeners, batch);
+        this.notifyListeners(this.delegateListeners, batch);
       }
       cursor = end;
     }
@@ -562,7 +611,7 @@ export class OndaAudioProcessor {
         entries: [],
         ...print,
       };
-      this.notifyExecutionOutputListeners(this.printListeners, batch);
+      this.notifyListeners(this.printListeners, batch);
     }
     if (
       delegate
@@ -574,7 +623,7 @@ export class OndaAudioProcessor {
         occurrences: [],
         ...delegate,
       };
-      this.notifyExecutionOutputListeners(this.delegateListeners, batch);
+      this.notifyListeners(this.delegateListeners, batch);
     }
   }
 
@@ -609,6 +658,29 @@ export class OndaAudioProcessor {
     }
   }
 
+  setParamElement(param, element, value) {
+    try {
+      if (!Array.isArray(this.paramInfo)) {
+        throw new Error(
+          "setParamElement requires processor metadata; construct the adapter with createOndaAudioProcessor()",
+        );
+      }
+      const info = paramElementInfoFor(
+        this.paramInfo,
+        param,
+        element,
+        this.paramElements,
+      );
+      return this.request("set-param", {
+        param,
+        element,
+        value: constrainParamValue(info, value, this.paramControls, this.paramElements),
+      });
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  }
+
   setParamNormalized(param, value) {
     try {
       if (!Array.isArray(this.paramInfo)) {
@@ -630,11 +702,51 @@ export class OndaAudioProcessor {
     }
   }
 
+  setParamElementNormalized(param, element, value) {
+    try {
+      if (!Array.isArray(this.paramInfo)) {
+        throw new Error(
+          "setParamElementNormalized requires processor metadata; construct the adapter with createOndaAudioProcessor()",
+        );
+      }
+      const info = paramElementInfoFor(
+        this.paramInfo,
+        param,
+        element,
+        this.paramElements,
+      );
+      const control = preparedParamControl(info, this.paramControls);
+      if (!control) {
+        throw new Error(`Onda parameter '${info.name}' has no scalar host-control domain`);
+      }
+      return this.request("set-param", {
+        param,
+        element,
+        value: control.normalizedToPlain(value),
+      });
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  }
+
   trigger(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 (Number.isInteger(event)) {
+        if (!Array.isArray(events)) {
+          throw new Error(
+            "event triggers require processor metadata; construct the adapter with createOndaAudioProcessor()",
+          );
+        }
+        if (event >= events.length) {
+          const payload = new Uint8Array();
+          return this.request("event", { event, payload }, [payload.buffer]);
+        }
+      }
+      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); }
@@ -643,6 +755,15 @@ export class OndaAudioProcessor {
     } catch (error) { return Promise.reject(error); }
   }
 
+  onExecutionError(listener) {
+    this.assertOpen();
+    if (typeof listener !== "function") {
+      throw new TypeError("execution-error listener must be a function");
+    }
+    this.executionErrorListeners.add(listener);
+    return () => this.executionErrorListeners.delete(listener);
+  }
+
   onDelegates(listener) {
     this.assertOpen();
     if (typeof listener !== "function") {
@@ -775,6 +896,7 @@ export class OndaAudioProcessor {
     this.stopExecutionOutputDrain();
     for (const pending of this.pending.values()) pending.reject(this.closeReason);
     this.pending.clear();
+    this.executionErrorListeners.clear();
     this.delegateListeners.clear();
     this.printListeners.clear();
   }

package/src/param-metadata.js

@@ -16,3 +16,18 @@ export function paramAddress(params, selector) {
   }
   throw new Error(`unknown Onda parameter '${String(selector)}'`);
 }
+
+export function paramElementAddress(params, selector, element) {
+  const address = paramAddress(params, selector);
+  if (address.element !== null) {
+    throw new Error("an explicit element write requires a parameter name or index");
+  }
+  if (
+    !Number.isSafeInteger(element)
+    || element < 0
+    || element >= address.info.array_len
+  ) {
+    throw new Error(`Onda parameter '${address.info.name}' element index is out of bounds`);
+  }
+  return { info: address.info, element };
+}

package/src/processor-constants.js

@@ -0,0 +1,10 @@
+// Keep the AudioWorklet dependency graph relative-only so the published module can be loaded
+// directly. The adapter tests verify these processor ABI values against @onda-lang/processor-abi.
+export const PROCESSOR_EXECUTION_OK = 0;
+export const PROCESSOR_EXECUTION_RUNTIME_SAFETY_FAILURE = 1;
+export const PROCESSOR_EXECUTION_INPUT_REJECTED = 2;
+export const PROCESSOR_BEGIN_BLOCK = 1 << 0;
+export const PROCESSOR_END_BLOCK = 1 << 1;
+export const PROCESSOR_FULL_BLOCK = PROCESSOR_BEGIN_BLOCK | PROCESSOR_END_BLOCK;
+export const PROCESSOR_INIT_PRESERVE_PINNED = 0;
+export const PROCESSOR_INIT_FULL = 1;

package/src/worklet.js

@@ -1,4 +1,4 @@
-import { paramAddress } from "./param-metadata.js";
+import { paramAddress, paramElementAddress } from "./param-metadata.js";
 import {
   EXECUTION_OPERATION_EVENT,
   EXECUTION_OPERATION_INIT,
@@ -7,16 +7,25 @@ import {
   openExecutionOutputRing,
   writeExecutionOutputRing,
 } from "./execution-output-ring.js";
-
-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;
+import {
+  PROCESSOR_BEGIN_BLOCK,
+  PROCESSOR_END_BLOCK,
+  PROCESSOR_EXECUTION_OK,
+  PROCESSOR_EXECUTION_INPUT_REJECTED,
+  PROCESSOR_INIT_FULL,
+  PROCESSOR_INIT_PRESERVE_PINNED,
+} from "./processor-constants.js";
 const ONDA_AUDIO_WORKLET_PROCESSOR_NAME = "onda-wasm-processor";
 const DEFAULT_EVENT_PAYLOAD_CAPACITY_BYTES = 64 * 1024;
 const DEFAULT_DELEGATE_CAPACITY_BYTES = 64 * 1024;
 const DEFAULT_PRINT_CAPACITY_BYTES = 64 * 1024;
+
+class ProcessorExecutionError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+}
 const DELEGATE_BATCH_SIZE_BYTES = 20;
 const PRINT_BATCH_SIZE_BYTES = 20;
 const EXECUTION_OUTPUT_SIZE_BYTES = 12;
@@ -289,7 +298,7 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     this.refreshMemoryCache(true);
     this.invalidateState();
     if (processorOptions.initialize === true) {
-      this.init(ONDA_INIT_FULL);
+      this.init(PROCESSOR_INIT_FULL);
     }
     this.allocationLocked = true;
     this.port.onmessage = (event) => this.handleMessage(event.data ?? {});
@@ -485,8 +494,10 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     }
   }
 
-  setParam(selector, value) {
-    const { info: param, element } = paramAddress(this.paramInfo, selector);
+  setParam(selector, value, explicitElement = null) {
+    const { info: param, element } = explicitElement === null
+      ? paramAddress(this.paramInfo, selector)
+      : paramElementAddress(this.paramInfo, selector, explicitElement);
     if (value === undefined) {
       throw new Error(`Onda parameter '${param.name}' requires a value`);
     }
@@ -517,10 +528,10 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
   }
 
   init(mode) {
-    if (mode !== ONDA_INIT_PRESERVE_PINNED && mode !== ONDA_INIT_FULL) {
+    if (mode !== PROCESSOR_INIT_PRESERVE_PINNED && mode !== PROCESSOR_INIT_FULL) {
       throw new Error(`invalid Onda init mode '${String(mode)}'`);
     }
-    if (mode === ONDA_INIT_PRESERVE_PINNED && !this.initialized) {
+    if (mode === PROCESSOR_INIT_PRESERVE_PINNED && !this.initialized) {
       throw new Error("full initialization is required before preserving pinned state");
     }
     this.runInitialization(mode);
@@ -538,7 +549,7 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     this.blockCursor = blockCursor;
   }
 
-  runInitialization(mode, afterInitialize) {
+  runInitialization(mode, afterInitialize, collectOutput = true) {
     // Reinitializing state does not create a compile-block boundary. Retain
     // the host-side position so the next process segment cannot synthesize an
     // extra BEGIN_BLOCK or postpone the matching END_BLOCK.
@@ -548,7 +559,7 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     // leaves the processor on the silent pending path.
     this.invalidateState();
     this.refreshMemoryCache();
-    this.prepareExecutionOutput();
+    if (collectOutput) this.prepareExecutionOutput();
     const status = this.exports.onda_processor_init(
       this.paramsPtr,
       this.statePtr,
@@ -557,13 +568,15 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
       this.bufferFramesPtr,
       this.bufferChannelsPtr,
       this.bufferSampleRatesPtr,
-      this.executionOutputPtr,
+      collectOutput ? this.executionOutputPtr : 0,
     );
     // Generated failures retain diagnostic prints but clear delegates.
-    this.publishExecutionOutput(
-      EXECUTION_OPERATION_INIT,
-      0,
-    );
+    if (collectOutput) {
+      this.publishExecutionOutput(
+        EXECUTION_OPERATION_INIT,
+        0,
+      );
+    }
     this.checkExecutionStatus(status, "processor init");
     afterInitialize?.();
     this.commitInitializedState(blockCursor);
@@ -576,9 +589,12 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
   }
 
   checkExecutionStatus(status, operation) {
-    if (status === 0) return;
+    if (status === PROCESSOR_EXECUTION_OK) return;
     this.invalidateState();
-    throw new Error(`${operation} failed with Onda execution status ${String(status)}`);
+    throw new ProcessorExecutionError(
+      `${operation} failed with Onda execution status ${String(status)}`,
+      status,
+    );
   }
 
   createSnapshot() {
@@ -609,7 +625,7 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
     // The ABI restore base is a fresh post-init image, so scratch and
     // control-mirror state never leak across a restore. Initialization and
     // overlay form one lifecycle transition: neither partial result is ready.
-    this.runInitialization(ONDA_INIT_FULL, () => {
+    this.runInitialization(PROCESSOR_INIT_FULL, () => {
       const state = this.stateBytes;
       for (const entry of this.snapshotInfo) {
         const packedOffset = Number(entry.packed_snapshot_byte_offset);
@@ -622,7 +638,7 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
         );
         this.normalizeSnapshotIntegerRange(entry, state, physicalOffset, byteSize);
       }
-    });
+    }, false);
   }
 
   normalizeSnapshotIntegerRange(entry, state, offset, byteSize) {
@@ -710,6 +726,7 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
         this.setParam(
           message.param ?? message.name ?? message.index,
           message.value,
+          message.element ?? null,
         );
         this.postResponse(message, { type: "onda-ok", operation: message.type });
       } else if (message.type === "init") {
@@ -751,17 +768,20 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
         throw new Error(`unknown Onda worklet operation '${String(message.type)}'`);
       }
     } catch (error) {
-      this.port.postMessage({
+      const response = {
         type: "onda-error",
         operation: message.type ?? "unknown",
         requestId: message.requestId,
         error: String(error && error.message ? error.message : error),
-      });
+      };
+      if (Number.isInteger(error?.status)) response.status = error.status;
+      this.port.postMessage(response);
     }
   }
 
   dispatchEvent(selector, payload) {
     this.requireInitialized("event dispatch");
+    if (Number.isInteger(selector) && selector >= this.eventInfo.length) return;
     const eventId = Number.isInteger(selector)
       ? selector
       : this.eventInfo.findIndex((event) => event.name === selector);
@@ -794,7 +814,12 @@ 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`);
+    if (status === PROCESSOR_EXECUTION_INPUT_REJECTED) {
+      throw new ProcessorExecutionError(
+        `event '${event.name}' input rejected: invalid payload or insufficient workspace`,
+        status,
+      );
+    }
     this.publishExecutionOutput(
       EXECUTION_OPERATION_EVENT,
       eventId,
@@ -1559,8 +1584,8 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
         this.blockSize - startFrame,
       );
       const endsBlock = startFrame + segmentFrames === this.blockSize;
-      const flags = (startFrame === 0 ? ONDA_PROCESS_BEGIN_BLOCK : 0)
-        | (endsBlock ? ONDA_PROCESS_END_BLOCK : 0);
+      const flags = (startFrame === 0 ? PROCESSOR_BEGIN_BLOCK : 0)
+        | (endsBlock ? PROCESSOR_END_BLOCK : 0);
 
       this.marshalInputSegment(
         inputs,
@@ -1578,12 +1603,13 @@ class OndaWasmProcessor extends AudioWorkletProcessor {
         EXECUTION_OPERATION_PROCESS,
         0,
       );
-      if (status !== 0) {
+      if (status !== PROCESSOR_EXECUTION_OK) {
         this.invalidateState();
         this.clearOutputs(outputs);
         this.port.postMessage({
           type: "onda-error",
           operation: "process",
+          status,
           error: `processor process failed with Onda execution status ${String(status)}`,
         });
         return true;