@myerscarpenter/quest-dev 1.4.1 → 2.0.0

package/packages/cast2-protocol/tests/mgik.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import {
+  detectSubMagic,
+  isMgikMagic,
+  packMgikSub,
+  parseMgikSub,
+} from "../src/mgik.js";
+import { MGIK_SUB_HEADER_SIZE } from "../src/constants.js";
+
+describe("MGIK", () => {
+  describe("packMgikSub / parseMgikSub round-trip", () => {
+    it("round-trips with typical values", () => {
+      const subMagic = 0xdeadbeef;
+      const msgSeq = 5;
+      const packed = packMgikSub(subMagic, msgSeq);
+      expect(packed.length).toBe(MGIK_SUB_HEADER_SIZE);
+
+      const parsed = parseMgikSub(packed);
+      expect(parsed).not.toBeNull();
+      expect(parsed!.subMagic).toBe(subMagic);
+      expect(parsed!.msgSeq).toBe(msgSeq);
+      expect(parsed!.ackSeq).toBe(msgSeq); // ack_seq defaults to msg_seq
+    });
+
+    it("includes fixed tail (0, 1, 2)", () => {
+      const packed = packMgikSub(0x12345678, 0);
+      expect(packed.readUInt32BE(12)).toBe(0);
+      expect(packed.readUInt32BE(16)).toBe(1);
+      expect(packed.readUInt32BE(20)).toBe(2);
+    });
+  });
+
+  describe("parseMgikSub", () => {
+    it("returns null for too-short buffer", () => {
+      expect(parseMgikSub(Buffer.alloc(20))).toBeNull();
+    });
+  });
+
+  describe("detectSubMagic", () => {
+    it("detects sub_magic from a valid Quest initial message", () => {
+      const buf = Buffer.alloc(MGIK_SUB_HEADER_SIZE);
+      buf.writeUInt32BE(0xaabbccdd, 0); // sub_magic
+      buf.writeUInt32BE(0, 4); // msg_seq
+      buf.writeUInt32BE(0, 8); // ack_seq
+      buf.writeUInt32BE(0, 12);
+      buf.writeUInt32BE(1, 16);
+      buf.writeUInt32BE(2, 20);
+      expect(detectSubMagic(buf)).toBe(0xaabbccdd);
+    });
+
+    it("returns null if tail signature does not match", () => {
+      const buf = Buffer.alloc(MGIK_SUB_HEADER_SIZE);
+      buf.writeUInt32BE(0xaabbccdd, 0);
+      buf.writeUInt32BE(0, 12);
+      buf.writeUInt32BE(1, 16);
+      buf.writeUInt32BE(3, 20); // wrong: should be 2
+      expect(detectSubMagic(buf)).toBeNull();
+    });
+
+    it("returns null for wrong-sized payload", () => {
+      expect(detectSubMagic(Buffer.alloc(16))).toBeNull();
+      expect(detectSubMagic(Buffer.alloc(32))).toBeNull();
+    });
+  });
+
+  describe("isMgikMagic", () => {
+    it("detects MGIK magic bytes", () => {
+      const buf = Buffer.from("MGIK", "ascii");
+      expect(isMgikMagic(buf)).toBe(true);
+    });
+
+    it("rejects non-MGIK bytes", () => {
+      expect(isMgikMagic(Buffer.from("XRSP"))).toBe(false);
+    });
+
+    it("returns false for short buffer", () => {
+      expect(isMgikMagic(Buffer.from("MG"))).toBe(false);
+    });
+  });
+});

package/packages/cast2-protocol/tests/mud.test.ts

