@johnhenry/browsermesh-priority-mux 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Henry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# browsermesh-priority-mux
+
+Application-level priority scheduling for single-stream transports. A plain
+WebSocket is one ordered TCP byte stream with no multi-stream capability at
+all -- unlike WebRTC, which gets a second `RTCDataChannel` almost for free
+(see `@johnhenry/browsermesh-transport`'s dual-datachannel priority split).
+Over a WebSocket, the only way to stop a large bulk send (a file transfer, a
+sync delta) from blocking a small urgent message (a control/heartbeat/chat
+message) behind it in delivery order is an application-level scheduler that
+chunks large messages and interleaves them with small ones by priority.
+
+This package borrows its scheduling *idea* -- prioritizing short messages so
+they don't queue behind long ones -- from Homa (Ousterhout et al., Stanford;
+a receiver-driven, message-oriented, SRPT-style datacenter RPC transport). It
+does not implement Homa's wire protocol, congestion control, or receiver-side
+scheduling; it's a much smaller, sender-side, WFQ-with-anti-starvation
+scheduler purpose-built for one already-open, ordered, message-boundary-
+preserving connection (WebSocket, but really anything shaped the same way).
+
+## Why this exists
+
+`@johnhenry/browsermesh-transport`'s `WebSocketTransport` is the real,
+already-integrated WebSocket fallback `TransportFactory.negotiate()` picks
+when WebRTC and WebTransport negotiation both fail (`preferredOrder =
+['webrtc', 'wsh-wt', 'wsh-ws']`). Once picked, it's a generic transport --
+every kind of traffic a WebRTC data channel would have carried (chat, file
+transfer, sync, consensus/control messages) gets tagged and multiplexed onto
+that one WebSocket, with a raw `ws.send()` per message and no chunking or
+priority separation at all. A large sync payload sent right before a small
+urgent chat message will delay that chat message until the sync payload's
+bytes clear the socket.
+
+## Design
+
+### Transport-agnostic adapter
+
+`PriorityMux` wraps anything shaped like:
+
+```js
+{ send(bytes), on(event, cb), close?() } // events: 'open' | 'message' | 'close' | 'error'
+```
+
+This is the same shape `@johnhenry/browsermesh-transport`'s
+`WebSocketTransport`/`WebRTCTransport`/`WebTransportTransport` already
+expose, so a mux instance is a drop-in wrapper: anywhere code did
+`transport.send(x)` / `transport.on('message', cb)`, it can do `mux.send(x)`
+/ `mux.on('message', cb)` instead, unchanged. The core scheduler has no
+WebSocket-specific code in it.
+
+### Wire framing
+
+Each chunk is one frame, one `adapter.send()` call. Mirrors the binary
+framing style already used in this monorepo
+(`browsermesh-transport/src/wisp-client.mjs`'s `encodeFrame`/`decodeFrame`:
+fixed-size header via `DataView`, little-endian) rather than
+`JSON.stringify`-ing an object per chunk:
+
+```
+[version:u8][priority:u8][msgId:u32][seq:u32][total:u32][payload:...]
+ byte 0       byte 1        bytes 2-5  bytes 6-9  bytes 10-13  bytes 14+
+```
+
+Messages are transparently wrapped in a 1-byte envelope tag before chunking
+(raw bytes / UTF-8 string / JSON value) so reassembly hands back the same
+shape that was sent -- callers don't need to know chunking happened at all.
+
+### Priority queues + anti-starvation
+
+Three tiers by default (`'high' | 'normal' | 'low'`, configurable). Draining
+picks the highest non-empty tier -- *except* every Nth drain slot
+(`starvationGuardInterval`, default 8), which is reserved unconditionally for
+the lowest non-empty tier, regardless of how much higher-tier backlog is
+queued. That gives a concrete bound: a message sitting alone in the lowest
+tier is dequeued within `starvationGuardInterval` drain slots, even under a
+continuous flood of higher-priority sends. See `src/scheduler.mjs`.
+
+### Reassembly
+
+Chunks are buffered by `msgId` (indexed by `seq`, not append order) until
+`total` distinct sequence numbers have arrived, then concatenated in order
+and delivered as one `'message'` event -- transparent to whatever already
+consumes `transport.on('message', ...)`. A message is never delivered
+partially. Closing the underlying adapter mid-flight discards all pending
+reassembly state so nothing hangs waiting for chunks that will never arrive.
+
+### Priority inference
+
+```js
+new PriorityMux(adapter, {
+  priorityOf: (data) => {
+    if (data?.type === 'ping' || data?.type === 'consensus') return 'high';
+    if (data?.type === 'file-chunk') return 'low';
+    // return undefined/null to fall through to defaultPriority
+  },
+});
+```
+
+The classifier is entirely caller-supplied -- this package has no built-in
+knowledge of any particular ecosystem's message-type names.
+
+## Install
+
+```bash
+npm install @johnhenry/browsermesh-priority-mux
+```
+
+## Quick start
+
+```js
+import { PriorityMux } from '@johnhenry/browsermesh-priority-mux';
+import { WebSocketTransport } from '@johnhenry/browsermesh-transport';
+
+const transport = new WebSocketTransport({ url: 'wss://example.com' });
+await transport.connect();
+
+const mux = new PriorityMux(transport, { chunkSize: 16 * 1024 });
+
+mux.on('message', (data, meta) => {
+  console.log('received', meta.priority, data);
+});
+
+// A big sync payload...
+mux.send(bigSyncDelta, { priority: 'low' });
+// ...won't delay this urgent ping, even though it was queued first.
+mux.send({ type: 'ping' }, { priority: 'high' });
+```
+
+## API
+
+- `new PriorityMux(adapter, opts)` -- `opts`: `chunkSize` (default 16384),
+  `tiers` (default `['high','normal','low']`), `starvationGuardInterval`
+  (default 8), `priorityOf(data)`, `defaultPriority` (default `'normal'`),
+  `scheduleFn` (injectable drain scheduler, default `setImmediate`).
+  - `.send(data, { priority })` -> `{ msgId, total, priority }`
+  - `.on(event, cb)` -- `'open' | 'message' | 'close' | 'error'`
+  - `.close()`
+  - `.getStats()`
+- `PriorityScheduler`, `Reassembler` -- the two pieces `PriorityMux` composes,
+  usable standalone.
+- `encodeChunkFrame`/`decodeChunkFrame`/`splitIntoChunks` -- wire framing.
+- `encodeEnvelope`/`decodeEnvelope` -- the transparent type-preserving
+  message envelope.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@johnhenry/browsermesh-priority-mux",
+  "version": "0.0.1",
+  "description": "Application-level priority scheduler that chunks and interleaves messages to prevent head-of-line blocking on single-stream transports (WebSocket) for BrowserMesh",
+  "type": "module",
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "websocket",
+    "priority",
+    "scheduler",
+    "head-of-line-blocking",
+    "multiplexing",
+    "mesh",
+    "browser"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/johnhenry/browsermesh",
+    "directory": "packages/browsermesh-priority-mux"
+  },
+  "homepage": "https://opensource.johnhenry.me/browsermesh/",
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}

