@m4l-jweb/bridge 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/bridge",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "m4l-jweb: the browser-side bridge connecting a device's web UI to Max for Live.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -124,6 +124,11 @@ export function simulate(name: string, ...args: unknown[]): void {
  * binding, and treat the reply as the source of truth.
  */
 export function uiReady(): void {
+  // Every ui_ready reply is a ONE-SHOT: the wrapper sends it once and never
+  // repeats it. A selector bound after this line therefore misses its only
+  // message. device_folder is bound here rather than by the component that wants
+  // it, so no page can lose it by subscribing in a later effect.
+  bindDeviceFolder();
   outlet("ui_ready");
 }
 
@@ -230,6 +235,66 @@ export const STATE_OUT = {
   sync_state: "sync_state",
 } as const;
 
+/**
+ * Selectors the WRAPPER sends to a device that declares `defineFiles()`.
+ *
+ * Wrapper-owned, like DEVICE_IN - no chain is involved, so it needs
+ * `unmatchedTo: "js"` like every other bare wrapper selector. `onDeviceFolder()`
+ * below binds it, and the app never types the name.
+ */
+export const FILES_IN = {
+  /** wrapper -> UI: `device_folder <path>` - the absolute folder this device's files land in. */
+  device_folder: "device_folder",
+} as const;
+
+/**
+ * What the wrapper says about the TRACK this device is on.
+ *
+ * A device cannot see its own container from the page, and several things depend on it:
+ * an audio clip can only be created on an audio track, a MIDI clip only on a MIDI one,
+ * and a device shipped in both flavours (one manifest entry per container) otherwise has
+ * to be told which it is at build time - two builds that differ in a fact Live already
+ * knows. Sent once at ui_ready, like `device_folder`.
+ */
+export const TRACK_IN = {
+  /** wrapper -> UI: `track_kind <audio|midi|none>`. `none` means no reachable track. */
+  track_kind: "track_kind",
+} as const;
+
+/** Which container this device is in, as Live reports it. */
+export type TrackKind = "audio" | "midi" | "none";
+
+const trackKindHandlers = new Set<(kind: TrackKind) => void>();
+let trackKindBound = false;
+/** The last kind reported, for a subscriber that mounts after ui_ready. */
+let knownTrackKind: TrackKind | null = null;
+
+/**
+ * What kind of track is this device on?
+ *
+ * `audio` takes audio clips, `midi` takes MIDI clips, and `none` means the device is not
+ * on a reachable track at all (inside something odd, or mid-load). A late subscriber gets
+ * the answer immediately - ui_ready fires once, and a component mounting after it would
+ * otherwise wait forever for a message already sent.
+ *
+ * @returns An unsubscribe, so it drops straight into `useEffect`.
+ */
+export function onTrackKind(fn: (kind: TrackKind) => void): () => void {
+  trackKindHandlers.add(fn);
+  if (!trackKindBound) {
+    trackKindBound = true;
+    // One binding, many subscribers: `bindInlet` keeps a single handler per selector.
+    bindInlet(TRACK_IN.track_kind, (kind) => {
+      knownTrackKind = String(kind) as TrackKind;
+      for (const h of trackKindHandlers) h(knownTrackKind);
+    });
+  }
+  if (knownTrackKind !== null) fn(knownTrackKind);
+  return () => {
+    trackKindHandlers.delete(fn);
+  };
+}
+
 /** Selectors the WRAPPER answers about this device's own Live parameters. */
 export const PARAM_OUT = {
   /** UI -> wrapper: `get_param_id <id>` - what is this parameter's LOM id? Reply on `param_id`. */
@@ -329,6 +394,8 @@ export const CLIP_OUT = {
   read_selected_clip: "read_selected_clip",
   /** UI -> wrapper: `write_clip <lengthBeats> <n> <pitch start duration velocity> ...` - fill the first empty slot. */
   write_clip: "write_clip",
+  /** UI -> wrapper: `create_audio_clip <requestId> <base64 spec>` - a WAV on disk into a clip slot. */
+  create_audio_clip: "create_audio_clip",
 } as const;
 
 /** ...and the reply from a read. */
@@ -337,6 +404,10 @@ export const CLIP_IN = {
   notes: "notes",
   /** wrapper -> UI: there was no clip on this track to read. */
   read_error: "read_error",
+  /** wrapper -> UI: `clip_created <requestId>` - the audio clip is in the slot. */
+  clip_created: "clip_created",
+  /** wrapper -> UI: `clip_error <requestId> <reason> <msg...>` - it is not, and why. */
+  clip_error: "clip_error",
 } as const;
 
 /** A note handed to the `midiout` chain. Max does the placing; you do the timing. */
@@ -506,7 +577,8 @@ let saveBound = false;
  * over base64 in slices and the wrapper writes them to a `.part` file, then atomically
  * places it at `destPath` via [maxurl] (the same move fetchToFile phase 2 uses). The
  * bytes travel base64 because Max splits messages on spaces/commas and base64 has
- * neither. Requires the `download` chain in the device manifest.
+ * neither. Requires `defineFiles({ saves: true })` in the device's `files.ts`, which
+ * is what puts [maxurl] in the patcher for the place.
  *
  * @param destPath Absolute path (or device-relative, resolved wrapper-side) to write.
  * @param bytes The payload. A per-cycle WAV is ~350 KB => ~60 messages.
@@ -543,6 +615,45 @@ export function saveToFile(destPath: string, bytes: ArrayBuffer): Promise<{ byte
   });
 }
 
