bitvid/docs/performance-efficiency-plan.md

# BitVid Performance & Efficiency Plan

Status: **Stage 2 shipped; Stage 3 in progress — observer teardown shipped, probe cancellation next**

## Progress snapshot — 2026-07-26

The plan is being delivered as independent, test-gated slices on `unstable`.

### Shipped

- **Stage 0 foundation:** the opt-in local performance harness is available;
  it remains disabled unless the loopback-only storage flag is set.
- **Stage 1 complete:** localhost relay-request monitoring is explicit opt-in.
- **Stage 2 complete:** `ExploreDataService` is demand-created for For You and
  Explore, pauses outside active recommendation views, coalesces concurrent
  history/IDF refreshes, and no longer blocks cached For You rendering.
- **Stage 3 first slice:** card, URL-health, and grid-health observers are
  disposed when feed markup is replaced or unmounted.
- **Stage 7 first slice:** recommendation refresh bursts are coalesced into one
  active pass plus one follow-up; Most Zapped ordering has regression coverage.

### Remaining

- Capture and retain the complete Stage 0 baseline scenarios, including cache
  size, worker lifetime, probe counts, and browser CPU/RSS.
- Finish Stage 3 with owner-aware queue pruning and abort signals for URL and
  WebTorrent probes, then verify hidden-card reveal and fallback behavior.
- Finish Stage 7 with bounded, category-aware event-cache eviction and same-feed
  refresh coalescing without swallowing explicit refreshes.
- Implement Stage 5's service-worker update cadence and image-cache freshness
  policy after measuring warm-feed revalidation.
- Profile before changing Stage 4 (modal visuals) or Stage 6 (bundle/lazy
  loading); these remain unstarted and measurement-dependent.

### Current release evidence

- `5f439d68`: lazy recommendation indexes.
- `687f8c43`: lifecycle disposal, refresh coalescing, and Most Zapped ordering.
- `bb6614e3`: cache-first For You navigation rendering.
- Targeted regression suites and production builds pass for each shipped slice;
  the current remote tip is `origin/unstable` at `bb6614e3`.

## Goal

Reduce idle CPU, GPU, memory, relay traffic, and unnecessary network activity
without making feeds stale or weakening BitVid's Nostr-native recommendation
system.

BitVid must continue to ingest relevant notes, follows, zaps, watch events, and
moderation signals promptly. The optimization is about scheduling and bounded
work, not removing recommendation inputs or live feed updates.

## Baseline findings

Local observations on 2026-07-26 while serving the production build:

| Component | Observed load | Conclusion |
| --- | --- | --- |
| Static `serve dist` process | under 1% CPU, about 115 MB RSS | Not the heat source. |
| Browser main/renderer/GPU processes | renderer about 22% CPU, GPU about 7% CPU, renderer about 430 MB RSS | Primary area for profiling and improvement. |
| System memory | 24 GiB available; no swap in use | Not currently memory pressured. |

Code audit candidates:

- `ExploreDataService` starts for every session and refreshes watch-history tags
  every minute and tag-IDF every five minutes, even outside Explore/For You.
- `devReqMonitor.js` automatically patches WebSocket sends on localhost and
  wakes every two seconds. This is development-only but makes local testing
  noisier and more expensive than production.
- App startup registers/checks the service worker and explicitly calls
  `registration.update()` on every load.
- URL/torrent health checks can allocate media probes and WebTorrent tracker
  work; they must remain viewport-driven, bounded, and cancellable.
- The video-modal ambient background can perform recurring canvas draws while a
  video plays. It is a likely GPU hotspot and needs measurement before tuning.
- The image service-worker cache revalidates external images in the background;
  warm feeds can still cause many network/cache operations.

## Deeper system audit

This table separates verified mechanics from hypotheses. It is deliberately not
a list of features to remove: every item has a product boundary that must stay
intact.

