@threenative/core 0.2.0 → 0.3.1

package/dist/net.js

@@ -0,0 +1,643 @@
+// src/net-protocol.ts
+var WIRE_VERSION = 1;
+var KIND_HELLO = 1;
+var KIND_WELCOME = 2;
+var KIND_BIND = 3;
+var KIND_BOUND = 4;
+var KIND_DATA = 16;
+var HEADER_BYTES = 8;
+var MAX_HELLO_BYTES = 4096;
+var DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_RELIABLE_MESSAGE_BYTES = 65536;
+var DEFAULT_MAX_QUEUED_RELIABLE_BYTES = 1048576;
+var DEFAULT_MAX_QUEUED_DATAGRAMS = 256;
+function invalidArgument(message) {
+  return new Error(`TN_NET_INVALID_ARGUMENT: ${message}`);
+}
+function isPositiveSafeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function normalizeOptions(url, options) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw invalidArgument("url must be a valid URL");
+  }
+  if (parsed.protocol !== "https:") throw invalidArgument("url must use https");
+  if (options === null || typeof options !== "object")
+    throw invalidArgument("options are required");
+  if (typeof options.applicationProtocol !== "string")
+    throw invalidArgument("applicationProtocol is required");
+  if (options.applicationProtocol.length < 1 || options.applicationProtocol.length > 64 || !/^[\x20-\x7e]+$/u.test(options.applicationProtocol))
+    throw invalidArgument("applicationProtocol must be 1-64 printable ASCII characters");
+  if (typeof options.credential !== "string" || options.credential.length === 0)
+    throw invalidArgument("credential must be nonempty");
+  if (!Array.isArray(options.channels) || options.channels.length < 1 || options.channels.length > 32)
+    throw invalidArgument("channels must list 1-32 entries");
+  const seen = /* @__PURE__ */ new Set();
+  const channels = options.channels.map((channel) => {
+    if (channel === null || typeof channel !== "object")
+      throw invalidArgument("channel entries are required");
+    if (!Number.isInteger(channel.id) || channel.id < 1 || channel.id > 65535)
+      throw invalidArgument("channel ids must be integers 1-65535");
+    if (channel.delivery !== "unreliable" && channel.delivery !== "reliable-ordered")
+      throw invalidArgument("channel delivery is unknown");
+    if (seen.has(channel.id)) throw invalidArgument("channel ids must be unique");
+    seen.add(channel.id);
+    return { id: channel.id, delivery: channel.delivery };
+  });
+  if (options.signal !== void 0 && !(options.signal instanceof AbortSignal))
+    throw invalidArgument("signal must be an AbortSignal");
+  const connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+  const maxReliableMessageBytes = options.maxReliableMessageBytes ?? DEFAULT_MAX_RELIABLE_MESSAGE_BYTES;
+  const maxQueuedReliableBytes = options.maxQueuedReliableBytes ?? DEFAULT_MAX_QUEUED_RELIABLE_BYTES;
+  const maxQueuedDatagrams = options.maxQueuedDatagrams ?? DEFAULT_MAX_QUEUED_DATAGRAMS;
+  if (!isPositiveSafeInteger(connectTimeoutMs))
+    throw invalidArgument("connectTimeoutMs must be positive");
+  if (!isPositiveSafeInteger(maxReliableMessageBytes))
+    throw invalidArgument("maxReliableMessageBytes must be positive");
+  if (!isPositiveSafeInteger(maxQueuedReliableBytes))
+    throw invalidArgument("maxQueuedReliableBytes must be positive");
+  if (!isPositiveSafeInteger(maxQueuedDatagrams))
+    throw invalidArgument("maxQueuedDatagrams must be positive");
+  if (maxReliableMessageBytes > maxQueuedReliableBytes)
+    throw invalidArgument("message limit cannot exceed queue limit");
+  return {
+    applicationProtocol: options.applicationProtocol,
+    credential: options.credential,
+    channels,
+    signal: options.signal,
+    connectTimeoutMs,
+    maxReliableMessageBytes,
+    maxQueuedReliableBytes,
+    maxQueuedDatagrams
+  };
+}
+function encodeFrame(kind, channel, payload) {
+  const out = new Uint8Array(HEADER_BYTES + payload.length);
+  const view = new DataView(out.buffer, out.byteOffset, out.byteLength);
+  out[0] = WIRE_VERSION;
+  out[1] = kind;
+  view.setUint16(2, channel);
+  view.setUint32(4, payload.length);
+  out.set(payload, HEADER_BYTES);
+  return out;
+}
+function checkFrameHead(version, kind, channel) {
+  if (version !== WIRE_VERSION) throw new Error("TN_NET_PROTOCOL: unknown wire version");
+  if (kind !== KIND_HELLO && kind !== KIND_WELCOME && kind !== KIND_BIND && kind !== KIND_BOUND && kind !== KIND_DATA)
+    throw new Error("TN_NET_PROTOCOL: unknown frame kind");
+  if (kind === KIND_DATA && channel === 0) throw new Error("TN_NET_PROTOCOL: DATA on channel 0");
+}
+function decodeStandaloneFrame(bytes) {
+  if (bytes.length < HEADER_BYTES) throw new Error("TN_NET_PROTOCOL: truncated header");
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const version = bytes[0] ?? 0;
+  const kind = bytes[1] ?? 0;
+  const channel = view.getUint16(2);
+  const length = view.getUint32(4);
+  checkFrameHead(version, kind, channel);
+  if (bytes.length !== HEADER_BYTES + length)
+    throw new Error("TN_NET_PROTOCOL: bad datagram length");
+  return { kind, channel, payload: bytes.slice(HEADER_BYTES) };
+}
+function readStreamFrame(buffer, limit) {
+  if (buffer.length < HEADER_BYTES) return void 0;
+  const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+  const version = buffer[0] ?? 0;
+  const kind = buffer[1] ?? 0;
+  const channel = view.getUint16(2);
+  const length = view.getUint32(4);
+  checkFrameHead(version, kind, channel);
+  if (length > limit) throw new Error("TN_NET_PROTOCOL: frame exceeds limit");
+  const frameBytes = HEADER_BYTES + length;
+  if (frameBytes > buffer.length) return void 0;
+  return {
+    frame: { kind, channel, payload: buffer.slice(HEADER_BYTES, frameBytes) },
+    rest: buffer.subarray(frameBytes)
+  };
+}
+function webTransportConstructor() {
+  const value = globalThis.WebTransport;
+  if (typeof value !== "function") return void 0;
+  return value;
+}
+function parseWelcome(payload, expectedProtocol) {
+  const text = new TextDecoder("utf-8", { fatal: true }).decode(payload);
+  const parsed = JSON.parse(text);
+  if (Object.keys(parsed).sort().join(",") !== "applicationProtocol,channels,maxQueuedDatagrams,maxQueuedReliableBytes,maxReliableMessageBytes,sessionId")
+    throw new Error("TN_NET_PROTOCOL: WELCOME has unexpected keys");
+  if (parsed.applicationProtocol !== expectedProtocol)
+    throw new Error("TN_NET_PROTOCOL: WELCOME protocol mismatch");
+  if (typeof parsed.sessionId !== "string" || !/^[0-9a-f]{32}$/u.test(parsed.sessionId))
+    throw new Error("TN_NET_PROTOCOL: WELCOME session id is invalid");
+  if (!Array.isArray(parsed.channels))
+    throw new Error("TN_NET_PROTOCOL: WELCOME channels are invalid");
+  const channels = parsed.channels.map((entry) => {
+    if (entry === null || typeof entry !== "object")
+      throw new Error("TN_NET_PROTOCOL: bad channel");
+    const record = entry;
+    if (Object.keys(record).sort().join(",") !== "delivery,id")
+      throw new Error("TN_NET_PROTOCOL: bad channel shape");
+    if (!Number.isInteger(record.id) || record.id < 1 || record.id > 65535)
+      throw new Error("TN_NET_PROTOCOL: bad channel id");
+    if (record.delivery !== "unreliable" && record.delivery !== "reliable-ordered")
+      throw new Error("TN_NET_PROTOCOL: bad delivery");
+    return {
+      id: record.id,
+      delivery: record.delivery
+    };
+  });
+  for (const key of [
+    "maxReliableMessageBytes",
+    "maxQueuedReliableBytes",
+    "maxQueuedDatagrams"
+  ]) {
+    const value = parsed[key];
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0)
+      throw new Error("TN_NET_PROTOCOL: bad WELCOME limit");
+  }
+  const messageLimit = parsed.maxReliableMessageBytes;
+  const queueLimit = parsed.maxQueuedReliableBytes;
+  if (messageLimit > queueLimit) throw new Error("TN_NET_PROTOCOL: invalid negotiated limits");
+  return {
+    sessionId: parsed.sessionId,
+    channels,
+    maxReliableMessageBytes: messageLimit,
+    maxQueuedReliableBytes: queueLimit,
+    maxQueuedDatagrams: parsed.maxQueuedDatagrams
+  };
+}
+async function writeAll(writable, bytes) {
+  const writer = writable.getWriter();
+  try {
+    await writer.write(bytes);
+  } finally {
+    writer.releaseLock();
+  }
+}
+function concatBytes(left, right) {
+  const out = new Uint8Array(left.length + right.length);
+  out.set(left, 0);
+  out.set(right, left.length);
+  return out;
+}
+function asBytes(chunk) {
+  if (chunk instanceof Uint8Array) return Uint8Array.from(chunk);
+  if (chunk instanceof ArrayBuffer) return Uint8Array.from(new Uint8Array(chunk));
+  return Uint8Array.from(new Uint8Array(chunk));
+}
+var FrameReader = class {
+  #reader;
+  #buffer = new Uint8Array(0);
+  #limit;
+  #released = false;
+  constructor(readable, limit) {
+    this.#reader = readable.getReader();
+    this.#limit = limit;
+  }
+  async nextFrame(signal) {
+    for (; ; ) {
+      if (signal?.aborted) throw new Error("TN_NET_CANCELLED: aborted");
+      const decoded = readStreamFrame(this.#buffer, this.#limit);
+      if (decoded !== void 0) {
+        this.#buffer = decoded.rest.length === 0 ? new Uint8Array(0) : decoded.rest;
+        return decoded.frame;
+      }
+      if (this.#buffer.length > this.#limit + HEADER_BYTES)
+        throw new Error("TN_NET_PROTOCOL: frame exceeds limit");
+      const abort = new Promise((_, reject) => {
+        signal?.addEventListener("abort", () => reject(new Error("TN_NET_CANCELLED: aborted")), {
+          once: true
+        });
+      });
+      const read = signal === void 0 ? await this.#reader.read() : await Promise.race([this.#reader.read(), abort]);
+      if (read.done) throw new Error("TN_NET_PROTOCOL: stream ended");
+      const chunk = asBytes(read.value);
+      this.#buffer = this.#buffer.length === 0 ? chunk : concatBytes(this.#buffer, chunk);
+    }
+  }
+  release() {
+    if (this.#released) return;
+    this.#released = true;
+    try {
+      this.#reader.releaseLock();
+    } catch {
+    }
+  }
+  cancel(reason) {
+    try {
+      return this.#reader.cancel(reason);
+    } catch {
+      return Promise.resolve();
+    }
+  }
+};
+
+// src/net-session.ts
+async function openConnection(url, normalized) {
+  if (normalized.signal?.aborted) throw new Error("TN_NET_CANCELLED: aborted before connect");
+  const Constructor = webTransportConstructor();
+  if (Constructor === void 0) throw new Error("TN_NET_UNAVAILABLE: WebTransport is missing");
+  const transport = new Constructor(url, {});
+  let timeoutId;
+  const onAbort = () => {
+    try {
+      transport.close();
+    } catch {
+    }
+  };
+  normalized.signal?.addEventListener("abort", onAbort, { once: true });
+  const deadline = new Promise((_, reject) => {
+    timeoutId = setTimeout(
+      () => reject(new Error("TN_NET_TIMEOUT: connect timed out")),
+      normalized.connectTimeoutMs
+    );
+  });
+  const cancelled = new Promise((_, reject) => {
+    if (normalized.signal === void 0) return;
+    if (normalized.signal.aborted) reject(new Error("TN_NET_CANCELLED: aborted"));
+    else
+      normalized.signal.addEventListener(
+        "abort",
+        () => reject(new Error("TN_NET_CANCELLED: aborted")),
+        { once: true }
+      );
+  });
+  try {
+    await Promise.race([Promise.resolve(transport.ready), deadline, cancelled]);
+  } finally {
+    if (timeoutId !== void 0) clearTimeout(timeoutId);
+    normalized.signal?.removeEventListener("abort", onAbort);
+  }
+  if (normalized.signal?.aborted) throw new Error("TN_NET_CANCELLED: aborted");
+  return establishSession(transport, normalized);
+}
+async function establishSession(transport, normalized) {
+  const abort = new AbortController();
+  const timer = setTimeout(() => abort.abort(), normalized.connectTimeoutMs);
+  const readers = [];
+  const writers = [];
+  try {
+    const controlStream = await Promise.resolve(transport.createBidirectionalStream());
+    writers.push(controlStream.writable);
+    const controlReader = new FrameReader(controlStream.readable, MAX_HELLO_BYTES);
+    readers.push(controlReader);
+    const helloPayload = new TextEncoder().encode(
+      JSON.stringify({
+        applicationProtocol: normalized.applicationProtocol,
+        credential: normalized.credential,
+        channels: normalized.channels.map((channel) => ({
+          id: channel.id,
+          delivery: channel.delivery
+        })),
+        maxReliableMessageBytes: normalized.maxReliableMessageBytes,
+        maxQueuedReliableBytes: normalized.maxQueuedReliableBytes,
+        maxQueuedDatagrams: normalized.maxQueuedDatagrams
+      })
+    );
+    if (helloPayload.length > MAX_HELLO_BYTES)
+      throw invalidArgument("handshake payload exceeds 4096 bytes");
+    await writeAll(controlStream.writable, encodeFrame(KIND_HELLO, 0, helloPayload));
+    const welcomeFrame = await controlReader.nextFrame(abort.signal);
+    if (welcomeFrame.kind !== KIND_WELCOME || welcomeFrame.channel !== 0)
+      throw new Error("TN_NET_PROTOCOL: expected WELCOME");
+    const welcome = parseWelcome(welcomeFrame.payload, normalized.applicationProtocol);
+    const expected = [...normalized.channels].sort((left, right) => left.id - right.id);
+    const offered = [...welcome.channels].sort((left, right) => left.id - right.id);
+    if (JSON.stringify(expected) !== JSON.stringify(offered))
+      throw new Error("TN_NET_PROTOCOL: WELCOME channels mismatch");
+    const messageLimit = Math.min(
+      normalized.maxReliableMessageBytes,
+      welcome.maxReliableMessageBytes
+    );
+    const queueLimit = Math.min(normalized.maxQueuedReliableBytes, welcome.maxQueuedReliableBytes);
+    const datagramLimit = Math.min(normalized.maxQueuedDatagrams, welcome.maxQueuedDatagrams);
+    if (messageLimit > queueLimit) throw new Error("TN_NET_PROTOCOL: invalid negotiated limits");
+    const maxDatagramSize = transport.datagrams.maxDatagramSize;
+    const maxDatagramPayload = typeof maxDatagramSize === "number" && Number.isFinite(maxDatagramSize) ? maxDatagramSize - HEADER_BYTES : Number.NaN;
+    if (!Number.isSafeInteger(maxDatagramPayload) || maxDatagramPayload <= 0)
+      throw new Error("TN_NET_UNAVAILABLE: datagram support is missing");
+    const reliableIds = expected.filter((channel) => channel.delivery === "reliable-ordered").map((channel) => channel.id);
+    const reliableReaders = /* @__PURE__ */ new Map();
+    const reliableWriters = /* @__PURE__ */ new Map();
+    for (const channelId of reliableIds) {
+      const stream = await Promise.resolve(transport.createBidirectionalStream());
+      writers.push(stream.writable);
+      const reader = new FrameReader(stream.readable, messageLimit);
+      readers.push(reader);
+      await writeAll(stream.writable, encodeFrame(KIND_BIND, channelId, new Uint8Array(0)));
+      const bound = await reader.nextFrame(abort.signal);
+      if (bound.kind !== KIND_BOUND || bound.channel !== channelId)
+        throw new Error("TN_NET_PROTOCOL: expected BOUND");
+      if (bound.payload.length !== 0) throw new Error("TN_NET_PROTOCOL: BOUND carries payload");
+      reliableReaders.set(channelId, reader);
+      reliableWriters.set(channelId, stream.writable);
+    }
+    clearTimeout(timer);
+    return createConnection({
+      transport,
+      channelById: new Map(normalized.channels.map((channel) => [channel.id, channel.delivery])),
+      sessionId: welcome.sessionId,
+      maxDatagramPayload,
+      maxReliableMessageBytes: messageLimit,
+      maxQueuedReliableBytes: queueLimit,
+      maxQueuedDatagrams: datagramLimit,
+      readers,
+      reliableReaders,
+      reliableWriters
+    });
+  } catch (error) {
+    clearTimeout(timer);
+    abort.abort();
+    for (const reader of readers) {
+      await reader.cancel(error);
+      reader.release();
+    }
+    try {
+      transport.close();
+    } catch {
+    }
+    if (normalized.signal?.aborted) throw new Error("TN_NET_CANCELLED: aborted");
+    if (error instanceof Error && error.message.startsWith("TN_NET_")) throw error;
+    if (error instanceof Error) throw new Error(`TN_NET_PROTOCOL: ${error.message}`);
+    throw new Error("TN_NET_UNAVAILABLE: handshake failed");
+  }
+}
+function createConnection(established) {
+  let state = "connected";
+  let disconnectReason = null;
+  let disconnectReported = false;
+  let closePromise;
+  let releasePromise;
+  let droppedDatagrams = 0;
+  let queuedReliableBytes = 0;
+  let queuedReliableBytesReceived = 0;
+  const pendingReliable = /* @__PURE__ */ new Map();
+  const pendingDatagrams = [];
+  const receiveQueue = [];
+  let flushScheduled = false;
+  for (const channelId of established.reliableReaders.keys()) pendingReliable.set(channelId, []);
+  const statsBase = {
+    transport: "webtransport",
+    sessionId: established.sessionId,
+    maxDatagramPayload: established.maxDatagramPayload,
+    maxReliableMessageBytes: established.maxReliableMessageBytes,
+    maxQueuedReliableBytes: established.maxQueuedReliableBytes,
+    maxQueuedDatagrams: established.maxQueuedDatagrams
+  };
+  const markDisconnected = (reason) => {
+    if (state === "closed") return;
+    state = "closed";
+    disconnectReason = reason;
+    void releaseAll();
+  };
+  const closedReason = (result) => {
+    if (typeof result === "object" && result !== null && "reason" in result) {
+      const reason = result.reason;
+      if (reason === null || reason === void 0) return null;
+      if (typeof reason === "string" && reason.length > 0) return reason;
+    }
+    return "transport closed";
+  };
+  void Promise.resolve(established.transport.closed).then(
+    (result) => markDisconnected(closedReason(result)),
+    () => markDisconnected("transport error")
+  );
+  const enqueueReceived = (channel, data) => {
+    const delivery = established.channelById.get(channel);
+    if (delivery === "reliable-ordered") {
+      if (queuedReliableBytesReceived + data.length > established.maxQueuedReliableBytes) return;
+      queuedReliableBytesReceived += data.length;
+      receiveQueue.push({ channel, data });
+      return;
+    }
+    if (delivery !== "unreliable") {
+      droppedDatagrams += 1;
+      return;
+    }
+    const unreliableCount = receiveQueue.filter(
+      (message) => established.channelById.get(message.channel) === "unreliable"
+    ).length;
+    if (unreliableCount >= established.maxQueuedDatagrams) {
+      const index = receiveQueue.findIndex(
+        (message) => established.channelById.get(message.channel) === "unreliable"
+      );
+      if (index >= 0) receiveQueue.splice(index, 1);
+      droppedDatagrams += 1;
+    }
+    receiveQueue.push({ channel, data });
+  };
+  const pumpReliable = (channelId, reader) => {
+    void (async () => {
+      try {
+        for (; ; ) {
+          if (state !== "connected") return;
+          if (queuedReliableBytesReceived >= established.maxQueuedReliableBytes) {
+            await new Promise((resolve) => setTimeout(resolve, 5));
+            continue;
+          }
+          const frame = await reader.nextFrame();
+          if (frame.kind !== KIND_DATA || frame.channel !== channelId)
+            throw new Error("TN_NET_PROTOCOL: wrong stream frame");
+          enqueueReceived(frame.channel, frame.payload.slice());
+        }
+      } catch {
+        if (state === "connected") markDisconnected("transport error");
+      }
+    })();
+  };
+  let datagramReader;
+  const pumpDatagrams = () => {
+    const reader = established.transport.datagrams.readable.getReader();
+    datagramReader = reader;
+    void (async () => {
+      try {
+        for (; ; ) {
+          if (state !== "connected") {
+            try {
+              reader.releaseLock();
+            } catch {
+            }
+            datagramReader = void 0;
+            return;
+          }
+          const read = await reader.read();
+          if (read.done) {
+            markDisconnected("transport closed");
+            return;
+          }
+          let frame;
+          try {
+            frame = decodeStandaloneFrame(asBytes(read.value).slice());
+          } catch {
+            droppedDatagrams += 1;
+            continue;
+          }
+          if (frame.kind !== KIND_DATA || established.channelById.get(frame.channel) !== "unreliable") {
+            droppedDatagrams += 1;
+            continue;
+          }
+          enqueueReceived(frame.channel, frame.payload.slice());
+        }
+      } catch {
+        if (state === "connected") markDisconnected("transport error");
+      }
+    })();
+  };
+  for (const [channelId, reader] of established.reliableReaders) pumpReliable(channelId, reader);
+  pumpDatagrams();
+  const flushQueues = () => {
+    if (flushScheduled) return;
+    flushScheduled = true;
+    void Promise.resolve().then(async () => {
+      try {
+        if (state !== "connected") return;
+        while (pendingDatagrams.length > 0) {
+          if (state !== "connected") return;
+          const next = pendingDatagrams.shift();
+          if (next === void 0) return;
+          try {
+            await writeAll(
+              established.transport.datagrams.writable,
+              encodeFrame(KIND_DATA, next.channel, next.bytes)
+            );
+          } catch {
+            markDisconnected("transport error");
+            return;
+          }
+        }
+        for (const [channelId, queue] of pendingReliable) {
+          while (queue.length > 0) {
+            if (state !== "connected") return;
+            const writer = established.reliableWriters.get(channelId);
+            const next = queue.shift();
+            if (writer === void 0 || next === void 0) break;
+            try {
+              await writeAll(writer, encodeFrame(KIND_DATA, channelId, next));
+              queuedReliableBytes -= next.length;
+            } catch {
+              markDisconnected("transport error");
+              return;
+            }
+          }
+        }
+      } finally {
+        flushScheduled = false;
+        if (state === "connected" && (pendingDatagrams.length > 0 || [...pendingReliable.values()].some((queue) => queue.length > 0)))
+          flushQueues();
+      }
+    });
+  };
+  async function releaseAll() {
+    if (releasePromise !== void 0) return releasePromise;
+    releasePromise = (async () => {
+      for (const reader of established.readers) {
+        try {
+          await reader.cancel(new Error("TN_NET_CLOSED: connection closed"));
+        } catch {
+        }
+        reader.release();
+      }
+      if (datagramReader !== void 0) {
+        try {
+          await datagramReader.cancel(new Error("TN_NET_CLOSED: connection closed"));
+        } catch {
+        }
+        try {
+          datagramReader.releaseLock();
+        } catch {
+        }
+        datagramReader = void 0;
+      } else {
+        try {
+          await established.transport.datagrams.readable.cancel(
+            new Error("TN_NET_CLOSED: connection closed")
+          );
+        } catch {
+        }
+      }
+      try {
+        established.transport.close();
+      } catch {
+      }
+    })();
+    return releasePromise;
+  }
+  return {
+    send(channel, data) {
+      const delivery = established.channelById.get(channel);
+      if (delivery === void 0) throw new Error("TN_NET_INVALID_ARGUMENT: unknown channel");
+      if (!(data instanceof Uint8Array))
+        throw new Error("TN_NET_INVALID_ARGUMENT: data must be bytes");
+      if (state !== "connected") throw new Error("TN_NET_CLOSED: connection is closed");
+      const bytes = Uint8Array.from(data);
+      if (delivery === "reliable-ordered") {
+        if (bytes.length > established.maxReliableMessageBytes)
+          throw new Error("TN_NET_MESSAGE_TOO_LARGE: reliable message exceeds limit");
+        if (queuedReliableBytes + bytes.length > established.maxQueuedReliableBytes) return false;
+        pendingReliable.get(channel)?.push(bytes);
+        queuedReliableBytes += bytes.length;
+        flushQueues();
+        return true;
+      }
+      const payloadLimit = established.maxDatagramPayload;
+      if (bytes.length > payloadLimit)
+        throw new Error("TN_NET_MESSAGE_TOO_LARGE: datagram exceeds limit");
+      if (pendingDatagrams.length >= established.maxQueuedDatagrams) {
+        pendingDatagrams.shift();
+        droppedDatagrams += 1;
+      }
+      pendingDatagrams.push({ channel, bytes });
+      flushQueues();
+      return true;
+    },
+    poll() {
+      const room = established.maxQueuedDatagrams * 2;
+      const messages = receiveQueue.splice(0, Math.max(0, room));
+      queuedReliableBytesReceived = receiveQueue.filter((message) => established.channelById.get(message.channel) === "reliable-ordered").reduce((sum, message) => sum + message.data.length, 0);
+      if (state === "closed" && !disconnectReported) {
+        disconnectReported = true;
+        return { messages, disconnected: true, reason: disconnectReason };
+      }
+      return { messages, disconnected: false, reason: null };
+    },
+    getStats() {
+      return {
+        ...statsBase,
+        state,
+        queuedReliableBytes,
+        queuedDatagrams: pendingDatagrams.length,
+        droppedDatagrams,
+        rttMs: null
+      };
+    },
+    close() {
+      if (closePromise !== void 0) return closePromise;
+      if (state === "connected") state = "closing";
+      closePromise = (async () => {
+        receiveQueue.length = 0;
+        pendingDatagrams.length = 0;
+        for (const queue of pendingReliable.values()) queue.length = 0;
+        queuedReliableBytes = 0;
+        queuedReliableBytesReceived = 0;
+        await releaseAll();
+        state = "closed";
+      })();
+      return closePromise;
+    }
+  };
+}
+
+// src/net.ts
+function connect(url, options) {
+  try {
+    const normalized = normalizeOptions(url, options);
+    return openConnection(url, normalized);
+  } catch (error) {
+    return Promise.reject(error);
+  }
+}
+
+export { connect };

package/dist/playtest.d.ts

@@ -1,8 +1,19 @@
-import { JsonValue } from '@threenative/playtest';
-import { c as IGamePluginHooks } from './game-DRt1Qhq3.js';
+import { JsonValue, JsonPrimitive } from '@threenative/playtest/protocol';
+import { b as IGamePluginHooks } from './game-XGrTzapq.js';
+import './assets-kyoF7JlJ.js';
 import 'three';
+import './renderer-C6hqZpoG.js';
+import 'three/webgpu';
+import './canvas-layer-BLVijiUJ.js';
 import 'zustand/vanilla';
 
+/**
+ * Install the playtest bridge into a portable game.
+ * @situation expose movement and world observations to a playtest
+ * @situation connect a game to the ThreeNative scenario runner
+ * @constraint install once in the game's plugin list
+ * @example const game = defineGame({ plugins: [playtest()] });
+ */
 declare function playtest<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined>(options?: IPlaytestOptions): IGamePluginHooks<TState, TPhysics>;
 declare const PLAYTEST_ATTACH_TIMEOUT_MS = 30000;
 /**
@@ -23,11 +34,33 @@ declare const PLAYTEST_RUNNER_EXPECTED_GLOBAL = "__THREENATIVE_PLAYTEST_RUNNER_E
 interface IPlaytestOptions {
     readonly events?: () => JsonValue[];
     /**
-     * Hold the frame loop until a runner attaches. Default false.
+     * Hold start-scene entry until a runner attaches. Defaults on for an announced runner.
      */
     readonly holdUntilAttached?: boolean;
     /** Milliseconds to wait when `holdUntilAttached` is set. Default {@link PLAYTEST_ATTACH_TIMEOUT_MS}. */
     readonly attachTimeoutMs?: number;
 }
+/**
+ * When a published value changed, and to what — the other half of "because".
+ *
+ * A run has always been able to say *a contact happened* and *the state reads `won`*. Nothing
+ * related the two, and a scenario could only compare at step boundaries, where a win arriving one
+ * tick after the contact and a win arriving 199 ticks later inside the same step are the same
+ * observation. That is exactly the shape of a game whose terminal state comes from a timer or a
+ * distance check and merely happens to land near a contact.
+ *
+ * The watcher diffs the published surface once per tick and records every change with the tick it
+ * happened on. It watches what a scenario can name: each registered entity's `state`, and the
+ * top-level primitive fields of the game's own published state. A deeper path is not watched, and
+ * an assertion about one fails closed rather than being answered from a value nobody diffed.
+ */
+declare const PLAYTEST_TRANSITION_LOG_LIMIT = 512;
+interface IPlaytestTransition {
+    from: JsonPrimitive;
+    /** `states.<entity>` for a registered entity, or `state.<field>` for a published field. */
+    path: string;
+    tick: number;
+    to: JsonPrimitive;
+}
 
-export { type IPlaytestOptions, PLAYTEST_ATTACH_TIMEOUT_MS, PLAYTEST_RUNNER_EXPECTED_GLOBAL, playtest };
+export { type IPlaytestOptions, type IPlaytestTransition, PLAYTEST_ATTACH_TIMEOUT_MS, PLAYTEST_RUNNER_EXPECTED_GLOBAL, PLAYTEST_TRANSITION_LOG_LIMIT, playtest };