@myerscarpenter/quest-dev 1.4.0 → 2.0.0

package/packages/cast2-protocol/src/constants.ts

@@ -0,0 +1,65 @@
+/** XRSP / MGIK / MUD protocol constants for Cast 2.0. */
+
+// XRSP header
+export const XRSP_FLAGS_STANDARD = 0x10;
+export const XRSP_FLAGS_ALIGNMENT_PAD = 0x18;
+export const XRSP_TOPIC_CAST = 2;
+export const XRSP_HEADER_SIZE = 8;
+
+// Markers
+export const VIDEO_META_MARKER = 0x64;
+export const ACK_MARKER = 0x03;
+export const CONFIG_MARKER = 0x12c; // LayerConfiguration (300)
+export const MGIK_MAGIC = 0x4d47494b; // "MGIK" as big-endian u32
+
+// MGIK sub-header tail signature: (0, 1, 2)
+export const MGIK_TAIL_SIGNATURE = [0, 1, 2] as const;
+export const MGIK_SUB_HEADER_SIZE = 24;
+
+// MUD command IDs
+export const CMD_KEEPALIVE = 0x04;
+export const CMD_CONFIG = 0x07;
+export const CMD_DISCONNECT = 0x08;
+export const CMD_DISPLAY_CONFIG = 0x09;
+export const CMD_SET_PROPERTY = 10; // 0x0a
+export const CMD_SHORT_ACK_65 = 0x65;
+export const CMD_VIDEO_META = 0x64;
+export const CMD_POSE = 0xce;
+export const CMD_SHORT_ACK_CD = 0xcd;
+export const CMD_VIRTUAL_MOUSE = 200; // 0xc8
+export const CMD_INPUT_FORWARDING_STATE = 205; // 0xcd
+export const CMD_START_INPUT_FORWARDING = 207; // 0xcf
+export const CMD_INIT = 0x258;
+export const CMD_LAYER_CONFIGURATION = 0x12c; // 300
+export const CMD_SHORT_ACK_12D = 0x12d;
+export const CMD_ACTIVATE_LAYER = 301; // 0x12d
+
+// VirtualMouse actions
+export const MOUSE_MOVE = 1;
+export const MOUSE_DOWN = 3;
+export const MOUSE_UP = 4;
+
+// Input forwarding states
+export const INPUT_STATE_NORMAL = 0;
+export const INPUT_STATE_CAMERA = 1;
+
+// Layer types
+export const LAYER_PANEL_APP = 0;
+export const LAYER_EYE_BUFFER = 1;
+export const LAYER_AETHER_APP = 2;
+export const LAYER_VOLUMETRIC_WINDOW = 3;
+
+export const LAYER_TYPE_NAMES: Record<number, string> = {
+  [LAYER_PANEL_APP]: "PANEL_APP",
+  [LAYER_EYE_BUFFER]: "EYE_BUFFER",
+  [LAYER_AETHER_APP]: "AETHER_APP",
+  [LAYER_VOLUMETRIC_WINDOW]: "VOLUMETRIC_WINDOW",
+};
+
+// Cast TCP ports — MQDH uses 4446 for debug.oculus.magic.port, maps both 4445 and 4446
+export const CAST_PORT = 4445;
+export const QUEST_CAST_PORT = 4446;
+
+// Keepalive ack value progression
+export const KEEPALIVE_INITIAL_ACK = 0xc8;
+export const KEEPALIVE_ACK_INCREMENT = 0xc8;

package/packages/cast2-protocol/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./constants.js";
+export * from "./types.js";
+export * from "./xrsp.js";
+export * from "./mgik.js";
+export * from "./mud.js";
+export * from "./pose.js";
+export * from "./resolutions.js";

package/packages/cast2-protocol/src/mgik.ts