| System | Verified finding | Risk / opportunity | Planned boundary |
| --- | --- | --- | --- |
| Nostr subscriptions and feed loading | Feed loading deduplicates normal in-flight requests and active feeds need live relay updates. | Over-throttling would make Home, follows, zaps, and moderation stale. | Preserve subscriptions and event ingestion; coalesce only duplicate refresh/re-rank work. |
| For You / Explore indexes | `ExploreDataService` is constructed during bootstrap, clones the video set into a worker, refreshes history tags each minute and IDF each five minutes. Event, visibility, and timer paths can request the same broad work. | Unused views pay recurrent CPU, worker-message, and allocation cost. | Keep lightweight dirty/version signals live; create and refresh the worker only for an active or imminent recommendation view, with one serialized refresh per index. |
| Event persistence and relay cache | IndexedDB writes are differential and idle-scheduled, but the payload is built from the complete `allEvents` and tombstone maps; restore likewise rehydrates the complete unexpired cache. TTL expiry is 10 minutes, with no explicit record/byte budget. | Large relay sessions can raise startup, structured-clone/serialization, IndexedDB, and renderer-memory cost. | Measure actual record/byte growth first, then add an eviction budget that preserves active/latest, user-owned, watched, and moderation-relevant events. Never replace the cache with a smaller unscoped relay query. |
| URL liveness cards | The observer is viewport/prefetch-margin driven, and URL checks are deduplicated at controller level. Hidden-until-verified cards intentionally start an eager check so they can become visible. | A large hidden-card batch can still fill work queues; discarded cards cannot presently express cancellation through the generic observer. | Retain the reveal guarantee, but add queue cancellation, page/feed budgets, and primary-source-first fallback. |
| WebTorrent stream health | Torrent probes are globally queued (two at a time), cached, deduplicated, capped at four peer connections and destroy each probe torrent. A reusable probe client remains after first use. | The safeguards are good, but queue entries may outlive a discarded feed and a health badge can still pull WebTorrent into an otherwise hosted-video session. | Add cancellation/queue pruning and explicit health-probe telemetry before changing limits; evaluate lazy WebTorrent loading separately from playback correctness. |
| WebTorrent startup bundle | The WebTorrent facade imports the roughly 212 KB minified implementation at module evaluation time. | Browsers can download/parse a torrent stack before the viewer plays or probes a torrent. | Measure module transfer/parse on cold Home, then introduce a lazy implementation loader only if hosted playback and health-badge behavior remain correct. |
| Service worker and external images | Boot checks existing registrations and calls `update()`; the image strategy returns cache quickly but starts a network revalidation for each cached image request. | Warm feeds can produce avoidable fetch/cache churn even when their images are already fresh. | Keep deploy reliability and bounded cache trimming; add a tested freshness policy rather than disabling updates or image caching. |
| Modal visuals and UI rendering | The ambient-video helper schedules animation-frame callbacks while active, although its current modal wiring needs trace validation. Feed rerenders replace card DOM and attach health observers again. | Canvas work may be a GPU cost; observer lifecycle needs a retained-node/queue profile before calling it a leak. | Instrument active animation callbacks and observed-card counts. Tune only if a playback trace shows material cost; add explicit observer teardown if retained cards are confirmed. |
| Development diagnostics | On localhost, `devReqMonitor` patches WebSocket sends and wakes every two seconds. | It contaminates local CPU and relay measurements but is not a production heat source. | Make it opt-in so normal development reproduces production behavior. |

### What is *not* a candidate for removal

- Nostr notes, follows, zaps, reactions, watch events, and moderation signals
  remain the raw material for feeds and recommendations.
- Active-feed subscriptions, source fallback, WebTorrent playback, and the
  stale-while-revalidate cache remain product capabilities.
- A timer or worker is changed only after a trace identifies it as active in a
  relevant scenario; no optimization is justified merely because code exists.

## Design rules

1. **Nostr ingestion stays live.** Keep subscriptions for active feeds and
   logged-in viewer context. New relevant events update local indexes promptly.
2. **Expensive work is demand-driven.** A new event marks an index stale; it
   does not force a whole recommendation rebuild until the associated feed is
   active or about to become active.
3. **Inactive views do no recurring work.** Hidden tabs, closed modals, and
   inactive feed views must pause timers, observers, and probe queues.
4. **Every background task has a bound.** Cap concurrency, use TTL caches,
   cancel obsolete work, and destroy listeners/workers when their feature is no
   longer in use.
