implement lazy guild loading

Author: jay3332

src/App.tsx

@@ -256,7 +256,7 @@ function DirectMessageButton({ channelId }: { channelId: bigint }) {
           }}>
             <span class="truncate min-w-0">
               {group
-                ? t('dms.group_members_other', { count: channel().recipient_ids.length })
+                ? t('generic.members', { count: channel().recipient_ids.length })
                 : (
                   lastMessage() ? (
                     (deltaMs()! > 30_000 ? t('time.past', { delta: humanizeTimeDeltaShort(deltaMs()!) }) : t('time.recently'))

src/Entrypoint.tsx

@@ -115,6 +115,11 @@ const Entrypoint: Component = () => {
       ws.connect().then(() => {
         setWs(ws)
         api?.pushNotifications.subscribe()
+
+        // ts workaround bypasses the params context
+        const match = window.location.pathname.match(/^\/guilds\/(\d+)/)
+        const focusedGuildId = match ? BigInt(match[1]) : undefined
+        ws.startBackgroundGuildLoading(focusedGuildId)
       })
       api.ws = ws
     }
@@ -126,8 +131,8 @@ const Entrypoint: Component = () => {
     if (contextMenu.menu() == null || contextMenuRef == null) return
 
     contextMenu.setPos(({ x, y }) => ({
-      x: contextMenuAdjustment(x, contextMenuRef!.offsetWidth, window.innerWidth),
-      y: contextMenuAdjustment(y, contextMenuRef!.offsetHeight, window.innerHeight),
+      x: contextMenuAdjustment(x, (contextMenuRef as any)!.offsetWidth, window.innerWidth),
+      y: contextMenuAdjustment(y, (contextMenuRef as any)!.offsetHeight, window.innerHeight),
     }))
   })
 
@@ -136,7 +141,7 @@ const Entrypoint: Component = () => {
       class="relative font-sans m-0 w-[100vw] h-[100vh] text-fg"
       onClick={(event) => contextMenu.setMenu(prev => {
         if (prev != null && contextMenuRef != null) {
-          if (contextMenuRef.contains(event.target)) return prev
+          if ((contextMenuRef as any).contains(event.target)) return prev
         }
       })}
     >

src/api/ApiCache.ts

@@ -64,6 +64,7 @@ export default class ApiCache {
   guildMentions: ReactiveMap<bigint, ReactiveMap<bigint, bigint[]>>
   dmMentions: ReactiveMap<bigint, bigint[]>
   customEmojis: ReactiveMap<bigint, CustomEmoji>
+  guildLoadingStates: ReactiveMap<bigint, boolean>
 
   constructor(private readonly api: Api) {
     this.clientUserReactor = null as any // lazy
@@ -88,6 +89,7 @@ export default class ApiCache {
     this.guildMentions = new ReactiveMap()
     this.dmMentions = new ReactiveMap()
     this.customEmojis = new ReactiveMap()
+    this.guildLoadingStates = new ReactiveMap()
   }
 
   static fromReadyEvent(api: Api, ready: ReadyEvent): ApiCache {
@@ -99,7 +101,7 @@ export default class ApiCache {
       cache.updateRelationship(relationship)
 
     for (const guild of ready.guilds)
-      cache.updateGuild(guild)
+      cache.updatePartialGuild(guild)
 
     for (const presence of ready.presences)
       cache.updatePresence(presence)
@@ -178,6 +180,8 @@ export default class ApiCache {
         this.updateEmoji(emoji)
 
     this.guildListReactor[1](prev => {
+      // If already in the list (e.g. was added as partial guild), don't add again
+      if (prev.includes(guild.id)) return prev
       // TODO: sort by true order, this is just creation date
       const index = sortedIndex(prev, guild.id)
       const next = [...prev]
@@ -186,6 +190,22 @@ export default class ApiCache {
     })
   }
 
+  updatePartialGuild(partialGuild: PartialGuild) {
+    const existing = this.guilds.get(partialGuild.id)
+    if (existing) {
+      this.guilds.set(partialGuild.id, { ...existing, ...partialGuild })
+      return
+    }
+
+    this.guilds.set(partialGuild.id, partialGuild as Guild)
+    this.guildListReactor[1](prev => {
+      const index = sortedIndex(prev, partialGuild.id)
+      const next = [...prev]
+      next.splice(index, 0, partialGuild.id)
+      return next
+    })
+  }
+
   patchGuild(partialGuild: PartialGuild) {
     const guild = this.guilds.get(partialGuild.id)
     if (!guild) return
@@ -364,7 +384,8 @@ export default class ApiCache {
     const roles = (member.roles ?? []).map(id => this.roles.get(BigInt(id))).filter(role => role != null) as Role[]
 
     const defaultRoleId = snowflakes.withModelType(guildId, snowflakes.ModelType.Role)
-    if (!roles.find(role => role.id === defaultRoleId)) roles.push(this.roles.get(defaultRoleId)!)
+    const defaultRole = this.roles.get(defaultRoleId)
+    if (defaultRole && !roles.find(role => role.id === defaultRoleId)) roles.push(defaultRole)
     return roles
   }
 
@@ -375,7 +396,7 @@ export default class ApiCache {
     if (!member) return Permissions.empty()
 
     const roles = this.getMemberRoles(guildId, userId)
-    const overwrites = channelId && (this.channels.get(channelId) as GuildChannel).overwrites || undefined
+    const overwrites = channelId && (this.channels.get(channelId) as GuildChannel)?.overwrites || undefined
     return calculatePermissions(userId, member.permissions, roles, overwrites)
   }
 
@@ -388,14 +409,17 @@ export default class ApiCache {
     return this.roles.get(defaultRoleId)!
   }
 
-  getMemberTopRole(guildId: bigint, userId: bigint): Role {
+  getMemberTopRole(guildId: bigint, userId: bigint): Role | undefined {
     const roles = this.getMemberRoles(guildId, userId)
     return maxIterator(roles, role => role.position) ?? this.getDefaultRole(guildId)
   }
 
   clientCanManage(guildId: bigint, userId: bigint): boolean {
-    return this.guilds.get(guildId)?.owner_id == this.clientId!
-      || this.getMemberTopRole(guildId, this.clientId!).position > this.getMemberTopRole(guildId, userId).position
+    if (this.guilds.get(guildId)?.owner_id == this.clientId!) return true
+    const clientTop = this.getMemberTopRole(guildId, this.clientId!)
+    const targetTop = this.getMemberTopRole(guildId, userId)
+    if (!clientTop || !targetTop) return false
+    return clientTop.position > targetTop.position
   }
 
   getMemberColor(guildId: bigint, memberId: bigint): ExtendedColor | undefined {
@@ -476,6 +500,16 @@ export default class ApiCache {
     }
   }
 
+  isGuildLoaded(guildId: bigint): boolean {
+    const guild = this.guilds.get(guildId)
+    if (!guild) return false
+    return guild.channels != null && guild.roles != null
+  }
+
+  isGuildLoading(guildId: bigint): boolean {
+    return this.guildLoadingStates.get(guildId) ?? false
+  }
+
   countGuildMentionsIn(guildId: bigint, channelId: bigint): number | null {
     return this.guildMentions.get(guildId)?.get(channelId)?.length ?? null
   }

src/api/WsClient.tsx

@@ -6,14 +6,15 @@ import {
   ChannelCreateEvent, ChannelDeleteEvent, ChannelUpdateEvent,
   GuildCreateEvent,
   GuildRemoveEvent, GuildUpdateEvent,
+  GuildsAvailableEvent,
   MemberJoinEvent,
   MemberRemoveEvent, MemberUpdateEvent,
   MessageCreateEvent,
   MessageDeleteEvent, MessageUpdateEvent,
   PresenceUpdateEvent,
   ReadyEvent,
   RelationshipCreateEvent,
-  RelationshipRemoveEvent, RoleCreateEvent, RoleDeleteEvent, RolePositionsUpdateEvent, RoleUpdateEvent,
+  RelationshipRemoveEvent, RequestGuildsPayload, RoleCreateEvent, RoleDeleteEvent, RolePositionsUpdateEvent, RoleUpdateEvent,
   TypingStartEvent,
   TypingStopEvent,
   UpdatePresencePayload,
@@ -50,6 +51,10 @@ export const WsEventHandlers: Record<string, WsEventHandler> = {
 
     ws.api.cache?.updateUser(data.after)
   },
+  guilds_available(ws: WsClient, data: GuildsAvailableEvent) {
+    for (const guild of data.guilds)
+      ws.api.cache?.updateGuild(guild)
+  },
   guild_create(ws: WsClient, data: GuildCreateEvent) {
     ws.api.cache?.updateGuild(data.guild)
   },
@@ -224,9 +229,7 @@ export default class WsClient {
 
   async forceReady() {
     let [guilds, dmChannels, clientUser, relationships] = await Promise.all([
-      this.api.request('GET', '/guilds', {
-        params: { channels: true, members: true, roles: true }
-      }),
+      this.api.request('GET', '/guilds'),
       this.api.request('GET', '/users/me/channels'),
       this.api.request('GET', '/users/me'),
       this.api.request('GET', '/relationships')
@@ -328,6 +331,121 @@ export default class WsClient {
     localStorage.setItem('presence', JSON.stringify(presence))
   }
 
+  /**
+   * Requests full guild data for up to 20 guild IDs. For each requested guild that the client is
+   * a member of, harmony responds with a `guilds_available` event which is handled automatically
+   * by the cache. Returns a promise that resolves once all responses have arrived.
+   */
+  requestGuilds(guildIds: bigint[], nonce?: string): Promise<void> {
+    const resolvedNonce = nonce ?? Math.random().toString(36).slice(2)
+    const payload: RequestGuildsPayload = { guild_ids: guildIds, nonce: resolvedNonce }
+    this.connection?.send(msgpack.encode({ op: 'request_guilds', ...payload }))
+
+    // Mark guilds as loading
+    const cache = this.api.cache
+    if (cache) {
+      for (const id of guildIds) {
+        if (!cache.isGuildLoaded(id))
+          cache.guildLoadingStates.set(id, true)
+      }
+    }
+
+    return new Promise((resolve) => {
+      const remove = this.on('guilds_available', (data: GuildsAvailableEvent, removeListener) => {
+        if (data.nonce !== resolvedNonce) return
+        removeListener()
+        // Clear loading states for guilds that were returned
+        if (cache) {
+          for (const guild of data.guilds)
+            cache.guildLoadingStates.delete(guild.id)
+          // Also clear any that weren't returned (e.g. guild no longer exists)
+          for (const id of guildIds)
+            cache.guildLoadingStates.delete(id)
+        }
+        resolve()
+      })
+      setTimeout(() => {
+        remove()
+        if (cache) {
+          for (const id of guildIds)
+            cache.guildLoadingStates.delete(id)
+        }
+        resolve()
+      }, 10_000)
+    })
+  }
+
+  /**
+   * Ensures that a guild's full data (channels, roles, members, emojis) is loaded. If already
+   * loaded, resolves immediately. If currently loading, waits for it to finish. Otherwise,
+   * sends a request and waits for the response.
+   */
+  ensureGuildLoaded(guildId: bigint): Promise<void> {
+    const cache = this.api.cache
+    if (!cache) return Promise.resolve()
+    if (cache.isGuildLoaded(guildId)) return Promise.resolve()
+
+    if (cache.isGuildLoading(guildId)) {
+      // Wait for the loading to complete by watching guilds_available
+      return new Promise((resolve) => {
+        const remove = this.on('guilds_available', (data: GuildsAvailableEvent) => {
+          if (data.guilds.some(g => g.id === guildId) || !cache.isGuildLoading(guildId)) {
+            remove()
+            resolve()
+          }
+        })
+        setTimeout(() => { remove(); resolve() }, 10_000)
+      })
+    }
+
+    return this.requestGuilds([guildId])
+  }
+
+  /**
+   * Loads all guilds in the background after the ready event, in priority order:
+   * 1. The focused guild (from the current URL, if any)
+   * 2. All remaining guilds sorted by member count (descending)
+   *
+   * Batches up to 20 guilds per request.
+   */
+  async startBackgroundGuildLoading(focusedGuildId?: bigint) {
+    const cache = this.api.cache
+    if (!cache) return
+
+    const allGuildIds = cache.guildList
+
+    // Build priority-ordered list
+    const ordered: bigint[] = []
+    const seen = new Set<bigint>()
+
+    const add = (id: bigint) => {
+      if (!seen.has(id) && !cache.isGuildLoaded(id)) {
+        seen.add(id)
+        ordered.push(id)
+      }
+    }
+
+    // Priority 1: focused guild
+    if (focusedGuildId != null) add(focusedGuildId)
+
+    // Priority 2: remaining guilds sorted by member count desc
+    const remaining = allGuildIds
+      .filter(id => !seen.has(id))
+      .sort((a, b) => {
+        const aCount = cache.guilds.get(a)?.member_count?.total ?? 0
+        const bCount = cache.guilds.get(b)?.member_count?.total ?? 0
+        return bCount - aCount
+      })
+    for (const id of remaining) add(id)
+
+    // Load in batches of up to 20
+    for (let i = 0; i < ordered.length; i += 20) {
+      const batch = ordered.slice(i, i + 20)
+      console.debug('[WS] Background loading guild batch:', batch.map(String))
+      await this.requestGuilds(batch)
+    }
+  }
+
   reconnectWithBackoff() {
     const delay = this.backoff.delay()
     console.debug(`[WS] Connection closed, attempting reconnect in ${delay / 1000} seconds`)

src/components/guilds/EditMemberRolesModal.tsx

@@ -20,7 +20,7 @@ export default function EditMemberRolesModal(props: { guildId: bigint, memberId:
   const [selected, setSelected] = createSignal<bigint[]>(currentRoles());
 
   const toggle = (id: bigint) => setSelected(prev => prev.includes(id) ? prev.filter(r => r !== id) : [...prev, id]);
-  const unaddable = (position: number) => clientTop().position <= position; // cannot manage equal-or-higher
+  const unaddable = (position: number) => (clientTop()?.position ?? Infinity) <= position; // cannot manage equal-or-higher
 
   const save = async () => {
     const resp = await api.request('PATCH', `/guilds/${props.guildId}/members/${props.memberId}`, { json: { roles: selected() } });

src/components/guilds/GuildIcon.tsx

@@ -54,6 +54,7 @@ export default function GuildIcon(props: GuildIconProps) {
     if (!id) return
 
     for (const guildId of api!.cache!.guildList) {
+      if (!api!.cache!.isGuildLoaded(guildId)) continue
       const member = api?.cache?.members.get(memberKey(guildId, id))
       if (!member) continue