package/src/envelope.mjs

@@ -0,0 +1,72 @@
+/**
+ * envelope.mjs -- transparent message envelope encoding.
+ *
+ * PriorityMux chunks and reassembles arbitrary messages. So that reassembly
+ * hands callers back the *same shape* they sent (string in -> string out,
+ * plain object in -> plain object out, bytes in -> bytes out) rather than
+ * always producing raw bytes, every message is wrapped in a 1-byte tag
+ * before chunking, and unwrapped again after reassembly.
+ *
+ * Wire layout: [tag:u8][body:...]
+ */
+
+/** @type {0} raw bytes (Uint8Array/ArrayBuffer), passed through untouched */
+export const ENVELOPE_BYTES = 0;
+/** @type {1} UTF-8 string */
+export const ENVELOPE_STRING = 1;
+/** @type {2} JSON-serializable value */
+export const ENVELOPE_JSON = 2;
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+/**
+ * Encode an arbitrary message into a tagged byte envelope.
+ * @param {Uint8Array|ArrayBuffer|string|*} data
+ * @returns {Uint8Array}
+ */
+export function encodeEnvelope(data) {
+  let tag;
+  let body;
+
+  if (data instanceof Uint8Array) {
+    tag = ENVELOPE_BYTES;
+    body = data;
+  } else if (data instanceof ArrayBuffer) {
+    tag = ENVELOPE_BYTES;
+    body = new Uint8Array(data);
+  } else if (typeof data === 'string') {
+    tag = ENVELOPE_STRING;
+    body = textEncoder.encode(data);
+  } else {
+    tag = ENVELOPE_JSON;
+    body = textEncoder.encode(JSON.stringify(data));
+  }
+
+  const out = new Uint8Array(1 + body.byteLength);
+  out[0] = tag;
+  out.set(body, 1);
+  return out;
+}
+
+/**
+ * Decode a tagged byte envelope back into its original shape.
+ * @param {Uint8Array} bytes
+ * @returns {Uint8Array|string|*}
+ */
+export function decodeEnvelope(bytes) {
+  if (bytes.byteLength < 1) throw new Error('priority-mux: envelope too short');
+  const tag = bytes[0];
+  const body = bytes.subarray(1);
+
+  switch (tag) {
+    case ENVELOPE_BYTES:
+      return body;
+    case ENVELOPE_STRING:
+      return textDecoder.decode(body);
+    case ENVELOPE_JSON:
+      return JSON.parse(textDecoder.decode(body));
+    default:
+      throw new Error(`priority-mux: unknown envelope tag ${tag}`);
+  }
+}