@@ -0,0 +1,69 @@
+/**
+ * MGIK sub-header packing and parsing.
+ *
+ * MGIK sub-header is 24 bytes, big-endian:
+ *   sub_magic(4 BE) + msg_seq(4 BE) + ack_seq(4 BE) + 0(4 BE) + 1(4 BE) + 2(4 BE)
+ *
+ * The sub_magic is learned from the Quest's first message.
+ * The tail (0, 1, 2) is a fixed signature.
+ */
+
+import { MGIK_MAGIC, MGIK_SUB_HEADER_SIZE } from "./constants.js";
+import type { MgikSubHeader } from "./types.js";
+
+/**
+ * Pack a MGIK sub-header (24 bytes, big-endian).
+ * ack_seq defaults to msg_seq (matching the Python implementation).
+ */
+export function packMgikSub(subMagic: number, msgSeq: number): Buffer {
+  const buf = Buffer.alloc(MGIK_SUB_HEADER_SIZE);
+  buf.writeUInt32BE(subMagic, 0);
+  buf.writeUInt32BE(msgSeq, 4);
+  buf.writeUInt32BE(msgSeq, 8); // ack_seq = msg_seq
+  buf.writeUInt32BE(0, 12);
+  buf.writeUInt32BE(1, 16);
+  buf.writeUInt32BE(2, 20);
+  return buf;
+}
+
+/**
+ * Parse a MGIK sub-header from a buffer.
+ * Returns null if the buffer is too small.
+ */
+export function parseMgikSub(data: Buffer): MgikSubHeader | null {
+  if (data.length < MGIK_SUB_HEADER_SIZE) {
+    return null;
+  }
+  return {
+    subMagic: data.readUInt32BE(0),
+    msgSeq: data.readUInt32BE(4),
+    ackSeq: data.readUInt32BE(8),
+  };
+}
+
+/**
+ * Detect the sub_magic from a Quest initial message.
+ *
+ * The Quest sends a 24-byte payload where the last 12 bytes are (0, 1, 2).
+ * The first 4 bytes are the sub_magic value.
+ */
+export function detectSubMagic(payload: Buffer): number | null {
+  if (payload.length !== MGIK_SUB_HEADER_SIZE) {
+    return null;
+  }
+  const tail0 = payload.readUInt32BE(12);
+  const tail1 = payload.readUInt32BE(16);
+  const tail2 = payload.readUInt32BE(20);
+  if (tail0 === 0 && tail1 === 1 && tail2 === 2) {
+    return payload.readUInt32BE(0);
+  }
+  return null;
+}
+
+/**
+ * Check if the first 4 bytes of payload match "MGIK" magic.
+ */
+export function isMgikMagic(payload: Buffer): boolean {
+  if (payload.length < 4) return false;
+  return payload.readUInt32BE(0) === MGIK_MAGIC;
+}

package/packages/cast2-protocol/src/mud.ts

