@onda-lang/webaudio 0.8.2 → 0.8.3

package/README.md

@@ -75,10 +75,12 @@ 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.

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`
@@ -271,6 +275,7 @@ PROCESSOR_INIT_PRESERVE_PINNED
 PROCESSOR_SNAPSHOT_FORMAT_VERSION
 constrainParamPlain
 createParamControl
+paramElementMetadata
 createParamDomain
 createProcessorArtifactFiles
 decodeDelegateRecords

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onda-lang/webaudio",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "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.3"
   },
   "publishConfig": {
     "access": "public"

package/src/index.js

@@ -1,5 +1,7 @@
+import { paramAddress } from "./param-metadata.js";
 import {
   createParamControl,
+  paramElementMetadata,
   decodeDelegateRecords,
   formatPrintRecords,
   validateProcessorArtifact,
@@ -152,18 +154,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 +181,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;
 }
 
@@ -291,6 +307,7 @@ export class OndaAudioProcessor {
     this.metadata = metadata;
     this.paramInfo = metadata?.metadata?.params ?? null;
     this.paramControls = new WeakMap();
+    this.paramElements = new WeakMap();
     this.nextRequestId = 1;
     this.pending = new Map();
     this.delegateListeners = new Set();
@@ -580,10 +597,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 +614,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`);

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,
@@ -477,13 +478,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 +497,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,