5. **No silent product degradation.** Feed freshness, source fallback,
   WebTorrent playback, moderation, and user-visible recommendation inputs are
   acceptance criteria in every stage.
6. **Use cancellation, not just lower limits.** A task belonging to a removed
   card, closed modal, inactive feed, or hidden document must be removable from
   the queue; lowering concurrency alone can leave obsolete work running.
7. **Measure both wall time and retained state.** A faster task that retains a
   large worker snapshot, observer target, cache record, or probe client is not
   an efficiency win.
8. **Preserve discovery boundaries.** A lifecycle or batching optimization must
   use the same scoped relay/source selection for historical fetch and live
   subscription. Never make a feature appear faster by querying a smaller,
   unrelated source set and silently omitting valid user data.
   Every affected feature needs a regression fixture containing data available
   only through its scoped historical source and data arriving live afterward.

## Measurement harness (Stage 0) — foundation shipped; baseline capture remains

Create a local-only, opt-in performance harness. It must be disabled by
default and absent from production behavior.

Implemented baseline surface: on `localhost`, `127.0.0.1`, or `::1`, set
`localStorage.__bitvidPerformanceHarness__ = "1"` and reload. The console API
`window.__bitvidPerformance.snapshot()` reports bounded long-task, resource,
navigation, heap (when supported), mark, and manually supplied gauge data.
`mark`, `setGauge`, and `increment` are available for later stage-specific
instrumentation. The harness does not initialize on a public host, even if the
storage key is set.

### Measurements

- Long tasks via `PerformanceObserver`.
- JS heap, where the browser exposes it.
- Active workers, timers, observers, URL media probes, torrent probes, and
  relay subscription/request counts.
- Feed refresh duration, item count, and recomputation reason.
- Recommendation-index snapshots: input size, queue/coalescing count, worker
  lifetime, and stale-to-fresh latency.
- Event-cache record count, estimated serialized bytes, restore duration, IDB
  writes/deletes, and protected-versus-evicted record categories.
- Browser process CPU/RSS sampled externally during test scenarios.

### Standard scenarios

1. Cold load to Home; wait 60 seconds without interaction.
2. Scroll through two feed pages, then stop.
3. Open and close Profile; remain on Home.
4. Open Explore and For You; receive a new relevant note, follow, zap, and
   moderation update.
5. Open hosted playback, then close it.
6. Open torrent-backed playback, then close it.
7. Background the tab for two minutes and restore it.
8. Load an inbox with both legacy NIP-04 and historical NIP-17 conversations,
   then receive a live NIP-17 message; verify all conversations are present.

### Stage gate

Record baseline results before any optimization. The harness itself must have a
test proving it does not initialize unless its explicit local debug flag is
set.

## Stage 1 — Make localhost relay monitoring explicit — complete

### Change

Change `js/devReqMonitor.js` so it only installs when
`localStorage.__bitvidReqMonitor__ === "1"` on a loopback host. Do not
auto-enable merely because the host is localhost, and never permit the monitor
on a public host.

### Why

It patches every WebSocket send, parses REQ frames, and has a two-second timer.
It is useful during a relay-storm investigation but should not distort ordinary
local performance testing.

### Tests and acceptance

- With the flag off: no WebSocket patch and no monitoring timer.
- With the flag on: existing relay-storm warnings still identify REQ kinds.
- No production host can enable it without the explicit local flag.
- Compare idle local CPU/long-task baseline before and after.

Implemented with `isRequestMonitorEnabled()` / `installRequestMonitor()` and
regression coverage for disabled localhost, enabled loopback, and public-host
rejection. To use it during a targeted local relay investigation, set
`localStorage.__bitvidReqMonitor__ = "1"` and reload; remove the key or set it
to any other value for normal profiling.

### Rollback

One isolated commit; restoring the previous activation condition restores the
old diagnostic behavior.

## Stage 2 — Lazy recommendation indexes

