modd-network 1.0.0 → 1.0.1

package/dist/index.d.ts

@@ -1,37 +1,2 @@
-export interface MODDOptions {
-    centralServiceUrl?: string;
-    nodeUrl?: string;
-}
-export interface OrderedInput {
-    data: any;
-    sequenceNumber: number;
-    timestamp: number;
-    clientId: string;
-    id: string;
-}
-export type InputHandler = (input: OrderedInput) => void;
-export type SnapshotHandler = (snapshot: any) => void;
-export declare class MODD {
-    private ws;
-    private roomId;
-    private appId;
-    private centralServiceUrl;
-    private nodeUrl;
-    private snapshot;
-    private inputHandlers;
-    private snapshotHandlers;
-    constructor(appId: string, options?: MODDOptions);
-    createRoom(roomId: string, initialSnapshot: any): Promise<void>;
-    joinRoom(roomId: string): Promise<void>;
-    private setupMessageHandlers;
-    sendInput(data: any): void;
-    sendSnapshot(snapshot: any): void;
-    onInput(handler: InputHandler): void;
-    onSnapshot(handler: SnapshotHandler): void;
-    getSnapshot(): any;
-    disconnect(): void;
-    private getNodeUrl;
-    private hashSnapshot;
-}
-export declare class MeshClient extends MODD {
-}
+export * from './modd-network';
+export * from './modd-engine';

package/dist/index.js

@@ -1,177 +1,18 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MeshClient = exports.MODD = void 0;
-const ws_1 = __importDefault(require("ws"));
-const crypto_1 = __importDefault(require("crypto"));
-// Primary SDK client: MODD
-class MODD {
-    ws = null;
-    roomId = null;
-    appId = null;
-    centralServiceUrl;
-    nodeUrl = null;
-    snapshot = null;
-    inputHandlers = [];
-    snapshotHandlers = [];
-    constructor(appId, options = {}) {
-        this.appId = appId;
-        this.centralServiceUrl = options.centralServiceUrl || 'ws://localhost:9001';
-        this.nodeUrl = options.nodeUrl || null;
-    }
-    async createRoom(roomId, initialSnapshot) {
-        if (!this.appId) {
-            throw new Error('appId is required. Initialize MODD with appId in constructor.');
-        }
-        this.roomId = roomId;
-        this.snapshot = initialSnapshot;
-        const nodeUrl = this.nodeUrl || await this.getNodeUrl(roomId);
-        return new Promise((resolve, reject) => {
-            this.ws = new ws_1.default(nodeUrl);
-            this.ws.on('open', () => {
-                this.ws.send(JSON.stringify({
-                    type: 'CREATE_ROOM',
-                    payload: { roomId, appId: this.appId, snapshot: initialSnapshot }
-                }));
-            });
-            this.ws.on('message', (data) => {
-                const message = JSON.parse(data.toString());
-                if (message.type === 'ROOM_CREATED') {
-                    console.log('Room created:', roomId);
-                    this.setupMessageHandlers();
-                    resolve();
-                }
-            });
-            this.ws.on('error', reject);
-        });
-    }
-    async joinRoom(roomId) {
-        if (!this.appId) {
-            throw new Error('appId is required. Initialize MODD with appId in constructor.');
-        }
-        this.roomId = roomId;
-        const nodeUrl = this.nodeUrl || await this.getNodeUrl(roomId);
-        return new Promise((resolve, reject) => {
-            this.ws = new ws_1.default(nodeUrl);
-            this.ws.on('open', () => {
-                this.ws.send(JSON.stringify({
-                    type: 'JOIN_ROOM',
-                    payload: { roomId, appId: this.appId }
-                }));
-            });
-            this.ws.on('message', (data) => {
-                const message = JSON.parse(data.toString());
-                if (message.type === 'INITIAL_STATE') {
-                    this.snapshot = message.payload.snapshot;
-                    const inputs = message.payload.inputs || [];
-                    // Apply any pending inputs to catch up (in sequence order)
-                    const sortedInputs = [...inputs].sort((a, b) => a.sequenceNumber - b.sequenceNumber);
-                    sortedInputs.forEach((input) => {
-                        const orderedInput = {
-                            data: input.data,
-                            sequenceNumber: input.sequenceNumber,
-                            timestamp: input.timestamp,
-                            clientId: input.clientId,
-                            id: input.id
-                        };
-                        this.inputHandlers.forEach(handler => handler(orderedInput));
-                    });
-                }
-                if (message.type === 'ROOM_JOINED') {
-                    console.log('Joined room:', roomId);
-                    this.setupMessageHandlers();
-                    resolve();
-                }
-            });
-            this.ws.on('error', reject);
-        });
-    }
-    setupMessageHandlers() {
-        if (!this.ws)
-            return;
-        this.ws.on('message', (data) => {
-            const message = JSON.parse(data.toString());
-            if (message.type === 'ORDERED_INPUTS') {
-                const inputs = message.payload.inputs || [];
-                inputs.forEach((input) => {
-                    const orderedInput = {
-                        data: input.data,
-                        sequenceNumber: input.sequenceNumber,
-                        timestamp: input.timestamp,
-                        clientId: input.clientId,
-                        id: input.id
-                    };
-                    this.inputHandlers.forEach(handler => handler(orderedInput));
-                });
-            }
-            if (message.type === 'SNAPSHOT_UPDATE') {
-                this.snapshot = message.payload.snapshot;
-                this.snapshotHandlers.forEach(handler => handler(this.snapshot));
-            }
-        });
-    }
-    sendInput(data) {
-        if (!this.ws || !this.roomId) {
-            throw new Error('Not connected to a room');
-        }
-        this.ws.send(JSON.stringify({
-            type: 'SEND_INPUT',
-            payload: { roomId: this.roomId, data }
-        }));
-    }
-    sendSnapshot(snapshot) {
-        if (!this.ws || !this.roomId) {
-            throw new Error('Not connected to a room');
-        }
-        this.snapshot = snapshot;
-        const hash = this.hashSnapshot(snapshot);
-        this.ws.send(JSON.stringify({
-            type: 'SEND_SNAPSHOT',
-            payload: { roomId: this.roomId, snapshot, hash }
-        }));
-    }
-    onInput(handler) {
-        this.inputHandlers.push(handler);
-    }
-    onSnapshot(handler) {
-        this.snapshotHandlers.push(handler);
-    }
-    getSnapshot() {
-        return this.snapshot;
-    }
-    disconnect() {
-        if (this.ws) {
-            this.ws.close();
-            this.ws = null;
-        }
-    }
-    async getNodeUrl(roomId) {
-        if (!this.appId) {
-            throw new Error('appId is required');
-        }
-        // Use REST API instead of WebSocket for better error handling
-        const httpUrl = this.centralServiceUrl.replace('ws://', 'http://').replace('wss://', 'https://');
-        const response = await fetch(`${httpUrl}/api/apps/${this.appId}/rooms/${roomId}/connect`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({})
-        });
-        if (!response.ok) {
-            const error = await response.json().catch(() => ({ error: 'Failed to connect to room' }));
-            throw new Error(error.error || `HTTP ${response.status}`);
-        }
-        const data = await response.json();
-        return data.url;
-    }
-    hashSnapshot(snapshot) {
-        const data = JSON.stringify(snapshot);
-        return crypto_1.default.createHash('sha256').update(data).digest('hex');
-    }
-}
-exports.MODD = MODD;
-// Backwards-compatible alias
-class MeshClient extends MODD {
-}
-exports.MeshClient = MeshClient;
+__exportStar(require("./modd-network"), exports);
+__exportStar(require("./modd-engine"), exports);

