screeps-connectivity 0.15.2 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.16.0
+
+### Minor Changes
+
+- f218429: Embedded clients are now configured from the first frame with no `/api/version` round-trip: both the xxscreeps mod and the classic server mod prefetch the version payload and inline it into the page (`window.__SCREEPS_BOOTSTRAP__`), and the client seeds it into both the pre-login UI and the connection. `ScreepsClient` gains an `initialVersion` option and `ServerStore` a `seedVersion()` method to support this.
+
 ## 0.15.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screeps-connectivity",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "license": "ISC",
   "type": "module",
   "repository": {

package/src/ScreepsClient.ts

@@ -14,6 +14,7 @@ import type { AuthStrategy } from './http/auth/AuthStrategy.js'
 import type { StorageAdapter } from './storage/StorageAdapter.js'
 import type { Subscription } from './subscription/index.js'
 import type { ApiRoomDecorationsResponse } from './types/api.js'
+import type { ServerVersion } from './types/game.js'
 
 type WsConstructor = typeof globalThis.WebSocket
 
@@ -49,6 +50,12 @@ export interface ScreepsClientOptions {
    * active regardless, so enabling this is a pure opt-in bandwidth trade.
    */
   gzip?: boolean
+  /**
+   * A pre-known `/api/version` response, seeded into the server store so `connect()`
+   * skips the initial version fetch. Used by embedded clients whose host mod inlines
+   * the payload into the page. Falls back to a normal fetch if omitted.
+   */
+  initialVersion?: ServerVersion
 }
 
 export class ScreepsClient {
@@ -100,6 +107,8 @@ export class ScreepsClient {
       navigation: new NavigationStore(50, this.logger.child('navigation')),
     }
 
+    if (opts.initialVersion) this.stores.server.seedVersion(opts.initialVersion)
+
     this.tokenRefreshIntervalMs = opts.tokenRefresh === false
       ? null
       : (opts.tokenRefresh?.intervalMs ?? 30_000)

package/src/stores/ServerStore.ts

@@ -43,9 +43,27 @@ export class ServerStore extends TypedStore<ServerStoreEvents> {
     this.socketSubs.length = 0
   }
 
+  /**
+   * Seed the server version without a network request. Used when the version is
+   * already known at construction time — e.g. an embedded client whose host mod
+   * inlines the `/api/version` payload into the page, sparing the initial fetch.
+   * Does not emit `server:version` (listeners aren't attached yet at that point);
+   * the value surfaces via the cache-hit path on the first `version()` call.
+   */
+  seedVersion(version: ServerVersion): void {
+    this._version = version
+    this.cache.set('server/version', version, 5 * 60_000)
+  }
+
   async version(): Promise<ServerVersion> {
     const cached = this.cache.get<ServerVersion>('server/version')
-    if (cached) return cached
+    if (cached) {
+      // Emit on cache hits too so a seeded version (see `seedVersion`) reaches
+      // listeners that only attach after construction. Idempotent for consumers.
+      this._version = cached
+      this.emit('server:version', cached)
+      return cached
+    }
     const res = await this.http.request<ServerVersion>('GET', '/api/version')
     this._version = res
     this.cache.set('server/version', res, 5 * 60_000)

package/tests/stores/ServerStore.test.ts

@@ -31,6 +31,18 @@ describe('ServerStore', () => {
     expect(http.request).toHaveBeenCalledOnce()
   })
 
+  it('serves a seeded version without fetching and emits server:version', async () => {
+    const { store, http } = makeStore()
+    const spy = vi.fn()
+    store.on('server:version', spy)
+    store.seedVersion({ ...mockVersion })
+    const v = await store.version()
+    expect(v.protocol).toBe(13)
+    expect(http.request).not.toHaveBeenCalled()
+    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ protocol: 13 }))
+    expect(store.versionInfo?.protocol).toBe(13)
+  })
+
   it('emits server:connected when socket fires connected event', () => {
     const { socket } = makeStore()
     let connectedCb: (data: unknown) => void = () => {}