@@ -0,0 +1,294 @@
+/**
+ * MUD (Messages Under Delivery) message builders and parsers.
+ *
+ * All MUD payloads are big-endian and prefixed with a MGIK sub-header.
+ * Each builder returns a complete XRSP payload: sub_header + command_id + body.
+ */
+
+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_START_INPUT_FORWARDING,
+  CMD_VIRTUAL_MOUSE,
+  LAYER_TYPE_NAMES,
+} from "./constants.js";
+import { packMgikSub } from "./mgik.js";
+import type { LayerInfo, PoseState } from "./types.js";
+
+/**
+ * Pack a MUD-style length-prefixed string with 4-byte alignment padding.
+ */
+export function packMudString(s: string): Buffer {
+  const raw = Buffer.from(s, "utf-8");
+  const padLen = (4 - (raw.length % 4)) % 4;
+  const buf = Buffer.alloc(4 + raw.length + padLen);
+  buf.writeUInt32BE(raw.length, 0);
+  raw.copy(buf, 4);
+  return buf;
+}
+
+/**
+ * Parse a MUD-style length-prefixed string from a buffer at an offset.
+ * Returns the parsed string and the next offset (after alignment padding).
+ */
+export function parseMudString(
+  buf: Buffer,
+  offset: number,
+): { value: string; nextOffset: number } {
+  if (offset + 4 > buf.length) {
+    return { value: "", nextOffset: buf.length };
+  }
+  const slen = buf.readUInt32BE(offset);
+  offset += 4;
+  if (offset + slen > buf.length) {
+    return { value: "", nextOffset: buf.length };
+  }
+  const value = buf.subarray(offset, offset + slen).toString("utf-8");
+  offset += slen;
+  offset += (4 - (slen % 4)) % 4; // alignment padding
+  return { value, nextOffset: offset };
+}
+
+/** Build Init command (0x258) payload. */
+export function buildInit(subMagic: number, seq: number): Buffer {
+  const sub = packMgikSub(subMagic, seq);
+  const body = Buffer.alloc(4 + 16); // cmd + 16 zero bytes
+  body.writeUInt32BE(CMD_INIT, 0);
+  return Buffer.concat([sub, body]);
+}
+
+/** Build Config command (0x07) payload. */
+export function buildConfig(
+  subMagic: number,
+  seq: number,
+  width: number,
+  height: number,
+  uuid: string,
+  timestamp: string,
+): Buffer {
+  const sub = packMgikSub(subMagic, seq);
+  // cmd(4) + width(4) + height(4) + 0(4) + 1(4) + 0(4) + 0(4) = 28 bytes
+  const body = Buffer.alloc(28);
+  body.writeUInt32BE(CMD_CONFIG, 0);
+  body.writeUInt32BE(width, 4);
+  body.writeUInt32BE(height, 8);
+  body.writeUInt32BE(0, 12);
+  body.writeUInt32BE(1, 16);
+  body.writeUInt32BE(0, 20);
+  body.writeUInt32BE(0, 24);
+  const uuidStr = packMudString(uuid);
+  const tsStr = packMudString(timestamp);
+  return Buffer.concat([sub, body, uuidStr, tsStr]);
+}
+
+/** Build Keepalive command (0x04) payload. */
+export function buildKeepalive(
+  subMagic: number,
+  msgSeq: number,
+  ackVal: number,
+  uuid: string,
+  timestamp: string,
+): Buffer {
+  const sub = packMgikSub(subMagic, msgSeq);
+  const body = Buffer.alloc(8);
+  body.writeUInt32BE(CMD_KEEPALIVE, 0);
+  body.writeUInt32BE(ackVal, 4);
+  const uuidStr = packMudString(uuid);
+  const tsStr = packMudString(timestamp);
+  return Buffer.concat([sub, body, uuidStr, tsStr]);
+}
+
+/** Build short ack payload (sub_header + cmd + 0). */
+export function buildShortAck(
+  subMagic: number,
+  msgSeq: number,
+  cmd: number,
+): Buffer {
+  const sub = packMgikSub(subMagic, msgSeq);
+  const body = Buffer.alloc(8);
+  body.writeUInt32BE(cmd, 0);
+  body.writeUInt32BE(0, 4);
+  return Buffer.concat([sub, body]);
+}
+
+/** Build Pose command (0xCE) payload. */
+export function buildPose(subMagic: number, seq: number, pose: PoseState): Buffer {
+  const sub = packMgikSub(subMagic, seq);
+  // cmd(4) + 8 floats (32 bytes) = 36 bytes
+  const body = Buffer.alloc(36);
+  body.writeUInt32BE(CMD_POSE, 0);
+  // Wire order: type(0), posX, posY, posZ, qw, qx, qy, qz
+  body.writeFloatBE(0.0, 4);
+  body.writeFloatBE(pose.x, 8);
+  body.writeFloatBE(pose.y, 12);
+  body.writeFloatBE(pose.z, 16);
+  body.writeFloatBE(pose.qw, 20);
+  body.writeFloatBE(pose.qx, 24);
+  body.writeFloatBE(pose.qy, 28);
+  body.writeFloatBE(pose.qz, 32);
+  return Buffer.concat([sub, body]);
+}
+
+/** Eye selector values for DisplayConfig (cmd 0x09). */
+export const EYE_RIGHT = 0;
+export const EYE_LEFT = 1;
+export const EYE_STEREO = 2;
+
+/** Build DisplayConfig / RES_CHANGE command (0x09) payload. */
+export function buildDisplayConfig(
+  subMagic: number,
+  seq: number,
+  width: number,
+  height: number,
+  eye: number = EYE_LEFT,
+): Buffer {
+  const sub = packMgikSub(subMagic, seq);
+  // Wire: u32(cmd) + u32(width) + u32(height) + u32(0) + u32(eye) + u32(0) + u32(0)
+  const body = Buffer.alloc(4 * 7);
+  body.writeUInt32BE(CMD_DISPLAY_CONFIG, 0);
+  body.writeUInt32BE(width, 4);
+  body.writeUInt32BE(height, 8);
+  body.writeUInt32BE(eye, 16);
+  return Buffer.concat([sub, body]);
+}
+
+/** Build Disconnect command (0x08) payload. */
+export function buildDisconnect(subMagic: number, seq: number): Buffer {
+  const sub = packMgikSub(subMagic, seq);
+  const body = Buffer.alloc(4);
+  body.writeUInt32BE(CMD_DISCONNECT, 0);
+  return Buffer.concat([sub, body]);
+}
+
+/** Build SetProperty MUD type 10 payload. */
+export function buildSetProperty(
+  subMagic: number,
+  seq: number,
+  name: string,
+  value: string,
+): Buffer {
+  const sub = packMgikSub(subMagic, seq);
+  const cmd = Buffer.alloc(4);
+  cmd.writeUInt32BE(CMD_SET_PROPERTY, 0);
+  return Buffer.concat([sub, cmd, packMudString(name), packMudString(value)]);
+}
+
+/** Build VirtualMouse MUD type 200 payload. */
+export function buildVirtualMouse(
+  subMagic: number,
+  seq: number,
+  layerId: number,
+  action: number,
+  x: number,
+  y: number,
+): Buffer {
+  const sub = packMgikSub(subMagic, seq);
+  const body = Buffer.alloc(4 + 4 + 4 + 4 + 4); // cmd + layerId + action + x(f32) + y(f32)
+  body.writeUInt32BE(CMD_VIRTUAL_MOUSE, 0);
+  body.writeUInt32BE(layerId, 4);
+  body.writeUInt32BE(action, 8);
+  body.writeFloatBE(x, 12);
+  body.writeFloatBE(y, 16);
+  return Buffer.concat([sub, body]);
+}
+
+/** Build InputForwardingStateChange MUD type 205 payload. */
+export function buildInputForwardingState(
+  subMagic: number,
+  seq: number,
+  state: number,
+): Buffer {
+  const sub = packMgikSub(subMagic, seq);
+  const body = Buffer.alloc(8);
+  body.writeUInt32BE(CMD_INPUT_FORWARDING_STATE, 0);
+  body.writeUInt32BE(state, 4);
+  return Buffer.concat([sub, body]);
+}
+
+/** Build StartInputForwarding MUD type 207 payload. */
+export function buildStartInputForwarding(
+  subMagic: number,
+  seq: number,
+): Buffer {
+  const sub = packMgikSub(subMagic, seq);
+  const cmd = Buffer.alloc(4);
+  cmd.writeUInt32BE(CMD_START_INPUT_FORWARDING, 0);
+  return Buffer.concat([sub, cmd]);
+}
+
+/** Build ActivateLayer MUD type 301 payload. */
+export function buildActivateLayer(
+  subMagic: number,
+  seq: number,
+  layerId: number,
+): Buffer {
+  const sub = packMgikSub(subMagic, seq);
+  const body = Buffer.alloc(8);
+  body.writeUInt32BE(CMD_ACTIVATE_LAYER, 0);
+  body.writeUInt32BE(layerId, 4);
+  return Buffer.concat([sub, body]);
+}
+
+/** Build arbitrary MUD message: sub_header + cmd(4) + payload. */
+export function buildMud(
+  subMagic: number,
+  seq: number,
+  typeId: number,
+  payload: Buffer = Buffer.alloc(0),
+): Buffer {
+  const sub = packMgikSub(subMagic, seq);
+  const cmd = Buffer.alloc(4);
+  cmd.writeUInt32BE(typeId, 0);
+  return Buffer.concat([sub, cmd, payload]);
+}
+
+/**
+ * Parse a LayerConfiguration (type 0x12C / 300) payload.
+ * Returns null if the payload is too short.
+ */
+export function parseLayerConfiguration(payload: Buffer): LayerInfo | null {
+  // Minimum: cmd(4) + id(4) + w(4) + h(4) + posX(4) + posY(4) + depth(4) + type(4) = 32
+  if (payload.length < 32) {
+    return null;
+  }
+
+  const id = payload.readUInt32BE(4);
+  const width = payload.readUInt32BE(8);
+  const height = payload.readUInt32BE(12);
+  const posX = payload.readFloatBE(16);
+  const posY = payload.readFloatBE(20);
+  const depth = payload.readFloatBE(24);
+  const type = payload.readUInt32BE(28);
+  const typeName = LAYER_TYPE_NAMES[type] ?? `UNKNOWN(${type})`;
+
+  // Parse 4 strings: appName, layerName, deviceSerial, packageName
+  const strings: string[] = [];
+  let offset = 32;
+  for (let i = 0; i < 4; i++) {
+    const result = parseMudString(payload, offset);
+    strings.push(result.value);
+    offset = result.nextOffset;
+  }
+
+  return {
+    id,
+    width,
+    height,
+    posX,
+    posY,
+    depth,
+    type,
+    typeName,
+    app: strings[0] ?? "",
+    layer: strings[1] ?? "",
+    serial: strings[2] ?? "",
+    pkg: strings[3] ?? "",
+  };
+}

