screeps-connectivity 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.15.0
+
+### Minor Changes
+
+- 66f88f8: Code panel branch management: create a new branch (clones the selected branch, with an inline name input) and set the selected branch to run on the server. The active-branch indicator now stays live via a new `set-active-branch` WebSocket subscription — `UserStore.subscribe('set-active-branch')` emits a `user:setActiveBranch` event whenever the active branch changes, including from another client or session.
+
+  The code panel can now add and delete modules: an add button in the module list opens an inline name input, and hovering a module reveals a delete button (the `main` entry module is protected). Both changes are staged locally and persisted on the next Save.
+
+  Also fixes a stale-response race in the code panel where switching branches while a previous branch's code fetch was still in flight could leave the editor showing the wrong branch's files.
+
+- 66f88f8: WebSocket compression support (opt-in): setting the new `ScreepsClientOptions.gzip` to `true` sends `gzip on` after auth, so the server deflates event frames (room updates, map stats, memory) and only transmits the compressed `gz:` form when it's actually smaller. Defaults to `false` to match the official client, which never enables it. The `gz:` decode path is always active regardless, so this is a pure opt-in bandwidth trade with no downside on small control frames.
+
 ## 0.14.0
 
 ### Minor Changes

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024-2026 Bastian Hoyer
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screeps-connectivity",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "license": "ISC",
   "type": "module",
   "repository": {
@@ -24,22 +24,22 @@
       "require": "./dist/file-storage.cjs"
     }
   },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.63.0",
+    "@typescript-eslint/parser": "^8.63.0",
+    "eslint": "^10.6.0",
+    "fake-indexeddb": "^6.0.0",
+    "globals": "^17.7.0",
+    "tsup": "^8.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src tests"
-  },
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@types/node": "^25.7.0",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "eslint": "^9.0.0",
-    "fake-indexeddb": "^6.0.0",
-    "globals": "^17.6.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.5.0",
-    "vitest": "^4.1.6"
   }
-}
+}

package/src/ScreepsClient.ts

