@primitiv/network-common 0.19.0

package/LICENSE.txt

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Thomas Piquet (THP Software)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,9 @@
+# @primitiv/network-common
+
+> **Internal package** - This is an internal module of the [Primitiv Engine](https://primitivengine.com/).
+
+For documentation, examples, and guides, visit **[primitivengine.com](https://primitivengine.com/)**.
+
+## 📄 License
+
+Apache-2.0 - See [LICENSE.txt](./LICENSE.txt).

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var B=Object.defineProperty;var G=Object.getOwnPropertyDescriptor;var Y=Object.getOwnPropertyNames;var J=Object.prototype.hasOwnProperty;var X=(n,t)=>{for(var e in t)B(n,e,{get:t[e],enumerable:!0})},ee=(n,t,e,i)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of Y(t))!J.call(n,a)&&a!==e&&B(n,a,{get:()=>t[a],enumerable:!(i=G(t,a))||i.enumerable});return n};var te=n=>ee(B({},"__esModule",{value:!0}),n);var se={};X(se,{CallbackSectionType:()=>m,DC_RELIABLE:()=>Z,DC_UNRELIABLE:()=>z,FragmentAssembler:()=>w,HEADER_SIZE_FRAG:()=>g,HEADER_SIZE_SINGLE:()=>h,HandshakeState:()=>L,HandshakeStatus:()=>O,InterleavingManager:()=>R,LoopbackTransport:()=>M,MTU:()=>k,Marker:()=>l,Tick:()=>y,TransportState:()=>F,calculateFragmentCount:()=>D,createPacket:()=>T,decodeClientCallback:()=>K,decodeHeader:()=>A,encodeClientCallback:()=>N,encodeHeader:()=>P,extractPayload:()=>S,fragmentPacket:()=>U,isFragMarker:()=>x,isReliableMarker:()=>I,toFragMarker:()=>v,willFragment:()=>_});module.exports=te(se);var h=9,g=13,k=1200,l={HandshakeRequest:1,HandshakeResponse:2,HandshakeStateClient:3,HandshakeStateServer:4,Ping:5,Pong:6,LoadBundle:16,LoadBundleFrag:17,UpdateReliable:32,UpdateReliableFrag:33,UpdateVolatile:34,UpdateVolatileFrag:35,EmptyUpdate:36,InputReliable:48,InputReliableFrag:49,InputVolatile:50,InputVolatileFrag:51,AudioOrder:64,HapticOrder:65,PostProcessOrder:66,MacroOrder:67,BridgeToServer:80,BridgeToServerFrag:81,BridgeToClient:82,BridgeToClientFrag:83,ClientCallback:96,ClientCallbackFrag:97};function x(n){return n===l.LoadBundleFrag||n===l.UpdateReliableFrag||n===l.UpdateVolatileFrag||n===l.InputReliableFrag||n===l.InputVolatileFrag||n===l.BridgeToServerFrag||n===l.BridgeToClientFrag||n===l.ClientCallbackFrag}function v(n){switch(n){case l.LoadBundle:return l.LoadBundleFrag;case l.UpdateReliable:return l.UpdateReliableFrag;case l.UpdateVolatile:return l.UpdateVolatileFrag;case l.InputReliable:return l.InputReliableFrag;case l.InputVolatile:return l.InputVolatileFrag;case l.BridgeToServer:return l.BridgeToServerFrag;case l.BridgeToClient:return l.BridgeToClientFrag;case l.ClientCallback:return l.ClientCallbackFrag;default:return n}}function I(n){return n<=15||n===l.LoadBundle||n===l.LoadBundleFrag||n===l.UpdateReliable||n===l.UpdateReliableFrag||n===l.InputReliable||n===l.InputReliableFrag||n>=80}var O=(a=>(a[a.OK=0]="OK",a[a.VersionMismatch=1]="VersionMismatch",a[a.ServerFull=2]="ServerFull",a[a.AuthFailed=3]="AuthFailed",a))(O||{}),L=(o=>(o[o.Connected=0]="Connected",o[o.WaitingForResponse=1]="WaitingForResponse",o[o.Authenticating=2]="Authenticating",o[o.LoadingAssets=3]="LoadingAssets",o[o.Ready=4]="Ready",o[o.InSimulation=5]="InSimulation",o[o.Disconnected=255]="Disconnected",o))(L||{});var y=class n{high;low;constructor(t,e){this.high=t>>>0,this.low=e>>>0}static ZERO=new n(0,0);static from(t){let e=Number(t>>32n&0xffffffffn),i=Number(t&0xffffffffn);return new n(e,i)}static fromNumber(t){if(t<0)throw new Error("Tick must be positive");let e=Math.floor(t/4294967296),i=t>>>0;return new n(e,i)}static fromBuffer(t,e=0){let i=(t[e]<<24|t[e+1]<<16|t[e+2]<<8|t[e+3])>>>0,a=(t[e+4]<<24|t[e+5]<<16|t[e+6]<<8|t[e+7])>>>0;return new n(i,a)}toBigInt(){return BigInt(this.high)<<32n|BigInt(this.low)}toNumber(){return this.high*4294967296+this.low}toBuffer(){let t=new Uint8Array(8);return this.writeToBuffer(t,0),t}writeToBuffer(t,e=0){t[e]=this.high>>>24&255,t[e+1]=this.high>>>16&255,t[e+2]=this.high>>>8&255,t[e+3]=this.high&255,t[e+4]=this.low>>>24&255,t[e+5]=this.low>>>16&255,t[e+6]=this.low>>>8&255,t[e+7]=this.low&255}increment(){let t=this.low+1,e=this.high;return t>4294967295&&(t=0,e++),new n(e,t)}compare(t){return this.high!==t.high?this.high-t.high:this.low-t.low}equals(t){return this.high===t.high&&this.low===t.low}isZero(){return this.high===0&&this.low===0}toString(){return`Tick(${this.toBigInt()})`}getHigh(){return this.high}getLow(){return this.low}};function P(n){let e=n.fragInfo!==void 0?13:9,i=new Uint8Array(e);return E(n,i,0),i}function E(n,t,e){let i=n.fragInfo!==void 0;return t[e]=n.marker,i&&n.fragInfo?(t[e+1]=n.fragInfo.totalChunks>>>8&255,t[e+2]=n.fragInfo.totalChunks&255,t[e+3]=n.fragInfo.chunkIndex>>>8&255,t[e+4]=n.fragInfo.chunkIndex&255,n.tick.writeToBuffer(t,e+5),13):(n.tick.writeToBuffer(t,e+1),9)}function A(n){if(n.length<9)throw new Error(`Buffer too small for header: ${n.length} < ${9}`);let t=n[0];if(x(t)){if(n.length<13)throw new Error(`Buffer too small for frag header: ${n.length} < ${13}`);let a=n[1]<<8|n[2],r=n[3]<<8|n[4],s=y.fromBuffer(n,5);return{header:{marker:t,tick:s,fragInfo:{totalChunks:a,chunkIndex:r}},payloadOffset:13}}let i=y.fromBuffer(n,1);return{header:{marker:t,tick:i},payloadOffset:9}}function T(n,t){let i=n.fragInfo!==void 0?13:9,a=t?t.length:0,r=new Uint8Array(i+a);return E(n,r,0),a>0&&r.set(t,i),r}function S(n){let{header:t,payloadOffset:e}=A(n),i=n.slice(e);return{header:t,payload:i}}function U(n,t,e,i){let a=i?.mtu??1200,r=a-13;if(e.length+9<=a)return[T({marker:n,tick:t},e)];let s=v(n);if(s===n)throw new Error(`Packet with marker 0x${n.toString(16)} exceeds MTU (${a}) but has no fragmentation variant.`);let o=Math.ceil(e.length/r),c=[];for(let d=0;d<o;d++){let p=d*r,b=Math.min(p+r,e.length),j=e.subarray(p,b),q={marker:s,tick:t,fragInfo:{totalChunks:o,chunkIndex:d}};c.push(T(q,j))}return c}function D(n,t=1200){if(n+9<=t)return 1;let e=t-13;return Math.ceil(n/e)}function _(n,t=1200){return n+9>t}function ne(n,t){return`${n}:${t.getHigh()}:${t.getLow()}`}var w=class{buckets=new Map;ttlMs;maxPendingBuckets;maxTotalChunks;lastRejection=null;constructor(t){this.ttlMs=t?.ttlMs??1e4,this.maxPendingBuckets=t?.maxPendingBuckets??0,this.maxTotalChunks=t?.maxTotalChunks??0}receive(t){this.lastRejection=null;let{header:e,payloadOffset:i}=A(t),a=t.subarray(i);return!x(e.marker)||!e.fragInfo?{marker:e.marker,tick:e.tick,payload:a}:this.handleFragment(e,a)}handleFragment(t,e){let{marker:i,tick:a,fragInfo:r}=t;if(!r)return null;let s=ne(i,a),o=this.buckets.get(s);if(!o){if(this.maxTotalChunks>0&&r.totalChunks>this.maxTotalChunks)return this.lastRejection=`Fragment totalChunks (${r.totalChunks}) exceeds limit (${this.maxTotalChunks})`,null;if(this.maxPendingBuckets>0&&this.buckets.size>=this.maxPendingBuckets)return this.lastRejection=`Pending transfers (${this.buckets.size}) reached limit (${this.maxPendingBuckets})`,null;o={marker:i,tick:a,totalChunks:r.totalChunks,receivedCount:0,chunks:new Array(r.totalChunks).fill(null),createdAt:Date.now()},this.buckets.set(s,o)}if(r.chunkIndex>=o.totalChunks)return null;if(o.chunks[r.chunkIndex]===null&&(o.chunks[r.chunkIndex]=e,o.receivedCount++),o.receivedCount===o.totalChunks){let c=0;for(let b=0;b<o.chunks.length;b++)o.chunks[b]&&(c+=o.chunks[b].length);let d=new Uint8Array(c),p=0;for(let b of o.chunks)b&&(d.set(b,p),p+=b.length);return this.buckets.delete(s),{marker:i,tick:a,payload:d}}return null}cleanup(){let t=Date.now(),e=0;for(let[i,a]of this.buckets)t-a.createdAt>this.ttlMs&&(this.buckets.delete(i),e++);return e}getPendingCount(){return this.buckets.size}clearTick(t){for(let[e,i]of this.buckets)i.tick.equals(t)&&this.buckets.delete(e)}destroy(){this.buckets.clear()}};var R=class{transport;backgroundQueue=[];immediateQueue=[];bgCursor=0;imCursor=0;options;constructor(t,e={}){this.transport=t,this.options={fragmentsPerTick:e.fragmentsPerTick??5,bufferedThreshold:e.bufferedThreshold??16384,maxBackgroundQueue:e.maxBackgroundQueue??4096}}enqueue(t,e,i){let a=I(t),r=U(t,e,i);for(let s of r)this.backgroundQueue.push({data:s,reliable:a});this.enforceBackgroundLimit()}enqueueImmediate(t,e,i){let a=I(t),r=U(t,e,i);for(let s of r)this.immediateQueue.push({data:s,reliable:a})}enqueueRawImmediate(t,e){this.immediateQueue.push({data:t,reliable:e})}flush(){if(!this.transport.isReady())return;for(;this.imCursor<this.immediateQueue.length;){let i=this.immediateQueue[this.imCursor++];this.transport.send(i.data,i.reliable)}this.imCursor>0&&(this.immediateQueue.length=0,this.imCursor=0);let t=0,e=this.options.fragmentsPerTick;for(;this.bgCursor<this.backgroundQueue.length&&t<e&&this.transport.getBufferedAmount()<this.options.bufferedThreshold;){let i=this.backgroundQueue[this.bgCursor++];this.transport.send(i.data,i.reliable),t++}this.bgCursor>0&&this.bgCursor>=this.backgroundQueue.length?(this.backgroundQueue.length=0,this.bgCursor=0):this.bgCursor>256&&(this.backgroundQueue.splice(0,this.bgCursor),this.bgCursor=0)}clear(){this.backgroundQueue.length=0,this.immediateQueue.length=0,this.bgCursor=0,this.imCursor=0}enforceBackgroundLimit(){let t=this.backgroundQueue.length-this.bgCursor;if(this.options.maxBackgroundQueue>0&&t>this.options.maxBackgroundQueue){let e=t-this.options.maxBackgroundQueue;this.bgCursor+=e}}getPendingCount(){return this.backgroundQueue.length-this.bgCursor}hasImmediatePending(){return this.imCursor<this.immediateQueue.length}};var m={AudioAck:1,MacroFeedback:2},Q=1,W=2,$=3,V=4,H=5,C=new TextEncoder,f=new TextDecoder;function N(n){let t=[];if(n.audioAcks.length>0&&t.push({type:m.AudioAck,payload:re(n.audioAcks)}),n.macroFeedbacks.length>0&&t.push({type:m.MacroFeedback,payload:ie(n.macroFeedbacks)}),t.length===0)return new Uint8Array(0);let e=1;for(let r of t)e+=2+r.payload.byteLength;let i=new Uint8Array(e),a=0;i[a++]=t.length;for(let r of t)i[a++]=r.type,r.type===m.AudioAck?i[a++]=n.audioAcks.length:r.type===m.MacroFeedback?i[a++]=n.macroFeedbacks.length:i[a++]=0,i.set(r.payload,a),a+=r.payload.byteLength;return i}function re(n){let t=0,e=[];for(let s of n)switch(s.type){case"sound-loaded":{let o=C.encode(s.name);e.push({name:o}),t+=4+o.byteLength;break}case"sound-error":{let o=C.encode(s.name),c=C.encode(s.error);e.push({name:o,error:c}),t+=4+o.byteLength+1+c.byteLength;break}case"playback-started":e.push({}),t+=7;break;case"playback-ended":e.push({}),t+=7;break;case"playback-error":{let o=C.encode(s.error);e.push({error:o}),t+=2+(s.instanceId!=null?4:0)+2+1+o.byteLength;break}}let i=new Uint8Array(t),a=new DataView(i.buffer),r=0;for(let s=0;s<n.length;s++){let o=n[s],c=e[s];switch(o.type){case"sound-loaded":i[r++]=Q,a.setUint16(r,o.soundId,!1),r+=2,i[r++]=c.name.byteLength,i.set(c.name,r),r+=c.name.byteLength;break;case"sound-error":i[r++]=W,a.setUint16(r,o.soundId,!1),r+=2,i[r++]=c.name.byteLength,i.set(c.name,r),r+=c.name.byteLength,i[r++]=c.error.byteLength,i.set(c.error,r),r+=c.error.byteLength;break;case"playback-started":i[r++]=$,a.setUint32(r,o.instanceId,!1),r+=4,a.setUint16(r,o.soundId,!1),r+=2;break;case"playback-ended":i[r++]=V,a.setUint32(r,o.instanceId,!1),r+=4,a.setUint16(r,o.soundId,!1),r+=2;break;case"playback-error":{i[r++]=H;let d=o.instanceId!=null?1:0;i[r++]=d,d&&(a.setUint32(r,o.instanceId,!1),r+=4);let p=typeof o.sound=="number"?o.sound:0;a.setUint16(r,p,!1),r+=2,i[r++]=c.error.byteLength,i.set(c.error,r),r+=c.error.byteLength;break}}}return i}function ie(n){let t=0,e=[];for(let s of n)switch(t+=3,s.cmd){case 1:e.push(null);break;case 2:e.push(null),t+=1+(s.valueType==="number"?2:1);break;case 3:{let o=C.encode(s.text);e.push(o),t+=2+o.byteLength;break}case 4:e.push(null),t+=2;break;case 5:{let o=C.encode(s.data);e.push(o),t+=2+o.byteLength;break}}let i=new Uint8Array(t),a=new DataView(i.buffer),r=0;for(let s=0;s<n.length;s++){let o=n[s];switch(i[r++]=o.cmd,a.setUint16(r,o.instanceId,!1),r+=2,o.cmd){case 1:break;case 2:o.valueType==="number"?(i[r++]=0,a.setUint16(r,o.value,!1),r+=2):(i[r++]=1,i[r++]=o.value?1:0);break;case 3:{let c=e[s];a.setUint16(r,c.byteLength,!1),r+=2,i.set(c,r),r+=c.byteLength;break}case 4:a.setUint16(r,o.index,!1),r+=2;break;case 5:{let c=e[s];a.setUint16(r,c.byteLength,!1),r+=2,i.set(c,r),r+=c.byteLength;break}}}return i}function u(n,t,e){if(t+e>n.byteLength)throw new RangeError(`ClientCallback: truncated payload \u2014 need ${e} bytes at offset ${t}, but only ${n.byteLength-t} remain (total ${n.byteLength})`)}function K(n){let t={audioAcks:[],macroFeedbacks:[]};if(n.byteLength===0)return t;let e=new DataView(n.buffer,n.byteOffset,n.byteLength),i=0;u(n,i,1);let a=n[i++];for(let r=0;r<a;r++){u(n,i,2);let s=n[i++],o=n[i++];switch(s){case m.AudioAck:for(let c=0;c<o;c++){let{ack:d,newOffset:p}=ae(n,e,i);t.audioAcks.push(d),i=p}break;case m.MacroFeedback:for(let c=0;c<o;c++){let{feedback:d,newOffset:p}=oe(n,e,i);t.macroFeedbacks.push(d),i=p}break;default:return t}}return t}function ae(n,t,e){u(n,e,1);let i=n[e++];switch(i){case Q:{u(n,e,3);let a=t.getUint16(e,!1);e+=2;let r=n[e++];u(n,e,r);let s=f.decode(n.subarray(e,e+r));return e+=r,{ack:{type:"sound-loaded",soundId:a,name:s},newOffset:e}}case W:{u(n,e,3);let a=t.getUint16(e,!1);e+=2;let r=n[e++];u(n,e,r);let s=f.decode(n.subarray(e,e+r));e+=r,u(n,e,1);let o=n[e++];u(n,e,o);let c=f.decode(n.subarray(e,e+o));return e+=o,{ack:{type:"sound-error",soundId:a,name:s,error:c},newOffset:e}}case $:{u(n,e,6);let a=t.getUint32(e,!1);e+=4;let r=t.getUint16(e,!1);return e+=2,{ack:{type:"playback-started",instanceId:a,soundId:r},newOffset:e}}case V:{u(n,e,6);let a=t.getUint32(e,!1);e+=4;let r=t.getUint16(e,!1);return e+=2,{ack:{type:"playback-ended",instanceId:a,soundId:r},newOffset:e}}case H:{u(n,e,1);let a=n[e++];a&&u(n,e,4);let r=a?t.getUint32(e,!1):void 0;a&&(e+=4),u(n,e,3);let s=t.getUint16(e,!1);e+=2;let o=n[e++];u(n,e,o);let c=f.decode(n.subarray(e,e+o));return e+=o,{ack:{type:"playback-error",instanceId:r,sound:s,error:c},newOffset:e}}default:throw new Error(`Unknown AudioAck sub-type: 0x${i.toString(16)}`)}}function oe(n,t,e){u(n,e,3);let i=n[e++],a=t.getUint16(e,!1);switch(e+=2,i){case 1:return{feedback:{cmd:1,instanceId:a},newOffset:e};case 2:{u(n,e,1);let r=n[e++]===0?"number":"boolean",s;return r==="number"?(u(n,e,2),s=t.getUint16(e,!1),e+=2):(u(n,e,1),s=n[e++]!==0),{feedback:{cmd:2,instanceId:a,valueType:r,value:s},newOffset:e}}case 3:{u(n,e,2);let r=t.getUint16(e,!1);e+=2,u(n,e,r);let s=f.decode(n.subarray(e,e+r));return e+=r,{feedback:{cmd:3,instanceId:a,text:s},newOffset:e}}case 4:{u(n,e,2);let r=t.getUint16(e,!1);return e+=2,{feedback:{cmd:4,instanceId:a,index:r},newOffset:e}}case 5:{u(n,e,2);let r=t.getUint16(e,!1);e+=2,u(n,e,r);let s=f.decode(n.subarray(e,e+r));return e+=r,{feedback:{cmd:5,instanceId:a,data:s},newOffset:e}}default:throw new Error(`Unknown MacroFeedback cmd: 0x${i.toString(16)}`)}}var F=(a=>(a[a.Connecting=0]="Connecting",a[a.Open=1]="Open",a[a.Closing=2]="Closing",a[a.Closed=3]="Closed",a))(F||{});var M=class{onMessage=null;onInputMessage=null;onStateChange=null;onError=null;send(t,e){this.onMessage?.(t)}sendInput(t,e){this.onInputMessage?.(t)}getState(){return 1}getBufferedAmount(){return 0}isReady(){return!0}close(t,e){}};var Z="reliable",z="unreliable";

