@m4l-jweb/wrapper 0.1.0

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@m4l-jweb/wrapper",
+  "version": "0.1.0",
+  "description": "m4l-jweb: the Max for Live glue layer connecting a device to LiveAPI.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alienmind/m4l-jweb.git",
+    "directory": "packages/wrapper"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./sources": "./sources.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "sources.mjs"
+  ]
+}

package/sources.mjs

@@ -0,0 +1,27 @@
+/**
+ * The wrapper is not a library you import - Max's [js] has no module system.
+ * It is a set of TypeScript sources the build COMPILES TOGETHER and
+ * CONCATENATES, in this order, into one ES5 script.
+ *
+ * Because they all compile as global scripts in a single TS program, they see
+ * each other's functions (core's bang() calls liveapi's startTickPoll()), and
+ * TypeScript still typechecks across the seam.
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const src = (f) => path.join(here, "src", f);
+
+/** Ambient types for post/outlet/LiveAPI/Task/File. Typechecked, never emitted. */
+export const types = src("max.d.ts");
+
+/**
+ * Ordered. core must come first: it owns the lifecycle that the rest hooks
+ * into. A device's own `wrapper/device.ts`, if present, is appended after these
+ * by the build, so it can define extra message handlers.
+ */
+export const sources = [
+	src("core.ts"), // build stamp, lifecycle, the anything() guard, payload extraction
+	src("liveapi.ts"), // transport poll, tempo observer, clip I/O
+];

package/src/core.ts

