screeps-connectivity 0.2.0

package/src/stores/MapStatsStore.ts

@@ -0,0 +1,115 @@
+import { TypedStore } from './TypedStore.js'
+import type { Logger } from '../logger.js'
+import type { HttpClient } from '../http/HttpClient.js'
+import type { ApiMapStatsRoomStat, ApiMapStatsBadge } from '../types/api.js'
+
+export interface MapStatsRoomData {
+  own?: { user: string; level: number }
+  mineral?: string
+  density?: number
+  username?: string
+  safeMode?: boolean
+  badge?: ApiMapStatsBadge
+}
+
+export interface MapStatsStoreEvents {
+  'mapStats:room': { room: string; shard: string | null; stat: MapStatsRoomData }
+}
+
+interface PendingBatch {
+  rooms: Set<string>
+  statName: string
+  shard: string
+}
+
+export class MapStatsStore extends TypedStore<MapStatsStoreEvents> {
+  private readonly http: HttpClient
+  private readonly debounceMs: number
+  private readonly minIntervalMs: number
+  private pending = new Map<string, PendingBatch>()
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private lastFlushTime = 0
+
+  constructor(http: HttpClient, debounceMs = 100, minIntervalMs = 500, logger?: Logger) {
+    super(logger)
+    this.http = http
+    this.debounceMs = debounceMs
+    this.minIntervalMs = minIntervalMs
+  }
+
+  /** Queue rooms for a batched mapStats fetch. No-op when rooms is empty. */
+  request(rooms: string[], statName: string, shard?: string): void {
+    if (rooms.length === 0) return
+
+    const key = JSON.stringify([statName, shard ?? 'shard0'])
+    let entry = this.pending.get(key)
+    if (!entry) {
+      entry = { rooms: new Set(), statName, shard: shard ?? 'shard0' }
+      this.pending.set(key, entry)
+    }
+    for (const room of rooms) entry.rooms.add(room)
+
+    if (this.timer) clearTimeout(this.timer)
+
+    const now = Date.now()
+    const timeSinceLastFlush = now - this.lastFlushTime
+    const delay = Math.max(this.debounceMs, this.minIntervalMs - timeSinceLastFlush)
+
+    this.timer = setTimeout(() => this.flush(), delay)
+  }
+
+  private async flush(): Promise<void> {
+    const toFlush = new Map(this.pending)
+    this.pending.clear()
+    this.timer = null
+    this.lastFlushTime = Date.now()
+
+    for (const [, batch] of toFlush) {
+      const allRooms = [...batch.rooms]
+      try {
+        const res = await this.http.request<{ ok: number; stats: Record<string, ApiMapStatsRoomStat>; users: Record<string, { _id: string; username: string; badge: ApiMapStatsBadge }> }>(
+          'POST', '/api/game/map-stats', { rooms: allRooms, statName: batch.statName, shard: batch.shard }
+        )
+
+        const userMap = res.users ?? {}
+
+        for (const [room, stat] of Object.entries(res.stats)) {
+          const data = this.buildData(stat, userMap)
+          this.emit('mapStats:room', { room, shard: batch.shard === 'shard0' ? null : batch.shard, stat: data })
+        }
+
+        // Emit empty data for rooms that don't exist on server
+        for (const room of allRooms) {
+          if (!res.stats[room]) {
+            this.emit('mapStats:room', { room, shard: batch.shard === 'shard0' ? null : batch.shard, stat: {} })
+          }
+        }
+      } catch (err) {
+        this.logger.log('mapStats fetch failed:', err)
+      }
+    }
+  }
+
+  private buildData(stat: ApiMapStatsRoomStat, userMap: Record<string, { username: string; badge: ApiMapStatsBadge }>): MapStatsRoomData {
+    let mineral: string | undefined
+    let density: number | undefined
+    for (let i = 0; i < 3; i++) {
+      const mineralKey = `minerals${i}` as `minerals${number}`
+      const mineralData = stat[mineralKey]
+      if (mineralData) {
+        mineral = mineralData.type
+        density = mineralData.density
+        break
+      }
+    }
+    const ownerId = stat.own?.user
+    return {
+      own: stat.own,
+      mineral,
+      density,
+      username: ownerId ? userMap[ownerId]?.username : undefined,
+      safeMode: stat.safeMode,
+      badge: ownerId ? userMap[ownerId]?.badge : undefined,
+    }
+  }
+}