package/dist/index.d.ts

@@ -0,0 +1,1002 @@
+import { AudioAck, MacroFeedback } from '@primitiv/types';
+
+/**
+ * Primitiv V6 Protocol Constants and Types
+ * @packageDocumentation
+ */
+/** Standard header: Marker(1) + Tick(8) */
+declare const HEADER_SIZE_SINGLE = 9;
+/** Fragmented header: Marker(1) + FragBlock(4) + Tick(8) */
+declare const HEADER_SIZE_FRAG = 13;
+/** Maximum packet size before fragmentation */
+declare const MTU = 1200;
+/**
+ * Super-Marker registry for Primitiv V6 protocol
+ */
+declare const Marker: {
+    readonly HandshakeRequest: 1;
+    readonly HandshakeResponse: 2;
+    readonly HandshakeStateClient: 3;
+    readonly HandshakeStateServer: 4;
+    /** Client sends Ping to measure latency */
+    readonly Ping: 5;
+    /** Server responds with Pong */
+    readonly Pong: 6;
+    readonly LoadBundle: 16;
+    readonly LoadBundleFrag: 17;
+    readonly UpdateReliable: 32;
+    readonly UpdateReliableFrag: 33;
+    readonly UpdateVolatile: 34;
+    readonly UpdateVolatileFrag: 35;
+    readonly EmptyUpdate: 36;
+    readonly InputReliable: 48;
+    readonly InputReliableFrag: 49;
+    readonly InputVolatile: 50;
+    readonly InputVolatileFrag: 51;
+    readonly AudioOrder: 64;
+    readonly HapticOrder: 65;
+    readonly PostProcessOrder: 66;
+    readonly MacroOrder: 67;
+    /** App -> Server tunnel message */
+    readonly BridgeToServer: 80;
+    /** App -> Server tunnel message (Fragmented) */
+    readonly BridgeToServerFrag: 81;
+    /** Server -> App tunnel message */
+    readonly BridgeToClient: 82;
+    /** Server -> App tunnel message (Fragmented) */
+    readonly BridgeToClientFrag: 83;
+    readonly ClientCallback: 96;
+    readonly ClientCallbackFrag: 97;
+};
+type MarkerType = (typeof Marker)[keyof typeof Marker];
+/**
+ * Check if a marker is a fragmented type
+ */
+declare function isFragMarker(marker: number): boolean;
+/**
+ * Get the fragmented version of a marker
+ */
+declare function toFragMarker(marker: number): number;
+/**
+ * Check if a marker requires reliable transport
+ */
+declare function isReliableMarker(marker: number): boolean;
+/**
+ * Handshake response status codes
+ */
+declare enum HandshakeStatus {
+    OK = 0,
+    VersionMismatch = 1,
+    ServerFull = 2,
+    AuthFailed = 3
+}
+/**
+ * Handshake state machine states
+ */
+declare enum HandshakeState {
+    /** Initial state */
+    Connected = 0,
+    /** Waiting for version check response */
+    WaitingForResponse = 1,
+    /** Client sending credentials */
+    Authenticating = 2,
+    /** Loading assets */
+    LoadingAssets = 3,
+    /** Ready to start simulation */
+    Ready = 4,
+    /** In active simulation */
+    InSimulation = 5,
+    /** Disconnected or error */
+    Disconnected = 255
+}
+
+/**
+ * Tick - 64-bit simulation timestamp wrapper for browser compatibility
+ *
+ * The Tick is the core timing primitive in Primitiv V6 protocol.
+ * It's a uint64 encoded as Big-Endian in the wire format.
+ *
+ * @example
+ * ```ts
+ * const tick = Tick.from(12345n);
+ * const buffer = tick.toBuffer();
+ * const restored = Tick.fromBuffer(buffer);
+ * ```
+ */
+declare class Tick {
+    private readonly high;
+    private readonly low;
+    private constructor();
+    /** Zero tick (used for handshake) */
+    static readonly ZERO: Tick;
+    /** Create from BigInt */
+    static from(value: bigint): Tick;
+    /** Create from number (safe for values < 2^53) */
+    static fromNumber(value: number): Tick;
+    /** Create from 8-byte Big-Endian buffer */
+    static fromBuffer(buffer: Uint8Array, offset?: number): Tick;
+    /** Convert to BigInt */
+    toBigInt(): bigint;
+    /** Convert to number (precision loss for large values) */
+    toNumber(): number;
+    /** Write to 8-byte Big-Endian buffer */
+    toBuffer(): Uint8Array;
+    /** Write to existing buffer at offset */
+    writeToBuffer(buffer: Uint8Array, offset?: number): void;
+    /** Increment by 1 */
+    increment(): Tick;
+    /** Compare with another tick */
+    compare(other: Tick): number;
+    /** Check equality */
+    equals(other: Tick): boolean;
+    /** Check if this tick is zero */
+    isZero(): boolean;
+    toString(): string;
+    /** Get high 32 bits */
+    getHigh(): number;
+    /** Get low 32 bits */
+    getLow(): number;
+}
+
+/**
+ * Primitiv V6 Header Encoding/Decoding
+ */
+
+/**
+ * Fragment information for large packets
+ */
+interface FragInfo {
+    /** Total number of chunks */
+    totalChunks: number;
+    /** Index of this chunk (0-based) */
+    chunkIndex: number;
+}
+/**
+ * Primitiv packet header
+ */
+interface PrimitivHeader {
+    /** Message marker (type identifier) */
+    marker: number;
+    /** Simulation tick */
+    tick: Tick;
+    /** Fragment info (only for Frag markers) */
+    fragInfo?: FragInfo;
+}
+/**
+ * Result of decoding a header
+ */
+interface DecodeResult {
+    header: PrimitivHeader;
+    /** Offset where payload starts */
+    payloadOffset: number;
+}
+/**
+ * Encode a Primitiv header to binary
+ *
+ * Single packet: [Marker(1) + Tick(8)] = 9 bytes
+ * Frag packet: [Marker(1) + TotalChunks(2) + ChunkIndex(2) + Tick(8)] = 13 bytes
+ */
+declare function encodeHeader(header: PrimitivHeader): Uint8Array;
+/**
+ * Decode a Primitiv header from binary
+ */
+declare function decodeHeader(buffer: Uint8Array): DecodeResult;
+/**
+ * Create a complete packet with header + payload.
+ * Writes header directly into the final buffer (single allocation).
+ */
+declare function createPacket(header: PrimitivHeader, payload?: Uint8Array): Uint8Array;
+/**
+ * Extract payload from a packet
+ */
+declare function extractPayload(packet: Uint8Array): {
+    header: PrimitivHeader;
+    payload: Uint8Array;
+};
+
+/**
+ * Primitiv V6 Packet Fragmenter
+ *
+ * Splits large payloads into MTU-sized chunks with proper headers.
+ */
+
+/**
+ * Fragment options
+ */
+interface FragmentOptions {
+    /** Custom MTU (default: 1200) */
+    mtu?: number;
+}
+/**
+ * Fragment a packet if it exceeds MTU
+ *
+ * @param marker - Base marker (will be converted to Frag version if needed)
+ * @param tick - Simulation tick
+ * @param payload - Payload to send
+ * @param options - Optional fragmentation options
+ * @returns Array of complete packets ready to send
+ */
+declare function fragmentPacket(marker: number, tick: Tick, payload: Uint8Array, options?: FragmentOptions): Uint8Array[];
+/**
+ * Calculate the number of fragments needed for a payload
+ */
+declare function calculateFragmentCount(payloadSize: number, mtu?: number): number;
+/**
+ * Check if a payload will require fragmentation
+ */
+declare function willFragment(payloadSize: number, mtu?: number): boolean;
+
+/**
+ * Primitiv V6 Fragment Assembler
+ *
+ * Reassembles fragmented packets using composite key (Marker, Tick).
+ * Note: Cleanup must be triggered externally (no internal timers).
+ */
+
+/**
+ * Completed packet result
+ */
+interface CompletePacket {
+    marker: number;
+    tick: Tick;
+    payload: Uint8Array;
+}
+/**
+ * Assembler options
+ */
+interface AssemblerOptions {
+    /** Time-to-live for pending transfers in ms (default: 10000) */
+    ttlMs?: number;
+    /** Maximum number of concurrent pending transfers (default: unlimited) */
+    maxPendingBuckets?: number;
+    /** Maximum totalChunks value accepted per transfer (default: unlimited) */
+    maxTotalChunks?: number;
+}
+/**
+ * Fragment Assembler
+ *
+ * Handles both single packets (pass-through) and fragmented packets.
+ * Uses composite key (Marker, Tick) for isolation.
+ *
+ * @example
+ * ```ts
+ * const assembler = new FragmentAssembler();
+ *
+ * // In your tick loop or periodic cleanup:
+ * assembler.cleanup();
+ * ```
+ */
+declare class FragmentAssembler {
+    private readonly buckets;
+    private readonly ttlMs;
+    private readonly maxPendingBuckets;
+    private readonly maxTotalChunks;
+    /**
+     * Set after `receive()` returns `null` due to a security limit.
+     * Contains a human-readable reason, or `null` if the last
+     * rejection was simply "more fragments needed".
+     * Reset on every `receive()` call.
+     */
+    lastRejection: string | null;
+    constructor(options?: AssemblerOptions);
+    /**
+     * Process an incoming packet
+     *
+     * @param packet - Raw packet bytes
+     * @returns Complete packet if ready, null if more fragments needed
+     */
+    receive(packet: Uint8Array): CompletePacket | null;
+    /**
+     * Handle a fragmented packet
+     */
+    private handleFragment;
+    /**
+     * Cleanup stale transfers (call this periodically from external tick loop)
+     */
+    cleanup(): number;
+    /**
+     * Get pending transfer count (for debugging/monitoring)
+     */
+    getPendingCount(): number;
+    /**
+     * Force cleanup of all pending transfers for a tick
+     */
+    clearTick(tick: Tick): void;
+    /**
+     * Clear all pending transfers
+     */
+    destroy(): void;
+}
+
+/**
+ * Transport Abstraction Layer
+ *
+ * Defines interfaces for network transport (WebSocket, WebRTC, TCP, etc.)
+ * without implementation dependencies.
+ */
+/**
+ * Transport connection state
+ */
+declare enum TransportState {
+    Connecting = 0,
+    Open = 1,
+    Closing = 2,
+    Closed = 3
+}
+/**
+ * Message received callback
+ */
+type OnMessageCallback = (data: Uint8Array) => void;
+/**
+ * Connection state change callback
+ */
+type OnStateChangeCallback = (state: TransportState) => void;
+/**
+ * Error callback
+ */
+type OnErrorCallback = (error: Error) => void;
+/**
+ * Transport interface
+ *
+ * Abstraction over different transport mechanisms.
+ * Implementations should handle their specific protocol details.
+ */
+interface ITransport {
+    /**
+     * Send binary data
+     * @param data - Data to send
+     * @param reliable - If true, use reliable channel (TCP/Reliable DataChannel)
+     */
+    send(data: Uint8Array, reliable: boolean): void;
+    /**
+     * Close the transport connection
+     * @param code - Optional close code
+     * @param reason - Optional close reason
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * Get current connection state
+     */
+    getState(): TransportState;
+    /**
+     * Get amount of data buffered for sending (bytes)
+     * Used for backpressure/pacing
+     */
+    getBufferedAmount(): number;
+    /**
+     * Check if transport is ready to send
+     */
+    isReady(): boolean;
+    /**
+     * Set message handler
+     */
+    onMessage: OnMessageCallback | null;
+    /**
+     * Set state change handler
+     */
+    onStateChange: OnStateChangeCallback | null;
+    /**
+     * Set error handler
+     */
+    onError: OnErrorCallback | null;
+}
+/**
+ * Client transport interface
+ *
+ * Extended transport interface for client-side use.
+ * Adds connection initiation capability.
+ */
+interface IClientTransport extends ITransport {
+    /**
+     * Connect to a server
+     * @param url - Server URL to connect to
+     */
+    connect(url: string): Promise<void>;
+}
+/**
+ * Server transport interface
+ *
+ * Extended transport interface for server-side use.
+ */
+interface IServerTransport {
+    /**
+     * Start accepting connections
+     * @param port - Port to listen on
+     * @param host - Host to bind to (default: 0.0.0.0)
+     */
+    listen(port: number, host?: string): Promise<void>;
+    /**
+     * Stop accepting connections
+     */
+    stop(): Promise<void>;
+    /**
+     * Called when a new client connects
+     */
+    onConnection: ((clientId: string, transport: ITransport) => void) | null;
+    /**
+     * Called when a client disconnects
+     */
+    onDisconnection: ((clientId: string, reason?: string) => void) | null;
+    /**
+     * Get all connected client IDs
+     */
+    getConnectedClients(): string[];
+    /**
+     * Get transport for a specific client
+     */
+    getClientTransport(clientId: string): ITransport | null;
+    /**
+     * Disconnect a specific client
+     */
+    disconnectClient(clientId: string, reason?: string): void;
+}
+
+/**
+ * Primitiv Interleaving Manager
+ *
+ * Manages prioritized message queuing and paced fragmentation for the network stack.
+ * Ensures that large data transfers (background) don't block real-time updates (immediate).
+ */
+
+/**
+ * Interleaving Manager configuration
+ */
+interface InterleavingOptions {
+    /** Max fragments sent per flush call (background stream) */
+    fragmentsPerTick?: number;
+    /** Transport buffered amount threshold (pacing) */
+    bufferedThreshold?: number;
+    /**
+     * Maximum number of packets allowed in the background queue.
+     * When exceeded, the oldest undelivered packets are dropped.
+     * Prevents unbounded memory growth from slow/stalled clients.
+     * @default 4096
+     */
+    maxBackgroundQueue?: number;
+}
+/**
+ * Manages interleaving of fragments and real-time packets
+ */
+declare class InterleavingManager {
+    private readonly transport;
+    private readonly backgroundQueue;
+    private readonly immediateQueue;
+    private bgCursor;
+    private imCursor;
+    private readonly options;
+    constructor(transport: ITransport, options?: InterleavingOptions);
+    /**
+     * Enqueue a payload for interleaved (background) delivery.
+     * Large payloads will be automatically fragmented.
+     */
+    enqueue(marker: number, tick: Tick, payload: Uint8Array): void;
+    /**
+     * Enqueue a payload for prioritized immediate delivery.
+     * Large payloads will be automatically fragmented.
+     */
+    enqueueImmediate(marker: number, tick: Tick, payload: Uint8Array): void;
+    /**
+     * Enqueue a pre-built packet for immediate delivery.
+     * Skipping all queues and fragmentation logic.
+     */
+    enqueueRawImmediate(data: Uint8Array, reliable: boolean): void;
+    /**
+     * Flush queues to the transport
+     * Respects budget and bufferedAmount thresholds.
+     */
+    flush(): void;
+    /**
+     * Clear all pending messages
+     */
+    clear(): void;
+    /**
+     * Drop oldest undelivered background packets when the queue exceeds the limit.
+     * This prevents unbounded memory growth from slow or stalled clients.
+     */
+    private enforceBackgroundLimit;
+    /**
+     * Get number of pending background fragments
+     */
+    getPendingCount(): number;
+    /**
+     * Check if there are any pending immediate messages
+     */
+    hasImmediatePending(): boolean;
+}
+
+/**
+ * ClientCallback - Batched client->server feedback codec.
+ *
+ * Wire format:
+ * ┌────────────────┬───────────────────────────────────────────────────┐
+ * │ numSections: 1 │ Section[]                                        │
+ * └────────────────┴───────────────────────────────────────────────────┘
+ *
+ * Each Section:
+ * ┌──────────┬──────────┬──────────────────────────────────────────────┐
+ * │ type: 1  │ count: 1 │ entries (type-specific encoding)             │
+ * └──────────┴──────────┴──────────────────────────────────────────────┘
+ *
+ * Callback types:
+ *   0x01 = AudioAck
+ *
+ * AudioAck entry encoding:
+ *   ┌─────────────────┬─────────────────────────────────────────────┐
+ *   │ ackType: 1      │ fields (varies by ackType)                  │
+ *   └─────────────────┴─────────────────────────────────────────────┘
+ *
+ *   ackType 0x01 sound-loaded:  soundId:u16, nameLen:u8, name:utf8
+ *   ackType 0x02 sound-error:   soundId:u16, nameLen:u8, name:utf8, errLen:u8, err:utf8
+ *   ackType 0x03 playback-started: instanceId:u32, soundId:u16
+ *   ackType 0x04 playback-ended:   instanceId:u32, soundId:u16
+ *   ackType 0x05 playback-error:   hasInstance:u8, instanceId?:u32, soundRef:u16, errLen:u8, err:utf8
+ *
+ * MacroFeedback entry encoding:
+ *   ┌─────────────────┬─────────────────────────────────────────────┐
+ *   │ cmd: 1          │ instanceId: 2 │ fields (varies by cmd)      │
+ *   └─────────────────┴─────────────────────────────────────────────┘
+ *
+ *   cmd 0x01 click:    (no extra fields)
+ *   cmd 0x02 change:   valueType:u8 (0=number,1=bool), value:u16|u8
+ *   cmd 0x03 submit:   textLen:u16, text:utf8
+ *   cmd 0x04 select:   index:u16
+ *   cmd 0x05 custom:   dataLen:u16, data:utf8
+ */
+
+declare const CallbackSectionType: {
+    readonly AudioAck: 1;
+    readonly MacroFeedback: 2;
+};
+/**
+ * Decoded client callback payload - one section per callback type.
+ */
+interface DecodedClientCallback {
+    audioAcks: AudioAck[];
+    macroFeedbacks: MacroFeedback[];
+}
+/**
+ * Encode batched client callbacks into a compact binary payload.
+ *
+ * Only non-empty sections are written. Returns an empty Uint8Array
+ * if there is nothing to send.
+ */
+declare function encodeClientCallback(data: DecodedClientCallback): Uint8Array;
+/**
+ * Decode a ClientCallback binary payload into structured sections.
+ *
+ * Throws `RangeError` if the payload is truncated or malformed.
+ */
+declare function decodeClientCallback(data: Uint8Array): DecodedClientCallback;
+
+/**
+ * LoopbackTransport - Synchronous in-process transport for standalone mode.
+ *
+ * Implements ITransport without fragmentation, without copying, without interleaving.
+ * Passes Uint8Array buffers directly to the onMessage callback synchronously.
+ *
+ * Bidirectional:
+ * - send() → onMessage (server→client direction, for tick updates)
+ * - sendInput() → onInputMessage (client→server direction, for input)
+ */
+
+declare class LoopbackTransport implements ITransport {
+    /** Callback for server→client messages (tick updates) */
+    onMessage: OnMessageCallback | null;
+    /** Callback for client→server messages (input) */
+    onInputMessage: OnMessageCallback | null;
+    onStateChange: OnStateChangeCallback | null;
+    onError: OnErrorCallback | null;
+    /**
+     * Send data synchronously (server→client direction).
+     * Used for tick updates from engine to renderer.
+     */
+    send(data: Uint8Array, _reliable: boolean): void;
+    /**
+     * Send input data synchronously (client→server direction).
+     * Used for input from client to engine.
+     */
+    sendInput(data: Uint8Array, _reliable: boolean): void;
+    /**
+     * Always open.
+     */
+    getState(): TransportState;
+    /**
+     * No buffering in loopback.
+     */
+    getBufferedAmount(): number;
+    /**
+     * Always ready.
+     */
+    isReady(): boolean;
+    /**
+     * No-op for loopback.
+     */
+    close(_code?: number, _reason?: string): void;
+}
+
+/**
+ * WebRTC Signaling Protocol Types
+ *
+ * Defines JSON messages exchanged over the WebSocket signaling channel
+ * to establish WebRTC DataChannel connections.
+ *
+ * ## Server Transport Modes
+ *
+ * The server supports three distinct WebRTC transport modes:
+ *
+ * - **`webrtc-direct`** — Full ICE with local signaling. The game server runs
+ *   its own signaling WebSocket endpoint. Requires the server to be directly
+ *   reachable by clients (public IP or port forwarding). Best for dedicated
+ *   servers with known addresses.
+ *
+ * - **`webrtc-relay`** — Full ICE with external relay signaling. The game
+ *   server connects to a public signaling relay and registers under a
+ *   `sessionId`. Clients connect to the same relay with the matching
+ *   `sessionId`. Enables "zero-config" networking where neither server nor
+ *   clients need public IPs. Best for peer-hosted games or NAT traversal.
+ *
+ * - **`webrtc-lite`** — ICE-lite mode. The server opens a single multiplexed
+ *   UDP port and announces its address directly. Requires port forwarding but
+ *   guarantees ~100% connectivity.  Best for maximum reliability with known
+ *   server infrastructure.
+ *
+ * ## Client Transport Modes
+ *
+ * The client supports two WebRTC modes:
+ *
+ * - **`webrtc-full`** — Full ICE negotiation with STUN. Works with both
+ *   `webrtc-direct` and `webrtc-relay` servers. When `sessionId` is provided,
+ *   connects via relay; otherwise connects directly to the server URL.
+ *
+ * - **`webrtc-lite`** — ICE-lite mode. Connects to a `webrtc-lite` server.
+ *   No STUN required on the client side.
+ *
+ * ## Signaling Flow
+ *
+ * 1. Client opens signaling WebSocket (direct to server or via relay)
+ * 2. Client creates RTCPeerConnection + 2 DataChannels (reliable, unreliable)
+ * 3. Client sends `rtc-offer` with SDP
+ * 4. Server creates PeerConnection, sets remote offer, creates answer
+ * 5. Server sends `rtc-answer` with SDP
+ * 6. Both sides exchange `rtc-candidate` messages (ICE candidates)
+ * 7. DataChannels open → game protocol flows over DataChannels
+ * 8. Signaling WebSocket stays alive as a health-check channel
+ */
+/**
+ * Messages the client sends to the server during WebRTC signaling.
+ * Used in direct mode (client connects to server's signaling endpoint).
+ */
+type ClientSignalingMessage = {
+    type: 'rtc-offer';
+    sdp: string;
+} | {
+    type: 'rtc-candidate';
+    candidate: string;
+    mid: string;
+};
+/**
+ * Messages the server sends to the client during WebRTC signaling.
+ * Used in direct mode and relayed in relay mode.
+ */
+type ServerSignalingMessage = {
+    type: 'rtc-answer';
+    sdp: string;
+} | {
+    type: 'rtc-candidate';
+    candidate: string;
+    mid: string;
+} | {
+    type: 'rtc-error';
+    message: string;
+};
+/**
+ * Shared configuration options for all WebRTC server modes.
+ */
+interface BaseWebRTCServerConfig {
+    /**
+     * Maximum number of concurrent WebRTC peer connections.
+     * @default 64
+     */
+    maxPeers?: number;
+    /**
+     * List of allowed origins for the signaling WebSocket.
+     * If set, only connections with a matching `Origin` header are accepted.
+     * If omitted or empty, all origins are allowed.
+     *
+     * @example ['https://mygame.com', 'http://localhost:5173']
+     */
+    allowedOrigins?: string[];
+}
+/**
+ * Configuration for `webrtc-direct` server mode.
+ *
+ * The server runs its own signaling WebSocket endpoint and uses full ICE
+ * with STUN servers for NAT traversal. Requires the server to be directly
+ * reachable by clients.
+ *
+ * @example
+ * ```ts
+ * {
+ *   mode: 'direct',
+ *   stunServers: ['stun:stun.l.google.com:19302'],
+ * }
+ * ```
+ */
+interface WebRTCDirectServerConfig extends BaseWebRTCServerConfig {
+    /** Discriminant for direct mode. */
+    mode: 'direct';
+    /**
+     * STUN server URIs for ICE candidate gathering.
+     * Required for NAT traversal in direct mode.
+     *
+     * @example ['stun:stun.l.google.com:19302']
+     */
+    stunServers?: string[];
+}
+/**
+ * Configuration for `webrtc-relay` server mode.
+ *
+ * The server connects to an external signaling relay as a WebSocket client
+ * and registers under a `sessionId`. Clients connect to the same relay
+ * with the matching `sessionId` and are routed to this server.
+ *
+ * This enables "zero-config" networking where both server and clients only
+ * need to know the relay URL and a shared session ID — no port forwarding
+ * or public IP required on the server.
+ *
+ * @example
+ * ```ts
+ * {
+ *   mode: 'relay',
+ *   signalingUrl: 'wss://signal.example.com',
+ *   sessionId: 'my-game-abc123',
+ *   stunServers: ['stun:stun.l.google.com:19302'],
+ * }
+ * ```
+ */
+interface WebRTCRelayServerConfig extends BaseWebRTCServerConfig {
+    /** Discriminant for relay mode. */
+    mode: 'relay';
+    /**
+     * URL of the external signaling relay server.
+     * The game server connects to this relay as a WebSocket client.
+     *
+     * @example 'wss://signal.example.com'
+     */
+    signalingUrl: string;
+    /**
+     * Session identifier for relay registration.
+     *
+     * The server registers under this ID. Clients connect to the same relay
+     * with the matching `sessionId` to be routed to this server.
+     *
+     * @example 'my-game-abc123'
+     */
+    sessionId: string;
+    /**
+     * STUN server URIs for ICE candidate gathering.
+     * Required for NAT traversal.
+     *
+     * @example ['stun:stun.l.google.com:19302']
+     */
+    stunServers?: string[];
+}
+/**
+ * Configuration for `webrtc-lite` server mode.
+ *
+ * ICE-lite mode: the server opens a single multiplexed UDP port and
+ * announces its address directly to clients. Requires port forwarding
+ * on the server side but guarantees ~100% connectivity.
+ *
+ * @example
+ * ```ts
+ * {
+ *   mode: 'lite',
+ *   dataPort: 9000,
+ * }
+ * ```
+ */
+interface WebRTCLiteServerConfig extends BaseWebRTCServerConfig {
+    /** Discriminant for ICE-lite mode. */
+    mode: 'lite';
+    /**
+     * UDP port for WebRTC data.
+     * All clients are multiplexed on this single port.
+     * @default port + 1 (where port is the signaling/HTTP port)
+     */
+    dataPort?: number;
+    /**
+     * Bind address for the UDP socket.
+     * @default '0.0.0.0'
+     */
+    bindAddress?: string;
+}
+/**
+ * Union of all WebRTC server configurations.
+ * Discriminated on the `mode` field.
+ */
+type WebRTCServerConfig = WebRTCDirectServerConfig | WebRTCRelayServerConfig | WebRTCLiteServerConfig;
+/**
+ * Configuration for `webrtc-full` client mode.
+ *
+ * Uses full ICE negotiation with STUN servers. Can connect to either:
+ * - A `webrtc-direct` server (via `signalingUrl` pointing to the server)
+ * - A `webrtc-relay` server (via `signalingUrl` pointing to relay + `sessionId`)
+ *
+ * The presence of `sessionId` determines whether to use relay mode.
+ *
+ * @example Direct mode (connect to server directly)
+ * ```ts
+ * {
+ *   mode: 'full',
+ *   signalingUrl: 'ws://gameserver.example.com:3000',
+ *   stunServers: ['stun:stun.l.google.com:19302'],
+ * }
+ * ```
+ *
+ * @example Relay mode (connect via signaling relay)
+ * ```ts
+ * {
+ *   mode: 'full',
+ *   signalingUrl: 'wss://signal.example.com',
+ *   sessionId: 'my-game-abc123',
+ *   stunServers: ['stun:stun.l.google.com:19302'],
+ * }
+ * ```
+ */
+interface WebRTCFullClientConfig {
+    /** Discriminant for full ICE mode. */
+    mode: 'full';
+    /**
+     * URL of the signaling endpoint.
+     *
+     * - In direct mode: WebSocket URL of the game server's signaling endpoint.
+     * - In relay mode: WebSocket URL of the external signaling relay.
+     *
+     * @example 'ws://gameserver:3000' or 'wss://signal.example.com'
+     */
+    signalingUrl?: string;
+    /**
+     * Session identifier for relay mode.
+     *
+     * When set, the client connects to the relay and requests to join the
+     * session with this ID. The relay routes the client to the game server
+     * that registered with the same `sessionId`.
+     *
+     * When omitted, the client connects directly to the server (direct mode).
+     *
+     * @example 'my-game-abc123'
+     */
+    sessionId?: string;
+    /**
+     * STUN server URIs for ICE candidate gathering.
+     *
+     * @example ['stun:stun.l.google.com:19302']
+     */
+    stunServers?: string[];
+}
+/**
+ * Configuration for `webrtc-lite` client mode.
+ *
+ * Connects to a `webrtc-lite` server. No STUN required on the client side
+ * since the server announces its address directly.
+ *
+ * @example
+ * ```ts
+ * {
+ *   mode: 'lite',
+ *   signalingUrl: 'ws://gameserver.example.com:3000',
+ * }
+ * ```
+ */
+interface WebRTCLiteClientConfig {
+    /** Discriminant for ICE-lite mode. */
+    mode: 'lite';
+    /**
+     * WebSocket URL of the game server's signaling endpoint.
+     *
+     * @example 'ws://gameserver.example.com:3000'
+     */
+    signalingUrl?: string;
+}
+/**
+ * Union of all WebRTC client configurations.
+ * Discriminated on the `mode` field.
+ */
+type WebRTCClientConfig = WebRTCFullClientConfig | WebRTCLiteClientConfig;
+/**
+ * Messages the game server sends TO the signaling relay.
+ *
+ * The relay is a lightweight WebSocket router. The game server connects as a
+ * WS client, registers with `'register-server'`, then receives client
+ * signaling messages and responds with SDP answers / ICE candidates - each
+ * tagged with `clientId` so the relay can route them.
+ */
+type ServerToRelayMessage = {
+    type: 'register-server';
+    sessionId: string;
+} | {
+    type: 'rtc-answer';
+    clientId: string;
+    sdp: string;
+} | {
+    type: 'rtc-candidate';
+    clientId: string;
+    candidate: string;
+    mid: string;
+} | {
+    type: 'rtc-error';
+    clientId: string;
+    message: string;
+};
+/**
+ * Messages the signaling relay sends TO the game server.
+ *
+ * Each message from a client is tagged with `clientId` so the server knows
+ * which PeerConnection it belongs to.
+ */
+type RelayToServerMessage = {
+    type: 'server-registered';
+    serverId: string;
+} | {
+    type: 'client-joined';
+    clientId: string;
+} | {
+    type: 'client-left';
+    clientId: string;
+} | {
+    type: 'rtc-offer';
+    clientId: string;
+    sdp: string;
+} | {
+    type: 'rtc-candidate';
+    clientId: string;
+    candidate: string;
+    mid: string;
+};
+/**
+ * Messages the client sends TO the signaling relay.
+ *
+ * The client connects to the relay, sends `'join-session'` with a `sessionId`
+ * to be routed to the game server that registered with that ID.
+ */
+type ClientToRelayMessage = {
+    type: 'join-session';
+    sessionId: string;
+} | {
+    type: 'rtc-offer';
+    sdp: string;
+} | {
+    type: 'rtc-candidate';
+    candidate: string;
+    mid: string;
+};
+/**
+ * Messages the signaling relay sends TO the client.
+ *
+ * The relay routes these messages from the game server to the client.
+ */
+type RelayToClientMessage = {
+    type: 'session-joined';
+    serverId: string;
+} | {
+    type: 'session-not-found';
+    sessionId: string;
+} | {
+    type: 'rtc-answer';
+    sdp: string;
+} | {
+    type: 'rtc-candidate';
+    candidate: string;
+    mid: string;
+} | {
+    type: 'rtc-error';
+    message: string;
+};
+/** Label for the ordered, reliable DataChannel */
+declare const DC_RELIABLE = "reliable";
+/** Label for the unordered, unreliable DataChannel (maxRetransmits = 0) */
+declare const DC_UNRELIABLE = "unreliable";
+
+export { CallbackSectionType, DC_RELIABLE, DC_UNRELIABLE, FragmentAssembler, HEADER_SIZE_FRAG, HEADER_SIZE_SINGLE, HandshakeState, HandshakeStatus, InterleavingManager, LoopbackTransport, MTU, Marker, Tick, TransportState, calculateFragmentCount, createPacket, decodeClientCallback, decodeHeader, encodeClientCallback, encodeHeader, extractPayload, fragmentPacket, isFragMarker, isReliableMarker, toFragMarker, willFragment };
+export type { AssemblerOptions, ClientSignalingMessage, ClientToRelayMessage, CompletePacket, DecodeResult, DecodedClientCallback, FragInfo, FragmentOptions, IClientTransport, IServerTransport, ITransport, InterleavingOptions, MarkerType, OnErrorCallback, OnMessageCallback, OnStateChangeCallback, PrimitivHeader, RelayToClientMessage, RelayToServerMessage, ServerSignalingMessage, ServerToRelayMessage, WebRTCClientConfig, WebRTCDirectServerConfig, WebRTCFullClientConfig, WebRTCLiteClientConfig, WebRTCLiteServerConfig, WebRTCRelayServerConfig, WebRTCServerConfig };