@@ -0,0 +1,295 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildActivateLayer,
+  buildConfig,
+  buildDisconnect,
+  buildDisplayConfig,
+  buildInit,
+  buildInputForwardingState,
+  buildKeepalive,
+  buildMud,
+  buildPose,
+  buildSetProperty,
+  buildShortAck,
+  buildStartInputForwarding,
+  buildVirtualMouse,
+  packMudString,
+  parseLayerConfiguration,
+  parseMudString,
+} from "../src/mud.js";
+import {
+  CMD_ACTIVATE_LAYER,
+  CMD_CONFIG,
+  CMD_DISCONNECT,
+  CMD_DISPLAY_CONFIG,
+  CMD_INIT,
+  CMD_INPUT_FORWARDING_STATE,
+  CMD_KEEPALIVE,
+  CMD_POSE,
+  CMD_SET_PROPERTY,
+  CMD_SHORT_ACK_65,
+  CMD_START_INPUT_FORWARDING,
+  CMD_VIRTUAL_MOUSE,
+  MGIK_SUB_HEADER_SIZE,
+} from "../src/constants.js";
+import type { PoseState } from "../src/types.js";
+
+const SUB_MAGIC = 0xdeadbeef;
+
+/** Helper: read command ID from payload after sub-header. */
+function readCmd(payload: Buffer): number {
+  return payload.readUInt32BE(MGIK_SUB_HEADER_SIZE);
+}
+
+/** Helper: verify sub-header in payload. */
+function verifySubHeader(payload: Buffer, subMagic: number, seq: number) {
+  expect(payload.readUInt32BE(0)).toBe(subMagic);
+  expect(payload.readUInt32BE(4)).toBe(seq);
+}
+
+describe("MUD strings", () => {
+  describe("packMudString / parseMudString round-trip", () => {
+    it("round-trips a simple string", () => {
+      const packed = packMudString("hello");
+      const { value, nextOffset } = parseMudString(packed, 0);
+      expect(value).toBe("hello");
+      // "hello" = 5 bytes, padded to 8, plus 4 byte length prefix = 12
+      expect(nextOffset).toBe(12);
+    });
+
+    it("round-trips an aligned string (4 bytes)", () => {
+      const packed = packMudString("test");
+      const { value, nextOffset } = parseMudString(packed, 0);
+      expect(value).toBe("test");
+      expect(nextOffset).toBe(8); // 4 len + 4 data, no padding needed
+    });
+
+    it("round-trips empty string", () => {
+      const packed = packMudString("");
+      const { value, nextOffset } = parseMudString(packed, 0);
+      expect(value).toBe("");
+      expect(nextOffset).toBe(4); // just the length prefix
+    });
+
+    it("handles UTF-8", () => {
+      const packed = packMudString("caf\u00e9");
+      const { value } = parseMudString(packed, 0);
+      expect(value).toBe("caf\u00e9");
+    });
+  });
+
+  describe("parseMudString edge cases", () => {
+    it("returns empty for offset at buffer end", () => {
+      const { value, nextOffset } = parseMudString(Buffer.alloc(4), 4);
+      expect(value).toBe("");
+      expect(nextOffset).toBe(4);
+    });
+  });
+});
+
+describe("MUD builders", () => {
+  describe("buildInit", () => {
+    it("builds correct init payload", () => {
+      const payload = buildInit(SUB_MAGIC, 0);
+      verifySubHeader(payload, SUB_MAGIC, 0);
+      expect(readCmd(payload)).toBe(CMD_INIT);
+      // 16 zero bytes after command
+      const trailing = payload.subarray(MGIK_SUB_HEADER_SIZE + 4);
+      expect(trailing.length).toBe(16);
+      expect(trailing.every((b) => b === 0)).toBe(true);
+    });
+  });
+
+  describe("buildConfig", () => {
+    it("encodes width, height, uuid, and timestamp", () => {
+      const payload = buildConfig(SUB_MAGIC, 1, 2064, 1162, "test-uuid", "12345");
+      verifySubHeader(payload, SUB_MAGIC, 1);
+      expect(readCmd(payload)).toBe(CMD_CONFIG);
+      // Width at sub_header(24) + cmd(4) + offset 4
+      expect(payload.readUInt32BE(MGIK_SUB_HEADER_SIZE + 4)).toBe(2064);
+      expect(payload.readUInt32BE(MGIK_SUB_HEADER_SIZE + 8)).toBe(1162);
+    });
+  });
+
+  describe("buildKeepalive", () => {
+    it("encodes ack value and strings", () => {
+      const payload = buildKeepalive(SUB_MAGIC, 5, 0xc8, "uuid1", "ts1");
+      verifySubHeader(payload, SUB_MAGIC, 5);
+      expect(readCmd(payload)).toBe(CMD_KEEPALIVE);
+      expect(payload.readUInt32BE(MGIK_SUB_HEADER_SIZE + 4)).toBe(0xc8);
+    });
+  });
+
+  describe("buildShortAck", () => {
+    it("encodes command and zero", () => {
+      const payload = buildShortAck(SUB_MAGIC, 3, CMD_SHORT_ACK_65);
+      verifySubHeader(payload, SUB_MAGIC, 3);
+      expect(readCmd(payload)).toBe(CMD_SHORT_ACK_65);
+      expect(payload.readUInt32BE(MGIK_SUB_HEADER_SIZE + 4)).toBe(0);
+    });
+  });
+
+  describe("buildPose", () => {
+    it("encodes pose with correct wire order", () => {
+      const pose: PoseState = {
+        x: 1.0, y: 2.0, z: 3.0,
+        qw: 1.0, qx: 0.0, qy: 0.0, qz: 0.0,
+        yaw: 0, pitch: 0,
+      };
+      const payload = buildPose(SUB_MAGIC, 0, pose);
+      verifySubHeader(payload, SUB_MAGIC, 0);
+      expect(readCmd(payload)).toBe(CMD_POSE);
+      const off = MGIK_SUB_HEADER_SIZE + 4;
+      // Wire order: type(0), posX, posY, posZ, qw, qx, qy, qz
+      expect(payload.readFloatBE(off)).toBeCloseTo(0.0); // type
+      expect(payload.readFloatBE(off + 4)).toBeCloseTo(1.0); // x
+      expect(payload.readFloatBE(off + 8)).toBeCloseTo(2.0); // y
+      expect(payload.readFloatBE(off + 12)).toBeCloseTo(3.0); // z
+      expect(payload.readFloatBE(off + 16)).toBeCloseTo(1.0); // qw
+      expect(payload.readFloatBE(off + 20)).toBeCloseTo(0.0); // qx
+      expect(payload.readFloatBE(off + 24)).toBeCloseTo(0.0); // qy
+      expect(payload.readFloatBE(off + 28)).toBeCloseTo(0.0); // qz
+      // Total: sub_header(24) + cmd(4) + 8 floats(32) = 60 bytes
+      expect(payload.length).toBe(MGIK_SUB_HEADER_SIZE + 36);
+    });
+  });
+
+  describe("buildDisplayConfig", () => {
+    it("encodes width and height", () => {
+      const payload = buildDisplayConfig(SUB_MAGIC, 0, 1920, 1080);
+      verifySubHeader(payload, SUB_MAGIC, 0);
+      expect(readCmd(payload)).toBe(CMD_DISPLAY_CONFIG);
+      expect(payload.readUInt32BE(MGIK_SUB_HEADER_SIZE + 4)).toBe(1920);
+      expect(payload.readUInt32BE(MGIK_SUB_HEADER_SIZE + 8)).toBe(1080);
+    });
+  });
+
+  describe("buildDisconnect", () => {
+    it("has only command ID", () => {
+      const payload = buildDisconnect(SUB_MAGIC, 0);
+      verifySubHeader(payload, SUB_MAGIC, 0);
+      expect(readCmd(payload)).toBe(CMD_DISCONNECT);
+      expect(payload.length).toBe(MGIK_SUB_HEADER_SIZE + 4);
+    });
+  });
+
+  describe("buildSetProperty", () => {
+    it("encodes name and value strings", () => {
+      const payload = buildSetProperty(SUB_MAGIC, 0, "key", "val");
+      verifySubHeader(payload, SUB_MAGIC, 0);
+      expect(readCmd(payload)).toBe(CMD_SET_PROPERTY);
+      // Parse name string after cmd
+      const nameResult = parseMudString(payload, MGIK_SUB_HEADER_SIZE + 4);
+      expect(nameResult.value).toBe("key");
+      const valueResult = parseMudString(payload, nameResult.nextOffset);
+      expect(valueResult.value).toBe("val");
+    });
+  });
+
+  describe("buildVirtualMouse", () => {
+    it("encodes layer, action, and coordinates", () => {
+      const payload = buildVirtualMouse(SUB_MAGIC, 0, 5, 3, 0.5, 0.5);
+      verifySubHeader(payload, SUB_MAGIC, 0);
+      expect(readCmd(payload)).toBe(CMD_VIRTUAL_MOUSE);
+      const off = MGIK_SUB_HEADER_SIZE + 4;
+      expect(payload.readUInt32BE(off)).toBe(5); // layerId
+      expect(payload.readUInt32BE(off + 4)).toBe(3); // action
+      expect(payload.readFloatBE(off + 8)).toBeCloseTo(0.5); // x
+      expect(payload.readFloatBE(off + 12)).toBeCloseTo(0.5); // y
+    });
+  });
+
+  describe("buildInputForwardingState", () => {
+    it("encodes state value", () => {
+      const payload = buildInputForwardingState(SUB_MAGIC, 0, 1);
+      expect(readCmd(payload)).toBe(CMD_INPUT_FORWARDING_STATE);
+      expect(payload.readUInt32BE(MGIK_SUB_HEADER_SIZE + 4)).toBe(1);
+    });
+  });
+
+  describe("buildStartInputForwarding", () => {
+    it("has only command ID", () => {
+      const payload = buildStartInputForwarding(SUB_MAGIC, 0);
+      expect(readCmd(payload)).toBe(CMD_START_INPUT_FORWARDING);
+      expect(payload.length).toBe(MGIK_SUB_HEADER_SIZE + 4);
+    });
+  });
+
+  describe("buildActivateLayer", () => {
+    it("encodes layer ID", () => {
+      const payload = buildActivateLayer(SUB_MAGIC, 0, 42);
+      expect(readCmd(payload)).toBe(CMD_ACTIVATE_LAYER);
+      expect(payload.readUInt32BE(MGIK_SUB_HEADER_SIZE + 4)).toBe(42);
+    });
+  });
+
+  describe("buildMud", () => {
+    it("builds arbitrary MUD with payload", () => {
+      const extra = Buffer.from([0x01, 0x02]);
+      const payload = buildMud(SUB_MAGIC, 0, 999, extra);
+      expect(readCmd(payload)).toBe(999);
+      expect(payload[MGIK_SUB_HEADER_SIZE + 4]).toBe(0x01);
+      expect(payload[MGIK_SUB_HEADER_SIZE + 5]).toBe(0x02);
+    });
+
+    it("builds MUD without payload", () => {
+      const payload = buildMud(SUB_MAGIC, 0, 999);
+      expect(payload.length).toBe(MGIK_SUB_HEADER_SIZE + 4);
+    });
+  });
+});
+
+describe("parseLayerConfiguration", () => {
+  it("parses a full layer configuration", () => {
+    // Build a mock LayerConfiguration payload
+    const buf = Buffer.alloc(128);
+    let off = 0;
+    buf.writeUInt32BE(0x12c, off); off += 4; // cmd
+    buf.writeUInt32BE(7, off); off += 4; // id
+    buf.writeUInt32BE(1920, off); off += 4; // width
+    buf.writeUInt32BE(1080, off); off += 4; // height
+    buf.writeFloatBE(0.0, off); off += 4; // posX
+    buf.writeFloatBE(0.0, off); off += 4; // posY
+    buf.writeFloatBE(1.0, off); off += 4; // depth
+    buf.writeUInt32BE(0, off); off += 4; // type = PANEL_APP
+
+    // Strings: appName, layerName, serial, pkg
+    const strings = ["MyApp", "main", "SERIAL123", "com.test.app"];
+    for (const s of strings) {
+      const raw = Buffer.from(s);
+      buf.writeUInt32BE(raw.length, off); off += 4;
+      raw.copy(buf, off); off += raw.length;
+      off += (4 - (raw.length % 4)) % 4;
+    }
+
+    const result = parseLayerConfiguration(buf.subarray(0, off));
+    expect(result).not.toBeNull();
+    expect(result!.id).toBe(7);
+    expect(result!.width).toBe(1920);
+    expect(result!.height).toBe(1080);
+    expect(result!.depth).toBeCloseTo(1.0);
+    expect(result!.type).toBe(0);
+    expect(result!.typeName).toBe("PANEL_APP");
+    expect(result!.app).toBe("MyApp");
+    expect(result!.layer).toBe("main");
+    expect(result!.serial).toBe("SERIAL123");
+    expect(result!.pkg).toBe("com.test.app");
+  });
+
+  it("returns null for too-short payload", () => {
+    expect(parseLayerConfiguration(Buffer.alloc(16))).toBeNull();
+  });
+
+  it("handles unknown layer type", () => {
+    const buf = Buffer.alloc(32);
+    buf.writeUInt32BE(0x12c, 0);
+    buf.writeUInt32BE(1, 4);
+    buf.writeUInt32BE(800, 8);
+    buf.writeUInt32BE(600, 12);
+    buf.writeUInt32BE(99, 28); // unknown type
+
+    const result = parseLayerConfiguration(buf);
+    expect(result).not.toBeNull();
+    expect(result!.typeName).toBe("UNKNOWN(99)");
+  });
+});

