@m4l-jweb/wrapper 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/wrapper",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "m4l-jweb: the Max for Live glue layer connecting a device to LiveAPI.",
   "type": "module",
   "license": "MIT",

package/src/max.d.ts

@@ -39,6 +39,34 @@ declare class Task {
   cancel(): void;
 }
 
+/**
+ * A named Max dictionary, addressed from [js].
+ *
+ * The reason this exists here at all is [maxurl]: downloading to a FILE is not
+ * expressible as a flat Max message. Per the reference, the file form is a
+ * `dictionary <name>` message carrying a dict with a `filename_out` key - so
+ * something has to build that dict, and [js] is the only thing in the patcher
+ * that can.
+ *
+ * VERIFIED in Live (doc/SPIKES.md spike 1.3): [js] built a maxurl request dict
+ * and read the response dict back. `constructor`, `set`, `clear` and `stringify`
+ * all behave as declared. `get`, `parse` and `freepeer` were not exercised.
+ */
+declare class Dict {
+  constructor(name?: string);
+  name: string;
+  set(key: string, value: unknown): void;
+  /** UNVERIFIED - the spike only ever wrote, and read back via stringify(). */
+  get(key: string): unknown;
+  /** The whole dict as JSON - the cheapest way to see what maxurl replied. */
+  stringify(): string;
+  /** UNVERIFIED. */
+  parse(json: string): void;
+  clear(): void;
+  /** Release the dict's reference. Max dictionaries are refcounted. UNVERIFIED. */
+  freepeer(): void;
+}
+
 /** Max's file object. Note: `writebytes` truncates silently past ~16 KB. */
 declare class File {
   constructor(path: string, mode?: "read" | "write" | "readwrite");
@@ -63,8 +91,18 @@ declare class File {
  * ASYNCHRONOUS: framecount() right after it still reads the old size. Come back
  * on a Task.
  *
- * UNVERIFIED. This declaration is what doc/SPIKES.md spike 1.2 exists to
- * confirm. Do not build on it until that spike is recorded as PASS.
+ * VERIFIED in Live (doc/SPIKES.md spike 1.2): an empty buffer~ went to 124439
+ * frames, 1 channel, midsample -0.0319 after `send("replace", "jongly.aif")`.
+ * `send`, `framecount`, `channelcount` and `peek` are all real and behave as
+ * declared. `poke` is the one member here still taken on faith from the docs.
+ *
+ * `replace` on a file buffer~ cannot decode is a SILENT NO-OP: no error, and the
+ * buffer keeps whatever it held before. So a frame count on its own never means
+ * "the read worked" - it only means something next to what the count was before.
+ *
+ * `replace` also adopts the FILE's channel count, whatever the buffer~ was
+ * declared with (a stereo .wav gave channelcount() === 2 from a buffer~ created
+ * with no arguments). Never assume mono. Ask.
  */
 declare class Buffer {
   constructor(name: string);
@@ -74,6 +112,7 @@ declare class Buffer {
   channelcount(): number;
   /** peek(channel, frameIndex, count) - channels and frames are 1-indexed. */
   peek(channel: number, index: number, count?: number): number;
+  /** UNVERIFIED - spike 1.2 exercised everything above this, but not poke. */
   poke(channel: number, index: number, value: number): void;
 }