@@ -0,0 +1,267 @@
+/**
+ * core.ts - lifecycle, the message guard, and the self-extracting UI payload.
+ *
+ * This runs inside Max's [js]: an ES5-era interpreter with no modules, no
+ * `console` (use `post`), and no `setTimeout` (use `Task`). It is compiled with
+ * `target: "ES5"` and the build then re-parses the output with acorn at
+ * `ecmaVersion: 5`, refusing to package on failure. One stray modern token
+ * kills the whole script at load, with a one-line error and no stack.
+ *
+ * Outlets:
+ *   0 - to [jweb]  ("url ...", "mode ...", "tick ...", "tempo ...", "build ...")
+ *   1 - spare/aux  (a second consumer: another engine, a print, ...)
+ */
+
+autowatch = 1;
+inlets = 1;
+outlets = 2;
+
+/**
+ * Set from the object box: `js wrapper.js <mode>` (see patcher/devices.mjs).
+ * Note jsarguments[0] is the SCRIPT NAME, not the first argument - the device
+ * mode is at index 1. Reading index 0 gets you the string "wrapper.js" and a
+ * mode comparison that is silently false forever.
+ */
+var MODE: string = jsarguments.length > 1 ? String(jsarguments[1]) : "midi";
+
+post("m4l-jweb: wrapper loaded (build " + buildStamp() + ", mode " + MODE + ")\n");
+
+/** The build this device instance actually is. Injected by the build. */
+function buildStamp(): string {
+	return typeof BUILD_STAMP !== "undefined" ? BUILD_STAMP : "dev";
+}
+
+/* ------------------------------------------------------------------ *
+ * Lifecycle
+ *
+ * LiveAPI objects created in a patcher-loading context (loadbang) are DEAD:
+ * they construct without error and then observe nothing, forever. Create every
+ * observer from live.thisdevice's bang, which fires once the device is fully in
+ * the Live set. Guard code like `if (obs) return` turns this bug permanent -
+ * recreate unconditionally.
+ *
+ * loadbang does file work only.
+ * ------------------------------------------------------------------ */
+
+/** live.thisdevice -> the device is fully loaded. Everything LiveAPI starts here. */
+function bang(): void {
+	post("m4l-jweb: bang (device ready)\n");
+	extractExtraPayloads();
+	loadWebview();
+	setupTempoObserver(); // liveapi.ts
+	startTickPoll(); // liveapi.ts
+	// A device's own wrapper/device.ts hooks in here: this is the ONLY safe place
+	// to create LiveAPI objects (see the loadbang trap above).
+	if (typeof onDeviceReady === "function") onDeviceReady();
+}
+
+/** Patcher loaded. File work is safe here; LiveAPI is NOT. */
+function loadbang(): void {
+	post("m4l-jweb: loadbang\n");
+	extractExtraPayloads();
+	loadWebview();
+}
+
+/** Manual re-init, handy while developing. */
+function reload(): void {
+	loadWebview();
+	setupTempoObserver();
+	startTickPoll();
+}
+
+/**
+ * The [jweb] outlet can fan out to this [js] AND to other consumers, so
+ * messages meant for someone else land here too. Swallow them instead of
+ * logging "js: no function <name>" on every one.
+ */
+function anything(): void {}
+
+/**
+ * The UI announces it finished loading. The page loads asynchronously, so never
+ * assume it was listening when state last changed - resend all of it.
+ */
+function ui_ready(): void {
+	outlet(0, "mode", MODE);
+	// The UI shows this next to its own baked-in version: a mismatch means a
+	// mixed install (stale .amxd instance vs newer extracted UI, or vice versa).
+	outlet(0, "build", buildStamp());
+	sendCurrentTempo(); // liveapi.ts
+	// The device resends its own state here. The page loads asynchronously, so
+	// anything sent before it was listening is simply gone.
+	if (typeof onUiReady === "function") onUiReady();
+}
+
+/* ------------------------------------------------------------------ *
+ * The self-extracting UI payload
+ *
+ * Chromium (jweb) cannot read Max's frozen virtual filesystem, so a frozen
+ * dependency is invisible to it - you cannot ship a UI inside your own device
+ * and then open it. But THIS script always runs. So the build appends the UI
+ * html to it as base64 (UI_PAYLOAD_B64 / _BYTES / _NAME), and we write it to a
+ * real file next to the .amxd on first load and point jweb at that file:// URL.
+ * ------------------------------------------------------------------ */
+
+function loadWebview(): void {
+	try {
+		var url = resolveUiUrl();
+		if (!url) return;
+		outlet(0, "url", url);
+		post("m4l-jweb: sent url " + url + "\n");
+	} catch (e) {
+		post("m4l-jweb: loadWebview error " + (e as Error).message + "\n");
+	}
+}
+
+function resolveUiUrl(): string | null {
+	var folder = deviceFolder();
+	if (!folder) {
+		post("m4l-jweb: patcher not saved yet - UI path unknown\n");
+		return null;
+	}
+	var name = typeof UI_PAYLOAD_NAME !== "undefined" ? UI_PAYLOAD_NAME : "ui.html";
+	var target = folder + "/" + name;
+
+	if (typeof UI_PAYLOAD_B64 !== "undefined" && typeof UI_PAYLOAD_BYTES !== "undefined") {
+		extractPayload(target, UI_PAYLOAD_B64, UI_PAYLOAD_BYTES);
+	} else {
+		post("m4l-jweb: no embedded payload (dev build) - using " + target + "\n");
+	}
+	// Cache-buster: the URL changes per build, so Chromium can never serve a page
+	// it cached from a previous build of the same file path.
+	return encodeURI("file:///" + target) + "?v=" + encodeURIComponent(buildStamp());
+}
+
+/** The folder the .amxd lives in, derived from the patcher's own path. */
+function deviceFolder(): string | null {
+	var fp: string = this.patcher.filepath;
+	return fp && fp.length ? fp.replace(/\/[^\/]*$/, "") : null;
+}
+
+/**
+ * Write every non-UI payload the build embedded (manifest `payloads`) next to
+ * the .amxd. Same reason as the UI: anything that is not a Max-native object is
+ * blind to the frozen virtual filesystem, so it needs a real file.
+ *
+ * Idempotent, and cheap after the first load: extractPayload() skips a file whose
+ * size and build stamp already match.
+ */
+function extractExtraPayloads(): void {
+	// The build emits all three together or none at all; bind them locally so the
+	// compiler can see that too.
+	if (typeof EXTRA_PAYLOAD_NAMES === "undefined" || typeof EXTRA_PAYLOAD_B64 === "undefined" || typeof EXTRA_PAYLOAD_BYTES === "undefined") {
+		return;
+	}
+	var names = EXTRA_PAYLOAD_NAMES;
+	var blobs = EXTRA_PAYLOAD_B64;
+	var sizes = EXTRA_PAYLOAD_BYTES;
+
+	var folder = deviceFolder();
+	if (!folder) {
+		post("m4l-jweb: patcher path unknown - cannot extract payloads\n");
+		return;
+	}
+	for (var i = 0; i < names.length; i++) {
+		extractPayload(folder + "/" + names[i], blobs[i], sizes[i]);
+	}
+}
+
+/**
+ * Write an embedded base64 payload to targetPath.
+ *
+ * Skipped only when BOTH the size matches AND a sidecar .stamp file records the
+ * same build - size alone proved too weak, since different builds can collide
+ * and leave a stale file that no longer matches the wrapper driving it.
+ */
+function extractPayload(targetPath: string, b64chunks: string[], byteCount: number): void {
+	try {
+		var existing = new File(targetPath);
+		if (existing.isopen) {
+			var sameSize = existing.eof === byteCount;
+			existing.close();
+			if (sameSize && readTextFile(targetPath + ".stamp") === buildStamp()) return;
+		}
+	} catch (e) {
+		/* fall through and (re)write */
+	}
+	try {
+		var out = new File(targetPath, "write");
+		if (!out.isopen) out.open();
+		if (!out.isopen) {
+			post("m4l-jweb: cannot write " + targetPath + "\n");
+			return;
+		}
+		out.eof = 0;
+		// File.writebytes silently truncates large calls (observed ~16 KB cap), so
+		// write in small slices and verify the byte count afterwards.
+		var SLICE = 4096;
+		for (var i = 0; i < b64chunks.length; i++) {
+			var bytes = b64decode(b64chunks[i]);
+			for (var off = 0; off < bytes.length; off += SLICE) {
+				out.writebytes(bytes.slice(off, off + SLICE));
+			}
+		}
+		out.close();
+
+		var check = new File(targetPath);
+		var written = check.isopen ? check.eof : -1;
+		if (check.isopen) check.close();
+		if (written === byteCount) {
+			post("m4l-jweb: extracted " + written + " bytes to " + targetPath + "\n");
+			writeTextFile(targetPath + ".stamp", buildStamp());
+		} else {
+			post("m4l-jweb: extract SIZE MISMATCH - wrote " + written + ", expected " + byteCount + "\n");
+		}
+	} catch (e2) {
+		post("m4l-jweb: extract failed - " + (e2 as Error).message + "\n");
+	}
+}
+
+function readTextFile(p: string): string | null {
+	try {
+		var f = new File(p);
+		if (!f.isopen) return null;
+		var s = f.readstring(Math.min(f.eof, 256));
+		f.close();
+		return s;
+	} catch (e) {
+		return null;
+	}
+}
+
+function writeTextFile(p: string, s: string): void {
+	try {
+		var f = new File(p, "write");
+		if (!f.isopen) f.open();
+		if (!f.isopen) return;
+		f.eof = 0;
+		f.writestring(s);
+		f.close();
+	} catch (e) {
+		/* non-fatal */
+	}
+}
+
+var B64CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+var b64lookup: { [c: string]: number } | null = null;
+
+/** Base64 -> array of byte values. Max's [js] has no atob. */
+function b64decode(s: string): number[] {
+	if (!b64lookup) {
+		b64lookup = {};
+		for (var i = 0; i < B64CHARS.length; i++) b64lookup[B64CHARS.charAt(i)] = i;
+	}
+	var out: number[] = [];
+	var buffer = 0;
+	var bits = 0;
+	for (var j = 0; j < s.length; j++) {
+		var c = s.charAt(j);
+		if (c === "=") break;
+		buffer = (buffer << 6) | b64lookup[c];
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			out.push((buffer >> bits) & 0xff);
+		}
+	}
+	return out;
+}