Implemented: `ExploreDataService` is no longer created during
ordinary bootstrap. Home/Profile sessions therefore create no recommendation
worker or recommendation intervals. Opening For You or Explore creates and
activates the service; events received while inactive mark it dirty and are
included in the activation refresh. Concurrent history/IDF signals share one
running rebuild and retain one forced follow-up pass. Focused lifecycle,
feed-coordinator, production-build, and browser navigation checks pass; manual
For You/Explore validation confirmed normal recommendations and responsive Home.

### Change

Do not initialize `ExploreDataService` globally in application bootstrap.
Start it when Explore or For You is first opened, and stop/pause its intervals
when neither view is active or the document is hidden.

Keep Nostr ingestion active. Incoming videos, watch-history changes, follows,
zaps, preference changes, and relevant moderation changes mark the associated
index stale. Refresh the index immediately when its feed is visible, or just
before rendering it.

Use a small lifecycle coordinator with these states: `not-created`, `idle`,
`dirty`, `refreshing`, and `paused-hidden`. A refresh request while refreshing
sets one follow-up dirty bit rather than starting another full worker message.
Snapshot only the minimal fields required by the worker and record snapshot
size in the local-only harness.

### Why

The current worker receives cloned video/history data on a one-minute and
five-minute cadence even when the viewer is using Home, Profile, or a modal.

### Tests and acceptance

- Home/Profile-only session creates no Explore worker or recommendation
  intervals.
- Opening Explore or For You initializes the worker once and produces the same
  ranking inputs as today.
- A new relevant note, follow, watch event, zap, or moderation update is
  reflected on the next active-feed refresh.
- Backgrounding the tab pauses the intervals; restoring it performs one bounded
  catch-up refresh.
- Existing For You tiering, Trending, and recommendation tests remain green.
- Timer, visibility, and event triggers coalesce into at most one active and
  one follow-up index calculation per index.

### Rollback

Feature-scoped lifecycle change behind a small coordinator boundary; restore
eager initialization if feed freshness regresses.

## Stage 3 — Bound source-health work to visible cards

**Progress:** first lifecycle-disposal slice shipped in `687f8c43`; queue
ownership, cancellation, and abortable active probes remain.

### Audit findings (2026-07-26)

- `createCardObserver` retains an `IntersectionObserver` per grid container but
  has no disposal API. `VideoListView.render()` replaces card DOM without
  disconnecting the old observer, so detached cards can stay observed.
- `gridHealth` has a globally bounded, priority-ordered torrent queue, but its
  queued jobs have no owner/cancellation handle. A discarded card can therefore
  still start a real tracker/WebRTC probe.
- URL health uses an independent observer and video-probe wait queue with the
  same missing ownership boundary. Its fetch timeout aborts only on timeout,
  not when the card/grid disappears.

Implementation order: add disposable observer registrations and call them from
grid replacement/unmount; associate queued jobs with card owners and prune jobs
when their last owner disappears; finally pass an abort signal into active URL
and torrent probes. Cache/in-flight deduplication stays shared so one visible
card never cancels work still needed by another visible card.

### Change

Keep the existing viewport/preload observer and current two-at-a-time torrent
queue. Add an abort/cancellation token through URL probes and queue pruning for
WebTorrent work when cards leave the feed or its container is discarded. Hidden
cards that must be verified before reveal receive a small, observable per-feed
budget rather than an unbounded eager batch. Preserve deduplication by
event/source and separate positive/negative TTLs.

Do not probe every alternate mirror eagerly. Probe the primary source first and
only test an alternate when the primary is unavailable or playback needs it.

### Why

Media-element probes and WebTorrent tracker probes are useful for accurate
source badges and fallback, but are among the most expensive background tasks.

### Tests and acceptance

- Scrolling a large feed never exceeds the configured URL/torrent concurrency
  limit.
- Off-screen and removed cards do not start or retain probes.
- Cached results render badges without a second request.
- Dead URL still falls back to a working mirror or WebTorrent source.
- Closing a feed/modal tears down pending health work.
- Hidden-card verification is bounded and still reveals cards whose source
  proves healthy.

### Rollback

Keep the existing probe implementation available behind the observer boundary
until playback and badge tests pass on Chromium and Firefox.

## Stage 4 — Reduce playback visual overhead

### Change