package/packages/cast2-protocol/src/pose.ts

@@ -0,0 +1,99 @@
+/**
+ * Pose state management: euler-to-quaternion conversion, incremental updates,
+ * and screen-to-yaw/pitch mapping.
+ *
+ * OpenXR coordinate convention: +X=right, +Y=up, -Z=forward.
+ *
+ * All pose coordinates are offsets from the headset's position at the time
+ * casting started — they are NOT absolute world-space coordinates.  The origin
+ * (0, 0, 0) corresponds to the headset's initial position; moving the pose
+ * shifts the virtual camera relative to that starting point.
+ */
+
+import type { PoseOffset, PoseDelta, PoseState } from "./types.js";
+
+/** Create a default pose state (identity orientation, zero offset from headset). */
+export function createPoseState(): PoseState {
+  return {
+    x: 0, y: 0, z: 0,
+    qw: 1, qx: 0, qy: 0, qz: 0,
+    yaw: 0, pitch: 0,
+  };
+}
+
+/** Convert yaw/pitch (radians) to quaternion (w, x, y, z). */
+export function eulerToQuat(yaw: number, pitch: number): {
+  qw: number; qx: number; qy: number; qz: number;
+} {
+  const cy = Math.cos(yaw * 0.5);
+  const sy = Math.sin(yaw * 0.5);
+  const cp = Math.cos(pitch * 0.5);
+  const sp = Math.sin(pitch * 0.5);
+  return {
+    qw: cy * cp,
+    qx: cy * sp,
+    qy: sy * cp,
+    qz: -sy * sp,
+  };
+}
+
+/**
+ * Apply incremental movement to a pose state.
+ * Returns a new PoseState (does not mutate the input).
+ */
+export function updatePose(state: PoseState, delta: PoseDelta): PoseState {
+  const yaw = state.yaw + (delta.dYaw ?? 0);
+  const pitch = Math.max(
+    -Math.PI / 2,
+    Math.min(Math.PI / 2, state.pitch + (delta.dPitch ?? 0)),
+  );
+
+  const dForward = delta.dForward ?? 0;
+  const dStrafe = delta.dStrafe ?? 0;
+  const dUp = delta.dUp ?? 0;
+
+  // Move in the direction we're facing (yaw only, not pitch).
+  // OpenXR: +X=right, +Y=up, -Z=forward.  Yaw rotates around Y.
+  const cy = Math.cos(yaw);
+  const sy = Math.sin(yaw);
+  const x = state.x - dForward * sy + dStrafe * cy;
+  const y = state.y + dUp;
+  const z = state.z - dForward * cy - dStrafe * sy;
+
+  const q = eulerToQuat(yaw, pitch);
+  return { x, y, z, ...q, yaw, pitch };
+}
+
+/**
+ * Set pose offset directly. Only provided fields are updated.
+ * Returns a new PoseState.
+ */
+export function setPoseOffset(state: PoseState, abs: PoseOffset): PoseState {
+  const x = abs.x ?? state.x;
+  const y = abs.y ?? state.y;
+  const z = abs.z ?? state.z;
+  const yaw = abs.yaw ?? state.yaw;
+  const pitch = abs.pitch ?? state.pitch;
+  const q = eulerToQuat(yaw, pitch);
+  return { x, y, z, ...q, yaw, pitch };
+}
+
+/**
+ * Convert normalized screen coordinates (0-1) to yaw/pitch angles.
+ * Screen center (0.5, 0.5) maps to the current camera orientation.
+ */
+export function screenToYawPitch(
+  x: number,
+  y: number,
+  currentYaw: number,
+  currentPitch: number,
+  width: number,
+  height: number,
+): { yaw: number; pitch: number } {
+  const hFov = Math.PI / 2; // 90 degrees
+  const vFov = hFov * (height / width);
+  return {
+    yaw: currentYaw - (x - 0.5) * hFov,
+    pitch: currentPitch - (y - 0.5) * vFov,
+  };
+}