package/dist/modd-engine.d.ts

@@ -0,0 +1,95 @@
+/**
+ * MODD Engine SDK
+ * Game synchronization utilities for multiplayer games
+ * - Proximity-based authority
+ * - Delta compression
+ * - Rest detection
+ * - Soft sync / interpolation
+ */
+import type { Connection } from './modd-network';
+export interface EntityState {
+    x: number;
+    y: number;
+    z: number;
+    vx?: number;
+    vy?: number;
+    vz?: number;
+    qx?: number;
+    qy?: number;
+    qz?: number;
+    qw?: number;
+    avx?: number;
+    avy?: number;
+    avz?: number;
+    [key: string]: any;
+}
+export interface PhysicsAdapter {
+    getState(): EntityState;
+    setState(state: EntityState): void;
+}
+export interface EngineOptions {
+    softSyncLerp?: number;
+    positionThreshold?: number;
+    velocityThreshold?: number;
+    rotationThreshold?: number;
+    restVelocityThreshold?: number;
+    restFramesRequired?: number;
+    touchBonusScore?: number;
+    touchBonusDecay?: number;
+}
+export interface Entity {
+    id: string;
+    adapter: PhysicsAdapter;
+    state: EntityState;
+    lastSentState?: EntityState;
+    restFrames: number;
+    lastTouchedBy?: string;
+    lastTouchFrame?: number;
+}
+export interface Player {
+    id: string;
+    x: number;
+    y: number;
+    z: number;
+    dead?: boolean;
+}
+export declare function createEngine(options?: EngineOptions): {
+    readonly config: {
+        softSyncLerp: number;
+        positionThreshold: number;
+        velocityThreshold: number;
+        rotationThreshold: number;
+        restVelocityThreshold: number;
+        restFramesRequired: number;
+        touchBonusScore: number;
+        touchBonusDecay: number;
+    };
+    setConnection(conn: Connection): void;
+    setLocalPlayer(playerId: string): void;
+    setFrame(frame: number): void;
+    registerEntity(id: string, adapter: PhysicsAdapter): void;
+    unregisterEntity(id: string): void;
+    getEntity(id: string): Entity | undefined;
+    updatePlayer(id: string, x: number, y: number, z: number, dead?: boolean): void;
+    removePlayer(id: string): void;
+    computeAuthority: (entityId: string) => string | null;
+    isLocalAuthority: (entityId: string) => boolean;
+    syncFromPhysics(entityId: string): void;
+    syncAllFromPhysics(): void;
+    sendUpdates: () => void;
+    handleEntityState: (id: string, state: EntityState) => void;
+    handleEntityTouch: (id: string, touchedBy: string, frame: number) => void;
+    checkPlayerTouches(playerId: string, playerX: number, playerZ: number, touchDistance?: number): void;
+    checkEntityCollisions(touchDistance?: number): void;
+    wakeEntity: (entityId: string) => void;
+    isAtRest: (entityId: string) => boolean;
+    hasStateChanged: (entityId: string) => boolean;
+};
+/**
+ * Rapier 3D physics adapter
+ */
+export declare function rapierAdapter(body: any): PhysicsAdapter;
+/**
+ * Generic 2D physics adapter (for Matter.js, Planck, etc.)
+ */
+export declare function generic2DAdapter(getBody: () => any, setBody: (state: any) => void): PhysicsAdapter;

