alphatheta-connect 0.23.2 → 0.25.0

package/lib/cli.js

@@ -742,8 +742,10 @@ exports.MAX_CDJ_DEVICE_ID = exports.MIN_CDJ_DEVICE_ID = exports.VIRTUAL_CDJ_FIRM
 /**
  * The default virtual CDJ ID to use.
  *
- * This particular ID is out of the 1-6 range, thus will not be able to request
- * metadata via the remotedb for CDJs.
+ * Out of the 1-6 player range, so it can never collide with a real CDJ.
+ * Remotedb metadata still works from here: the 1-6 restriction applies to the
+ * device-ID byte inside remotedb messages, which RemoteDatabase picks
+ * per-connection independently of the announced ID.
  */
 exports.DEFAULT_VCDJ_ID = 0x07;
 /**
@@ -1647,7 +1649,6 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _Database_instances, _Database_deviceManager, _Database_localDatabase, _Database_remoteDatabase, _Database_logger, _Database_getTrackLookupStrategy, _Database_getMediaLookupStrategy, _Database_metadataViaRemoteFallback;
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-const constants_1 = __webpack_require__(/*! src/constants */ "./src/constants.ts");
 const logger_1 = __webpack_require__(/*! src/logger */ "./src/logger.ts");
 const types_1 = __webpack_require__(/*! src/types */ "./src/types.ts");
 const utils_1 = __webpack_require__(/*! src/utils */ "./src/utils/index.ts");