package/src/liveapi.ts

@@ -0,0 +1,250 @@
+/**
+ * liveapi.ts - everything that touches Live's object model.
+ *
+ * Concatenated after core.ts into a single ES5 script, so these functions are
+ * visible to core's lifecycle (bang() calls startTickPoll() and
+ * setupTempoObserver()) without any module system.
+ *
+ * If your device does not touch clips, the clip I/O half is dead weight but
+ * harmless - Max only calls what the patcher routes to it.
+ */
+
+/* ------------------------------------------------------------------ *
+ * Transport: "tick <playing> <beats>" at 20 Hz
+ *
+ * Polled from LiveAPI (live_set is_playing + current_song_time), NOT from a
+ * [plugsync~] -> [snapshot~] signal chain: MIDI-effect devices do not reliably
+ * run a DSP graph, and such a chain reads zero in the field. LiveAPI has no such
+ * dependency and works in every device type. An engine's lookahead window
+ * absorbs the 20 Hz poll rate.
+ * ------------------------------------------------------------------ */
+
+var tickPoll = new Task(pollTransport, this);
+var liveSetApi: LiveAPI | null = null;
+
+function startTickPoll(): void {
+	try {
+		liveSetApi = new LiveAPI("live_set");
+	} catch (e) {
+		post("m4l-jweb: tick poll unavailable - " + (e as Error).message + "\n");
+		return;
+	}
+	tickPoll.cancel();
+	tickPoll.interval = 50;
+	tickPoll.repeat();
+	post("m4l-jweb: transport poll on\n");
+}
+
+function pollTransport(): void {
+	if (!liveSetApi) return;
+	try {
+		var playing = parseInt(String(liveSetApi.get("is_playing")), 10);
+		var beats = parseFloat(String(liveSetApi.get("current_song_time")));
+		outlet(0, "tick", playing, beats);
+		// A device with a second consumer (another engine on outlet 1) mirrors the
+		// clock here rather than polling Live twice.
+		if (typeof onTick === "function") onTick(playing, beats);
+	} catch (e) {
+		/* transient - the next poll retries */
+	}
+}
+
+/* ------------------------------------------------------------------ *
+ * Tempo: observed, not polled.
+ *
+ * The signal-domain alternative reports samples-per-beat, not BPM. The observer
+ * callback fires once on attach and then on every change.
+ * ------------------------------------------------------------------ */
+
+var tempoObs: LiveAPI | null = null;
+
+function setupTempoObserver(): void {
+	// Recreate unconditionally: an object left over from a loading context is
+	// dead and must not block the real one.
+	try {
+		tempoObs = new LiveAPI(onTempo, "live_set");
+		tempoObs.property = "tempo";
+		post("m4l-jweb: tempo observer on (current " + tempoObs.get("tempo") + ")\n");
+	} catch (e) {
+		post("m4l-jweb: tempo observer unavailable - " + (e as Error).message + "\n");
+	}
+}
+
+function onTempo(a: unknown[]): void {
+	if (a && a[0] == "tempo") {
+		outlet(0, "tempo", a[1]);
+		if (typeof onTempoChange === "function") onTempoChange(Number(a[1]));
+	}
+}
+
+/** The observer's first callback can beat the page's binding - ui_ready re-reads. */
+function sendCurrentTempo(): void {
+	try {
+		var api = new LiveAPI("live_set");
+		var t = parseFloat(String(api.get("tempo")));
+		if (t > 0) {
+			outlet(0, "tempo", t);
+			if (typeof onTempoChange === "function") onTempoChange(t);
+		}
+	} catch (e) {
+		post("m4l-jweb: tempo read failed - " + (e as Error).message + "\n");
+	}
+}
+
+/* ------------------------------------------------------------------ *
+ * Generic property observer
+ *
+ * Anything observable in Live (scale, track name, selected scene...) reaches
+ * the UI the same way: attach, forward on change. Call this from bang(), never
+ * from loadbang().
+ * ------------------------------------------------------------------ */
+
+/**
+ * observeProperty("live_set", "scale_name", "scale") forwards every change to
+ * the UI as `scale <value>`. Returns the LiveAPI object so you can keep it
+ * alive; drop it and the observer dies with it.
+ */
+function observeProperty(objectPath: string, property: string, selector: string): LiveAPI | null {
+	try {
+		var api = new LiveAPI(function (a: unknown[]) {
+			if (a && a[0] == property) {
+				var args: unknown[] = [0, selector];
+				for (var i = 1; i < a.length; i++) args.push(a[i]);
+				(outlet as Function).apply(this, args);
+			}
+		}, objectPath);
+		api.property = property;
+		return api;
+	} catch (e) {
+		post("m4l-jweb: cannot observe " + objectPath + " " + property + " - " + (e as Error).message + "\n");
+		return null;
+	}
+}
+
+/* ------------------------------------------------------------------ *
+ * Clip I/O
+ * ------------------------------------------------------------------ */
+
+interface LiveNote {
+	pitch: number;
+	start_time: number;
+	duration: number;
+	velocity: number;
+	mute?: number;
+}
+
+/** The LiveAPI for the track this device sits on. */
+function ownTrack(): LiveAPI {
+	return new LiveAPI("this_device canonical_parent");
+}
+
+/**
+ * write_clip <lengthBeats> <n> <pitch start duration velocity> ...
+ * Creates a clip in the first empty slot on this device's track and fills it.
+ */
+function write_clip(): void {
+	var a = arrayfromargs(arguments);
+	if (a.length < 2) return;
+	var lengthBeats = a[0];
+	var n = Number(a[1]);
+
+	var slot = firstEmptySlot();
+	if (!slot) {
+		post("m4l-jweb: no empty clip slot on this track\n");
+		return;
+	}
+	slot.call("create_clip", lengthBeats);
+	var clip = new LiveAPI(slot.unquotedpath + " clip");
+
+	var notes: LiveNote[] = [];
+	for (var k = 0; k < n; k++) {
+		var o = 2 + k * 4;
+		notes.push({
+			pitch: Number(a[o]),
+			start_time: Number(a[o + 1]),
+			duration: Number(a[o + 2]),
+			velocity: Number(a[o + 3]),
+			mute: 0,
+		});
+	}
+	try {
+		clip.call("add_new_notes", { notes: notes });
+	} catch (e) {
+		post("m4l-jweb: add_new_notes failed - " + (e as Error).message + "\n");
+		return;
+	}
+	post("m4l-jweb: wrote " + n + " notes over " + lengthBeats + " beats\n");
+}
+
+function firstEmptySlot(): LiveAPI | null {
+	try {
+		var track = ownTrack();
+		var count = parseInt(String(track.getcount("clip_slots")), 10);
+		for (var i = 0; i < count; i++) {
+			var s = new LiveAPI(track.unquotedpath + " clip_slots " + i);
+			if (parseInt(String(s.get("has_clip")), 10) === 0) return s;
+		}
+		return null;
+	} catch (e) {
+		post("m4l-jweb: firstEmptySlot error " + (e as Error).message + "\n");
+		return null;
+	}
+}
+
+/**
+ * read_notes - pick a clip on this device's track (the playing one, else the
+ * first found), read its notes and send them to the UI as
+ * "notes <loopEnd> <n> <pitch start duration> ...".
+ */
+function read_notes(): void {
+	var clip = pickClip();
+	if (!clip) {
+		post("m4l-jweb: no clip found on this track\n");
+		outlet(0, "read_error", "no_clip");
+		return;
+	}
+	var loopEnd = parseFloat(String(clip.get("loop_end")));
+	var notes = getNotes(clip, loopEnd);
+	if (!notes) return;
+
+	var out: unknown[] = ["notes", loopEnd, notes.length];
+	for (var i = 0; i < notes.length; i++) {
+		out.push(notes[i].pitch, notes[i].start_time, notes[i].duration);
+	}
+	// A note list is variadic, so the message has to be spread with apply().
+	// outlet()'s typed signature cannot express that; go through Function.
+	(outlet as Function).apply(this, ([0] as unknown[]).concat(out));
+	post("m4l-jweb: read " + notes.length + " notes (loop_end " + loopEnd + ")\n");
+}
+
+function pickClip(): LiveAPI | null {
+	try {
+		var track = ownTrack();
+		var count = parseInt(String(track.getcount("clip_slots")), 10);
+		var firstWithClip: LiveAPI | null = null;
+		for (var i = 0; i < count; i++) {
+			var s = new LiveAPI(track.unquotedpath + " clip_slots " + i);
+			if (parseInt(String(s.get("has_clip")), 10) === 1) {
+				var c = new LiveAPI(s.unquotedpath + " clip");
+				if (parseInt(String(c.get("is_playing")), 10) === 1) return c;
+				if (!firstWithClip) firstWithClip = c;
+			}
+		}
+		return firstWithClip;
+	} catch (e) {
+		post("m4l-jweb: pickClip error " + (e as Error).message + "\n");
+		return null;
+	}
+}
+
+function getNotes(clip: LiveAPI, loopEnd: number): LiveNote[] | null {
+	// Live 11+: get_notes_extended returns a JSON string.
+	try {
+		var d = clip.call("get_notes_extended", 0, 128, 0, loopEnd);
+		var obj = typeof d === "string" ? JSON.parse(d) : d;
+		if (obj && obj.notes) return obj.notes;
+	} catch (e) {
+		post("m4l-jweb: get_notes_extended failed - " + (e as Error).message + "\n");
+	}
+	return null;
+}