package/dist/modd-engine.js

@@ -0,0 +1,389 @@
+"use strict";
+/**
+ * MODD Engine SDK
+ * Game synchronization utilities for multiplayer games
+ * - Proximity-based authority
+ * - Delta compression
+ * - Rest detection
+ * - Soft sync / interpolation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEngine = createEngine;
+exports.rapierAdapter = rapierAdapter;
+exports.generic2DAdapter = generic2DAdapter;
+// ============================================
+// Engine Implementation
+// ============================================
+function createEngine(options = {}) {
+    // Configuration with defaults
+    const config = {
+        softSyncLerp: options.softSyncLerp ?? 0.5,
+        positionThreshold: options.positionThreshold ?? 0.01,
+        velocityThreshold: options.velocityThreshold ?? 0.1,
+        rotationThreshold: options.rotationThreshold ?? 0.01,
+        restVelocityThreshold: options.restVelocityThreshold ?? 0.05,
+        restFramesRequired: options.restFramesRequired ?? 30,
+        touchBonusScore: options.touchBonusScore ?? 50,
+        touchBonusDecay: options.touchBonusDecay ?? 100,
+    };
+    // State
+    const entities = new Map();
+    const players = new Map();
+    let localPlayerId = null;
+    let currentFrame = 0;
+    let connection = null;
+    // ==========================================
+    // Authority Computation
+    // ==========================================
+    function simpleHash(str) {
+        let h = 0;
+        for (let i = 0; i < str.length; i++) {
+            h = ((h << 5) - h + str.charCodeAt(i)) | 0;
+        }
+        return Math.abs(h);
+    }
+    function computeAuthority(entityId) {
+        const entity = entities.get(entityId);
+        if (!entity)
+            return null;
+        const playerIds = Array.from(players.keys()).sort();
+        if (playerIds.length === 0)
+            return null;
+        let bestPlayer = null;
+        let bestScore = -Infinity;
+        for (const pid of playerIds) {
+            const player = players.get(pid);
+            if (player.dead)
+                continue;
+            // Distance-based score (closer = higher)
+            const dx = player.x - entity.state.x;
+            const dz = player.z - entity.state.z;
+            const dist = Math.sqrt(dx * dx + dz * dz);
+            let score = 1000 - dist * 10;
+            // Touch bonus (decays over time)
+            if (entity.lastTouchedBy === pid) {
+                const framesSinceTouch = currentFrame - (entity.lastTouchFrame || 0);
+                const decayRate = config.touchBonusScore / config.touchBonusDecay;
+                score += Math.max(0, config.touchBonusScore - framesSinceTouch * decayRate);
+            }
+            // Deterministic tiebreaker
+            score += simpleHash(pid + entityId) * 0.0001;
+            if (score > bestScore) {
+                bestScore = score;
+                bestPlayer = pid;
+            }
+        }
+        return bestPlayer;
+    }
+    function isLocalAuthority(entityId) {
+        return localPlayerId !== null && computeAuthority(entityId) === localPlayerId;
+    }
+    // ==========================================
+    // Delta Compression
+    // ==========================================
+    function hasStateChanged(entityId) {
+        const entity = entities.get(entityId);
+        if (!entity || !entity.lastSentState)
+            return true;
+        const curr = entity.state;
+        const last = entity.lastSentState;
+        // Position
+        if (Math.abs(curr.x - last.x) > config.positionThreshold)
+            return true;
+        if (Math.abs(curr.y - last.y) > config.positionThreshold)
+            return true;
+        if (Math.abs(curr.z - last.z) > config.positionThreshold)
+            return true;
+        // Velocity
+        if (Math.abs((curr.vx || 0) - (last.vx || 0)) > config.velocityThreshold)
+            return true;
+        if (Math.abs((curr.vy || 0) - (last.vy || 0)) > config.velocityThreshold)
+            return true;
+        if (Math.abs((curr.vz || 0) - (last.vz || 0)) > config.velocityThreshold)
+            return true;
+        // Rotation
+        if (Math.abs((curr.qx || 0) - (last.qx || 0)) > config.rotationThreshold)
+            return true;
+        if (Math.abs((curr.qy || 0) - (last.qy || 0)) > config.rotationThreshold)
+            return true;
+        if (Math.abs((curr.qz || 0) - (last.qz || 0)) > config.rotationThreshold)
+            return true;
+        if (Math.abs((curr.qw || 1) - (last.qw || 1)) > config.rotationThreshold)
+            return true;
+        return false;
+    }
+    // ==========================================
+    // Rest Detection
+    // ==========================================
+    function isAtRest(entityId) {
+        const entity = entities.get(entityId);
+        if (!entity)
+            return false;
+        const state = entity.state;
+        const speed = Math.sqrt((state.vx || 0) ** 2 +
+            (state.vy || 0) ** 2 +
+            (state.vz || 0) ** 2);
+        const angSpeed = Math.sqrt((state.avx || 0) ** 2 +
+            (state.avy || 0) ** 2 +
+            (state.avz || 0) ** 2);
+        if (speed < config.restVelocityThreshold && angSpeed < config.restVelocityThreshold) {
+            entity.restFrames++;
+            return entity.restFrames > config.restFramesRequired;
+        }
+        else {
+            entity.restFrames = 0;
+            return false;
+        }
+    }
+    function wakeEntity(entityId) {
+        const entity = entities.get(entityId);
+        if (entity) {
+            entity.restFrames = 0;
+        }
+    }
+    // ==========================================
+    // Soft Sync
+    // ==========================================
+    function applySoftSync(entityId, targetState) {
+        const entity = entities.get(entityId);
+        if (!entity)
+            return;
+        // Skip if we're authority
+        if (isLocalAuthority(entityId))
+            return;
+        const lerp = config.softSyncLerp;
+        // Lerp position
+        entity.state.x += (targetState.x - entity.state.x) * lerp;
+        entity.state.y += (targetState.y - entity.state.y) * lerp;
+        entity.state.z += (targetState.z - entity.state.z) * lerp;
+        // Hard sync velocity
+        entity.state.vx = targetState.vx;
+        entity.state.vy = targetState.vy;
+        entity.state.vz = targetState.vz;
+        // Hard sync rotation
+        entity.state.qx = targetState.qx;
+        entity.state.qy = targetState.qy;
+        entity.state.qz = targetState.qz;
+        entity.state.qw = targetState.qw;
+        // Hard sync angular velocity
+        entity.state.avx = targetState.avx;
+        entity.state.avy = targetState.avy;
+        entity.state.avz = targetState.avz;
+        // Apply to physics
+        entity.adapter.setState(entity.state);
+        // Wake the entity
+        wakeEntity(entityId);
+    }
+    // ==========================================
+    // Network Integration
+    // ==========================================
+    function sendEntityUpdates() {
+        if (!connection?.connected)
+            return;
+        for (const [id, entity] of entities) {
+            // Skip if not authority
+            if (!isLocalAuthority(id))
+                continue;
+            // Skip if at rest
+            if (isAtRest(id))
+                continue;
+            // Skip if no meaningful change
+            if (!hasStateChanged(id))
+                continue;
+            // Sync state from physics
+            entity.state = entity.adapter.getState();
+            // Send update
+            connection.send({
+                type: 'entityState',
+                id,
+                ...entity.state
+            });
+            // Remember what we sent
+            entity.lastSentState = { ...entity.state };
+        }
+    }
+    function handleEntityState(id, state) {
+        const entity = entities.get(id);
+        if (!entity)
+            return;
+        // Skip if we're authority
+        if (isLocalAuthority(id))
+            return;
+        applySoftSync(id, state);
+    }
+    function handleEntityTouch(id, touchedBy, frame) {
+        const entity = entities.get(id);
+        if (entity) {
+            entity.lastTouchedBy = touchedBy;
+            entity.lastTouchFrame = frame;
+            wakeEntity(id);
+        }
+    }
+    // ==========================================
+    // Public API
+    // ==========================================
+    return {
+        // Configuration
+        get config() {
+            return { ...config };
+        },
+        // Setup
+        setConnection(conn) {
+            connection = conn;
+        },
+        setLocalPlayer(playerId) {
+            localPlayerId = playerId;
+        },
+        setFrame(frame) {
+            currentFrame = frame;
+        },
+        // Entity management
+        registerEntity(id, adapter) {
+            entities.set(id, {
+                id,
+                adapter,
+                state: adapter.getState(),
+                restFrames: 0
+            });
+        },
+        unregisterEntity(id) {
+            entities.delete(id);
+        },
+        getEntity(id) {
+            return entities.get(id);
+        },
+        // Player management (for authority calculation)
+        updatePlayer(id, x, y, z, dead = false) {
+            players.set(id, { id, x, y, z, dead });
+        },
+        removePlayer(id) {
+            players.delete(id);
+        },
+        // Authority
+        computeAuthority,
+        isLocalAuthority,
+        // Sync operations
+        syncFromPhysics(entityId) {
+            const entity = entities.get(entityId);
+            if (entity) {
+                entity.state = entity.adapter.getState();
+            }
+        },
+        syncAllFromPhysics() {
+            for (const entity of entities.values()) {
+                entity.state = entity.adapter.getState();
+            }
+        },
+        // Network operations (call each tick)
+        sendUpdates: sendEntityUpdates,
+        // Input handlers (call from processInput)
+        handleEntityState,
+        handleEntityTouch,
+        // Touch detection (call after physics step)
+        checkPlayerTouches(playerId, playerX, playerZ, touchDistance = 2.0) {
+            if (!connection?.connected || playerId !== localPlayerId)
+                return;
+            for (const [id, entity] of entities) {
+                const dx = playerX - entity.state.x;
+                const dz = playerZ - entity.state.z;
+                const dist = Math.sqrt(dx * dx + dz * dz);
+                if (dist < touchDistance && entity.lastTouchedBy !== playerId) {
+                    connection.send({
+                        type: 'entityTouch',
+                        id,
+                        touchedBy: playerId,
+                        frame: currentFrame
+                    });
+                }
+            }
+        },
+        checkEntityCollisions(touchDistance = 4.0) {
+            if (!connection?.connected)
+                return;
+            const entityIds = Array.from(entities.keys());
+            for (let i = 0; i < entityIds.length; i++) {
+                const idA = entityIds[i];
+                if (!isLocalAuthority(idA))
+                    continue;
+                const entityA = entities.get(idA);
+                for (let j = i + 1; j < entityIds.length; j++) {
+                    const idB = entityIds[j];
+                    const entityB = entities.get(idB);
+                    const dx = entityA.state.x - entityB.state.x;
+                    const dz = entityA.state.z - entityB.state.z;
+                    const dist = Math.sqrt(dx * dx + dz * dz);
+                    if (dist < touchDistance && entityB.lastTouchedBy !== localPlayerId) {
+                        connection.send({
+                            type: 'entityTouch',
+                            id: idB,
+                            touchedBy: localPlayerId,
+                            frame: currentFrame
+                        });
+                    }
+                }
+            }
+        },
+        // Utility
+        wakeEntity,
+        isAtRest,
+        hasStateChanged,
+    };
+}
+// ============================================
+// Physics Adapters
+// ============================================
+/**
+ * Rapier 3D physics adapter
+ */
+function rapierAdapter(body) {
+    return {
+        getState() {
+            const pos = body.translation();
+            const vel = body.linvel();
+            const rot = body.rotation();
+            const angvel = body.angvel();
+            return {
+                x: pos.x, y: pos.y, z: pos.z,
+                vx: vel.x, vy: vel.y, vz: vel.z,
+                qx: rot.x, qy: rot.y, qz: rot.z, qw: rot.w,
+                avx: angvel.x, avy: angvel.y, avz: angvel.z
+            };
+        },
+        setState(state) {
+            body.setTranslation({ x: state.x, y: state.y, z: state.z }, true);
+            body.setLinvel({ x: state.vx || 0, y: state.vy || 0, z: state.vz || 0 }, true);
+            body.setRotation({ x: state.qx || 0, y: state.qy || 0, z: state.qz || 0, w: state.qw || 1 }, true);
+            body.setAngvel({ x: state.avx || 0, y: state.avy || 0, z: state.avz || 0 }, true);
+        }
+    };
+}
+/**
+ * Generic 2D physics adapter (for Matter.js, Planck, etc.)
+ */
+function generic2DAdapter(getBody, setBody) {
+    return {
+        getState() {
+            const body = getBody();
+            return {
+                x: body.x || body.position?.x || 0,
+                y: body.y || body.position?.y || 0,
+                z: 0,
+                vx: body.vx || body.velocity?.x || 0,
+                vy: body.vy || body.velocity?.y || 0,
+                vz: 0
+            };
+        },
+        setState(state) {
+            setBody({
+                x: state.x,
+                y: state.y,
+                vx: state.vx,
+                vy: state.vy
+            });
+        }
+    };
+}
+// Browser global fallback
+if (typeof window !== 'undefined') {
+    window.moddEngine = { createEngine, rapierAdapter, generic2DAdapter };
+}