@@ -41,6 +41,14 @@ export interface ScreepsClientOptions {
   tokenRefresh?: TokenRefreshOptions | false
   /** Override the /api/game/room-decorations response with static data (useful for dev/testing when the server doesn't support the endpoint). */
   decorationsMock?: ApiRoomDecorationsResponse
+  /**
+   * Enable WebSocket message compression by sending `gzip on` after auth. The
+   * server then deflates event frames (room updates, etc.) and only sends the
+   * compressed `gz:` form when it's smaller. Defaults to `false` — matching the
+   * official client, which never enables it. The `gz:` decode path is always
+   * active regardless, so enabling this is a pure opt-in bandwidth trade.
+   */
+  gzip?: boolean
 }
 
 export class ScreepsClient {
@@ -77,7 +85,7 @@ export class ScreepsClient {
     this.logger.log(`[screeps:client] init ${opts.url}`)
     this.cache = new Cache(namespace, opts.storage ?? null)
     this.http = new HttpClient({ url: opts.url, auth: opts.auth, logger: this.logger.child('http'), serverPassword: opts.serverPassword, decorationsMock: opts.decorationsMock })
-    this.socket = new SocketClient({ url: opts.url, WebSocket: opts.WebSocket, logger: this.logger.child('socket') })
+    this.socket = new SocketClient({ url: opts.url, WebSocket: opts.WebSocket, logger: this.logger.child('socket'), gzip: opts.gzip })
     const map2Storage = new Map2Storage({
       adapter: opts.storage ?? null,
       namespace,

package/src/socket/SocketClient.ts

@@ -8,6 +8,7 @@ export class SocketClient {
   private readonly wsUrl: string
   private readonly WS: WsConstructor
   private readonly logger: Logger
+  private readonly gzip: boolean
   private ws: WebSocket | null = null
   private token: string | null = null
   private authed = false
@@ -22,11 +23,14 @@ export class SocketClient {
   private readonly MAX_DELAY_MS = 60_000
   private _intentionalClose = false
 
-  constructor(opts: { url: string; WebSocket?: WsConstructor; logger?: Logger }) {
+  constructor(opts: { url: string; WebSocket?: WsConstructor; logger?: Logger; gzip?: boolean }) {
     const base = opts.url.replace(/^http/, 'ws').replace(/\/$/, '')
     this.wsUrl = `${base}/socket/websocket`
     this.WS = opts.WebSocket ?? globalThis.WebSocket
     this.logger = opts.logger ?? Logger.create()
+    // Off by default — matches the official client, which never sends `gzip on`.
+    // The decode path is always available; opt in explicitly to enable it.
+    this.gzip = opts.gzip ?? false
   }
 
   get isConnected(): boolean {
@@ -64,6 +68,11 @@ export class SocketClient {
               this.token = cmd.token
               this.emit('socket:tokenRefresh', { token: cmd.token })
             }
+            // Ask the server to deflate outbound event frames before any
+            // subscribe is flushed, so the first updates already arrive as gz:.
+            // The server only sends the compressed form when it's actually
+            // smaller, so this never enlarges small control frames.
+            if (this.gzip) this.rawSend('gzip on')
             while (this.queue.length) this.rawSend(this.queue.shift()!)
             this.emit('connected', {})
             resolve()

package/src/stores/UserStore.ts

@@ -82,7 +82,7 @@ export class UserStore extends TypedStore<UserStoreEvents> {
     return this.worldStatus()
   }
 
-  subscribe(channel: 'console' | 'cpu' | 'code'): Subscription {
+  subscribe(channel: 'console' | 'cpu' | 'code' | 'set-active-branch'): Subscription {
     this.logger.log('subscribe', channel)
     let socketSub: Subscription | null = null
     let listenerSub: Subscription | null = null
@@ -115,6 +115,8 @@ export class UserStore extends TypedStore<UserStoreEvents> {
             this.emit('user:console', { messages: msg })
           } else if (channel === 'code') {
             this.emit('user:code', data as { branch: string; modules: Record<string, string> })
+          } else if (channel === 'set-active-branch') {
+            this.emit('user:setActiveBranch', data as { activeName: 'activeWorld' | 'activeSim'; branch: string })
           }
         })
       } catch (err) {

package/src/types/events.ts

@@ -40,6 +40,7 @@ export interface UserStoreEvents {
     'user:cpu': CpuStats
     'user:console': { messages: ConsoleMessage }
     'user:code': { branch: string; modules: Record<string, string> }
+    'user:setActiveBranch': { activeName: 'activeWorld' | 'activeSim'; branch: string }
     'user:stream': Record<string, unknown>
     'user:memory': { path: string; shard: string | null; value: unknown }
     'user:mapVisual': { shard: string | null; data: string }

package/tests/socket/SocketClient.test.ts

@@ -58,6 +58,31 @@ describe('SocketClient', () => {
     await expect(connectClient(client)).resolves.toBeDefined()
   })
 
+  it('does not send gzip on by default', async () => {
+    const client = makeClient()
+    const ws = await connectClient(client)
+    expect(ws.sent).not.toContain('gzip on')
+  })
+
+  it('sends gzip on when explicitly enabled, before any subscribe', async () => {
+    const client = new SocketClient({ url: 'https://screeps.com', gzip: true, WebSocket: MockWS as unknown as typeof WebSocket })
+    const connectPromise = client.connect('tok')
+    const ws = MockWS.instances[0]
+    ws.simulateOpen()
+    ws.simulateMessage('auth ok newtoken')
+    await connectPromise
+    expect(ws.sent).toContain('gzip on')
+    // gzip on must precede subscribes so the first updates already arrive as gz:
+    client.subscribe('room:shard0/W7N7')
+    expect(ws.sent.indexOf('gzip on')).toBeLessThan(ws.sent.indexOf('subscribe room:shard0/W7N7'))
+  })
+
+  it('explicit gzip:false does not send gzip on', async () => {
+    const client = new SocketClient({ url: 'https://screeps.com', gzip: false, WebSocket: MockWS as unknown as typeof WebSocket })
+    const ws = await connectClient(client)
+    expect(ws.sent).not.toContain('gzip on')
+  })
+
   it('subscribe sends subscribe message when authed', async () => {
     const client = makeClient()
     const ws = await connectClient(client)

package/tsconfig.json

@@ -11,7 +11,8 @@
     "sourceMap": true,
     "outDir": "./dist",
     "rootDir": "./src",
-    "verbatimModuleSyntax": true
+    "verbatimModuleSyntax": true,
+    "ignoreDeprecations": "6.0"
   },
   "include": ["src"]
 }