screeps-connectivity 0.13.1 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # 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
+
+- 57a7e1d: Hide the connection ("server") password field for xxscreeps servers.
+
+  `screeps-connectivity` adds a `hasOfficialLike(version)` capability helper that
+  detects the `official-like` feature advertised at `/api/version`. The login
+  screens (web and desktop) now use it to hide the server-password field on
+  xxscreeps servers, where the screepsmod-auth connection password does not apply.
+
+### Patch Changes
+
+- 5d46b8e: Fix flag removal and color changes failing with "invalid shard" on multi-shard servers. `removeFlag` and `changeFlagColor` now accept and forward the current shard, matching the other room-scoped game endpoints.
+- 3b9b951: Revamp the public profile page (`/profile/<username>`):
+
+  - Header now mirrors the self Overview chrome — small badge, the player's name
+    as the title, and a compact GCL/GPL readout rendered as rounded chips bordered
+    in the rank color (teal / red).
+  - The "Last 7 days" stat block is now a dropdown (1 hour / 24 hours / 7 days);
+    the tiles refetch the user's public stats for the selected window.
+  - Stat tiles now render correctly on servers that return `/api/user/stats`
+    metrics as a single pre-summed total per interval, not just per-tick buckets
+    (`ApiUserStatsResponse.stats` widened to `number | bucket[]`).
+  - Cross-links between the two account views: the username on the self Overview
+    links to the public profile, and your own public profile links back to your
+    private Overview.
+  - The top-bar Overview button no longer appears active while a profile is open —
+    a profile is a separate view.
+
+- 79bd3d0: Add a read-only per-room overview page at `/room-overview/<shard>/<room>` (or
+  `/room-overview/<room>` on single-shard servers):
+
+  - Header with the room name, owner (badge + profile link, or "Unclaimed room"),
+    and a room minimap thumbnail that opens the live room view.
+  - The same seven stat tiles as the account Overview, summed over a selectable
+    interval (1 hour / 24 hours / 7 days).
+  - A history graph rendering the six per-bucket metrics (energy harvested,
+    construction, control, energy on creeps, creeps produced/lost) as
+    opacity-scaled dot strips.
+  - Entry points: a chart button next to each room name on the self Overview and
+    public Profile pages, plus a button in the in-game room view's left toolbar
+    (between the World Map and History buttons).
+  - `screeps-connectivity`: the existing `game.roomOverview` endpoint is now typed
+    with the new exported `ApiRoomOverviewResponse` (was `unknown`).
+
 ## 0.13.1
 
 ### Patch 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.13.1",
+  "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/http/endpoints/game.ts

@@ -19,6 +19,7 @@ import type {
   ApiMarketOrdersResponse,
   ApiMarketMyOrdersResponse,
   ApiMarketStatsResponse,
+  ApiRoomOverviewResponse,
 } from '../../types/api.js'
 import { createPowerCreepsEndpoints, type PowerCreepsEndpoints } from './power-creeps.js'
 