package/dist/modd-network.d.ts

@@ -0,0 +1,40 @@
+/**
+ * MODD Network SDK
+ * Pure network layer for real-time multiplayer applications
+ * Works with any app type: games, chat, collaboration, etc.
+ */
+export interface ConnectOptions {
+    appId?: string;
+    snapshot?: any;
+    user?: any;
+    centralServiceUrl?: string;
+    creatorNodeId?: string;
+    getStateHash?: () => string;
+    onConnect?: (snapshot: any, inputs: Input[]) => void;
+    onDisconnect?: () => void;
+    onError?: (error: string) => void;
+    onMessage?: (data: any, seq: number) => void;
+    onTick?: (frame: number, inputs: Input[], isCatchUp?: boolean) => void;
+    onSnapshot?: (snapshot: any, hash: string) => void;
+}
+export interface Input {
+    sequenceNumber: number;
+    data: any;
+    clientId?: string;
+    timestamp?: number;
+}
+export interface Connection {
+    send(data: any): void;
+    sendSnapshot(snapshot: any, hash: string): void;
+    leaveRoom(): void;
+    close(): void;
+    readonly connected: boolean;
+    readonly node: string | null;
+    readonly bandwidthIn: number;
+    readonly bandwidthOut: number;
+    readonly totalBytesIn: number;
+    readonly totalBytesOut: number;
+    readonly frame: number;
+}
+export declare function connect(roomId: string, options?: ConnectOptions): Promise<Connection>;
+export declare const modd: typeof connect;