package/dist/index.mjs

@@ -0,0 +1 @@
+var h=9,p=13,C=1200,l={HandshakeRequest:1,HandshakeResponse:2,HandshakeStateClient:3,HandshakeStateServer:4,Ping:5,Pong:6,LoadBundle:16,LoadBundleFrag:17,UpdateReliable:32,UpdateReliableFrag:33,UpdateVolatile:34,UpdateVolatileFrag:35,EmptyUpdate:36,InputReliable:48,InputReliableFrag:49,InputVolatile:50,InputVolatileFrag:51,AudioOrder:64,HapticOrder:65,PostProcessOrder:66,MacroOrder:67,BridgeToServer:80,BridgeToServerFrag:81,BridgeToClient:82,BridgeToClientFrag:83,ClientCallback:96,ClientCallbackFrag:97};function f(n){return n===l.LoadBundleFrag||n===l.UpdateReliableFrag||n===l.UpdateVolatileFrag||n===l.InputReliableFrag||n===l.InputVolatileFrag||n===l.BridgeToServerFrag||n===l.BridgeToClientFrag||n===l.ClientCallbackFrag}function v(n){switch(n){case l.LoadBundle:return l.LoadBundleFrag;case l.UpdateReliable:return l.UpdateReliableFrag;case l.UpdateVolatile:return l.UpdateVolatileFrag;case l.InputReliable:return l.InputReliableFrag;case l.InputVolatile:return l.InputVolatileFrag;case l.BridgeToServer:return l.BridgeToServerFrag;case l.BridgeToClient:return l.BridgeToClientFrag;case l.ClientCallback:return l.ClientCallbackFrag;default:return n}}function I(n){return n<=15||n===l.LoadBundle||n===l.LoadBundleFrag||n===l.UpdateReliable||n===l.UpdateReliableFrag||n===l.InputReliable||n===l.InputReliableFrag||n>=80}var B=(a=>(a[a.OK=0]="OK",a[a.VersionMismatch=1]="VersionMismatch",a[a.ServerFull=2]="ServerFull",a[a.AuthFailed=3]="AuthFailed",a))(B||{}),O=(o=>(o[o.Connected=0]="Connected",o[o.WaitingForResponse=1]="WaitingForResponse",o[o.Authenticating=2]="Authenticating",o[o.LoadingAssets=3]="LoadingAssets",o[o.Ready=4]="Ready",o[o.InSimulation=5]="InSimulation",o[o.Disconnected=255]="Disconnected",o))(O||{});var y=class n{high;low;constructor(t,e){this.high=t>>>0,this.low=e>>>0}static ZERO=new n(0,0);static from(t){let e=Number(t>>32n&0xffffffffn),i=Number(t&0xffffffffn);return new n(e,i)}static fromNumber(t){if(t<0)throw new Error("Tick must be positive");let e=Math.floor(t/4294967296),i=t>>>0;return new n(e,i)}static fromBuffer(t,e=0){let i=(t[e]<<24|t[e+1]<<16|t[e+2]<<8|t[e+3])>>>0,a=(t[e+4]<<24|t[e+5]<<16|t[e+6]<<8|t[e+7])>>>0;return new n(i,a)}toBigInt(){return BigInt(this.high)<<32n|BigInt(this.low)}toNumber(){return this.high*4294967296+this.low}toBuffer(){let t=new Uint8Array(8);return this.writeToBuffer(t,0),t}writeToBuffer(t,e=0){t[e]=this.high>>>24&255,t[e+1]=this.high>>>16&255,t[e+2]=this.high>>>8&255,t[e+3]=this.high&255,t[e+4]=this.low>>>24&255,t[e+5]=this.low>>>16&255,t[e+6]=this.low>>>8&255,t[e+7]=this.low&255}increment(){let t=this.low+1,e=this.high;return t>4294967295&&(t=0,e++),new n(e,t)}compare(t){return this.high!==t.high?this.high-t.high:this.low-t.low}equals(t){return this.high===t.high&&this.low===t.low}isZero(){return this.high===0&&this.low===0}toString(){return`Tick(${this.toBigInt()})`}getHigh(){return this.high}getLow(){return this.low}};function $(n){let e=n.fragInfo!==void 0?13:9,i=new Uint8Array(e);return L(n,i,0),i}function L(n,t,e){let i=n.fragInfo!==void 0;return t[e]=n.marker,i&&n.fragInfo?(t[e+1]=n.fragInfo.totalChunks>>>8&255,t[e+2]=n.fragInfo.totalChunks&255,t[e+3]=n.fragInfo.chunkIndex>>>8&255,t[e+4]=n.fragInfo.chunkIndex&255,n.tick.writeToBuffer(t,e+5),13):(n.tick.writeToBuffer(t,e+1),9)}function A(n){if(n.length<9)throw new Error(`Buffer too small for header: ${n.length} < ${9}`);let t=n[0];if(f(t)){if(n.length<13)throw new Error(`Buffer too small for frag header: ${n.length} < ${13}`);let a=n[1]<<8|n[2],r=n[3]<<8|n[4],s=y.fromBuffer(n,5);return{header:{marker:t,tick:s,fragInfo:{totalChunks:a,chunkIndex:r}},payloadOffset:13}}let i=y.fromBuffer(n,1);return{header:{marker:t,tick:i},payloadOffset:9}}function T(n,t){let i=n.fragInfo!==void 0?13:9,a=t?t.length:0,r=new Uint8Array(i+a);return L(n,r,0),a>0&&r.set(t,i),r}function V(n){let{header:t,payloadOffset:e}=A(n),i=n.slice(e);return{header:t,payload:i}}function U(n,t,e,i){let a=i?.mtu??1200,r=a-13;if(e.length+9<=a)return[T({marker:n,tick:t},e)];let s=v(n);if(s===n)throw new Error(`Packet with marker 0x${n.toString(16)} exceeds MTU (${a}) but has no fragmentation variant.`);let o=Math.ceil(e.length/r),c=[];for(let d=0;d<o;d++){let g=d*r,b=Math.min(g+r,e.length),Q=e.subarray(g,b),W={marker:s,tick:t,fragInfo:{totalChunks:o,chunkIndex:d}};c.push(T(W,Q))}return c}function H(n,t=1200){if(n+9<=t)return 1;let e=t-13;return Math.ceil(n/e)}function N(n,t=1200){return n+9>t}function K(n,t){return`${n}:${t.getHigh()}:${t.getLow()}`}var w=class{buckets=new Map;ttlMs;maxPendingBuckets;maxTotalChunks;lastRejection=null;constructor(t){this.ttlMs=t?.ttlMs??1e4,this.maxPendingBuckets=t?.maxPendingBuckets??0,this.maxTotalChunks=t?.maxTotalChunks??0}receive(t){this.lastRejection=null;let{header:e,payloadOffset:i}=A(t),a=t.subarray(i);return!f(e.marker)||!e.fragInfo?{marker:e.marker,tick:e.tick,payload:a}:this.handleFragment(e,a)}handleFragment(t,e){let{marker:i,tick:a,fragInfo:r}=t;if(!r)return null;let s=K(i,a),o=this.buckets.get(s);if(!o){if(this.maxTotalChunks>0&&r.totalChunks>this.maxTotalChunks)return this.lastRejection=`Fragment totalChunks (${r.totalChunks}) exceeds limit (${this.maxTotalChunks})`,null;if(this.maxPendingBuckets>0&&this.buckets.size>=this.maxPendingBuckets)return this.lastRejection=`Pending transfers (${this.buckets.size}) reached limit (${this.maxPendingBuckets})`,null;o={marker:i,tick:a,totalChunks:r.totalChunks,receivedCount:0,chunks:new Array(r.totalChunks).fill(null),createdAt:Date.now()},this.buckets.set(s,o)}if(r.chunkIndex>=o.totalChunks)return null;if(o.chunks[r.chunkIndex]===null&&(o.chunks[r.chunkIndex]=e,o.receivedCount++),o.receivedCount===o.totalChunks){let c=0;for(let b=0;b<o.chunks.length;b++)o.chunks[b]&&(c+=o.chunks[b].length);let d=new Uint8Array(c),g=0;for(let b of o.chunks)b&&(d.set(b,g),g+=b.length);return this.buckets.delete(s),{marker:i,tick:a,payload:d}}return null}cleanup(){let t=Date.now(),e=0;for(let[i,a]of this.buckets)t-a.createdAt>this.ttlMs&&(this.buckets.delete(i),e++);return e}getPendingCount(){return this.buckets.size}clearTick(t){for(let[e,i]of this.buckets)i.tick.equals(t)&&this.buckets.delete(e)}destroy(){this.buckets.clear()}};var R=class{transport;backgroundQueue=[];immediateQueue=[];bgCursor=0;imCursor=0;options;constructor(t,e={}){this.transport=t,this.options={fragmentsPerTick:e.fragmentsPerTick??5,bufferedThreshold:e.bufferedThreshold??16384,maxBackgroundQueue:e.maxBackgroundQueue??4096}}enqueue(t,e,i){let a=I(t),r=U(t,e,i);for(let s of r)this.backgroundQueue.push({data:s,reliable:a});this.enforceBackgroundLimit()}enqueueImmediate(t,e,i){let a=I(t),r=U(t,e,i);for(let s of r)this.immediateQueue.push({data:s,reliable:a})}enqueueRawImmediate(t,e){this.immediateQueue.push({data:t,reliable:e})}flush(){if(!this.transport.isReady())return;for(;this.imCursor<this.immediateQueue.length;){let i=this.immediateQueue[this.imCursor++];this.transport.send(i.data,i.reliable)}this.imCursor>0&&(this.immediateQueue.length=0,this.imCursor=0);let t=0,e=this.options.fragmentsPerTick;for(;this.bgCursor<this.backgroundQueue.length&&t<e&&this.transport.getBufferedAmount()<this.options.bufferedThreshold;){let i=this.backgroundQueue[this.bgCursor++];this.transport.send(i.data,i.reliable),t++}this.bgCursor>0&&this.bgCursor>=this.backgroundQueue.length?(this.backgroundQueue.length=0,this.bgCursor=0):this.bgCursor>256&&(this.backgroundQueue.splice(0,this.bgCursor),this.bgCursor=0)}clear(){this.backgroundQueue.length=0,this.immediateQueue.length=0,this.bgCursor=0,this.imCursor=0}enforceBackgroundLimit(){let t=this.backgroundQueue.length-this.bgCursor;if(this.options.maxBackgroundQueue>0&&t>this.options.maxBackgroundQueue){let e=t-this.options.maxBackgroundQueue;this.bgCursor+=e}}getPendingCount(){return this.backgroundQueue.length-this.bgCursor}hasImmediatePending(){return this.imCursor<this.immediateQueue.length}};var m={AudioAck:1,MacroFeedback:2},P=1,E=2,S=3,D=4,_=5,k=new TextEncoder,x=new TextDecoder;function Z(n){let t=[];if(n.audioAcks.length>0&&t.push({type:m.AudioAck,payload:z(n.audioAcks)}),n.macroFeedbacks.length>0&&t.push({type:m.MacroFeedback,payload:j(n.macroFeedbacks)}),t.length===0)return new Uint8Array(0);let e=1;for(let r of t)e+=2+r.payload.byteLength;let i=new Uint8Array(e),a=0;i[a++]=t.length;for(let r of t)i[a++]=r.type,r.type===m.AudioAck?i[a++]=n.audioAcks.length:r.type===m.MacroFeedback?i[a++]=n.macroFeedbacks.length:i[a++]=0,i.set(r.payload,a),a+=r.payload.byteLength;return i}function z(n){let t=0,e=[];for(let s of n)switch(s.type){case"sound-loaded":{let o=k.encode(s.name);e.push({name:o}),t+=4+o.byteLength;break}case"sound-error":{let o=k.encode(s.name),c=k.encode(s.error);e.push({name:o,error:c}),t+=4+o.byteLength+1+c.byteLength;break}case"playback-started":e.push({}),t+=7;break;case"playback-ended":e.push({}),t+=7;break;case"playback-error":{let o=k.encode(s.error);e.push({error:o}),t+=2+(s.instanceId!=null?4:0)+2+1+o.byteLength;break}}let i=new Uint8Array(t),a=new DataView(i.buffer),r=0;for(let s=0;s<n.length;s++){let o=n[s],c=e[s];switch(o.type){case"sound-loaded":i[r++]=P,a.setUint16(r,o.soundId,!1),r+=2,i[r++]=c.name.byteLength,i.set(c.name,r),r+=c.name.byteLength;break;case"sound-error":i[r++]=E,a.setUint16(r,o.soundId,!1),r+=2,i[r++]=c.name.byteLength,i.set(c.name,r),r+=c.name.byteLength,i[r++]=c.error.byteLength,i.set(c.error,r),r+=c.error.byteLength;break;case"playback-started":i[r++]=S,a.setUint32(r,o.instanceId,!1),r+=4,a.setUint16(r,o.soundId,!1),r+=2;break;case"playback-ended":i[r++]=D,a.setUint32(r,o.instanceId,!1),r+=4,a.setUint16(r,o.soundId,!1),r+=2;break;case"playback-error":{i[r++]=_;let d=o.instanceId!=null?1:0;i[r++]=d,d&&(a.setUint32(r,o.instanceId,!1),r+=4);let g=typeof o.sound=="number"?o.sound:0;a.setUint16(r,g,!1),r+=2,i[r++]=c.error.byteLength,i.set(c.error,r),r+=c.error.byteLength;break}}}return i}function j(n){let t=0,e=[];for(let s of n)switch(t+=3,s.cmd){case 1:e.push(null);break;case 2:e.push(null),t+=1+(s.valueType==="number"?2:1);break;case 3:{let o=k.encode(s.text);e.push(o),t+=2+o.byteLength;break}case 4:e.push(null),t+=2;break;case 5:{let o=k.encode(s.data);e.push(o),t+=2+o.byteLength;break}}let i=new Uint8Array(t),a=new DataView(i.buffer),r=0;for(let s=0;s<n.length;s++){let o=n[s];switch(i[r++]=o.cmd,a.setUint16(r,o.instanceId,!1),r+=2,o.cmd){case 1:break;case 2:o.valueType==="number"?(i[r++]=0,a.setUint16(r,o.value,!1),r+=2):(i[r++]=1,i[r++]=o.value?1:0);break;case 3:{let c=e[s];a.setUint16(r,c.byteLength,!1),r+=2,i.set(c,r),r+=c.byteLength;break}case 4:a.setUint16(r,o.index,!1),r+=2;break;case 5:{let c=e[s];a.setUint16(r,c.byteLength,!1),r+=2,i.set(c,r),r+=c.byteLength;break}}}return i}function u(n,t,e){if(t+e>n.byteLength)throw new RangeError(`ClientCallback: truncated payload \u2014 need ${e} bytes at offset ${t}, but only ${n.byteLength-t} remain (total ${n.byteLength})`)}function q(n){let t={audioAcks:[],macroFeedbacks:[]};if(n.byteLength===0)return t;let e=new DataView(n.buffer,n.byteOffset,n.byteLength),i=0;u(n,i,1);let a=n[i++];for(let r=0;r<a;r++){u(n,i,2);let s=n[i++],o=n[i++];switch(s){case m.AudioAck:for(let c=0;c<o;c++){let{ack:d,newOffset:g}=G(n,e,i);t.audioAcks.push(d),i=g}break;case m.MacroFeedback:for(let c=0;c<o;c++){let{feedback:d,newOffset:g}=Y(n,e,i);t.macroFeedbacks.push(d),i=g}break;default:return t}}return t}function G(n,t,e){u(n,e,1);let i=n[e++];switch(i){case P:{u(n,e,3);let a=t.getUint16(e,!1);e+=2;let r=n[e++];u(n,e,r);let s=x.decode(n.subarray(e,e+r));return e+=r,{ack:{type:"sound-loaded",soundId:a,name:s},newOffset:e}}case E:{u(n,e,3);let a=t.getUint16(e,!1);e+=2;let r=n[e++];u(n,e,r);let s=x.decode(n.subarray(e,e+r));e+=r,u(n,e,1);let o=n[e++];u(n,e,o);let c=x.decode(n.subarray(e,e+o));return e+=o,{ack:{type:"sound-error",soundId:a,name:s,error:c},newOffset:e}}case S:{u(n,e,6);let a=t.getUint32(e,!1);e+=4;let r=t.getUint16(e,!1);return e+=2,{ack:{type:"playback-started",instanceId:a,soundId:r},newOffset:e}}case D:{u(n,e,6);let a=t.getUint32(e,!1);e+=4;let r=t.getUint16(e,!1);return e+=2,{ack:{type:"playback-ended",instanceId:a,soundId:r},newOffset:e}}case _:{u(n,e,1);let a=n[e++];a&&u(n,e,4);let r=a?t.getUint32(e,!1):void 0;a&&(e+=4),u(n,e,3);let s=t.getUint16(e,!1);e+=2;let o=n[e++];u(n,e,o);let c=x.decode(n.subarray(e,e+o));return e+=o,{ack:{type:"playback-error",instanceId:r,sound:s,error:c},newOffset:e}}default:throw new Error(`Unknown AudioAck sub-type: 0x${i.toString(16)}`)}}function Y(n,t,e){u(n,e,3);let i=n[e++],a=t.getUint16(e,!1);switch(e+=2,i){case 1:return{feedback:{cmd:1,instanceId:a},newOffset:e};case 2:{u(n,e,1);let r=n[e++]===0?"number":"boolean",s;return r==="number"?(u(n,e,2),s=t.getUint16(e,!1),e+=2):(u(n,e,1),s=n[e++]!==0),{feedback:{cmd:2,instanceId:a,valueType:r,value:s},newOffset:e}}case 3:{u(n,e,2);let r=t.getUint16(e,!1);e+=2,u(n,e,r);let s=x.decode(n.subarray(e,e+r));return e+=r,{feedback:{cmd:3,instanceId:a,text:s},newOffset:e}}case 4:{u(n,e,2);let r=t.getUint16(e,!1);return e+=2,{feedback:{cmd:4,instanceId:a,index:r},newOffset:e}}case 5:{u(n,e,2);let r=t.getUint16(e,!1);e+=2,u(n,e,r);let s=x.decode(n.subarray(e,e+r));return e+=r,{feedback:{cmd:5,instanceId:a,data:s},newOffset:e}}default:throw new Error(`Unknown MacroFeedback cmd: 0x${i.toString(16)}`)}}var F=(a=>(a[a.Connecting=0]="Connecting",a[a.Open=1]="Open",a[a.Closing=2]="Closing",a[a.Closed=3]="Closed",a))(F||{});var M=class{onMessage=null;onInputMessage=null;onStateChange=null;onError=null;send(t,e){this.onMessage?.(t)}sendInput(t,e){this.onInputMessage?.(t)}getState(){return 1}getBufferedAmount(){return 0}isReady(){return!0}close(t,e){}};var J="reliable",X="unreliable";export{m as CallbackSectionType,J as DC_RELIABLE,X as DC_UNRELIABLE,w as FragmentAssembler,p as HEADER_SIZE_FRAG,h as HEADER_SIZE_SINGLE,O as HandshakeState,B as HandshakeStatus,R as InterleavingManager,M as LoopbackTransport,C as MTU,l as Marker,y as Tick,F as TransportState,H as calculateFragmentCount,T as createPacket,q as decodeClientCallback,A as decodeHeader,Z as encodeClientCallback,$ as encodeHeader,V as extractPayload,U as fragmentPacket,f as isFragMarker,I as isReliableMarker,v as toFragMarker,N as willFragment};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@primitiv/network-common",
+  "version": "0.19.0",
+  "description": "Primitiv network common module",
+  "author": "THP Software",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thp-software/primitiv",
+    "directory": "packages/network-common"
+  },
+  "homepage": "https://primitivengine.com",
+  "bugs": {
+    "url": "https://github.com/thp-software/primitiv/issues"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@primitiv/types": "0.19.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "rimraf dist && node ../../scripts/build-package.mjs packages/network-common",
+    "dev": "tsc --watch",
+    "clean": "rimraf dist",
+    "lint": "eslint \"src/**/*.ts\" --max-warnings 0",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --import tsx src/**/*.test.ts"
+  }
+}