bsky-social-app/docs/postthread-perf-analysis.md

PostThread Screen Performance Analysis

Initial Render Waterfall

Navigation triggers PostThreadScreen mount
  │
  ├─ 1. Route params parsed (name, rkey → URI)
  │     setMinimalShellMode(false)
  │
  ├─ 2. Dependencies resolve (blocking gates before query fires)
  │     ├─ useThreadPreferences() → sort, view  [from server prefs, cached]
  │     ├─ useModerationOpts()                   [from preferences context]
  │     └─ useSession()                          [from session context]
  │
  ├─ 3. usePostThread query fires
  │     ├─ placeholderData: getThreadPlaceholder() scans cache:
  │     │   other thread queries → notifications → feeds → quotes → search → explore
  │     │   (returns cached post if found, so user sees content immediately)
  │     │
  │     └─ getPostThreadV2({anchor, sort, view, branchingFactor, below})
  │         └─ Network round-trip to AppView
  │
  ├─ 4. While network pending: Render with placeholder or skeletons
  │     ├─ If placeholder found: anchor post renders with cached data
  │     └─ If no placeholder: anchor skeleton + reply skeletons
  │
  ├─ 5. Response arrives → sortAndAnnotateThreadItems()
  │     ├─ Pass 1: Build traversal metadata (depth, siblings, moderation)
  │     ├─ Pass 2: Insert readMore/readMoreUp items, compute UI state
  │     └─ buildThread(): Combine items + composer + skeletons
  │
  ├─ 6. List renders with deferParents=true
  │     ├─ Anchor post renders first (index 0)
  │     ├─ Anchor onLayout fires → setDeferParents(false)
  │     └─ Parent posts prepend above anchor
  │         ├─ Native: maintainVisibleContentPosition keeps anchor pinned
  │         └─ Web: manual scroll offset adjustment in onContentSizeChange
  │
  └─ 7. Pagination as user scrolls
        ├─ onStartReached: load more parents (chunks of 5)
        └─ onEndReached: load more children (chunks of 50)

Data Dependencies Graph

PostThread
├── usePostThread(anchor)
│   ├── useThreadPreferences()        ← server preferences (cached)
│   │   └── usePreferencesQuery()     ← app.bsky.actor.getPreferences
│   ├── useModerationOpts()           ← label/moderation config (context)
│   ├── useSession()                  ← auth state (context)
│   ├── useMergeThreadgateHiddenReplies() ← local + server hidden replies
│   ├── useAgent()                    ← API client (context)
│   └── useBreakpoints()              ← screen size → affects `below` param
│
├── Query: getPostThreadV2
│   ├── placeholderData → scans all query caches for cached post
│   └── enabled: prefs loaded AND anchor exists AND modOpts available
│
└── Lazy Query: getPostThreadOtherV2 (only on user action)
    └── enabled: otherItemsVisible AND hasOtherThreadItems

Key observation: The main query is gated on 3 conditions — preferences, anchor URI, and moderation options must all be available before getPostThreadV2 fires. If preferences are slow to load from the server, the thread query is delayed.

FlatList Virtualization Config

Parameter	Value	Default	Impact
initialNumToRender	Dynamic (from useInitialNumToRender)	10	Calculated from window height
windowSize	7	21	Renders 3.5 screens above/below viewport
maxToRenderPerBatch	5	10	Smaller batches = more responsive scrolling
updateCellsBatchingPeriod	100ms	50ms	Reduces render frequency
onEndReachedThreshold	4	2	Prefetches children early
onStartReachedThreshold	1	—	Loads parents when near top

Key Performance Patterns

1. Placeholder Data (eliminates blank screen)

• getThreadPlaceholder() searches 6 different query caches for the post
• If found in a feed or notification, the anchor post renders instantly with cached data
• Full thread data replaces placeholder when API responds

2. Deferred Parent Rendering (prevents scroll jump)

• On mount, deferParents=true — only anchor + children render
• Anchor's onLayout callback sets deferParents=false
• Parents then prepend above anchor
• Native uses maintainVisibleContentPosition to keep anchor stable
• Web recalculates scroll offset manually

3. Chunked Pagination

• Parents: 5 at a time (avoids large prepend causing jank)
• Children: 50 at a time (generous to reduce load-more triggers)

4. Lazy "Other Replies" Query

• Moderated/filtered replies not fetched until user taps "Show other replies"
• Avoids unnecessary network and render cost