package/dist/modd-network.js

@@ -0,0 +1,449 @@
+"use strict";
+/**
+ * MODD Network SDK
+ * Pure network layer for real-time multiplayer applications
+ * Works with any app type: games, chat, collaboration, etc.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modd = void 0;
+exports.connect = connect;
+const ws_1 = __importDefault(require("ws"));
+// ============================================
+// Binary Protocol
+// ============================================
+const BinaryMessageType = {
+    TICK: 0x01,
+    INITIAL_STATE: 0x02,
+    ROOM_JOINED: 0x03,
+    ROOM_CREATED: 0x04,
+    ERROR: 0x05,
+    SNAPSHOT_UPDATE: 0x06,
+    ROOM_LEFT: 0x07,
+    SYNC_HASH: 0x08
+};
+function encodeSyncHash(roomId, hash, seq, frame) {
+    const roomIdBytes = new TextEncoder().encode(roomId);
+    const hashBytes = new TextEncoder().encode(hash);
+    const totalLen = 1 + 2 + roomIdBytes.length + 2 + hashBytes.length + 4 + 4;
+    const buffer = new ArrayBuffer(totalLen);
+    const view = new DataView(buffer);
+    const uint8 = new Uint8Array(buffer);
+    let offset = 0;
+    view.setUint8(offset, BinaryMessageType.SYNC_HASH);
+    offset += 1;
+    view.setUint16(offset, roomIdBytes.length, true);
+    offset += 2;
+    uint8.set(roomIdBytes, offset);
+    offset += roomIdBytes.length;
+    view.setUint16(offset, hashBytes.length, true);
+    offset += 2;
+    uint8.set(hashBytes, offset);
+    offset += hashBytes.length;
+    view.setUint32(offset, seq, true);
+    offset += 4;
+    view.setUint32(offset, frame, true);
+    return buffer;
+}
+function decodeBinaryMessage(buffer) {
+    const view = new DataView(buffer);
+    if (buffer.byteLength === 0)
+        return null;
+    const type = view.getUint8(0);
+    switch (type) {
+        case BinaryMessageType.TICK: {
+            const frame = view.getUint32(1, true);
+            let inputs = [];
+            if (buffer.byteLength > 5) {
+                const inputCount = view.getUint16(5, true);
+                if (inputCount > 0) {
+                    const inputsJson = new TextDecoder().decode(buffer.slice(7));
+                    inputs = JSON.parse(inputsJson);
+                }
+            }
+            return { type: 'TICK', frame, inputs };
+        }
+        case BinaryMessageType.INITIAL_STATE: {
+            let offset = 1;
+            const frame = view.getUint32(offset, true);
+            offset += 4;
+            const roomIdLen = view.getUint16(offset, true);
+            offset += 2;
+            const roomId = new TextDecoder().decode(buffer.slice(offset, offset + roomIdLen));
+            offset += roomIdLen;
+            const snapshotLen = view.getUint32(offset, true);
+            offset += 4;
+            const snapshotJson = new TextDecoder().decode(buffer.slice(offset, offset + snapshotLen));
+            offset += snapshotLen;
+            const inputsLen = view.getUint32(offset, true);
+            offset += 4;
+            const inputsJson = new TextDecoder().decode(buffer.slice(offset, offset + inputsLen));
+            const { snapshot, snapshotHash } = JSON.parse(snapshotJson);
+            const inputs = JSON.parse(inputsJson);
+            return { type: 'INITIAL_STATE', roomId, frame, snapshot, snapshotHash, inputs };
+        }
+        case BinaryMessageType.ROOM_JOINED: {
+            const roomIdLen = view.getUint16(1, true);
+            const roomId = new TextDecoder().decode(buffer.slice(3, 3 + roomIdLen));
+            return { type: 'ROOM_JOINED', roomId };
+        }
+        case BinaryMessageType.ROOM_CREATED: {
+            let offset = 1;
+            const roomIdLen = view.getUint16(offset, true);
+            offset += 2;
+            const roomId = new TextDecoder().decode(buffer.slice(offset, offset + roomIdLen));
+            offset += roomIdLen;
+            const snapshotLen = view.getUint32(offset, true);
+            offset += 4;
+            const snapshotJson = new TextDecoder().decode(buffer.slice(offset, offset + snapshotLen));
+            const { snapshot, snapshotHash } = JSON.parse(snapshotJson);
+            return { type: 'ROOM_CREATED', roomId, snapshot, snapshotHash };
+        }
+        case BinaryMessageType.ERROR: {
+            const msgLen = view.getUint16(1, true);
+            const message = new TextDecoder().decode(buffer.slice(3, 3 + msgLen));
+            return { type: 'ERROR', message };
+        }
+        case BinaryMessageType.SNAPSHOT_UPDATE: {
+            let offset = 1;
+            const roomIdLen = view.getUint16(offset, true);
+            offset += 2;
+            const roomId = new TextDecoder().decode(buffer.slice(offset, offset + roomIdLen));
+            offset += roomIdLen;
+            const snapshotLen = view.getUint32(offset, true);
+            offset += 4;
+            const snapshotJson = new TextDecoder().decode(buffer.slice(offset, offset + snapshotLen));
+            const { snapshot, snapshotHash } = JSON.parse(snapshotJson);
+            return { type: 'SNAPSHOT_UPDATE', roomId, snapshot, snapshotHash };
+        }
+        case BinaryMessageType.ROOM_LEFT: {
+            const roomIdLen = view.getUint16(1, true);
+            const roomId = new TextDecoder().decode(buffer.slice(3, 3 + roomIdLen));
+            return { type: 'ROOM_LEFT', roomId };
+        }
+        default:
+            return null;
+    }
+}
+// Helper to normalize binary data to ArrayBuffer
+async function toArrayBuffer(data) {
+    if (data instanceof ArrayBuffer) {
+        return data;
+    }
+    if (typeof Blob !== 'undefined' && data instanceof Blob) {
+        return await data.arrayBuffer();
+    }
+    // Fallback for Buffer, ArrayBufferView, or array-like
+    // creating a new Uint8Array(data) copies the data to a new ArrayBuffer
+    return new Uint8Array(data).buffer;
+}
+// ============================================
+// Main Connect Function
+// ============================================
+async function connect(roomId, options = {}) {
+    const appId = options.appId || 'app';
+    const initialSnapshot = options.snapshot || {};
+    const user = options.user || null;
+    const onConnect = options.onConnect || (() => { });
+    const onDisconnect = options.onDisconnect || (() => { });
+    const onError = options.onError || ((err) => console.error('[modd-network]', err));
+    const onMessage = options.onMessage || (() => { });
+    const onTick = options.onTick || null;
+    const getStateHash = options.getStateHash || null;
+    // Determine central service URL
+    const centralServiceUrl = options.centralServiceUrl || (typeof window !== 'undefined' && (window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1')
+        ? 'http://localhost:9001'
+        : 'https://nodes.modd.io');
+    let connected = false;
+    let initialStateReceived = null;
+    let deliveredSeqs = new Set();
+    let pendingTicks = [];
+    let ws = null;
+    let nodeUrl = null;
+    // Bandwidth tracking
+    let bytesIn = 0;
+    let bytesOut = 0;
+    let lastBytesIn = 0;
+    let lastBytesOut = 0;
+    let bandwidthIn = 0;
+    let bandwidthOut = 0;
+    let bandwidthInterval = null;
+    // Hash sync tracking
+    let hashInterval = null;
+    let lastSyncSeq = 0;
+    let lastSyncFrame = 0;
+    let currentFrame = 0;
+    try {
+        const res = await fetch(`${centralServiceUrl}/api/apps/${appId}/rooms/${roomId}/connect`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ creatorNodeId: options.creatorNodeId })
+        });
+        if (!res.ok) {
+            throw new Error(`Central service error: ${res.status}`);
+        }
+        const { url } = await res.json();
+        nodeUrl = url;
+        // Use imported WebSocket (work in Node) or global WebSocket if present (Browser)
+        // Note: importing 'ws' gives a constructor. In browser env, 'ws' module might be shimmed.
+        // However, for best compat, let's use globalThis.WebSocket if available, else WS.
+        const WS = (typeof globalThis !== 'undefined' && globalThis.WebSocket) ? globalThis.WebSocket : ws_1.default;
+        // @ts-ignore - TS might complain about mixing types
+        ws = new WS(nodeUrl);
+        ws.binaryType = 'arraybuffer'; // Ensure we get ArrayBuffer if possible (in Browser)
+        ws.onopen = () => {
+            bandwidthInterval = setInterval(() => {
+                bandwidthIn = bytesIn - lastBytesIn;
+                bandwidthOut = bytesOut - lastBytesOut;
+                lastBytesIn = bytesIn;
+                lastBytesOut = bytesOut;
+            }, 1000);
+            if (getStateHash) {
+                hashInterval = setInterval(() => {
+                    if (!connected || !ws || ws.readyState !== 1)
+                        return;
+                    try {
+                        const hash = getStateHash();
+                        if (hash) {
+                            const hashMsg = encodeSyncHash(roomId, hash, lastSyncSeq, lastSyncFrame);
+                            bytesOut += hashMsg.byteLength;
+                            ws.send(hashMsg);
+                        }
+                    }
+                    catch (err) {
+                        console.warn('[modd-network] Error getting state hash:', err);
+                    }
+                }, 1000);
+            }
+            const joinMsg = JSON.stringify({ type: 'JOIN_ROOM', payload: { roomId } });
+            bytesOut += joinMsg.length;
+            ws.send(joinMsg);
+        };
+        ws.onerror = (e) => onError(`Failed to connect to ${nodeUrl}: ${e.message || 'Unknown error'}`);
+        ws.onclose = () => {
+            connected = false;
+            if (bandwidthInterval)
+                clearInterval(bandwidthInterval);
+            if (hashInterval)
+                clearInterval(hashInterval);
+            onDisconnect();
+        };
+        ws.onmessage = async (e) => {
+            // Handle various binary formats
+            let buffer;
+            try {
+                buffer = await toArrayBuffer(e.data);
+            }
+            catch (err) {
+                console.warn('[modd-network] Failed to read message data:', err);
+                return;
+            }
+            bytesIn += buffer.byteLength;
+            const msg = decodeBinaryMessage(buffer);
+            if (!msg) {
+                console.warn('[modd-network] Failed to decode binary message');
+                return;
+            }
+            switch (msg.type) {
+                case 'TICK': {
+                    if (!connected) {
+                        pendingTicks.push(msg);
+                        break;
+                    }
+                    currentFrame = msg.frame;
+                    lastSyncFrame = msg.frame;
+                    if (msg.inputs && msg.inputs.length > 0) {
+                        const maxSeq = Math.max(...msg.inputs.map(i => i.sequenceNumber || 0));
+                        if (maxSeq > lastSyncSeq)
+                            lastSyncSeq = maxSeq;
+                    }
+                    if (onTick) {
+                        const newInputs = msg.inputs.filter(i => !deliveredSeqs.has(i.sequenceNumber));
+                        newInputs.forEach(i => deliveredSeqs.add(i.sequenceNumber));
+                        onTick(msg.frame, newInputs);
+                    }
+                    break;
+                }
+                case 'ERROR': {
+                    if (msg.message === 'Room not found') {
+                        const createMsg = JSON.stringify({
+                            type: 'CREATE_ROOM',
+                            payload: { roomId, appId, snapshot: initialSnapshot }
+                        });
+                        bytesOut += createMsg.length;
+                        ws.send(createMsg);
+                    }
+                    else {
+                        onError(msg.message);
+                    }
+                    break;
+                }
+                case 'ROOM_CREATED': {
+                    connected = true;
+                    if (user) {
+                        const joinInputMsg = JSON.stringify({ type: 'SEND_INPUT', payload: { roomId, data: { type: 'join', user } } });
+                        bytesOut += joinInputMsg.length;
+                        ws.send(joinInputMsg);
+                    }
+                    onConnect(initialSnapshot, []);
+                    break;
+                }
+                case 'INITIAL_STATE': {
+                    initialStateReceived = {
+                        snapshot: msg.snapshot,
+                        inputs: msg.inputs || [],
+                        frame: msg.frame
+                    };
+                    lastSyncFrame = msg.frame;
+                    if (msg.inputs && msg.inputs.length > 0) {
+                        const maxSeq = Math.max(...msg.inputs.map(i => i.sequenceNumber || 0));
+                        if (maxSeq > lastSyncSeq)
+                            lastSyncSeq = maxSeq;
+                    }
+                    break;
+                }
+                case 'ROOM_JOINED': {
+                    connected = true;
+                    if (user) {
+                        const joinInputMsg = JSON.stringify({ type: 'SEND_INPUT', payload: { roomId, data: { type: 'join', user } } });
+                        bytesOut += joinInputMsg.length;
+                        ws.send(joinInputMsg);
+                    }
+                    const processInitialState = () => {
+                        if (initialStateReceived) {
+                            const { snapshot, inputs, frame } = initialStateReceived;
+                            onConnect(snapshot, inputs);
+                            const newInputs = inputs.filter(i => !deliveredSeqs.has(i.sequenceNumber));
+                            newInputs.forEach(i => deliveredSeqs.add(i.sequenceNumber));
+                            if (onTick && newInputs.length > 0) {
+                                onTick(frame, newInputs, true);
+                            }
+                            else {
+                                newInputs.forEach(i => onMessage(i.data, i.sequenceNumber));
+                            }
+                            initialStateReceived = null;
+                            // Process buffered ticks
+                            if (pendingTicks.length > 0) {
+                                pendingTicks.sort((a, b) => a.frame - b.frame);
+                                for (const tickMsg of pendingTicks) {
+                                    if (onTick) {
+                                        const tickInputs = tickMsg.inputs.filter(i => !deliveredSeqs.has(i.sequenceNumber));
+                                        tickInputs.forEach(i => deliveredSeqs.add(i.sequenceNumber));
+                                        if (tickInputs.length > 0 || tickMsg.frame > frame) {
+                                            onTick(tickMsg.frame, tickInputs);
+                                        }
+                                    }
+                                }
+                                pendingTicks = [];
+                            }
+                        }
+                        else {
+                            onConnect(null, []);
+                        }
+                    };
+                    if (initialStateReceived) {
+                        processInitialState();
+                    }
+                    else {
+                        setTimeout(processInitialState, 100);
+                    }
+                    break;
+                }
+                case 'SNAPSHOT_UPDATE': {
+                    if (options.onSnapshot) {
+                        options.onSnapshot(msg.snapshot, msg.snapshotHash);
+                    }
+                    break;
+                }
+                case 'ROOM_LEFT': {
+                    console.log(`[modd-network] Left room ${msg.roomId}`);
+                    break;
+                }
+            }
+        };
+        // Auto leave on page unload
+        if (user && typeof window !== 'undefined') {
+            window.addEventListener('beforeunload', () => {
+                if (connected && ws) {
+                    const leaveMsg = JSON.stringify({ type: 'SEND_INPUT', payload: { roomId, data: { type: 'leave', user } } });
+                    bytesOut += leaveMsg.length;
+                    ws.send(leaveMsg);
+                }
+            });
+        }
+        return {
+            send(data) {
+                if (connected && ws) {
+                    const msg = JSON.stringify({ type: 'SEND_INPUT', payload: { roomId, data } });
+                    bytesOut += msg.length;
+                    ws.send(msg);
+                }
+            },
+            sendSnapshot(snapshot, hash) {
+                if (connected && ws) {
+                    const msg = JSON.stringify({ type: 'SEND_SNAPSHOT', payload: { roomId, snapshot, hash } });
+                    bytesOut += msg.length;
+                    ws.send(msg);
+                }
+            },
+            leaveRoom() {
+                if (connected && user && ws) {
+                    const msg = JSON.stringify({ type: 'SEND_INPUT', payload: { roomId, data: { type: 'leave', user } } });
+                    bytesOut += msg.length;
+                    ws.send(msg);
+                }
+                if (ws)
+                    ws.close();
+            },
+            close() {
+                if (ws)
+                    ws.close();
+            },
+            get connected() {
+                return connected;
+            },
+            get node() {
+                return nodeUrl ? (nodeUrl.match(/:(\d+)/)?.[1] || nodeUrl) : null;
+            },
+            get bandwidthIn() {
+                return bandwidthIn;
+            },
+            get bandwidthOut() {
+                return bandwidthOut;
+            },
+            get totalBytesIn() {
+                return bytesIn;
+            },
+            get totalBytesOut() {
+                return bytesOut;
+            },
+            get frame() {
+                return currentFrame;
+            }
+        };
+    }
+    catch (err) {
+        onError(`Failed to get node assignment: ${err.message}`);
+        return {
+            send() { },
+            sendSnapshot() { },
+            leaveRoom() { },
+            close() { },
+            get connected() { return false; },
+            get node() { return null; },
+            get bandwidthIn() { return 0; },
+            get bandwidthOut() { return 0; },
+            get totalBytesIn() { return 0; },
+            get totalBytesOut() { return 0; },
+            get frame() { return 0; }
+        };
+    }
+}
+// Legacy alias for backwards compatibility
+exports.modd = connect;
+// Browser global fallback
+if (typeof window !== 'undefined') {
+    window.moddNetwork = { connect, modd: exports.modd };
+}

package/package.json

@@ -1,18 +1,22 @@
 {
   "name": "modd-network",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "SDK for connecting to mesh network for multiplayer applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist"
   ],
+  "browser": {
+    "ws": false
+  },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "tsc",
-    "dev": "tsx watch src/index.ts"
+    "build:browser": "node build-browser.js",
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
     "mesh",
@@ -28,7 +32,7 @@
   "devDependencies": {
     "@types/node": "^20.10.6",
     "@types/ws": "^8.5.10",
-    "tsx": "^4.7.0",
+    "esbuild": "^0.27.2",
     "typescript": "^5.3.3"
   }
 }