package/packages/cast2-protocol/src/resolutions.ts

@@ -0,0 +1,34 @@
+export interface Resolution {
+  width: number;
+  height: number;
+  label: string;
+}
+
+export const RESOLUTIONS: Record<string, Resolution> = {
+  "720p":  { width: 1280, height: 720,  label: "720p" },
+  "1080p": { width: 1920, height: 1080, label: "1080p" },
+  "native": { width: 2064, height: 1162, label: "native" },
+};
+
+export const DEFAULT_RESOLUTION = "720p";
+
+export function resolveResolution(
+  resolution?: string,
+  width?: number,
+  height?: number,
+): { width: number; height: number } {
+  if (resolution) {
+    const preset = RESOLUTIONS[resolution];
+    if (!preset) {
+      throw new Error(
+        `Unknown resolution "${resolution}". Valid: ${Object.keys(RESOLUTIONS).join(", ")}`,
+      );
+    }
+    return { width: preset.width, height: preset.height };
+  }
+  if (width != null && height != null) {
+    return { width, height };
+  }
+  const def = RESOLUTIONS[DEFAULT_RESOLUTION];
+  return { width: def.width, height: def.height };
+}

package/packages/cast2-protocol/src/types.ts

@@ -0,0 +1,64 @@
+/** Type definitions for Cast 2.0 protocol structures. */
+
+export interface XrspHeader {
+  flags: number;
+  topic: number;
+  wordCount: number;
+  seq: number;
+  padding: number;
+}
+
+export interface MgikSubHeader {
+  subMagic: number;
+  msgSeq: number;
+  ackSeq: number;
+}
+
+export interface LayerInfo {
+  id: number;
+  width: number;
+  height: number;
+  posX: number;
+  posY: number;
+  depth: number;
+  type: number;
+  typeName: string;
+  app: string;
+  layer: string;
+  serial: string;
+  pkg: string;
+}
+
+/**
+ * Camera pose as an offset from the headset's position when casting started.
+ * Coordinates are relative to the headset, not absolute world space.
+ */
+export interface PoseState {
+  x: number;
+  y: number;
+  z: number;
+  qw: number;
+  qx: number;
+  qy: number;
+  qz: number;
+  yaw: number;
+  pitch: number;
+}
+
+/** Incremental movement relative to the current camera offset. */
+export interface PoseDelta {
+  dForward?: number;
+  dStrafe?: number;
+  dUp?: number;
+  dYaw?: number;
+  dPitch?: number;
+}
+
+/** Set camera offset directly (relative to headset, not world space). */
+export interface PoseOffset {
+  x?: number;
+  y?: number;
+  z?: number;
+  yaw?: number;
+  pitch?: number;
+}