package/src/frame.mjs

@@ -0,0 +1,98 @@
+/**
+ * frame.mjs -- wire framing for chunked, prioritized messages.
+ *
+ * Mirrors the framing style already used in this monorepo (see
+ * `@johnhenry/browsermesh-transport`'s `wisp-client.mjs` `encodeFrame`/
+ * `decodeFrame`: a fixed-size binary header via DataView, little-endian,
+ * followed by a raw payload) rather than inventing a new convention or
+ * throwing an object at JSON.stringify.
+ *
+ * Frame layout (little-endian):
+ *   [version:u8][priority:u8][msgId:u32][seq:u32][total:u32][payload:...]
+ *    byte 0       byte 1       bytes 2-5   bytes 6-9  bytes 10-13  bytes 14+
+ *
+ * One frame is one discrete adapter `send()` call -- the underlying
+ * transport (WebSocket, WebRTC data channel, etc.) is expected to preserve
+ * message boundaries on its own (as WebSocket and RTCDataChannel both do),
+ * so no additional length-prefixing of the transport stream itself is
+ * needed here.
+ */
+
+export const FRAME_VERSION = 1;
+
+/** Priority tier -> wire code. Order here has no bearing on scheduling order. */
+export const PRIORITY_CODES = Object.freeze({ high: 0, normal: 1, low: 2 });
+/** Wire code -> priority tier name. */
+export const PRIORITY_NAMES = Object.freeze(['high', 'normal', 'low']);
+
+const HEADER_BYTES = 14;
+
+/**
+ * Encode one chunk frame.
+ * @param {object} chunk
+ * @param {'high'|'normal'|'low'} chunk.priority
+ * @param {number} chunk.msgId - u32
+ * @param {number} chunk.seq - u32, 0-based index of this chunk
+ * @param {number} chunk.total - u32, total chunk count for this message
+ * @param {Uint8Array} chunk.payload
+ * @returns {Uint8Array}
+ */
+export function encodeChunkFrame({ priority, msgId, seq, total, payload }) {
+  const priorityCode = PRIORITY_CODES[priority];
+  if (priorityCode === undefined) {
+    throw new Error(`priority-mux: unknown priority tier "${priority}"`);
+  }
+  const payloadBytes = payload || new Uint8Array(0);
+  const buf = new Uint8Array(HEADER_BYTES + payloadBytes.byteLength);
+  const view = new DataView(buf.buffer);
+  view.setUint8(0, FRAME_VERSION);
+  view.setUint8(1, priorityCode);
+  view.setUint32(2, msgId >>> 0, true);
+  view.setUint32(6, seq >>> 0, true);
+  view.setUint32(10, total >>> 0, true);
+  buf.set(payloadBytes, HEADER_BYTES);
+  return buf;
+}
+
+/**
+ * Decode one chunk frame.
+ * @param {ArrayBuffer|Uint8Array} data
+ * @returns {{ priority: 'high'|'normal'|'low', msgId: number, seq: number, total: number, payload: Uint8Array }}
+ */
+export function decodeChunkFrame(data) {
+  const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+  if (bytes.byteLength < HEADER_BYTES) {
+    throw new Error('priority-mux: frame too short');
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const version = view.getUint8(0);
+  if (version !== FRAME_VERSION) {
+    throw new Error(`priority-mux: unsupported frame version ${version}`);
+  }
+  const priority = PRIORITY_NAMES[view.getUint8(1)];
+  if (!priority) {
+    throw new Error(`priority-mux: unknown priority code ${view.getUint8(1)}`);
+  }
+  const msgId = view.getUint32(2, true);
+  const seq = view.getUint32(6, true);
+  const total = view.getUint32(10, true);
+  const payload = bytes.subarray(HEADER_BYTES);
+  return { priority, msgId, seq, total, payload };
+}
+
+/**
+ * Split an envelope's bytes into an ordered array of chunk descriptors
+ * (without `priority`/`msgId`, which the caller attaches).
+ * @param {Uint8Array} bytes
+ * @param {number} chunkSize
+ * @returns {{ seq: number, total: number, payload: Uint8Array }[]}
+ */
+export function splitIntoChunks(bytes, chunkSize) {
+  const total = Math.max(1, Math.ceil(bytes.byteLength / chunkSize));
+  const chunks = new Array(total);
+  for (let seq = 0; seq < total; seq++) {
+    const start = seq * chunkSize;
+    chunks[seq] = { seq, total, payload: bytes.subarray(start, start + chunkSize) };
+  }
+  return chunks;
+}

package/src/index.mjs

@@ -0,0 +1,6 @@
+// browsermesh-priority-mux -- WebSocket head-of-line-blocking mitigation
+export * from './priority-mux.mjs';
+export * from './scheduler.mjs';
+export * from './reassembler.mjs';
+export * from './frame.mjs';
+export * from './envelope.mjs';

package/src/priority-mux.mjs

@@ -0,0 +1,234 @@
+import { encodeEnvelope, decodeEnvelope } from './envelope.mjs';
+import { encodeChunkFrame, decodeChunkFrame, splitIntoChunks } from './frame.mjs';
+import { PriorityScheduler, DEFAULT_TIERS, DEFAULT_STARVATION_GUARD_INTERVAL } from './scheduler.mjs';
+import { Reassembler } from './reassembler.mjs';
+
+/** Default chunk size in bytes: large messages above this get split. */
+export const DEFAULT_CHUNK_SIZE = 16 * 1024;
+
+/** Events re-emitted by PriorityMux. */
+const EVENTS = Object.freeze(['open', 'message', 'close', 'error']);
+
+const defaultSchedule = typeof setImmediate === 'function'
+  ? setImmediate
+  : (fn) => setTimeout(fn, 0);
+
+/**
+ * PriorityMux -- an application-level scheduler that prevents head-of-line
+ * blocking on a single ordered byte-stream transport (WebSocket and
+ * similar) by chunking large messages and interleaving them with small,
+ * high-priority ones, borrowing the scheduling idea (not the wire
+ * protocol) from Homa's SRPT-style short-message prioritization.
+ *
+ * Transport-agnostic: wraps anything shaped like
+ * `{ send(bytes), on(event, cb), close() }` -- the same adapter shape
+ * `@johnhenry/browsermesh-transport`'s `WebSocketTransport` (and its
+ * WebRTC/WebTransport siblings) already exposes. PriorityMux itself
+ * exposes that exact same shape back out, so it drops in as a transparent
+ * wrapper: anywhere code did `transport.send(x)` / `transport.on('message', cb)`,
+ * it can instead do `mux.send(x)` / `mux.on('message', cb)` unchanged.
+ */
+export class PriorityMux {
+  #adapter;
+  #chunkSize;
+  #tiers;
+  #priorityOf;
+  #defaultPriority;
+  #scheduleFn;
+  #scheduler;
+  #reassembler = new Reassembler();
+  #callbacks = { open: [], message: [], close: [], error: [] };
+  #draining = false;
+  #closed = false;
+  #nextMsgId = Math.floor(Math.random() * 0xfffffffe) >>> 0;
+  #stats = { chunksSent: 0, chunksReceived: 0, messagesSent: 0, messagesReceived: 0 };
+
+  /**
+   * @param {{ send(bytes: Uint8Array): void, on(event: string, cb: Function): void, close?: Function }} adapter
+   * @param {object} [opts]
+   * @param {number} [opts.chunkSize=16384] - Messages whose encoded byte
+   *   length exceeds this get split into multiple chunk frames.
+   * @param {string[]} [opts.tiers=['high','normal','low']] - Priority tier
+   *   names, highest priority first. `send()`'s `priority` option and any
+   *   `priorityOf()` classifier must return one of these.
+   * @param {number} [opts.starvationGuardInterval=8] - Anti-starvation
+   *   bound: every Nth drain slot is reserved for the lowest non-empty
+   *   tier regardless of higher-tier backlog. See `PriorityScheduler`.
+   * @param {(parsedEnvelope: *) => (string|undefined|null)} [opts.priorityOf]
+   *   Optional classifier: given the *original* value passed to `send()`
+   *   (before wire encoding), return a tier name to auto-derive priority.
+   *   Domain-specific message-shape knowledge belongs here, supplied by
+   *   the caller -- this package stays domain-agnostic.
+   * @param {string} [opts.defaultPriority='normal'] - Used when neither an
+   *   explicit `send()` option nor `priorityOf()` yields a tier.
+   * @param {(fn: Function) => void} [opts.scheduleFn] - Injectable drain
+   *   scheduler (defaults to `setImmediate`, falling back to
+   *   `setTimeout(fn, 0)`). Exposed mainly for deterministic tests.
+   */
+  constructor(adapter, opts = {}) {
+    if (!adapter || typeof adapter.send !== 'function' || typeof adapter.on !== 'function') {
+      throw new Error('priority-mux: adapter must have send() and on()');
+    }
+    this.#adapter = adapter;
+    this.#chunkSize = opts.chunkSize ?? DEFAULT_CHUNK_SIZE;
+    if (this.#chunkSize < 1) throw new Error('priority-mux: chunkSize must be >= 1');
+    this.#tiers = opts.tiers || DEFAULT_TIERS;
+    this.#priorityOf = opts.priorityOf || null;
+    this.#defaultPriority = opts.defaultPriority || (this.#tiers.includes('normal') ? 'normal' : this.#tiers[0]);
+    this.#scheduleFn = opts.scheduleFn || defaultSchedule;
+    this.#scheduler = new PriorityScheduler({
+      tiers: this.#tiers,
+      starvationGuardInterval: opts.starvationGuardInterval ?? DEFAULT_STARVATION_GUARD_INTERVAL,
+    });
+
+    this.#adapter.on('message', (raw) => this.#handleIncoming(raw));
+    this.#adapter.on('close', (ev) => this.#handleClose(ev));
+    this.#adapter.on('open', (ev) => this.#emit('open', ev));
+    this.#adapter.on('error', (err) => this.#emit('error', err));
+  }
+
+  /**
+   * Send a message, transparently chunking it if it's large and queuing
+   * each chunk under the resolved priority tier.
+   * @param {Uint8Array|ArrayBuffer|string|*} data
+   * @param {{ priority?: string }} [opts]
+   * @returns {{ msgId: number, total: number, priority: string }}
+   */
+  send(data, opts = {}) {
+    if (this.#closed) throw new Error('priority-mux: mux is closed');
+
+    const priority = opts.priority
+      || (this.#priorityOf ? this.#priorityOf(data) : null)
+      || this.#defaultPriority;
+    if (!this.#tiers.includes(priority)) {
+      throw new Error(`priority-mux: unknown priority tier "${priority}"`);
+    }
+
+    const envelopeBytes = encodeEnvelope(data);
+    const msgId = this.#allocMsgId();
+    const chunks = splitIntoChunks(envelopeBytes, this.#chunkSize);
+
+    for (const { seq, total, payload } of chunks) {
+      this.#scheduler.enqueue(priority, { priority, msgId, seq, total, payload });
+    }
+    this.#stats.messagesSent++;
+    this.#scheduleDrain();
+
+    return { msgId, total: chunks.length, priority };
+  }
+
+  /**
+   * Register a listener. Supported events: 'open', 'message', 'close', 'error'.
+   * @param {string} event
+   * @param {Function} cb
+   */
+  on(event, cb) {
+    if (!EVENTS.includes(event)) throw new Error(`priority-mux: unknown event "${event}"`);
+    this.#callbacks[event].push(cb);
+  }
+
+  /**
+   * Close the underlying adapter (if it supports `close()`) and stop
+   * draining. Safe to call more than once.
+   */
+  close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    if (typeof this.#adapter.close === 'function') {
+      this.#adapter.close();
+    }
+    this.#reassembler.reset();
+  }
+
+  /** Snapshot of internal counters, useful for tests/observability. */
+  getStats() {
+    return {
+      ...this.#stats,
+      pendingReassembly: this.#reassembler.pendingCount,
+      queued: this.#scheduler.size,
+    };
+  }
+
+  // -- Internal ----------------------------------------------------------
+
+  #allocMsgId() {
+    const id = this.#nextMsgId;
+    this.#nextMsgId = (this.#nextMsgId + 1) >>> 0;
+    return id;
+  }
+
+  #handleIncoming(raw) {
+    let frame;
+    try {
+      frame = decodeChunkFrame(raw);
+    } catch (err) {
+      this.#emit('error', err);
+      return;
+    }
+
+    this.#stats.chunksReceived++;
+
+    let result;
+    try {
+      result = this.#reassembler.receive(frame);
+    } catch (err) {
+      this.#emit('error', err);
+      return;
+    }
+    if (!result) return; // message still incomplete
+
+    let value;
+    try {
+      value = decodeEnvelope(result.bytes);
+    } catch (err) {
+      this.#emit('error', err);
+      return;
+    }
+
+    this.#stats.messagesReceived++;
+    this.#emit('message', value, { msgId: result.msgId, priority: result.priority });
+  }
+
+  #handleClose(ev) {
+    // Closing mid-flight must not leave partially-reassembled messages
+    // sitting around waiting for chunks that will never arrive, and must
+    // not leave the drain loop scheduling forever against a dead adapter.
+    this.#closed = true;
+    this.#draining = false;
+    this.#reassembler.reset();
+    this.#emit('close', ev);
+  }
+
+  #scheduleDrain() {
+    if (this.#draining || this.#closed) return;
+    this.#draining = true;
+    this.#scheduleFn(() => this.#drainTick());
+  }
+
+  #drainTick() {
+    if (this.#closed) {
+      this.#draining = false;
+      return;
+    }
+    const item = this.#scheduler.dequeue();
+    if (!item) {
+      this.#draining = false;
+      return;
+    }
+    try {
+      this.#adapter.send(encodeChunkFrame(item));
+      this.#stats.chunksSent++;
+    } catch (err) {
+      this.#draining = false;
+      this.#emit('error', err);
+      return;
+    }
+    this.#scheduleFn(() => this.#drainTick());
+  }
+
+  #emit(event, ...args) {
+    for (const cb of this.#callbacks[event] || []) {
+      try { cb(...args); } catch { /* listener errors must not break the mux */ }
+    }
+  }
+}