package/packages/cast2-protocol/tests/pose.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it } from "vitest";
+import {
+  createPoseState,
+  eulerToQuat,
+  screenToYawPitch,
+  setPoseOffset,
+  updatePose,
+} from "../src/pose.js";
+
+describe("pose", () => {
+  describe("createPoseState", () => {
+    it("returns identity pose at origin", () => {
+      const pose = createPoseState();
+      expect(pose.x).toBe(0);
+      expect(pose.y).toBe(0);
+      expect(pose.z).toBe(0);
+      expect(pose.qw).toBe(1);
+      expect(pose.qx).toBe(0);
+      expect(pose.qy).toBe(0);
+      expect(pose.qz).toBe(0);
+      expect(pose.yaw).toBe(0);
+      expect(pose.pitch).toBe(0);
+    });
+  });
+
+  describe("eulerToQuat", () => {
+    it("returns identity quaternion for zero yaw/pitch", () => {
+      const q = eulerToQuat(0, 0);
+      expect(q.qw).toBeCloseTo(1);
+      expect(q.qx).toBeCloseTo(0);
+      expect(q.qy).toBeCloseTo(0);
+      expect(q.qz).toBeCloseTo(0);
+    });
+
+    it("produces unit quaternion for 90-degree yaw", () => {
+      const q = eulerToQuat(Math.PI / 2, 0);
+      const mag = Math.sqrt(q.qw ** 2 + q.qx ** 2 + q.qy ** 2 + q.qz ** 2);
+      expect(mag).toBeCloseTo(1);
+    });
+
+    it("produces unit quaternion for arbitrary angles", () => {
+      const q = eulerToQuat(0.7, -0.3);
+      const mag = Math.sqrt(q.qw ** 2 + q.qx ** 2 + q.qy ** 2 + q.qz ** 2);
+      expect(mag).toBeCloseTo(1);
+    });
+
+    it("handles 180-degree yaw", () => {
+      const q = eulerToQuat(Math.PI, 0);
+      const mag = Math.sqrt(q.qw ** 2 + q.qx ** 2 + q.qy ** 2 + q.qz ** 2);
+      expect(mag).toBeCloseTo(1);
+    });
+  });
+
+  describe("updatePose", () => {
+    it("applies yaw increment", () => {
+      const pose = createPoseState();
+      const updated = updatePose(pose, { dYaw: 0.5 });
+      expect(updated.yaw).toBeCloseTo(0.5);
+      // Position shouldn't change without forward/strafe
+      expect(updated.x).toBeCloseTo(0);
+      expect(updated.y).toBeCloseTo(0);
+      expect(updated.z).toBeCloseTo(0);
+    });
+
+    it("clamps pitch to ±π/2", () => {
+      const pose = createPoseState();
+      const up = updatePose(pose, { dPitch: 5.0 });
+      expect(up.pitch).toBeCloseTo(Math.PI / 2);
+
+      const down = updatePose(pose, { dPitch: -5.0 });
+      expect(down.pitch).toBeCloseTo(-Math.PI / 2);
+    });
+
+    it("moves forward in facing direction", () => {
+      const pose = createPoseState(); // facing -Z (yaw=0)
+      const moved = updatePose(pose, { dForward: 1.0 });
+      expect(moved.z).toBeCloseTo(-1.0);
+      expect(moved.x).toBeCloseTo(0);
+    });
+
+    it("moves forward in rotated direction", () => {
+      let pose = createPoseState();
+      pose = updatePose(pose, { dYaw: Math.PI / 2 }); // face -X
+      const moved = updatePose(pose, { dForward: 1.0 });
+      expect(moved.x).toBeCloseTo(-1.0);
+      expect(moved.z).toBeCloseTo(0, 5);
+    });
+
+    it("strafes perpendicular to facing", () => {
+      const pose = createPoseState(); // facing -Z, strafe right = +X
+      const moved = updatePose(pose, { dStrafe: 1.0 });
+      expect(moved.x).toBeCloseTo(1.0);
+      expect(moved.z).toBeCloseTo(0);
+    });
+
+    it("applies vertical movement", () => {
+      const pose = createPoseState();
+      const moved = updatePose(pose, { dUp: 0.5 });
+      expect(moved.y).toBeCloseTo(0.5);
+    });
+
+    it("does not mutate the original state", () => {
+      const pose = createPoseState();
+      updatePose(pose, { dYaw: 1.0, dForward: 1.0 });
+      expect(pose.yaw).toBe(0);
+      expect(pose.x).toBe(0);
+    });
+
+    it("updates quaternion after movement", () => {
+      const pose = createPoseState();
+      const moved = updatePose(pose, { dYaw: Math.PI / 4 });
+      // Quaternion should not be identity anymore
+      expect(moved.qw).not.toBeCloseTo(1);
+      // But should still be unit
+      const mag = Math.sqrt(moved.qw ** 2 + moved.qx ** 2 + moved.qy ** 2 + moved.qz ** 2);
+      expect(mag).toBeCloseTo(1);
+    });
+  });
+
+  describe("setPoseOffset", () => {
+    it("sets position fields", () => {
+      const pose = createPoseState();
+      const updated = setPoseOffset(pose, { x: 1, y: 2, z: 3 });
+      expect(updated.x).toBe(1);
+      expect(updated.y).toBe(2);
+      expect(updated.z).toBe(3);
+    });
+
+    it("sets orientation fields", () => {
+      const pose = createPoseState();
+      const updated = setPoseOffset(pose, { yaw: 0.5, pitch: 0.3 });
+      expect(updated.yaw).toBeCloseTo(0.5);
+      expect(updated.pitch).toBeCloseTo(0.3);
+    });
+
+    it("preserves unset fields", () => {
+      const pose = setPoseOffset(createPoseState(), { x: 5, yaw: 1 });
+      const updated = setPoseOffset(pose, { y: 10 });
+      expect(updated.x).toBe(5);
+      expect(updated.y).toBe(10);
+      expect(updated.yaw).toBeCloseTo(1);
+    });
+
+    it("does not mutate the original", () => {
+      const pose = createPoseState();
+      setPoseOffset(pose, { x: 99 });
+      expect(pose.x).toBe(0);
+    });
+  });
+
+  describe("screenToYawPitch", () => {
+    it("maps screen center to current orientation", () => {
+      const result = screenToYawPitch(0.5, 0.5, 0, 0, 1920, 1080);
+      expect(result.yaw).toBeCloseTo(0);
+      expect(result.pitch).toBeCloseTo(0);
+    });
+
+    it("maps left edge to positive yaw offset", () => {
+      const result = screenToYawPitch(0, 0.5, 0, 0, 1920, 1080);
+      expect(result.yaw).toBeGreaterThan(0);
+    });
+
+    it("maps right edge to negative yaw offset", () => {
+      const result = screenToYawPitch(1, 0.5, 0, 0, 1920, 1080);
+      expect(result.yaw).toBeLessThan(0);
+    });
+
+    it("respects current yaw", () => {
+      const result = screenToYawPitch(0.5, 0.5, 1.0, 0, 1920, 1080);
+      expect(result.yaw).toBeCloseTo(1.0);
+    });
+  });
+});