package/src/max.d.ts

@@ -0,0 +1,105 @@
+/**
+ * max.d.ts - ambient types for the globals Max's [js] object provides.
+ *
+ * The [js] runtime is an ES5-era interpreter: no modules, no `console`, no
+ * `setTimeout`. It is also the ONLY place with LiveAPI access, and it always
+ * runs - even inside a frozen device. Hence this file: enough typing to write
+ * the glue in TypeScript without pretending it is a browser or Node.
+ */
+
+/** Print to the Max console. There is no `console` here. */
+declare function post(...args: unknown[]): void;
+
+/** Send a message out of outlet `n`. */
+declare function outlet(n: number, ...args: unknown[]): void;
+
+/** Collect the `arguments` of a Max message handler into a real array. */
+declare function arrayfromargs(args: IArguments): unknown[];
+
+/** Arguments given to the object box, e.g. `js wrapper.js midi` -> ["midi"]. */
+declare const jsarguments: unknown[];
+
+declare let autowatch: number;
+declare let inlets: number;
+declare let outlets: number;
+
+/*
+ * The patcher hosting this [js] is reached as `this.patcher` - at [js] global
+ * scope `this` IS the jsthis object, and a plainly-called function inherits it.
+ * `this.patcher.filepath` is how the wrapper locates the .amxd's folder on
+ * disk. (Hence `noImplicitThis: false` in wrapper/tsconfig.json.)
+ */
+
+/** Max's scheduler. There is no `setTimeout` in [js]. */
+declare class Task {
+	constructor(fn: () => void, ctx: unknown);
+	interval: number;
+	repeat(count?: number): void;
+	schedule(delayMs?: number): void;
+	cancel(): void;
+}
+
+/** Max's file object. Note: `writebytes` truncates silently past ~16 KB. */
+declare class File {
+	constructor(path: string, mode?: "read" | "write" | "readwrite");
+	isopen: boolean;
+	eof: number;
+	open(): void;
+	close(): void;
+	readstring(count: number): string;
+	writestring(s: string): void;
+	writebytes(bytes: number[]): void;
+}
+
+/** The Live object model. The whole reason [js] still exists in this stack. */
+declare class LiveAPI {
+	constructor(pathOrCallback: string | ((args: unknown[]) => void), path?: string);
+	property: string;
+	unquotedpath: string;
+	get(prop: string): unknown;
+	set(prop: string, value: unknown): void;
+	getcount(child: string): number;
+	call(method: string, ...args: unknown[]): unknown;
+}
+
+/** Injected by @m4l-jweb/build: "<version> <iso date>". */
+declare const BUILD_STAMP: string | undefined;
+
+/** Injected by @m4l-jweb/build: the UI html, base64, in chunks. */
+declare const UI_PAYLOAD_NAME: string | undefined;
+declare const UI_PAYLOAD_BYTES: number | undefined;
+declare const UI_PAYLOAD_B64: string[] | undefined;
+
+/**
+ * Injected by @m4l-jweb/build from the manifest's `payloads`: any other file
+ * that must exist on disk next to the .amxd, because whatever reads it is not a
+ * Max-native object and so cannot see the frozen virtual filesystem.
+ */
+declare const EXTRA_PAYLOAD_NAMES: string[] | undefined;
+declare const EXTRA_PAYLOAD_BYTES: number[] | undefined;
+declare const EXTRA_PAYLOAD_B64: string[][] | undefined;
+
+/*
+ * Device hooks.
+ *
+ * Define any of these as a plain function in your repo's `wrapper/device.ts` and
+ * the packaged wrapper will call it; leave it out and nothing happens. They are
+ * declared here (rather than defined) so both sides typecheck: the wrapper guards
+ * every call with `typeof onX === "function"`, which is safe even when the
+ * identifier was never declared at runtime.
+ */
+
+/**
+ * live.thisdevice has fired: the device is fully loaded and LiveAPI is finally
+ * safe. Create your observers HERE - objects built during loadbang are dead.
+ */
+declare function onDeviceReady(): void;
+
+/** The UI announced itself. Resend any device-specific state it needs. */
+declare function onUiReady(): void;
+
+/** Every transport poll (20 Hz), after the packaged wrapper has sent its tick. */
+declare function onTick(playing: number, beats: number): void;
+
+/** Live's tempo changed (and once on attach). */
+declare function onTempoChange(bpm: number): void;