@threenative/core 0.3.0 → 0.3.2

package/dist/net.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Optional portable message transport over the platform WebTransport seam.
+ *
+ * Browser and native share this implementation: WebTransport owns QUIC/HTTP3
+ * security and reliability, while this module owns validation, bounded queues,
+ * application framing and delivery semantics. Gameplay serialization and
+ * simulation stay in game/server code.
+ */
+interface INetworkChannel {
+    id: number;
+    delivery: "unreliable" | "reliable-ordered";
+}
+interface INetworkOptions {
+    applicationProtocol: string;
+    credential: string;
+    channels: readonly INetworkChannel[];
+    signal?: AbortSignal;
+    connectTimeoutMs?: number;
+    maxReliableMessageBytes?: number;
+    maxQueuedReliableBytes?: number;
+    maxQueuedDatagrams?: number;
+}
+interface INetworkMessage {
+    channel: number;
+    data: Uint8Array;
+}
+interface INetworkPoll {
+    messages: INetworkMessage[];
+    disconnected: boolean;
+    reason: string | null;
+}
+interface INetworkStats {
+    transport: "webtransport";
+    state: "connected" | "closing" | "closed";
+    sessionId: string;
+    maxDatagramPayload: number;
+    maxReliableMessageBytes: number;
+    maxQueuedReliableBytes: number;
+    maxQueuedDatagrams: number;
+    queuedReliableBytes: number;
+    queuedDatagrams: number;
+    droppedDatagrams: number;
+    rttMs: number | null;
+}
+interface INetworkConnection {
+    send(channel: number, data: Uint8Array): boolean;
+    poll(): INetworkPoll;
+    getStats(): INetworkStats;
+    close(): Promise<void>;
+}
+/**
+ * Open a bounded, authenticated WebTransport message channel shared by browser and native games.
+ *
+ * @situation connect two game clients over the portable WebTransport seam
+ * @situation send ordered actions and bounded unreliable state messages between game clients
+ * @situation exchange multiplayer messages without putting replication or gameplay in the engine
+ * @constraint the URL must use HTTPS and the credential is supplied by the game's identity flow; this API never issues credentials
+ * @constraint channels, message sizes, and queues are validated before WebTransport opens, and reliable overflow returns false
+ * @constraint native qualification depends on the installed host WebTransport bridge; iOS remains unverified
+ * @override connectTimeoutMs, maxReliableMessageBytes, maxQueuedReliableBytes, and maxQueuedDatagrams are named per-connection limits
+ * @example const connection = await connect("https://game.example/game", { applicationProtocol: "my-game/1", credential, channels: [{ id: 1, delivery: "unreliable" }] });
+ */
+declare function connect(url: string, options: INetworkOptions): Promise<INetworkConnection>;
+
+export { type INetworkChannel, type INetworkConnection, type INetworkMessage, type INetworkOptions, type INetworkPoll, type INetworkStats, connect };