package/src/stores/MapStore.ts

@@ -0,0 +1,254 @@
+import { TypedStore } from './TypedStore.js'
+import { Map2Storage } from '../cache/Map2Storage.js'
+import type { SocketClient } from '../socket/SocketClient.js'
+import type { Subscription } from '../subscription/index.js'
+import type { MapStoreEvents, Map2SubscriptionStatus } from '../types/events.js'
+import type { RoomMap2Data } from '../types/game.js'
+import type { Logger } from '../logger.js'
+
+function canonicalize(data: RoomMap2Data): string {
+  const sortedKeys = Object.keys(data).sort()
+  const obj: Record<string, [number, number][] | null> = {}
+  for (const k of sortedKeys) {
+    const v = data[k]
+    obj[k] = v ? [...v].sort((a, b) => a[0] - b[0] || a[1] - b[1]) : null
+  }
+  return JSON.stringify(obj)
+}
+
+export interface Map2Subscription extends Subscription {
+  /** Current subscription status — updated in place when waitlist entry is promoted. */
+  readonly status: () => Map2SubscriptionStatus
+  /** Last data the library has for this room (memory only; synchronous). */
+  readonly cachedData: () => RoomMap2Data | null
+  /** Register a handler called whenever status changes. Returns a disposable. */
+  onStatusChange(handler: (status: Map2SubscriptionStatus) => void): Subscription
+}
+
+export interface MapStoreOptions {
+  /** Max simultaneous WebSocket roomMap2 subscriptions. Default 500. */
+  maxSubscriptions?: number
+}
+
+interface ActiveEntry {
+  room: string
+  shard: string | null
+  refCount: number
+  socketSub: Subscription
+  listenerSub: Subscription
+  /** Canonical hash of the last data we emitted/stored. null until first message or cache-warm init. */
+  lastHash: string | null
+}
+
+interface WaitlistEntry {
+  key: string
+  room: string
+  shard: string | null
+  refCount: number
+}
+
+interface KeyState {
+  status: Map2SubscriptionStatus
+  statusHandlers: Set<(status: Map2SubscriptionStatus) => void>
+}
+
+export class MapStore extends TypedStore<MapStoreEvents> {
+  private readonly socket: SocketClient
+  private readonly storage: Map2Storage
+  private readonly maxSubscriptions: number
+  private readonly active = new Map<string, ActiveEntry>()
+  private readonly waitlist: WaitlistEntry[] = []
+  private readonly keyStates = new Map<string, KeyState>()
+  private warnedAboutWaitlist = false
+
+  constructor(socket: SocketClient, storage: Map2Storage, opts: MapStoreOptions = {}, logger?: Logger) {
+    super(logger)
+    this.socket = socket
+    this.storage = storage
+    this.maxSubscriptions = opts.maxSubscriptions ?? 500
+    void this.socket.on('connected', () => this.onReconnect())
+  }
+
+  map2data(room: string, shard: string | null): RoomMap2Data | null {
+    return this.storage.getMemory(room, shard)
+  }
+
+  subscribeMap2(room: string, shard: string | null): Map2Subscription {
+    const mapKey = `${room}/${shard}`
+
+    // Case 1: already active — increment refCount and reuse the open WS sub
+    const activeEntry = this.active.get(mapKey)
+    if (activeEntry) {
+      activeEntry.refCount++
+      this.logger.log('subscribeMap2', room, shard, `(active, refs: ${activeEntry.refCount})`)
+      const keyState = this.getOrCreateKeyState(mapKey, 'active')
+      this.emitWarmStart(room, shard)
+      return this.makeSubscription(room, shard, mapKey, keyState)
+    }
+
+    // Case 2: already on waitlist — increment refCount
+    const waitEntry = this.waitlist.find(e => e.key === mapKey)
+    if (waitEntry) {
+      waitEntry.refCount++
+      this.logger.log('subscribeMap2', room, shard, `(pending, refs: ${waitEntry.refCount})`)
+      const keyState = this.getOrCreateKeyState(mapKey, 'pending')
+      this.emitWarmStart(room, shard)
+      return this.makeSubscription(room, shard, mapKey, keyState)
+    }
+
+    // Case 3: new subscription
+    if (this.active.size < this.maxSubscriptions) {
+      this.activateKey(room, shard, mapKey, 1)
+      this.logger.log('subscribeMap2', room, shard, '(new active)')
+      const keyState = this.getOrCreateKeyState(mapKey, 'active')
+      this.emit('room:map2state', { room, shard, status: 'active' })
+      this.emitWarmStart(room, shard)
+      return this.makeSubscription(room, shard, mapKey, keyState)
+    }
+
+    // Limit reached — enqueue on waitlist
+    this.waitlist.push({ key: mapKey, room, shard, refCount: 1 })
+    this.logger.log('subscribeMap2', room, shard, '(new pending)')
+    const keyState = this.getOrCreateKeyState(mapKey, 'pending')
+    this.emit('room:map2state', { room, shard, status: 'pending' })
+    this.emitWarmStart(room, shard)
+    if (!this.warnedAboutWaitlist) {
+      this.logger.log(
+        `subscription limit (${this.maxSubscriptions}) reached — `,
+        'some rooms are on a waitlist and will be promoted as slots free up.'
+      )
+      this.warnedAboutWaitlist = true
+    }
+    return this.makeSubscription(room, shard, mapKey, keyState)
+  }
+
+  private activateKey(room: string, shard: string | null, mapKey: string, refCount: number): void {
+    const channel = shard ? `roomMap2:${shard}/${room}` : `roomMap2:${room}`
+    const socketSub = this.socket.subscribe(channel)
+    const cached = this.storage.getMemory(room, shard)
+    const entry: ActiveEntry = {
+      room,
+      shard,
+      refCount,
+      socketSub,
+      listenerSub: undefined as unknown as Subscription,
+      lastHash: cached ? canonicalize(cached) : null,
+    }
+    entry.listenerSub = this.socket.on(channel, (data) => {
+      const next = data as RoomMap2Data
+      const nextHash = canonicalize(next)
+      if (entry.lastHash === nextHash) return
+      entry.lastHash = nextHash
+      void this.storage.put(room, shard, next)
+      this.emit('room:map2update', { room, shard, data: next, source: 'live' })
+    })
+    this.active.set(mapKey, entry)
+  }
+
+  private promoteNext(): void {
+    const next = this.waitlist.shift()
+    if (!next) return
+
+    this.activateKey(next.room, next.shard, next.key, next.refCount)
+    this.logger.log('promoteNext', next.room, next.shard, '(promoted from waitlist)')
+
+    const keyState = this.keyStates.get(next.key)
+    if (keyState) {
+      keyState.status = 'active'
+      keyState.statusHandlers.forEach(h => h('active'))
+    }
+
+    this.emit('room:map2state', { room: next.room, shard: next.shard, status: 'active' })
+  }
+
+  private getOrCreateKeyState(mapKey: string, status: Map2SubscriptionStatus): KeyState {
+    let state = this.keyStates.get(mapKey)
+    if (!state) {
+      state = { status, statusHandlers: new Set() }
+      this.keyStates.set(mapKey, state)
+    }
+    return state
+  }
+
+  private makeSubscription(room: string, shard: string | null, mapKey: string, keyState: KeyState): Map2Subscription {
+    let disposed = false
+    return {
+      status: () => keyState.status,
+      cachedData: () => this.storage.getMemory(room, shard),
+      onStatusChange: (handler) => {
+        keyState.statusHandlers.add(handler)
+        return { dispose: () => { keyState.statusHandlers.delete(handler) } }
+      },
+      dispose: () => {
+        if (disposed) return
+        disposed = true
+        this.disposeSubscription(room, shard, mapKey)
+      },
+    }
+  }
+
+  private disposeSubscription(room: string, shard: string | null, mapKey: string): void {
+    // Check waitlist first — no WS sub to close, no promotion needed
+    const waitIdx = this.waitlist.findIndex(e => e.key === mapKey)
+    if (waitIdx >= 0) {
+      const wait = this.waitlist[waitIdx]
+      wait.refCount--
+      this.logger.log('unsubscribeMap2', room, shard, `(pending, refs: ${wait.refCount})`)
+      if (wait.refCount <= 0) {
+        this.waitlist.splice(waitIdx, 1)
+        this.keyStates.delete(mapKey)
+        this.logger.log('unsubscribeMap2', room, shard, '(removed from waitlist)')
+      }
+      return
+    }
+
+    const active = this.active.get(mapKey)
+    if (!active) return
+
+    active.refCount--
+    this.logger.log('unsubscribeMap2', room, shard, `(active, refs: ${active.refCount})`)
+    if (active.refCount <= 0) {
+      active.socketSub.dispose()
+      active.listenerSub.dispose()
+      this.active.delete(mapKey)
+      this.keyStates.delete(mapKey)
+      this.logger.log('unsubscribeMap2', room, shard, '(deactivated, promoting next)')
+      this.promoteNext()
+    }
+  }
+
+  private emitWarmStart(room: string, shard: string | null): void {
+    const mapKey = `${room}/${shard}`
+    const cached = this.storage.getMemory(room, shard)
+    if (cached) {
+      queueMicrotask(() => {
+        if (this.isSubscribed(mapKey)) {
+          this.emit('room:map2update', { room, shard, data: cached, source: 'cache' })
+        }
+      })
+    } else {
+      void this.storage.get(room, shard).then(data => {
+        if (data && this.isSubscribed(mapKey)) {
+          this.emit('room:map2update', { room, shard, data, source: 'cache' })
+        }
+      })
+    }
+  }
+
+  private onReconnect(): void {
+    this.logger.log('onReconnect —', this.active.size, 'active,', this.waitlist.length, 'pending')
+    for (const entry of this.active.values()) {
+      // After a resubscribe, the server resends initial state. Clear the dedup hash so the first
+      // message after reconnect always fires an emit — even if the payload happens to match.
+      entry.lastHash = null
+      this.emit('room:map2state', { room: entry.room, shard: entry.shard, status: 'active' })
+    }
+    for (const entry of this.waitlist) {
+      this.emit('room:map2state', { room: entry.room, shard: entry.shard, status: 'pending' })
+    }
+  }
+
+  private isSubscribed(mapKey: string): boolean {
+    return this.active.has(mapKey) || this.waitlist.some(e => e.key === mapKey)
+  }
+}