@@ -28,7 +29,7 @@ export interface GameEndpoints {
   roomObjects(room: string, shard?: string | null): Promise<ApiRoomObjectsResponse>
   roomDecorations(room: string, shard?: string | null): Promise<ApiRoomDecorationsResponse>
   roomStatus(room: string, shard?: string | null): Promise<{ ok: number; status: string; novice?: string }>
-  roomOverview(room: string, interval?: number, shard?: string | null): Promise<unknown>
+  roomOverview(room: string, interval?: number, shard?: string | null): Promise<ApiRoomOverviewResponse>
   time(shard?: string | null): Promise<{ ok: number; time: number }>
   tick(): Promise<ApiGameTickResponse>
   worldSize(shard?: string | null): Promise<unknown>
@@ -37,8 +38,8 @@ export interface GameEndpoints {
   createFlag(room: string, x: number, y: number, name: string, color: number, secondaryColor: number, shard?: string | null): Promise<ApiCreateFlagResponse>
   genUniqueFlagName(): Promise<ApiGenUniqueFlagNameResponse>
   checkUniqueFlagName(name: string): Promise<ApiCheckUniqueFlagNameResponse>
-  changeFlagColor(room: string, name: string, color: number, secondaryColor: number): Promise<ApiChangeFlagColorResponse>
-  removeFlag(room: string, name: string): Promise<ApiRemoveFlagResponse>
+  changeFlagColor(room: string, name: string, color: number, secondaryColor: number, shard?: string | null): Promise<ApiChangeFlagColorResponse>
+  removeFlag(room: string, name: string, shard?: string | null): Promise<ApiRemoveFlagResponse>
   genUniqueObjectName(type: string, shard?: string | null): Promise<ApiGenUniqueObjectNameResponse>
   checkUniqueObjectName(type: string, name: string, shard?: string | null): Promise<ApiCheckUniqueObjectNameResponse>
   placeSpawn(room: string, x: number, y: number, name?: string, shard?: string | null): Promise<{ ok: number }>
@@ -88,8 +89,8 @@ export function createGameEndpoints(http: HttpClient, decorationsMock?: ApiRoomD
     createFlag: (room, x, y, name, color, secondaryColor, shard) => http.request('POST', '/api/game/create-flag', withShard({ room, x, y, name, color, secondaryColor }, shard)),
     genUniqueFlagName: () => http.request('POST', '/api/game/gen-unique-flag-name'),
     checkUniqueFlagName: (name) => http.request('POST', '/api/game/check-unique-flag-name', { name }),
-    changeFlagColor: (room, name, color, secondaryColor) => http.request('POST', '/api/game/change-flag-color', { room, name, color, secondaryColor }),
-    removeFlag: (room, name) => http.request('POST', '/api/game/remove-flag', { room, name }),
+    changeFlagColor: (room, name, color, secondaryColor, shard) => http.request('POST', '/api/game/change-flag-color', withShard({ room, name, color, secondaryColor }, shard)),
+    removeFlag: (room, name, shard) => http.request('POST', '/api/game/remove-flag', withShard({ room, name }, shard)),
     genUniqueObjectName: (type, shard) => http.request('POST', '/api/game/gen-unique-object-name', withShard({ type }, shard)),
     checkUniqueObjectName: (type, name, shard) => http.request('POST', '/api/game/check-unique-object-name', withShard({ type, name }, shard)),
     placeSpawn: (room, x, y, name, shard) => http.request('POST', '/api/game/place-spawn', withShard({ room, x, y, ...(name ? { name } : {}) }, shard)),

package/src/http/fetchServerVersion.ts

@@ -206,3 +206,16 @@ export function getXxscreepsModClientFeature(version: ServerVersion): XxscreepsM
 export function getDiscordFeature(version: ServerVersion): DiscordFeature | undefined {
   return getServerFeature<DiscordFeature>(version, 'discord')
 }
+
+/**
+ * Returns `true` when the server advertises the `official-like` feature — the
+ * marker xxscreeps servers publish at `/api/version`. Such servers do not
+ * implement the screepsmod-auth connection ("server") password, so the client
+ * can hide that field entirely.
+ *
+ * @example
+ * if (hasOfficialLike(version)) hideServerPasswordField()
+ */
+export function hasOfficialLike(version: ServerVersion): boolean {
+  return getServerFeature(version, 'official-like') !== undefined
+}

package/src/index.ts

@@ -42,9 +42,9 @@ export type {
   MapVisualEntry,
 } from './types/game.js'
 
-export { fetchServerVersion, fetchAuthModInfo, checkUsername, checkEmail, registerUser, fetchAuthMeWithToken, completeProviderRegistration, getServerFeature, getScreepsmodAuth, getXxscreepsModClientFeature, getDiscordFeature } from './http/fetchServerVersion.js'
+export { fetchServerVersion, fetchAuthModInfo, checkUsername, checkEmail, registerUser, fetchAuthMeWithToken, completeProviderRegistration, getServerFeature, getScreepsmodAuth, getXxscreepsModClientFeature, getDiscordFeature, hasOfficialLike } from './http/fetchServerVersion.js'
 export type { ApiAuthModInfoResponse } from './http/fetchServerVersion.js'
-export type { ApiAuthMeResponse, RoomHistoryChunk, ApiRoomDecorationsResponse, ApiRoomDecorationItem, ApiRoomDecorationDef, ApiRoomDecorationGraphic, ApiRoomDecorationActive, ApiUserOverviewResponse, ApiUserOverviewTotals, ApiUserRoomsResponse, ApiUserStatsResponse, ApiLeaderboardFindResponse, ApiUserMoneyHistoryResponse, ApiMarketOrder, ApiMarketOrdersIndexResponse, ApiMarketOrdersResponse, ApiMarketMyOrdersResponse, ApiMarketStat, ApiMarketStatsResponse, ApiPowerCreep, ApiPowerCreepsListResponse, ApiUserMessage, ApiUserMessagesListResponse, ApiUserMessagesIndexEntry, ApiUserMessagesIndexResponse, ApiUserMessagesUnreadCountResponse, ApiUserFindResponse } from './types/api.js'
+export type { ApiAuthMeResponse, RoomHistoryChunk, ApiRoomDecorationsResponse, ApiRoomDecorationItem, ApiRoomDecorationDef, ApiRoomDecorationGraphic, ApiRoomDecorationActive, ApiUserOverviewResponse, ApiUserOverviewTotals, ApiRoomOverviewResponse, ApiUserRoomsResponse, ApiUserStatsResponse, ApiLeaderboardFindResponse, ApiUserMoneyHistoryResponse, ApiMarketOrder, ApiMarketOrdersIndexResponse, ApiMarketOrdersResponse, ApiMarketMyOrdersResponse, ApiMarketStat, ApiMarketStatsResponse, ApiPowerCreep, ApiPowerCreepsListResponse, ApiUserMessage, ApiUserMessagesListResponse, ApiUserMessagesIndexEntry, ApiUserMessagesIndexResponse, ApiUserMessagesUnreadCountResponse, ApiUserFindResponse } from './types/api.js'
 export { ROOM_DECORATIONS_MOCK } from './mocks/roomDecorations.js'
 
 export { badgeToSvg } from './badge/index.js'

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/api.ts

@@ -46,6 +46,15 @@ export interface ApiUserOverviewResponse {
   statsMax?: number
 }
 
+/** Response of GET /api/game/room-overview?room=&interval=&shard=. `stats` holds per-stat time-series buckets over the requested interval (same metric keys as the account overview tiles); `owner` is absent for unowned rooms. */
+export interface ApiRoomOverviewResponse {
+  ok: number
+  owner?: { username: string; badge: import('./game.js').Badge } | null
+  stats?: Record<string, Array<{ value: number; endTime: number }>>
+  statsMax?: Record<string, number>
+  totals?: ApiUserOverviewTotals
+}
+
 /** Response of GET /api/user/rooms?id=<userId> — the rooms a user owns. Multishard servers key by shard; single-shard servers may return a flat list. */
 export interface ApiUserRoomsResponse {
   ok: number
@@ -271,10 +280,14 @@ export interface ApiUserFindResponse {
   }
 }
 
-/** Response of GET /api/user/stats?id=&interval=. `stats` maps a metric to per-tick buckets; consumers sum the bucket values over the interval. */
+/**
+ * Response of GET /api/user/stats?id=&interval=. `stats` maps a metric to
+ * either per-tick buckets (consumers sum the bucket values over the interval)
+ * or a single pre-summed total for the interval — servers differ on which.
+ */
 export interface ApiUserStatsResponse {
   ok: number
-  stats?: Record<string, Array<{ value: number; endTime?: number }>>
+  stats?: Record<string, number | Array<{ value: number; endTime?: number }>>
   statsMax?: Record<string, number>
 }
 

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"]
 }