package/packages/cast2-protocol/tests/xrsp.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import {
+  packXrsp,
+  parseXrspHeader,
+  xrspPayloadSize,
+} from "../src/xrsp.js";
+import {
+  XRSP_FLAGS_STANDARD,
+  XRSP_HEADER_SIZE,
+  XRSP_TOPIC_CAST,
+} from "../src/constants.js";
+
+describe("XRSP", () => {
+  describe("packXrsp / parseXrspHeader round-trip", () => {
+    it("round-trips with empty payload", () => {
+      const packed = packXrsp(0, Buffer.alloc(0));
+      expect(packed.length).toBe(XRSP_HEADER_SIZE); // header only, word_count=1
+      const header = parseXrspHeader(packed);
+      expect(header.flags).toBe(XRSP_FLAGS_STANDARD);
+      expect(header.topic).toBe(XRSP_TOPIC_CAST);
+      expect(header.wordCount).toBe(1);
+      expect(header.seq).toBe(0);
+      expect(xrspPayloadSize(header)).toBe(0);
+    });
+
+    it("round-trips with 4-byte aligned payload", () => {
+      const payload = Buffer.from([0x01, 0x02, 0x03, 0x04]);
+      const packed = packXrsp(42, payload);
+      expect(packed.length).toBe(XRSP_HEADER_SIZE + 4);
+      const header = parseXrspHeader(packed);
+      expect(header.wordCount).toBe(2); // 4 bytes / 4 + 1
+      expect(header.seq).toBe(42);
+      expect(xrspPayloadSize(header)).toBe(4);
+      // Verify payload preserved
+      expect(packed.subarray(XRSP_HEADER_SIZE)).toEqual(payload);
+    });
+
+    it("pads non-aligned payload to 4 bytes", () => {
+      const payload = Buffer.from([0xaa, 0xbb]); // 2 bytes → padded to 4
+      const packed = packXrsp(1, payload);
+      expect(packed.length).toBe(XRSP_HEADER_SIZE + 4);
+      const header = parseXrspHeader(packed);
+      expect(header.wordCount).toBe(2);
+      // First 2 bytes are payload, next 2 are zero padding
+      expect(packed[XRSP_HEADER_SIZE]).toBe(0xaa);
+      expect(packed[XRSP_HEADER_SIZE + 1]).toBe(0xbb);
+      expect(packed[XRSP_HEADER_SIZE + 2]).toBe(0);
+      expect(packed[XRSP_HEADER_SIZE + 3]).toBe(0);
+    });
+
+    it("pads 5-byte payload to 8 bytes", () => {
+      const payload = Buffer.alloc(5, 0xff);
+      const packed = packXrsp(0, payload);
+      expect(packed.length).toBe(XRSP_HEADER_SIZE + 8);
+      const header = parseXrspHeader(packed);
+      expect(header.wordCount).toBe(3); // 8/4 + 1
+      expect(xrspPayloadSize(header)).toBe(8);
+    });
+
+    it("preserves custom flags", () => {
+      const packed = packXrsp(0, Buffer.alloc(0), 0x18);
+      const header = parseXrspHeader(packed);
+      expect(header.flags).toBe(0x18);
+    });
+
+    it("masks topic to 6 bits", () => {
+      // Topic byte on wire might have high bits, parseXrspHeader masks to 0x3F
+      const buf = Buffer.alloc(XRSP_HEADER_SIZE);
+      buf.writeUInt8(0x10, 0); // flags
+      buf.writeUInt8(0xc2, 1); // topic = 0xC2, masked = 0x02
+      buf.writeUInt16LE(1, 2);
+      const header = parseXrspHeader(buf);
+      expect(header.topic).toBe(2);
+    });
+  });
+
+  describe("parseXrspHeader", () => {
+    it("throws on too-short buffer", () => {
+      expect(() => parseXrspHeader(Buffer.alloc(4))).toThrow();
+    });
+  });
+
+  describe("sequence number wrapping", () => {
+    it("handles high sequence numbers", () => {
+      const packed = packXrsp(65535, Buffer.alloc(0));
+      const header = parseXrspHeader(packed);
+      expect(header.seq).toBe(65535);
+    });
+  });
+});

package/packages/cast2-protocol/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./build",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "build"]
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - "packages/*"