package/src/stores/NavigationStore.ts

@@ -0,0 +1,61 @@
+import { TypedStore } from './TypedStore.js'
+import type { Logger } from '../logger.js'
+
+export interface NavigationState {
+  room: string | null
+  shard: string | null
+  index: number
+  history: Array<{ room: string; shard: string | null }>
+}
+
+export interface NavigationStoreEvents {
+  'navigation:change': NavigationState
+}
+
+export class NavigationStore extends TypedStore<NavigationStoreEvents> {
+  private _history: Array<{ room: string; shard: string | null }> = []
+  private _index = -1
+  private readonly maxHistory: number
+
+  constructor(maxHistory = 50, logger?: Logger) {
+    super(logger)
+    this.maxHistory = maxHistory
+  }
+
+  navigateTo(room: string, shard: string | null): void {
+    this._history = this._history.slice(0, this._index + 1)
+    this._history.push({ room, shard })
+    if (this._history.length > this.maxHistory) {
+      this._history.shift()
+    } else {
+      this._index++
+    }
+    this.emit('navigation:change', this.current())
+  }
+
+  back(): boolean {
+    if (!this.canBack()) return false
+    this._index--
+    this.emit('navigation:change', this.current())
+    return true
+  }
+
+  forward(): boolean {
+    if (!this.canForward()) return false
+    this._index++
+    this.emit('navigation:change', this.current())
+    return true
+  }
+
+  canBack(): boolean { return this._index > 0 }
+  canForward(): boolean { return this._index < this._history.length - 1 }
+
+  current(): NavigationState {
+    return {
+      room: this._history[this._index]?.room ?? null,
+      shard: this._history[this._index]?.shard ?? null,
+      index: this._index,
+      history: [...this._history],
+    }
+  }
+}