5. Optimistic Reply Insertion

• createCacheMutator inserts new replies directly into query cache
• No refetch needed after posting a reply
• Post shadow system updates like/reply counts without re-render of entire tree

Potential Performance Concerns

1. sortAndAnnotateThreadItems is synchronous and O(n)

• Two full passes over all thread items on every query update
• Computes moderation for every post (moderatePost())
• For deeply nested threads with many replies, this could block the JS thread
• Located in src/state/queries/usePostThread/traversal.ts

2. No explicit staleTime configured

• The main query has no staleTime set, so TanStack Query treats data as immediately stale
• Navigating back to a previously viewed thread will refetch, though placeholder data covers the gap
• Could save unnecessary refetches by adding a staleTime (e.g., STALE.SECONDS.FIFTEEN)

3. Thread preference changes re-derive everything

• Changing sort or view triggers prepareForParamsUpdate() which resets deferParents=true
• The query key includes sort/view, so it's a fresh fetch + full re-render
• No transition animation or optimistic sorting

4. Parent prepend scroll management (web)

• Web path uses onContentSizeChange with manual scroll math
• shouldHandleScroll ref + anchorTop ref coordination is fragile
• Potential for scroll position glitches if content size changes during prepend

5. Multiple context providers in render path

• PostThreadContextProvider wraps the entire tree
• Each ThreadItemPost reads from thread context, session, theme, moderation, preferences
• React Compiler helps here, but deep context dependency chains can still cause cascading re-renders if a provider value changes

6. Embed loading within thread

• Each post independently loads its embeds (images, videos, link cards, quote posts)
• No coordinated prefetching of embed content
• In a thread with many image/video embeds, this creates a waterfall of media requests
• Video embeds are particularly expensive — managed by updateActiveVideoViewAsync on scroll

API Parameter Tuning

Mode	branchingFactor	below (phone)	below (desktop)
Linear	1	10	10
Tree	undefined (all)	4	6

Linear view fetches deeper (10 levels) but only one branch. Tree view fetches shallower (4-6 levels) but all branches. This is a reasonable tradeoff — tree view with unlimited depth would be extremely expensive.

Component Render Tree

PostThread (main component)
├── PostThreadContextProvider
│   ├── Layout.Header.Outer
│   │   ├── Layout.Header.BackButton
│   │   ├── Layout.Header.TitleText ("Post")
│   │   └── HeaderDropdown (sort/view controls)
│   │
│   └── List (FlatList with virtualization)
│       └── renderItem() dispatches to:
│           ├── ThreadItemAnchor (depth=0, large format)
│           │   └── PostControls (big variant), engagement stats, full embed
│           ├── ThreadItemPost (depth<0 parents, depth>0 linear replies)
│           │   └── PostControls (standard), condensed embed
│           ├── ThreadItemTreePost (depth>0, tree view)
│           │   └── Indented with vertical connection lines, compact controls
│           ├── ThreadItemPostTombstone (blocked/not-found)
│           ├── ThreadItemReadMore / ThreadItemReadMoreUp
│           ├── ThreadItemShowOtherReplies
│           ├── ThreadComposePrompt
│           └── Skeleton variants (anchor, reply, composer)
│
└── MobileComposePrompt (floating reply button on native)

Key Files Reference

File	Purpose
src/screens/PostThread/index.tsx	Main component, list rendering, scroll handling
src/view/screens/PostThread.tsx	Navigation screen wrapper
src/state/queries/usePostThread/index.ts	Query hook, state management
src/state/queries/usePostThread/traversal.ts	Sorting, annotation, moderation
src/state/queries/usePostThread/queryCache.ts	Optimistic cache mutation
src/state/queries/usePostThread/const.ts	API params (branching factor, below)
src/screens/PostThread/const.ts	UI constants (spacing, widths)
src/screens/PostThread/components/*.tsx	Individual item renderers

Summary

The PostThread screen is well-optimized for the common case. The placeholder data system, deferred parent rendering, and chunked pagination create a smooth experience for typical threads. The main areas where performance could degrade are:

1. Very large threads where sortAndAnnotateThreadItems becomes expensive on the JS thread
2. Media-heavy threads where embed loading creates waterfalls of network requests
3. Lack of staleTime causing unnecessary refetches on re-navigation
4. Web scroll management during parent prepending being fragile