bitvid/docs/comment-threading.md

Comment threads & discussion counts (Nostr → UI flow)

This note documents how bitvid turns Nostr comment events into UI comment threads and discussion counts. The primary implementations live in:

• js/services/commentThreadService.js (comment thread hydration + caching)
• js/services/discussionCountService.js (NIP-45 count queries + DOM updates)

Comment thread flow (CommentThreadService)

Data sources

CommentThreadService is the single place that fetches and subscribes to comment events for a video. It relies on the injected nostrClient APIs:

• fetchVideoComments(target, options) for the initial thread load.
• subscribeVideoComments(target, options) to keep the thread up to date in real time.

The service builds a target payload using the current video metadata:

• videoEventId (event id)
• videoDefinitionAddress from buildVideoAddressPointer(video)
• videoKind
• videoAuthorPubkey
• rootIdentifier / rootIdentifierRelay (derived from video.videoRootId, pointer identifiers, or tag data)
• optional parentCommentId context when fetching a reply thread

Internally, it also infers parentage from the incoming comment events by looking at e tags; the most recent e tag that is not the video event id becomes the parent comment id for threading. It also watches for the i tag to update root identifier and relay details.

Caching

When FEATURE_IMPROVED_COMMENT_FETCHING is enabled, comment events are cached in localStorage:

• Key format: bitvid:comments:<videoEventId>
• TTL: 5 minutes
• Versioned schema: COMMENT_CACHE_VERSION = 2

Cache usage is simple: load from cache during loadThread, and write the latest event list after thread updates. Cache diagnostics (commentCacheDiagnostics.storageUnavailable) are surfaced to consumers to indicate storage issues.

Polling & refresh

There is no polling loop for comments. Refresh happens through:

1. A one-time fetch via fetchVideoComments during loadThread.
2. A live subscription via subscribeVideoComments, which streams new comments into the thread.

Profile hydration for comment authors is batched and debounced (default 25ms), with up to three retry attempts and a backoff delay between attempts.

UI surfacing

VideoModalCommentController owns the comment UI and subscribes to CommentThreadService callbacks:

• onThreadReady → full thread render
• onCommentsAppended → incremental updates
• onError → status messaging

The controller translates the thread snapshot into UI state for the modal and uses the comment thread’s profile cache to annotate authors.

Telemetry/logging

All comment-thread telemetry is routed through logger.dev/logger.user (no direct console logging). The service emits warnings for:

• Nostr client failures (fetch/subscribe)
• Comment cache read/write errors
• Profile hydration retries and failures

Discussion count flow (DiscussionCountService)

Data sources

DiscussionCountService uses NIP-45 COUNT queries to count comment events across relays. It requires a Nostr client that exposes:

• nostrClient.pool (relay pool)
• nostrClient.countEventsAcrossRelays(filters)

Filters & event kinds

The service builds COUNT filters based on the current video metadata. The base event kind is COMMENT_EVENT_KIND (video comment kind). Filters include:

• #E (root event id)
• #A (address pointer from buildVideoAddressPointer(video))
• #I (root identifier / videoRootId)
• #K (root kind)
• #P (root author)

It always tries an #E filter first, then constructs an uppercase-tag filter that uses the best available pointer information, and finally a lowercase #A filter when available.

Caching

Counts are cached in-memory per video id during a session:

• videoDiscussionCountCache stores resolved counts.
• inFlightDiscussionCounts deduplicates concurrent requests.

There is no persistence beyond the runtime session.

Polling & refresh

Discussion counts are not polled on a timer. They refresh when the UI asks for them (typically after feed renders). The application triggers refreshes via app.refreshVideoDiscussionCounts, which is wired into video list rendering flows.

UI surfacing

The service updates DOM nodes directly using data attributes:

• Root node: [data-discussion-count="<video id>"]
• Count value: [data-discussion-count-value]

The element’s data-count-state is set to:

• pending while a COUNT request is in flight
• ready after a successful response
• unsupported or error when COUNT is unavailable or fails

If relay support is missing, the service sets a tooltip (title) explaining that COUNT is unsupported.

Telemetry/logging

Failures to fetch counts are logged through the injected logger (default devLogger.warn), and the UI falls back to the error/unsupported state rather than throwing.