First trace whether the video-modal ambient canvas is actually wired into the
current modal path, then profile it. If it appears in the hot path,
replace the free-running animation loop with `requestVideoFrameCallback` where
available, a capped fallback cadence, and automatic disablement for
`prefers-reduced-motion` or a low-power preference.

The effect must exist only while the modal video is actively playing and be
fully torn down on pause, close, source change, and hidden document.

### Tests and acceptance

- Hosted and torrent playback remain visually correct.
- Pause/close/source-change cancel all animation callbacks and observers.
- Background tabs make no canvas draws.
- Reduced-motion mode does not attach the visual effect.
- Compare renderer/GPU CPU while playing the same short clip before and after.

### Rollback

Keep the visual treatment behind a feature/config gate until manual playback QA
is complete.

## Stage 5 — Service-worker and image-cache cadence

### Change

- Keep service-worker registration, but avoid forcing a full update check on
  every application boot. Use normal browser update cadence or a bounded
  version/age policy.
- Add an image-cache freshness window so a cached external image is served
  immediately and only revalidated when stale or needed by a visible card.

### Tests and acceptance

- A fresh deploy still activates normally without a hard refresh.
- Rollback deploy still works with hashed assets and normal reload.
- Cached thumbnails/avatars paint immediately.
- Warm feed loads do not revalidate every external image at once.
- Image cache remains bounded and recovers safely from quota failures.

### Rollback

Keep cache format/version semantics intact; any regression can revert the
freshness policy without deleting user-visible image caching.

## Stage 6 — Bundle and feature activation review

### Change

Start with the WebTorrent implementation, because it is currently imported by
the facade at module evaluation time. Review other heavy feature modules only
from measured cold-load transfer/parse evidence. Dynamically import at first
use where safe: profile management, DMs, upload, torrent playback, and
feature-specific Nostr helpers. Do not defer the active feed, authentication,
or basic playback path in a way that creates visible delay.

### Tests and acceptance

- Initial Home load has fewer transferred/parsed bytes.
- Opening each deferred UI initializes once and still works offline/static-hosted.
- No feature code is fetched when its flag is off.
- Build artifact, cache, E2E, and visual tests pass.

## Stage 7 — Cache budget and feed-refresh coalescing

**Progress:** recommendation-index refresh coalescing shipped in `5f439d68`;
the event-cache budget and full same-feed refresh coordinator remain.

### Change

After Stage 0 records real cache growth, add explicit event-cache record and
byte budgets plus category-aware eviction. Protect currently active feed items,
the newest active version of an event, local/user-owned content, recent watch
history pointers, and moderation state needed for the current viewer. Evict
older, unreferenced relay data first. In the feed coordinator, coalesce
same-feed refresh requests and record the initiating reason, without delaying
an explicit user refresh.

### Why

The cache is already incremental at write time, but its full-map snapshot and
restore behavior can become expensive as a long-lived relay session grows.
Coalescing protects against several valid live signals causing redundant
render/rank passes together.

### Tests and acceptance

- Seeded oversized caches restore only the protected/bounded record set and
  issue normal scoped relay fetches for missing items.
- Feed data, deletions, replacements, moderation decisions, and recent watch
  history produce the same visible result before and after eviction.
- A burst of equivalent refresh signals produces one running refresh plus, at
  most, one follow-up; an explicit refresh is never swallowed.
- IndexedDB and localStorage fallback behavior remain covered.

### Rollback

Version cache metadata and keep the current restore format readable. Reverting
the budget must not erase cached user data.

## Release procedure

Each stage ships independently. The recommended order is Stage 0, Stage 1,
Stage 2, Stage 3, Stage 7, Stage 5, then the measurement-dependent visual and
bundle work (Stages 4 and 6):

1. Capture baseline and define the expected improvement.
2. Make one focused implementation commit.
3. Run the stage's targeted tests plus relevant browser QA.
4. Compare measurement results to the baseline.
5. Run `npm run build` and the applicable design checks.
6. Promote only when no feed freshness, playback, moderation, or cache
   regression is observed.

Do not combine stages in one commit. A failed stage is reverted independently
without discarding validated improvements from earlier stages.