package/src/reassembler.mjs

@@ -0,0 +1,73 @@
+/**
+ * reassembler.mjs -- reconstructs full messages from chunk frames.
+ *
+ * Buffers chunks by `msgId` until `total` distinct sequence numbers have
+ * arrived, then hands back the concatenated bytes in the correct order --
+ * regardless of the order chunks actually arrived in (interleaving across
+ * concurrent messages, or even out-of-order delivery of one message's own
+ * chunks, must both reassemble correctly). A message is never handed back
+ * partially: `receive()` returns a result only on the exact frame that
+ * completes it.
+ */
+
+export class Reassembler {
+  #pending = new Map(); // msgId -> { total, priority, chunks: Array<Uint8Array|undefined>, receivedCount }
+
+  /**
+   * Feed one decoded chunk frame in. Returns the reassembled message once
+   * complete, otherwise `undefined`.
+   * @param {{ priority: string, msgId: number, seq: number, total: number, payload: Uint8Array }} frame
+   * @returns {{ msgId: number, priority: string, bytes: Uint8Array }|undefined}
+   */
+  receive({ priority, msgId, seq, total, payload }) {
+    if (total < 1) throw new Error('priority-mux: frame has invalid total');
+    if (seq < 0 || seq >= total) {
+      throw new Error(`priority-mux: chunk seq ${seq} out of range for total ${total}`);
+    }
+
+    let entry = this.#pending.get(msgId);
+    if (!entry) {
+      entry = { total, priority, chunks: new Array(total), receivedCount: 0 };
+      this.#pending.set(msgId, entry);
+    } else if (entry.total !== total) {
+      throw new Error(`priority-mux: msgId ${msgId} total mismatch (${entry.total} vs ${total})`);
+    }
+
+    // Duplicate delivery of the same (msgId, seq) is a no-op, not a
+    // duplicate-count bump -- keeps `receivedCount` accurate even if a
+    // transport ever redelivers.
+    if (entry.chunks[seq] === undefined) {
+      entry.chunks[seq] = payload;
+      entry.receivedCount++;
+    }
+
+    if (entry.receivedCount < entry.total) return undefined;
+
+    // Complete -- concatenate in seq order and remove the pending entry so
+    // it can never be double-delivered or leak memory.
+    this.#pending.delete(msgId);
+    let byteLength = 0;
+    for (const chunk of entry.chunks) byteLength += chunk.byteLength;
+    const bytes = new Uint8Array(byteLength);
+    let offset = 0;
+    for (const chunk of entry.chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return { msgId, priority: entry.priority, bytes };
+  }
+
+  /** Number of messages currently mid-reassembly. */
+  get pendingCount() {
+    return this.#pending.size;
+  }
+
+  /**
+   * Discard all in-flight reassembly state. Must be called when the
+   * underlying transport closes so a partially-received message never
+   * hangs around waiting for chunks that will never arrive.
+   */
+  reset() {
+    this.#pending.clear();
+  }
+}

package/src/scheduler.mjs

@@ -0,0 +1,99 @@
+/**
+ * scheduler.mjs -- priority queues with a weighted-fair-queueing drain
+ * order and a real anti-starvation bound.
+ *
+ * Borrows its scheduling *idea* (not its wire protocol) from Homa
+ * (Ousterhout et al., Stanford): prioritize short messages so they don't
+ * queue behind long ones, but bound how long any tier can be starved.
+ *
+ * Tiers drain in strict priority order (highest non-empty tier first) on
+ * every slot *except* one slot in every `starvationGuardInterval`, which
+ * is reserved unconditionally for the lowest non-empty tier -- regardless
+ * of how much backlog sits in higher tiers. That gives a concrete,
+ * testable bound: any single item sitting alone in the lowest tier is
+ * dequeued within `starvationGuardInterval` `dequeue()` calls, no matter
+ * how continuously higher tiers are fed.
+ */
+
+/** Default tier order, highest priority first. */
+export const DEFAULT_TIERS = Object.freeze(['high', 'normal', 'low']);
+
+/** Default anti-starvation guard: 1 in every 8 drain slots is reserved. */
+export const DEFAULT_STARVATION_GUARD_INTERVAL = 8;
+
+export class PriorityScheduler {
+  /**
+   * @param {object} [opts]
+   * @param {string[]} [opts.tiers] - Tier names, highest priority first.
+   * @param {number} [opts.starvationGuardInterval] - Every Nth `dequeue()`
+   *   call is forced to serve the lowest non-empty tier regardless of
+   *   backlog elsewhere. Must be >= 1. Set to `Infinity` to disable (pure
+   *   strict priority, no starvation guard -- not recommended).
+   */
+  constructor(opts = {}) {
+    this.tiers = opts.tiers || DEFAULT_TIERS;
+    if (this.tiers.length === 0) throw new Error('priority-mux: scheduler needs at least one tier');
+    this.starvationGuardInterval = opts.starvationGuardInterval ?? DEFAULT_STARVATION_GUARD_INTERVAL;
+    if (this.starvationGuardInterval < 1) {
+      throw new Error('priority-mux: starvationGuardInterval must be >= 1');
+    }
+    this.queues = new Map(this.tiers.map((t) => [t, []]));
+    this.slotCounter = 0;
+  }
+
+  /**
+   * Enqueue one item under a given tier.
+   * @param {string} tier
+   * @param {*} item
+   */
+  enqueue(tier, item) {
+    const q = this.queues.get(tier);
+    if (!q) throw new Error(`priority-mux: unknown tier "${tier}"`);
+    q.push(item);
+  }
+
+  /** Total number of items queued across all tiers. */
+  get size() {
+    let n = 0;
+    for (const q of this.queues.values()) n += q.length;
+    return n;
+  }
+
+  /** Size of a single tier's queue. */
+  sizeOf(tier) {
+    const q = this.queues.get(tier);
+    return q ? q.length : 0;
+  }
+
+  /**
+   * Pop the next item to send, or `undefined` if every queue is empty.
+   * Advances the internal slot counter (used by the starvation guard) on
+   * every call, including calls that find nothing to dequeue -- so the
+   * guard period is measured in *drain attempts*, matching how a real
+   * drain loop calls this once per tick.
+   * @returns {*|undefined}
+   */
+  dequeue() {
+    this.slotCounter++;
+
+    const isGuardSlot = Number.isFinite(this.starvationGuardInterval)
+      && this.slotCounter % this.starvationGuardInterval === 0;
+
+    if (isGuardSlot) {
+      // Anti-starvation: scan from the *lowest*-priority tier up, and
+      // serve the first non-empty one, ignoring higher-tier backlog.
+      for (let i = this.tiers.length - 1; i >= 0; i--) {
+        const q = this.queues.get(this.tiers[i]);
+        if (q.length) return q.shift();
+      }
+      return undefined; // everything empty -- fall through is unreachable
+    }
+
+    // Strict priority: highest non-empty tier wins.
+    for (const tier of this.tiers) {
+      const q = this.queues.get(tier);
+      if (q.length) return q.shift();
+    }
+    return undefined;
+  }
+}