package/src/stores/RoomStore.ts

@@ -0,0 +1,264 @@
+import { TypedStore } from './TypedStore.js'
+import { RoomTerrain } from '../types/game.js'
+import type { Logger } from '../logger.js'
+import type { RoomStoreEvents } from '../types/events.js'
+import type { RoomObject, RoomObjectMap, RoomObjectDiff } from '../types/game.js'
+import type { HttpClient } from '../http/HttpClient.js'
+import type { SocketClient } from '../socket/SocketClient.js'
+import type { Cache } from '../cache/Cache.js'
+import type { Subscription } from '../subscription/index.js'
+
+export class RoomStore extends TypedStore<RoomStoreEvents> {
+  private readonly http: HttpClient
+  private readonly socket: SocketClient
+  private readonly cache: Cache
+  private readonly roomObjects = new Map<string, RoomObjectMap>()
+  private readonly roomUsers = new Map<string, Record<string, { _id: string; username: string }>>()
+  private readonly roomSubCount = new Map<string, number>()
+  private readonly lastFlagsString = new Map<string, string>()
+
+  private parseFlagsString(flagsStr: string | undefined, roomName: string): RoomObject[] {
+    if (!flagsStr || flagsStr.length === 0) return []
+    const result: RoomObject[] = []
+    const entries = flagsStr.split('|')
+    for (const entry of entries) {
+      const parts = entry.split('~')
+      if (parts.length !== 5) continue
+      const [name, colorStr, secColorStr, xStr, yStr] = parts
+      const color = parseInt(colorStr, 10)
+      const secondaryColor = parseInt(secColorStr, 10)
+      const x = parseInt(xStr, 10)
+      const y = parseInt(yStr, 10)
+      if (isNaN(color) || isNaN(secondaryColor) || isNaN(x) || isNaN(y)) continue
+      result.push({
+        _id: name,
+        type: 'flag',
+        room: roomName,
+        name,
+        x,
+        y,
+        color,
+        secondaryColor,
+      })
+    }
+    return result
+  }
+
+  constructor(http: HttpClient, socket: SocketClient, cache: Cache, logger?: Logger) {
+    super(logger)
+    this.http = http
+    this.socket = socket
+    this.cache = cache
+  }
+
+  async terrain(room: string, shard: string | null): Promise<RoomTerrain> {
+    const key = `terrain/${shard}/${room}`
+
+    const cached = this.cache.get<RoomTerrain>(key)
+    if (cached) {
+      this.logger.log('terrain', room, shard, '(memory cache hit)')
+      return cached
+    }
+
+    const persisted = await this.cache.getPersistent(key)
+    if (persisted) {
+      this.logger.log('terrain', room, shard, '(persistent cache hit)')
+      const terrain = new RoomTerrain(persisted)
+      this.cache.set(key, terrain)
+      return terrain
+    }
+
+    this.logger.log('terrain', room, shard, '(fetching)')
+    const res = await this.http.game.roomTerrain(room, shard ?? undefined)
+    const entry = res.terrain[0]
+    if (!entry) throw new Error(`No terrain data for room ${room} shard ${shard}`)
+    const terrain = RoomTerrain.fromEncodedString(entry.terrain)
+
+    this.cache.set(key, terrain)
+    await this.cache.setPersistent(key, terrain.raw)
+    this.emit('room:terrainavailable', { room, shard, terrain })
+
+    return terrain
+  }
+
+  async terrainBulk(rooms: string[], shard: string | null): Promise<Map<string, RoomTerrain>> {
+    const result = new Map<string, RoomTerrain>()
+    const needPersistentCheck: string[] = []
+
+    for (const room of rooms) {
+      const cached = this.cache.get<RoomTerrain>(`terrain/${shard}/${room}`)
+      if (cached) {
+        result.set(room, cached)
+      } else {
+        needPersistentCheck.push(room)
+      }
+    }
+
+    if (needPersistentCheck.length === 0) return result
+
+    const needFetch: string[] = []
+    await Promise.all(needPersistentCheck.map(async (room) => {
+      const key = `terrain/${shard}/${room}`
+      const persisted = await this.cache.getPersistent(key)
+      if (persisted) {
+        const terrain = new RoomTerrain(persisted)
+        this.cache.set(key, terrain)
+        result.set(room, terrain)
+      } else {
+        needFetch.push(room)
+      }
+    }))
+
+    if (needFetch.length === 0) return result
+
+    this.logger.log('terrainBulk', `fetching ${needFetch.length} rooms`, shard)
+    const res = await this.http.game.roomsTerrain(needFetch, shard ?? undefined)
+
+    await Promise.all(res.rooms.map(async (entry) => {
+      const terrain = RoomTerrain.fromEncodedString(entry.terrain)
+      const key = `terrain/${shard}/${entry.room}`
+      this.cache.set(key, terrain)
+      await this.cache.setPersistent(key, terrain.raw)
+      this.emit('room:terrainavailable', { room: entry.room, shard, terrain })
+      result.set(entry.room, terrain)
+    }))
+
+    return result
+  }
+
+  /**
+   * Snapshot of the room's current object map, or null if nothing has been
+   * received yet. Returns a shallow copy so callers cannot mutate the
+   * store's internal state. Each tick's update creates fresh object refs,
+   * so the shallow copy is sufficient.
+   */
+  objects(room: string, shard: string | null): RoomObjectMap | null {
+    const map = this.roomObjects.get(`${room}/${shard}`)
+    return map ? { ...map } : null
+  }
+
+  /** @deprecated Room objects are delivered via WebSocket on subscription. This endpoint is not supported by all servers and is not needed. */
+  async fetchObjects(room: string, shard: string | null): Promise<void> {
+    const mapKey = `${room}/${shard}`
+    const res = await this.http.game.roomObjects(room, shard ?? undefined)
+    const map: RoomObjectMap = {}
+    for (const obj of res.objects as RoomObject[]) {
+      if (obj && typeof obj === 'object' && '_id' in obj) {
+        map[(obj as RoomObject)._id] = obj as RoomObject
+      }
+    }
+    this.roomObjects.set(mapKey, map)
+    const users = this.roomUsers.get(mapKey)
+    this.emit('room:update', { room, shard, gameTime: undefined, objects: map, diff: map, visual: '', users })
+  }
+
+  private activeRooms(): string {
+    return Array.from(this.roomSubCount.entries())
+      .map(([key, count]) => `${key}(${count})`)
+      .join(', ') || '(none)'
+  }
+
+  subscribe(room: string, shard: string | null): Subscription {
+    const mapKey = `${room}/${shard}`
+    const count = this.roomSubCount.get(mapKey) ?? 0
+    this.roomSubCount.set(mapKey, count + 1)
+    this.logger.log('subscribe', room, shard, `(refs: ${count + 1})`, 'active:', this.activeRooms())
+
+    const channel = shard ? `room:${shard}/${room}` : `room:${room}`
+    const errChannel = shard ? `err@room:${shard}/${room}` : `err@room:${room}`
+    const socketSub = this.socket.subscribe(channel)
+
+    const errListenerSub = this.socket.on(errChannel, (data) => {
+      const msg = typeof data === 'string' ? data : JSON.stringify(data)
+      this.logger.log('room error', room, shard, msg)
+      this.emit('room:error', { room, shard, message: msg })
+    })
+
+    const listenerSub = this.socket.on(channel, (data) => {
+      const update = data as { objects: RoomObjectDiff; gameTime?: number; visual?: string; flags?: string; users?: Record<string, { _id: string; username: string }> }
+      const current: RoomObjectMap = { ...(this.roomObjects.get(mapKey) ?? {}) }
+
+      for (const [id, obj] of Object.entries(update.objects)) {
+        if (obj === null) {
+          delete current[id]
+        } else if (current[id]) {
+          current[id] = { ...current[id], ...obj } as RoomObject
+        } else {
+          current[id] = obj as RoomObject
+        }
+      }
+
+      // Build diff that includes flags so ObjectLayer can incremental-update them
+      const diff: RoomObjectDiff = { ...update.objects }
+
+      // Parse and inject flags from the dedicated flags field — only when the
+      // server-sent flag string actually changed. The flags field is included
+      // on every tick even when nothing about the flags changed, so without
+      // this guard every selected flag would get a fresh object each tick and
+      // re-trigger UI subscriptions for no reason.
+      if ('flags' in update) {
+        const newFlagsString = update.flags ?? ''
+        const prevFlagsString = this.lastFlagsString.get(mapKey) ?? ''
+
+        if (newFlagsString !== prevFlagsString) {
+          this.lastFlagsString.set(mapKey, newFlagsString)
+
+          const parsed = this.parseFlagsString(newFlagsString, room)
+          const newFlags = new Map<string, RoomObject>()
+          for (const f of parsed) newFlags.set(f.name as string, f)
+
+          // Emit removed flags as null in diff and drop them from current
+          for (const id in current) {
+            const obj = current[id]
+            if (obj?.type === 'flag' && !newFlags.has(id)) {
+              delete current[id]
+              diff[id] = null
+              this.logger.log(`[flag:room] removed ${id} @ ${room}`)
+            }
+          }
+
+          // Emit added/changed flags
+          for (const [id, flag] of newFlags) {
+            const prev = current[id]
+            const changed =
+              !prev ||
+              prev.x !== flag.x ||
+              prev.y !== flag.y ||
+              prev.color !== flag.color ||
+              prev.secondaryColor !== flag.secondaryColor
+            if (changed) {
+              current[id] = flag
+              diff[id] = flag
+              this.logger.log(`[flag:room] ${prev ? 'changed' : 'added'} ${id} @ ${room} (${flag.x},${flag.y})`)
+            }
+          }
+        }
+      }
+
+      if (update.users) {
+        this.roomUsers.set(mapKey, update.users)
+      }
+      this.roomObjects.set(mapKey, current)
+      const users = this.roomUsers.get(mapKey)
+      this.emit('room:update', { room, shard, gameTime: update.gameTime, objects: current, diff, visual: update.visual ?? '', users })
+    })
+
+    return {
+      dispose: () => {
+        socketSub.dispose()
+        listenerSub.dispose()
+        errListenerSub.dispose()
+        const remaining = (this.roomSubCount.get(mapKey) ?? 1) - 1
+        if (remaining <= 0) {
+          this.roomSubCount.delete(mapKey)
+          this.roomObjects.delete(mapKey)
+          this.lastFlagsString.delete(mapKey)
+          this.logger.log('unsubscribe', room, shard, '(last ref)', 'active:', this.activeRooms())
+        } else {
+          this.roomSubCount.set(mapKey, remaining)
+          this.logger.log('unsubscribe', room, shard, `(refs: ${remaining})`, 'active:', this.activeRooms())
+        }
+      },
+    }
+  }
+}