@@ -1947,20 +1948,14 @@ _Database_deviceManager = new WeakMap(), _Database_localDatabase = new WeakMap()
 /**
  * Second chance for a track the local database could not answer for.
  *
- * CDJs only answer remote database queries from a host announcing a device
- * ID in the 1-6 range, so this is unavailable whenever the virtual CDJ sits
- * outside it (the package default is 7). That is a real configuration, not
- * an error — log why the fallback was skipped rather than throwing, so the
- * next report says which of the two happened.
+ * Available regardless of the virtual CDJ's announced ID: CDJs restrict
+ * remote database queries to a device-ID byte in the 1-6 range, but that
+ * byte lives inside the remotedb messages and RemoteDatabase picks an
+ * in-range one per connection — the announced ID never constrains this
+ * lookup. A failure here is logged rather than thrown, so a field report
+ * says what actually went wrong.
  */
 async function _Database_metadataViaRemoteFallback(opts) {
-    const hostId = __classPrivateFieldGet(this, _Database_remoteDatabase, "f").hostDevice.id;
-    if (hostId < constants_1.MIN_CDJ_DEVICE_ID || hostId > constants_1.MAX_CDJ_DEVICE_ID) {
-        __classPrivateFieldGet(this, _Database_logger, "f").warn(`No remote fallback for track ${opts.trackId}: this player is device ` +
-            `${hostId}, and CDJs only answer remote database queries from ` +
-            `devices ${constants_1.MIN_CDJ_DEVICE_ID}-${constants_1.MAX_CDJ_DEVICE_ID}`);
-        return null;
-    }
     try {
         const track = await GetMetadata.viaRemote(__classPrivateFieldGet(this, _Database_remoteDatabase, "f"), opts);
         if (track === null) {
@@ -6718,7 +6713,7 @@ class MixstatusProcessor {
         // able to report it as live
         const startedAt = __classPrivateFieldGet(this, _MixstatusProcessor_lastStartTime, "f").get(deviceId);
         const requiredPlayTime = __classPrivateFieldGet(this, _MixstatusProcessor_config, "f").beatsUntilReported *
-            (0, utils_1.bpmToSeconds)(state.trackBPM, state.sliderPitch) *
+            (0, utils_1.bpmToSeconds)(state.trackBPM, state.effectivePitch) *
             1000;
         if (__classPrivateFieldGet(this, _MixstatusProcessor_config, "f").mode === types_1.MixstatusMode.SmartTiming &&
             startedAt !== undefined &&
@@ -6729,7 +6724,7 @@ class MixstatusProcessor {
         // we can mark the track as truly stopped.
         const stoppedAt = __classPrivateFieldGet(this, _MixstatusProcessor_lastStoppedTimes, "f").get(deviceId);
         const requiredStopTime = __classPrivateFieldGet(this, _MixstatusProcessor_config, "f").allowedInterruptBeats *
-            (0, utils_1.bpmToSeconds)(state.trackBPM, state.sliderPitch) *
+            (0, utils_1.bpmToSeconds)(state.trackBPM, state.effectivePitch) *
             1000;
         if (stoppedAt !== undefined && requiredStopTime <= Date.now() - stoppedAt) {
             __classPrivateFieldGet(this, _MixstatusProcessor_markPlayerStopped, "f").call(this, state);
@@ -7020,6 +7015,14 @@ class ProlinkNetwork {
             announcer = new virtualcdj_1.Announcer(vcdj, __classPrivateFieldGet(this, _ProlinkNetwork_announceSocket, "f"), this.deviceManager, __classPrivateFieldGet(this, _ProlinkNetwork_config, "f").iface, (_d = __classPrivateFieldGet(this, _ProlinkNetwork_config, "f").fullStartup) !== null && _d !== void 0 ? _d : false, (_e = __classPrivateFieldGet(this, _ProlinkNetwork_config, "f").announceToStagehand) !== null && _e !== void 0 ? _e : false, __classPrivateFieldGet(this, _ProlinkNetwork_logger, "f"));
         }
         announcer.start();
+        // In Stagehand mode, unicast keep-alives to discovered players and the
+        // mixer so they push live state to us (mixer 0x39/0x58, CDJ 0x69/waveforms).
+        // Broadcast presence alone does not bootstrap that stream.
+        let heartbeat = null;
+        if (connectMethod === 'stagehand') {
+            heartbeat = new virtualcdj_1.StagehandHeartbeat(vcdj, __classPrivateFieldGet(this, _ProlinkNetwork_statusSocket, "f"), __classPrivateFieldGet(this, _ProlinkNetwork_deviceManager, "f"), __classPrivateFieldGet(this, _ProlinkNetwork_logger, "f"));
+            heartbeat.start();
+        }
         // Create remote and local databases
         const remotedb = new remotedb_1.default(__classPrivateFieldGet(this, _ProlinkNetwork_deviceManager, "f"), vcdj);
         const localdb = new localdb_1.default(vcdj, __classPrivateFieldGet(this, _ProlinkNetwork_deviceManager, "f"), __classPrivateFieldGet(this, _ProlinkNetwork_statusEmitter, "f"), (_f = __classPrivateFieldGet(this, _ProlinkNetwork_config, "f").databasePreference) !== null && _f !== void 0 ? _f : 'auto');
@@ -7028,23 +7031,24 @@ class ProlinkNetwork {
         // Create controller service
         const control = new control_1.default(__classPrivateFieldGet(this, _ProlinkNetwork_beatSocket, "f"), vcdj);
         __classPrivateFieldSet(this, _ProlinkNetwork_state, types_1.NetworkState.Connected, "f");
-        __classPrivateFieldSet(this, _ProlinkNetwork_connection, { announcer, control, remotedb, localdb, database }, "f");
+        __classPrivateFieldSet(this, _ProlinkNetwork_connection, { announcer, heartbeat, control, remotedb, localdb, database }, "f");
         tx.finish();
     }
     /**
      * Disconnect from the network
      */
     disconnect() {
-        var _a, _b, _c;
+        var _a, _b, _c, _d, _e;
         if (__classPrivateFieldGet(this, _ProlinkNetwork_config, "f") === null) {
             throw new Error(connectErrorHelp);
         }
         // Stop announcing ourself
         (_a = __classPrivateFieldGet(this, _ProlinkNetwork_connection, "f")) === null || _a === void 0 ? void 0 : _a.announcer.stop();
+        (_c = (_b = __classPrivateFieldGet(this, _ProlinkNetwork_connection, "f")) === null || _b === void 0 ? void 0 : _b.heartbeat) === null || _c === void 0 ? void 0 : _c.stop();
         // Disconnect devices from the remote and local databases
         for (const device of this.deviceManager.devices.values()) {
-            (_b = this.remotedb) === null || _b === void 0 ? void 0 : _b.disconnectFromDevice(device);
-            (_c = this.localdb) === null || _c === void 0 ? void 0 : _c.disconnectForDevice(device);
+            (_d = this.remotedb) === null || _d === void 0 ? void 0 : _d.disconnectFromDevice(device);
+            (_e = this.localdb) === null || _e === void 0 ? void 0 : _e.disconnectForDevice(device);
         }
         return this.close;
     }
@@ -8504,15 +8508,17 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
-var _Connection_socket, _Connection_txId, _Connection_lock, _QueryInterface_conn, _QueryInterface_hostDevice, _QueryInterface_lock, _RemoteDatabase_hostDevice, _RemoteDatabase_deviceManager, _RemoteDatabase_connections, _RemoteDatabase_deviceLocks;
+var _Connection_socket, _Connection_txId, _Connection_lock, _QueryInterface_conn, _QueryInterface_hostDevice, _QueryInterface_lock, _RemoteDatabase_instances, _RemoteDatabase_hostDevice, _RemoteDatabase_deviceManager, _RemoteDatabase_connections, _RemoteDatabase_deviceLocks, _RemoteDatabase_queryIds, _RemoteDatabase_pickQueryId, _RemoteDatabase_queryIdFor;
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.QueryInterface = exports.Connection = exports.Query = exports.MenuTarget = void 0;
 exports.getQueryName = getQueryName;
 const async_mutex_1 = __webpack_require__(/*! async-mutex */ "async-mutex");
 const promise_socket_1 = __importDefault(__webpack_require__(/*! promise-socket */ "promise-socket"));
 const net_1 = __webpack_require__(/*! net */ "net");
+const types_1 = __webpack_require__(/*! src/types */ "./src/types.ts");
 const Telemetry = __importStar(__webpack_require__(/*! src/utils/telemetry */ "./src/utils/telemetry.ts"));
-const types_1 = __webpack_require__(/*! ./message/types */ "./src/remotedb/message/types.ts");
+const device_id_1 = __webpack_require__(/*! src/virtualcdj/device-id */ "./src/virtualcdj/device-id.ts");
+const types_2 = __webpack_require__(/*! ./message/types */ "./src/remotedb/message/types.ts");
 const constants_1 = __webpack_require__(/*! ./constants */ "./src/remotedb/constants.ts");
 const fields_1 = __webpack_require__(/*! ./fields */ "./src/remotedb/fields.ts");
 const message_1 = __webpack_require__(/*! ./message */ "./src/remotedb/message/index.ts");
@@ -8525,7 +8531,7 @@ var MenuTarget;
 (function (MenuTarget) {
     MenuTarget[MenuTarget["Main"] = 1] = "Main";
 })(MenuTarget || (exports.MenuTarget = MenuTarget = {}));
-exports.Query = types_1.Request;
+exports.Query = types_2.Request;
 const QueryInverse = Object.fromEntries(Object.entries(exports.Query).map(e => [e[1], e[0]]));
 /**
  * Returns a string representation of a remote query
@@ -8571,7 +8577,7 @@ class Connection {
         var _a;
         const tx = span.startChild({
             op: 'writeMessage',
-            description: (0, types_1.getMessageName)(message.type),
+            description: (0, types_2.getMessageName)(message.type),
         });
         message.transactionId = __classPrivateFieldSet(this, _Connection_txId, (_a = __classPrivateFieldGet(this, _Connection_txId, "f"), ++_a), "f");
         await __classPrivateFieldGet(this, _Connection_socket, "f").write(message.buffer);
@@ -8632,7 +8638,8 @@ _QueryInterface_conn = new WeakMap(), _QueryInterface_hostDevice = new WeakMap()
  * Service that maintains remote database connections with devices on the network.
  */
 class RemoteDatabase {
-    constructor(deviceManager, hostDevice) {
+    constructor(deviceManager, hostDevice, { pickQueryId = true } = {}) {
+        _RemoteDatabase_instances.add(this);
         _RemoteDatabase_hostDevice.set(this, void 0);
         _RemoteDatabase_deviceManager.set(this, void 0);
         /**
@@ -8643,6 +8650,17 @@ class RemoteDatabase {
          * Locks for each device when locating the connection
          */
         _RemoteDatabase_deviceLocks.set(this, new Map());
+        /**
+         * The device ID each connection introduced itself with. Queries on that
+         * connection must carry the same ID.
+         */
+        _RemoteDatabase_queryIds.set(this, new Map());
+        /**
+         * Whether to substitute an in-range query ID when the host device sits
+         * outside 1-6. Disabled only by protocol probes that need to observe how a
+         * device treats the raw announced ID (see examples/remotedb-id-probe.ts).
+         */
+        _RemoteDatabase_pickQueryId.set(this, void 0);
         /**
          * Open a connection to the specified device for querying
          */
@@ -8667,20 +8685,22 @@ class RemoteDatabase {
                 throw new Error(`Expected 0x01 during preamble handshake. Got ${data.value}`);
             }
             // Send introduction message to set context for querying
+            const queryId = __classPrivateFieldGet(this, _RemoteDatabase_instances, "m", _RemoteDatabase_queryIdFor).call(this, device);
             const intro = new message_1.Message({
                 transactionId: 0xfffffffe,
-                type: types_1.MessageType.Introduce,
-                args: [new fields_1.UInt32(__classPrivateFieldGet(this, _RemoteDatabase_hostDevice, "f").id)],
+                type: types_2.MessageType.Introduce,
+                args: [new fields_1.UInt32(queryId)],
             });
             await socket.write(intro.buffer);
-            const resp = await message_1.Message.fromStream(socket, types_1.MessageType.Success, tx);
-            if (resp.type !== types_1.MessageType.Success) {
+            const resp = await message_1.Message.fromStream(socket, types_2.MessageType.Success, tx);
+            if (resp.type !== types_2.MessageType.Success) {
                 throw new Error(`Failed to introduce self to device ID: ${device.id}`);
             }
             // Clear socket timeout after successful connection — the per-device mutex
             // and application-level Promise.race timeouts handle query timeouts
             socket.stream.setTimeout(0);
             __classPrivateFieldGet(this, _RemoteDatabase_connections, "f").set(device.id, new Connection(device, socket));
+            __classPrivateFieldGet(this, _RemoteDatabase_queryIds, "f").set(device.id, queryId);
             tx.finish();
         };
         /**
@@ -8694,22 +8714,26 @@ class RemoteDatabase {
             }
             const goodbye = new message_1.Message({
                 transactionId: 0xfffffffe,
-                type: types_1.MessageType.Disconnect,
+                type: types_2.MessageType.Disconnect,
                 args: [],
             });
             await conn.writeMessage(goodbye, tx);
             conn.close();
             __classPrivateFieldGet(this, _RemoteDatabase_connections, "f").delete(device.id);
+            __classPrivateFieldGet(this, _RemoteDatabase_queryIds, "f").delete(device.id);
             tx.finish();
         };
         __classPrivateFieldSet(this, _RemoteDatabase_deviceManager, deviceManager, "f");
         __classPrivateFieldSet(this, _RemoteDatabase_hostDevice, hostDevice, "f");
+        __classPrivateFieldSet(this, _RemoteDatabase_pickQueryId, pickQueryId, "f");
     }
     /**
-     * The device we introduce ourselves as when opening a remote database
-     * connection. CDJs only answer queries from a host announcing an ID in the
-     * 1-6 range, so callers need to read this before deciding a remote lookup is
-     * even possible.
+     * The device this service belongs to — the virtual CDJ announced on the
+     * network. Note that this is NOT necessarily the ID carried inside remotedb
+     * messages: CDJs only answer queries whose in-protocol device-ID byte is
+     * 1-6, so when this device sits outside that range (announced above the
+     * player range to avoid collisions), each connection picks an in-range
+     * query ID via {@link pickRemoteDbQueryId} instead.
      */
     get hostDevice() {
         return __classPrivateFieldGet(this, _RemoteDatabase_hostDevice, "f");
@@ -8723,7 +8747,7 @@ class RemoteDatabase {
      * @returns null if the device does not export a remote database service
      */
     async get(deviceId) {
-        var _a;
+        var _a, _b;
         const device = __classPrivateFieldGet(this, _RemoteDatabase_deviceManager, "f").devices.get(deviceId);
         if (device === undefined) {
             return null;
@@ -8738,14 +8762,28 @@ class RemoteDatabase {
             conn = __classPrivateFieldGet(this, _RemoteDatabase_connections, "f").get(deviceId);
             // NOTE: We pass the same lock we use for this device to the query
             // interface to ensure all query interfaces use the same lock.
-            return new QueryInterface(conn, lock, __classPrivateFieldGet(this, _RemoteDatabase_hostDevice, "f"));
+            // Queries must carry the same device ID the connection introduced
+            // itself with, which is not always the announced host ID.
+            const queryId = (_b = __classPrivateFieldGet(this, _RemoteDatabase_queryIds, "f").get(device.id)) !== null && _b !== void 0 ? _b : __classPrivateFieldGet(this, _RemoteDatabase_hostDevice, "f").id;
+            return new QueryInterface(conn, lock, { ...__classPrivateFieldGet(this, _RemoteDatabase_hostDevice, "f"), id: queryId });
         }
         finally {
             releaseLock();
         }
     }
 }
-_RemoteDatabase_hostDevice = new WeakMap(), _RemoteDatabase_deviceManager = new WeakMap(), _RemoteDatabase_connections = new WeakMap(), _RemoteDatabase_deviceLocks = new WeakMap();
+_RemoteDatabase_hostDevice = new WeakMap(), _RemoteDatabase_deviceManager = new WeakMap(), _RemoteDatabase_connections = new WeakMap(), _RemoteDatabase_deviceLocks = new WeakMap(), _RemoteDatabase_queryIds = new WeakMap(), _RemoteDatabase_pickQueryId = new WeakMap(), _RemoteDatabase_instances = new WeakSet(), _RemoteDatabase_queryIdFor = function _RemoteDatabase_queryIdFor(device) {
+    const hostId = __classPrivateFieldGet(this, _RemoteDatabase_hostDevice, "f").id;
+    // An announced ID already inside the answered range keeps working exactly
+    // as it always has. Rekordbox (which numbers itself far above 6) answers
+    // queries regardless, so only CDJ targets need an in-range stand-in.
+    if (!__classPrivateFieldGet(this, _RemoteDatabase_pickQueryId, "f") ||
+        hostId <= device_id_1.REMOTEDB_MAX_DEVICE_ID ||
+        device.type !== types_1.DeviceType.CDJ) {
+        return hostId;
+    }
+    return (0, device_id_1.pickRemoteDbQueryId)(device.id, __classPrivateFieldGet(this, _RemoteDatabase_deviceManager, "f").devices.values());
+};
 exports["default"] = RemoteDatabase;
 
 
@@ -10039,10 +10077,29 @@ exports["default"] = PositionEmitter;
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.PlayState = exports.StatusFlag = void 0;
 /**
- * Status flag bitmasks
+ * Status flag bitmasks (byte 0x89 of the CDJ status packet).
+ *
+ * Verified against CDJ-3000 firmware (EP122 FW3.20): the deck assembles this
+ * byte in `sub_d7d3c8` (0xd7d3c8) from the BeatSyncMaster state struct, one
+ * source boolean per bit. The bits not named here:
+ *
+ * - bit 0 (0x01): structurally unused — no code path ever sets it (always 0).
+ * - bit 2 (0x04): a real, dedicated beat-sync boolean (struct +5), but its
+ *   name did not survive in the stripped `usecase::sync` async-task code. It
+ *   is normally 0, which is why it has never been observed on the wire.
+ * - bit 7 (0x80): a real bit (struct +0xa) that is default-set at init and
+ *   whose de-assertion itself triggers a state-change notification — best read
+ *   as a "sync-master active / handoff-in-progress" toggle. Also normally 0 in
+ *   steady state.
  */
 var StatusFlag;
 (function (StatusFlag) {
+    /**
+     * Degraded to BPM Sync: the player is still tracking the master's tempo, but
+     * beat alignment was dropped after a pitch-bend / jog nudge. Firmware sources
+     * this from BeatSyncMaster struct +4.
+     */
+    StatusFlag[StatusFlag["BpmSync"] = 2] = "BpmSync";
     StatusFlag[StatusFlag["OnAir"] = 8] = "OnAir";
     StatusFlag[StatusFlag["Sync"] = 16] = "Sync";
     StatusFlag[StatusFlag["Master"] = 32] = "Master";
@@ -10115,14 +10172,24 @@ function statusFromPacket(packet) {
         playState: packet[0x7b],
         isOnAir: (packet[0x89] & types_1.CDJStatus.StatusFlag.OnAir) !== 0,
         isSync: (packet[0x89] & types_1.CDJStatus.StatusFlag.Sync) !== 0,
+        isBpmSync: (packet[0x89] & types_1.CDJStatus.StatusFlag.BpmSync) !== 0,
         isMaster: (packet[0x89] & types_1.CDJStatus.StatusFlag.Master) !== 0,
         isEmergencyMode: !!packet[0xba],
         trackBPM,
-        sliderPitch: calcPitch(packet.slice(0x8d, 0x8d + 3)),
-        effectivePitch: calcPitch(packet.slice(0x99, 0x99 + 3)),
+        // The CDJ status packet carries four pitch values (firmware CDJ-3000 FW3.20,
+        // sub_d7d610): Pitch1@0x8c and Pitch3@0xc0 are the *effective* pitch (in
+        // effect / on the BPM display, from the fader or a synced master), while
+        // Pitch2@0x98 and Pitch4@0xc4 track the *local fader* position. We expose
+        // Pitch1 as `effectivePitch` and Pitch2 as `sliderPitch`.
+        effectivePitch: calcPitch(packet.slice(0x8d, 0x8d + 3)),
+        sliderPitch: calcPitch(packet.slice(0x99, 0x99 + 3)),
         beatInMeasure: packet[0xa6],
         beatsUntilCue,
         beat,
+        // Player-type / capability byte (dysentery's "nx"). Guarded because the
+        // length check above only guarantees 0xc8; older/short packets may not
+        // reach 0xcc, in which case the field reads as 0 (version-gated to 0 anyway).
+        deviceType: packet.length > 0xcc ? packet[0xcc] : 0,
         packetNum: packet.readUInt32BE(0xc8),
     };
     return status;
@@ -10867,11 +10934,17 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.DEFAULT_MIXER_PLAYER_CEILING = exports.MIXER_PLAYER_CEILING = exports.MAX_DEVICE_ID = exports.REMOTEDB_MAX_DEVICE_ID = void 0;
 exports.playerNumberCeiling = playerNumberCeiling;
 exports.pickAvailableDeviceId = pickAvailableDeviceId;
+exports.pickRemoteDbQueryId = pickRemoteDbQueryId;
 /**
  * The highest device ID a CDJ will answer remotedb queries from.
  *
- * CDJs ignore metadata requests from devices numbered above this, which is why
- * the 1-6 range is worth preferring even though real players live there too.
+ * This limit applies to the device-ID byte inside the remotedb protocol (the
+ * Introduce message and every query header), NOT to the ID we announce on the
+ * network. Hardware-verified on a CDJ-3000 (2026-08-30, two players + DJM-V5,
+ * announced as VCDJ 7 throughout): queries carrying 1-6 are all answered —
+ * including IDs of absent players and the target's own ID — while 7 and above
+ * are silently ignored (the TCP connection and Introduce succeed, the query
+ * never gets a response). See {@link pickRemoteDbQueryId}.
  */
 exports.REMOTEDB_MAX_DEVICE_ID = 6;
 /**
@@ -10879,11 +10952,13 @@ exports.REMOTEDB_MAX_DEVICE_ID = 6;
  */
 exports.MAX_DEVICE_ID = 32;
 /**
- * `DeviceType.Mixer`, inlined so this module stays free of runtime imports —
- * it is re-exported into consumers' test environments, where pulling in the
- * whole type module (and its ip-address dependency) is dead weight.
+ * `DeviceType.Mixer` and `DeviceType.CDJ`, inlined so this module stays free
+ * of runtime imports — it is re-exported into consumers' test environments,
+ * where pulling in the whole type module (and its ip-address dependency) is
+ * dead weight.
  */
 const MIXER_DEVICE_TYPE = 0x03;
+const CDJ_DEVICE_TYPE = 0x01;
 /**
  * How many player numbers each mixer can hand out.
  *
@@ -10982,24 +11057,233 @@ const ascending = (from, to) => {
  * Returns null when every ID from 1 to 32 is occupied, in which case there is
  * no safe ID and the caller must not join the network.
  */
-function pickAvailableDeviceId(usedIds, { preferRemoteDb = false, playerCeiling } = {}) {
+function pickAvailableDeviceId(usedIds, { preferPlayerRange = false, playerCeiling } = {}) {
     var _a;
     const used = new Set(usedIds);
     const aboveThePlayers = playerCeiling === undefined
         ? descending(exports.REMOTEDB_MAX_DEVICE_ID, 1)
         : ascending(playerCeiling + 1, exports.REMOTEDB_MAX_DEVICE_ID);
-    const outsideRemoteDb = ascending(exports.REMOTEDB_MAX_DEVICE_ID + 1, exports.MAX_DEVICE_ID);
+    const outsidePlayerRange = ascending(exports.REMOTEDB_MAX_DEVICE_ID + 1, exports.MAX_DEVICE_ID);
     // Numbers a player on this rig could be assigned. Last resort: better to
     // contend for a slot than not to join at all, and the announcer moves us if
     // the player that owns it shows up.
     const amongThePlayers = playerCeiling === undefined
         ? []
         : descending(Math.min(playerCeiling, exports.REMOTEDB_MAX_DEVICE_ID), 1);
-    const search = preferRemoteDb
-        ? [...aboveThePlayers, ...outsideRemoteDb, ...amongThePlayers]
-        : [...outsideRemoteDb, ...aboveThePlayers, ...amongThePlayers];
+    const search = preferPlayerRange
+        ? [...aboveThePlayers, ...outsidePlayerRange, ...amongThePlayers]
+        : [...outsidePlayerRange, ...aboveThePlayers, ...amongThePlayers];
     return (_a = search.find(id => !used.has(id))) !== null && _a !== void 0 ? _a : null;
 }
+/**
+ * Choose the device ID to carry inside remotedb messages when querying a CDJ.
+ *
+ * CDJs only answer remotedb queries whose in-protocol device-ID byte is in
+ * 1-6, but that byte is independent of the ID we announce on the network — so
+ * a virtual CDJ announced safely above the player range (say 7 behind a
+ * DJM-V10) can still query metadata by carrying an in-range ID here. Verified
+ * on a CDJ-3000 (2026-08-30): absent IDs and even the target's own ID are
+ * answered; 7+ is silently dropped.
+ *
+ * Older players are documented (dysentery, nexus era) as stricter: the byte
+ * had to be 1-4, belong to a player actually on the network, and not be the
+ * player being queried. The preference order below satisfies those rules
+ * whenever the rig makes it possible, then falls back through choices newer
+ * players accept.
+ */
+function pickRemoteDbQueryId(targetId, devices) {
+    const playerIds = new Set();
+    for (const device of devices) {
+        if (device.type === CDJ_DEVICE_TYPE && device.id <= exports.REMOTEDB_MAX_DEVICE_ID) {
+            playerIds.add(device.id);
+        }
+    }
+    // A live player that isn't the target, lowest first — 1-4 satisfies every
+    // documented era of the restriction.
+    const otherPlayers = [...playerIds].filter(id => id !== targetId).sort((a, b) => a - b);
+    if (otherPlayers.length > 0) {
+        return otherPlayers[0];
+    }
+    // No other player on the rig: take the lowest 1-6 ID no player holds.
+    for (let id = 1; id <= exports.REMOTEDB_MAX_DEVICE_ID; id++) {
+        if (id !== targetId && !playerIds.has(id)) {
+            return id;
+        }
+    }
+    // Six players and every one of them is the target? Impossible, but the
+    // target's own ID is answered too, so it is a safe closing fallback.
+    return targetId;
+}
+
+
+/***/ },
+
+/***/ "./src/virtualcdj/heartbeat.ts"
+/*!*************************************!*\
+  !*** ./src/virtualcdj/heartbeat.ts ***!
+  \*************************************/
+(__unused_webpack_module, exports, __webpack_require__) {
+
+"use strict";
+
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _StagehandHeartbeat_instances, _StagehandHeartbeat_statusSocket, _StagehandHeartbeat_vcdj, _StagehandHeartbeat_deviceManager, _StagehandHeartbeat_logger, _StagehandHeartbeat_intervalHandle, _StagehandHeartbeat_sendHeartbeats;
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.StagehandHeartbeat = exports.STAGEHAND_HEARTBEAT_INTERVAL = void 0;
+exports.makeStagehandMixerHeartbeat = makeStagehandMixerHeartbeat;
+exports.makeStagehandPlayerHeartbeat = makeStagehandPlayerHeartbeat;
+const constants_1 = __webpack_require__(/*! src/constants */ "./src/constants.ts");
+const logger_1 = __webpack_require__(/*! src/logger */ "./src/logger.ts");
+const types_1 = __webpack_require__(/*! src/types */ "./src/types.ts");
+/**
+ * Cadence of the Stagehand unicast keep-alive, in milliseconds.
+ *
+ * The real iOS Stagehand app heartbeats every discovered player and the mixer
+ * at ~4 Hz (250ms median inter-packet gap in captured traffic). This is the
+ * stream that keeps AlphaTheta hardware unicasting live state (`0x39` mixer
+ * fader/EQ, `0x58` VU on the mixer; `0x69` slim status, waveform families on
+ * the CDJs) to our IP — subnet-broadcast presence alone (the `0x06` keep-alive)
+ * is not enough to bootstrap it.
+ */
+exports.STAGEHAND_HEARTBEAT_INTERVAL = 250;
+/**
+ * Builds a Stagehand name field for a unicast frame.
+ *
+ * Unlike the 20-byte {@link buildName} used by the broadcast announce/claim
+ * frames, unicast frames carry a 19-byte name field (offsets 11..29) with the
+ * device type / model bytes beginning at offset 30. The name is ASCII, NUL
+ * padded.
+ */
+function buildUnicastName(name) {
+    const field = new Uint8Array(19);
+    field.set(Buffer.from(name, 'ascii').subarray(0, 19));
+    return field;
+}
+/**
+ * Build the Stagehand mixer keep-alive (`0x3a`, 40 bytes).
+ *
+ * Verified byte-for-byte against the real iOS Stagehand app unicasting to a
+ * DJM-A9 at 4 Hz (Phase 4/5 captures §4.14.2). The 10-byte trailer
+ * `21 02 00 fe 00 04 00 1c 00 00` is constant across every observed sample —
+ * byte 33 (`0xfe`) is a VCDJ sentinel, not our runtime device number, so no
+ * per-device bytes vary here.
+ */
+function makeStagehandMixerHeartbeat(vcdj) {
+    const parts = [
+        ...constants_1.PROLINK_HEADER, // 0-9: magic
+        0x3a, // 10: type 0x3a (mixer keep-alive)
+        ...buildUnicastName(vcdj.name), // 11-29: name (19 bytes)
+        0x21,
+        0x02,
+        0x00,
+        0xfe,
+        0x00,
+        0x04,
+        0x00,
+        0x1c,
+        0x00,
+        0x00, // 30-39: constant trailer
+    ];
+    return Uint8Array.from(parts);
+}
+/**
+ * Build the Stagehand player keep-alive (`0x68`, 36 bytes).
+ *
+ * Verified byte-for-byte against the real iOS Stagehand app unicasting to a
+ * CDJ-3000 at ~2-4 Hz. Body (offsets 30-35) is `03 01 00 3a 00 00`: `0x03`
+ * persona/channel, `0x01` device subkind, `0x00` flag, `0x3a` Stagehand
+ * model-code stamp, two reserved bytes. Constant across every observed sample.
+ */
+function makeStagehandPlayerHeartbeat(vcdj) {
+    const parts = [
+        ...constants_1.PROLINK_HEADER, // 0-9: magic
+        0x68, // 10: type 0x68 (player keep-alive)
+        ...buildUnicastName(vcdj.name), // 11-29: name (19 bytes)
+        0x03,
+        0x01,
+        0x00,
+        0x3a,
+        0x00,
+        0x00, // 30-35: constant body
+    ];
+    return Uint8Array.from(parts);
+}
+/**
+ * Unicasts Stagehand keep-alive frames to every discovered player and mixer so
+ * that AlphaTheta hardware begins (and keeps) pushing live state to our IP.
+ *
+ * The {@link StagehandAnnouncer} makes us *visible* on the network via subnet
+ * broadcast; this heartbeat is what makes hardware actually *talk back*. It
+ * targets the mixer with `0x3a` and each CDJ with `0x68`, mirroring the real
+ * iOS Stagehand app. Frames are sent from the status socket (port 50002) to
+ * each device's port 50002, which is where their unicast state replies land and
+ * where {@link StatusEmitter} listens for them.
+ */
+class StagehandHeartbeat {
+    constructor(vcdj, statusSocket, deviceManager, logger = logger_1.noopLogger) {
+        _StagehandHeartbeat_instances.add(this);
+        _StagehandHeartbeat_statusSocket.set(this, void 0);
+        _StagehandHeartbeat_vcdj.set(this, void 0);
+        _StagehandHeartbeat_deviceManager.set(this, void 0);
+        _StagehandHeartbeat_logger.set(this, void 0);
+        _StagehandHeartbeat_intervalHandle.set(this, void 0);
+        __classPrivateFieldSet(this, _StagehandHeartbeat_vcdj, vcdj, "f");
+        __classPrivateFieldSet(this, _StagehandHeartbeat_statusSocket, statusSocket, "f");
+        __classPrivateFieldSet(this, _StagehandHeartbeat_deviceManager, deviceManager, "f");
+        __classPrivateFieldSet(this, _StagehandHeartbeat_logger, logger, "f");
+    }
+    start() {
+        if (__classPrivateFieldGet(this, _StagehandHeartbeat_intervalHandle, "f") !== undefined) {
+            return;
+        }
+        __classPrivateFieldGet(this, _StagehandHeartbeat_logger, "f").info('Starting Stagehand heartbeat (unicast keep-alive)');
+        __classPrivateFieldGet(this, _StagehandHeartbeat_instances, "m", _StagehandHeartbeat_sendHeartbeats).call(this);
+        __classPrivateFieldSet(this, _StagehandHeartbeat_intervalHandle, setInterval(() => __classPrivateFieldGet(this, _StagehandHeartbeat_instances, "m", _StagehandHeartbeat_sendHeartbeats).call(this), exports.STAGEHAND_HEARTBEAT_INTERVAL), "f");
+    }
+    stop() {
+        __classPrivateFieldGet(this, _StagehandHeartbeat_logger, "f").info('Stopping Stagehand heartbeat');
+        if (__classPrivateFieldGet(this, _StagehandHeartbeat_intervalHandle, "f") !== undefined) {
+            clearInterval(__classPrivateFieldGet(this, _StagehandHeartbeat_intervalHandle, "f"));
+            __classPrivateFieldSet(this, _StagehandHeartbeat_intervalHandle, undefined, "f");
+        }
+    }
+}
+exports.StagehandHeartbeat = StagehandHeartbeat;
+_StagehandHeartbeat_statusSocket = new WeakMap(), _StagehandHeartbeat_vcdj = new WeakMap(), _StagehandHeartbeat_deviceManager = new WeakMap(), _StagehandHeartbeat_logger = new WeakMap(), _StagehandHeartbeat_intervalHandle = new WeakMap(), _StagehandHeartbeat_instances = new WeakSet(), _StagehandHeartbeat_sendHeartbeats = function _StagehandHeartbeat_sendHeartbeats() {
+    for (const device of __classPrivateFieldGet(this, _StagehandHeartbeat_deviceManager, "f").devices.values()) {
+        // Never heartbeat ourselves.
+        if (device.id === __classPrivateFieldGet(this, _StagehandHeartbeat_vcdj, "f").id) {
+            continue;
+        }
+        let packet = null;
+        switch (device.type) {
+            case types_1.DeviceType.Mixer:
+                packet = makeStagehandMixerHeartbeat(__classPrivateFieldGet(this, _StagehandHeartbeat_vcdj, "f"));
+                break;
+            case types_1.DeviceType.CDJ:
+                packet = makeStagehandPlayerHeartbeat(__classPrivateFieldGet(this, _StagehandHeartbeat_vcdj, "f"));
+                break;
+            default:
+                // Rekordbox / other Stagehand peers are not heartbeat targets.
+                continue;
+        }
+        __classPrivateFieldGet(this, _StagehandHeartbeat_statusSocket, "f").send(packet, constants_1.STATUS_PORT, device.ip.address, err => {
+            if (err) {
+                __classPrivateFieldGet(this, _StagehandHeartbeat_logger, "f").debug(`Stagehand heartbeat to ${device.name} (${device.ip.address}) failed: ${err.message}`);
+            }
+        });
+    }
+};
 
 
 /***/ },
@@ -11428,16 +11712,16 @@ _Announcer_announceSocket = new WeakMap(), _Announcer_deviceManager = new WeakMa
 }, _Announcer_handleConflict = function _Announcer_handleConflict() {
     // Stop announcing under the contested ID
     __classPrivateFieldGet(this, _Announcer_instances, "m", _Announcer_clearTimer).call(this);
-    // Stay in whichever range we were already in. Dropping out of 1-6 would
-    // silently lose remotedb metadata for unanalyzed and streaming tracks, so
-    // a conflict on player 5 looks for another free player number first.
+    // Stay in whichever range we were already in, so a conflict on player 5
+    // looks for another free player number first rather than jumping the
+    // whole device out of the range the DJ configured it into.
     //
     // The mixer decides which of those numbers are actually safe: a player can
     // only be assigned a number its mixer has a channel for, so anything above
     // that is out of reach of the rig that just contested us.
     const devices = [...__classPrivateFieldGet(this, _Announcer_deviceManager, "f").devices.values()];
     const newId = (0, device_id_1.pickAvailableDeviceId)(devices.map(d => d.id), {
-        preferRemoteDb: __classPrivateFieldGet(this, _Announcer_vcdj, "f").id <= device_id_1.REMOTEDB_MAX_DEVICE_ID,
+        preferPlayerRange: __classPrivateFieldGet(this, _Announcer_vcdj, "f").id <= device_id_1.REMOTEDB_MAX_DEVICE_ID,
         playerCeiling: (0, device_id_1.playerNumberCeiling)(devices),
     });
     if (newId === null) {
@@ -11540,6 +11824,7 @@ _Announcer_announceSocket = new WeakMap(), _Announcer_deviceManager = new WeakMa
     __classPrivateFieldSet(this, _Announcer_intervalHandle, setInterval(sendKeepAlive, constants_1.ANNOUNCE_INTERVAL), "f");
 };
 __exportStar(__webpack_require__(/*! ./device-id */ "./src/virtualcdj/device-id.ts"), exports);
+__exportStar(__webpack_require__(/*! ./heartbeat */ "./src/virtualcdj/heartbeat.ts"), exports);
 __exportStar(__webpack_require__(/*! ./stagehand */ "./src/virtualcdj/stagehand.ts"), exports);