package/packages/cast2-protocol/src/xrsp.ts

@@ -0,0 +1,73 @@
+/**
+ * XRSP frame packing and parsing.
+ *
+ * XRSP header is 8 bytes, little-endian:
+ *   flags(1) + topic(1) + word_count(2 LE) + seq(2 LE) + pad(2 LE)
+ *
+ * Payload is padded to 4-byte alignment.
+ * Total packet size = word_count × 4 bytes (includes the 8-byte header as 2 words).
+ * Payload size = (word_count - 1) × 4 bytes... wait, looking at Python:
+ *   word_count = len(padded_payload) / 4 + 1
+ * So header takes 2 words (8 bytes) but word_count only accounts for 1 word of header?
+ * Actually the pack_xrsp packs the 8-byte header separately, then appends padded payload.
+ * word_count = padded_payload_len/4 + 1, so payload_size = (word_count - 1) * 4.
+ * The header itself is NOT counted in word_count properly — it's prepended separately.
+ */
+
+import {
+  XRSP_FLAGS_STANDARD,
+  XRSP_HEADER_SIZE,
+  XRSP_TOPIC_CAST,
+} from "./constants.js";
+import type { XrspHeader } from "./types.js";
+
+/**
+ * Pack an XRSP frame: 8-byte LE header + padded payload.
+ */
+export function packXrsp(
+  seq: number,
+  payload: Buffer,
+  flags: number = XRSP_FLAGS_STANDARD,
+  topic: number = XRSP_TOPIC_CAST,
+): Buffer {
+  const padLen = (4 - (payload.length % 4)) % 4;
+  const paddedLen = payload.length + padLen;
+  const wordCount = paddedLen / 4 + 1;
+
+  const header = Buffer.alloc(XRSP_HEADER_SIZE);
+  header.writeUInt8(flags, 0);
+  header.writeUInt8(topic, 1);
+  header.writeUInt16LE(wordCount, 2);
+  header.writeUInt16LE(seq, 4);
+  header.writeUInt16LE(0, 6); // padding field
+
+  if (padLen === 0) {
+    return Buffer.concat([header, payload]);
+  }
+  return Buffer.concat([header, payload, Buffer.alloc(padLen)]);
+}
+
+/**
+ * Parse an XRSP header from the first 8 bytes of a buffer.
+ */
+export function parseXrspHeader(data: Buffer): XrspHeader {
+  if (data.length < XRSP_HEADER_SIZE) {
+    throw new Error(
+      `XRSP header requires ${XRSP_HEADER_SIZE} bytes, got ${data.length}`,
+    );
+  }
+  return {
+    flags: data.readUInt8(0),
+    topic: data.readUInt8(1) & 0x3f,
+    wordCount: data.readUInt16LE(2),
+    seq: data.readUInt16LE(4),
+    padding: data.readUInt16LE(6),
+  };
+}
+
+/**
+ * Compute payload size from an XRSP header.
+ */
+export function xrspPayloadSize(header: XrspHeader): number {
+  return Math.max(0, (header.wordCount - 1) * 4);
+}