+const folderHandlers = new Set<(folder: string) => void>();
+let folderBound = false;
+/** The last folder the wrapper reported, for a subscriber that arrives after it. */
+let knownFolder: string | null = null;
+
+/**
+ * Where this device's files land, as an absolute path.
+ *
+ * The wrapper sends it once at ui_ready for a device that declares `defineFiles()`.
+ * It is the only way a page learns its own device's folder - and the only answer to
+ * "where did my export go", because Max cannot open a file manager (`launchbrowser`
+ * on a `file://` path reaches the shell and does nothing; see doc/MAX-FACTS.md). Pair
+ * it with `copyPath()` and the user can paste the folder into Explorer or Finder.
+ *
+ * A late subscriber gets the folder immediately: ui_ready fires once, and a component
+ * that mounts after it would otherwise wait forever for a message already sent.
+ *
+ * @returns An unsubscribe, so it drops straight into `useEffect`.
+ */
+function bindDeviceFolder(): void {
+  if (folderBound) return;
+  folderBound = true;
+  // One binding, many subscribers - `bindInlet` keeps a single handler per
+  // selector, so a second bind on this name would silently replace the first.
+  bindInlet(FILES_IN.device_folder, (path) => {
+    knownFolder = String(path);
+    for (const h of folderHandlers) h(knownFolder);
+  });
+}
+
+export function onDeviceFolder(fn: (folder: string) => void): () => void {
+  folderHandlers.add(fn);
+  bindDeviceFolder();
+  if (knownFolder !== null) fn(knownFolder);
+  return () => {
+    folderHandlers.delete(fn);
+  };
+}
+
 
 
 /* ------------------------------------------------------------------ *
@@ -733,6 +844,129 @@ export function writeClip(lengthBeats: number, notes: readonly ClipNote[]): void
   outlet(CLIP_OUT.write_clip, ...flat);
 }
 
+/* ------------------------------------------------------------------ *
+ * A rendered file INTO a Live clip
+ *
+ * The other half of `saveToFile()`. A device that bounces its pattern writes a WAV and
+ * then has no way to hand it over: a page cannot give Live a file (Chromium strips the
+ * drag payload), Max cannot open a file manager, so the whole handoff was a path on the
+ * clipboard and five manual steps in Explorer.
+ *
+ * `ClipSlot.create_audio_clip` is ordinary LOM, so `[js]` can call it - which the drawer
+ * said for months was impossible. It is Live 12.0.5 or newer (documented earlier, and
+ * non-functional before that), so the wrapper reads Live's version and refuses rather
+ * than trusting the docs, and answers `clip_error <id> needs_live_1205` where a device
+ * should keep offering the clipboard instead.
+ *
+ * NO CHAIN AND NO BOXES. This is pure LiveAPI, like `defineWatch()` - nothing is derived
+ * into the patcher graph. It does need `unmatchedTo: "js"`, like every other bare
+ * wrapper selector.
+ * ------------------------------------------------------------------ */
+
+/** Where a created clip lands. */
+export type AudioClipTarget =
+  /** Live's highlighted clip slot - which, in a device's own view, is always a slot on
+   *  the device's OWN track: a device's UI is only visible while its track is selected,
+   *  so there is no reachable moment at which the highlighted slot is somebody else's. */
+  | { target: "selected" }
+  /** A slot named by index. `track` is the index in `live_set tracks`, `slot` the scene. */
+  | { target: "track"; track: number; slot: number }
+  /** A brand-new audio track (`create_audio_track(-1)`), first slot. The one target that
+   *  cannot fail on a MIDI track, and therefore the honest escape for an instrument. */
+  | { target: "new" };
+
+/** What to make of the clip once it exists - the things a render already knows. */
+export interface AudioClipSetup {
+  /** The clip's name. What the user wrote, not `export-1785343077706.wav`. */
+  name?: string;
+  /** Warping on, so the clip follows Live's tempo. */
+  warp?: boolean;
+  /** Live's warp mode index (0 Beats, 1 Tones, 2 Texture, 3 Re-Pitch, 4 Complex...). */
+  warpMode?: number;
+  /**
+   * The loop end in BEATS - `cycles * beatsPerCycle` for a pattern render.
+   *
+   * The reason to send it: a device that rendered N whole cycles at a known cps knows the
+   * loop length exactly, and Live otherwise guesses it from transient analysis. The
+   * difference is a bounce that plays in time and one that needs hand-warping.
+   */
+  loopEnd?: number;
+}
+
+/** Why a clip was not created. Branch on it - `not_audio_track` is the one a device can offer a way out of. */
+export type AudioClipFailure =
+  /** Live is older than 12.0.5, where the call exists but does nothing. */
+  | "needs_live_1205"
+  /** The target is a MIDI track (or a return, or the master). */
+  | "not_audio_track"
+  /** The target track is frozen, or armed and recording. */
+  | "track_busy"
+  /** No slot resolved: nothing highlighted, or the index does not exist. */
+  | "no_slot"
+  /** The file is not on disk at the path given. */
+  | "no_file"
+  /** The call ran and the slot still holds no clip. */
+  | "failed";
+
+/** The rejection `createAudioClip()` throws, with the reason machine-readable. */
+export class AudioClipError extends Error {
+  readonly reason: AudioClipFailure;
+  constructor(reason: AudioClipFailure, message: string) {
+    super(message);
+    this.name = "AudioClipError";
+    this.reason = reason;
+  }
+}
+
+const clipCreateResolvers = new Map<string, { resolve: () => void; reject: (e: Error) => void }>();
+let clipCreateBound = false;
+
+/**
+ * Put a file that is already on disk into a Live clip slot.
+ *
+ * @param path Absolute, or relative to the device folder (resolved wrapper-side, the same
+ *   resolution `saveToFile()` uses - so pass back exactly the name you saved).
+ * @param where Which slot. See AudioClipTarget.
+ * @param setup Name, warping and loop points, applied after the clip exists.
+ *
+ * THE PAYLOAD IS BASE64, and that is not ceremony. Max parses a message into atoms on
+ * whitespace, and both of the strings here have spaces in them in practice: a real
+ * install's path contains "Ableton Library", and a clip name is whatever the user typed.
+ * Two variadic fields cannot be rejoined from one flat message - there is no way to tell
+ * where the first ends - so the whole spec travels as one JSON blob in one atom, which is
+ * what `encodeBase64` exists for. (m4l-jweb's TODO sketched `create_audio_clip <id>
+ * <path> <target...>`; that shape splits at the first space and loses the target.)
+ *
+ * A CLIP IS NOT ATOMIC. When the call succeeds but a `setup` field does not take, the
+ * clip still exists and this still resolves - the wrapper posts what failed. Refusing a
+ * bounce that landed because its name did not is the wrong trade.
+ */
+export function createAudioClip(path: string, where: AudioClipTarget = { target: "selected" }, setup: AudioClipSetup = {}): Promise<void> {
+  if (!clipCreateBound) {
+    clipCreateBound = true;
+    bindInlet(CLIP_IN.clip_created, (id) => {
+      const p = clipCreateResolvers.get(String(id));
+      if (!p) return;
+      clipCreateResolvers.delete(String(id));
+      p.resolve();
+    });
+    bindInlet(CLIP_IN.clip_error, (id, reason, ...rest) => {
+      const p = clipCreateResolvers.get(String(id));
+      if (!p) return;
+      clipCreateResolvers.delete(String(id));
+      // The message is human text and splits on its spaces; the REASON is one word and
+      // does not, which is why it is a separate atom rather than parsed out of the text.
+      p.reject(new AudioClipError(String(reason) as AudioClipFailure, rest.join(" ") || String(reason)));
+    });
+  }
+
+  return new Promise((resolve, reject) => {
+    const requestId = Math.random().toString(36).substring(2, 10);
+    clipCreateResolvers.set(requestId, { resolve, reject });
+    outlet(CLIP_OUT.create_audio_clip, requestId, encodeBase64(JSON.stringify({ path, ...where, ...setup })));
+  });
+}
+
 /**
  * Max splits messages on commas and semicolons, so any structured payload -
  * JSON, code, a filesystem path - must be encoded before it crosses the bridge.