bitvid/docs/historyView-overview.md

# Overview: `js/historyView.js`

## Summary
The `js/historyView.js` module is responsible for rendering and managing the watch history user interface. It handles loading history data (via a preferred feed engine or a service fallback), formatting it chronologically, displaying moderation states for videos, and allowing users to interact with history items (play, view channel, or remove).

It fits into the application as a view-layer controller. It retrieves application state and services via `getApplication()` and relies heavily on `watchHistoryService` for data and NIP-07/NIP-46 signers (via `nostrClientFacade`) to identify the user.

## Public Surface

### `buildHistoryCard({ item, video, profile, variant })`
Creates a DOM article element representing a single watch history entry.
- **Parameters:**
  - `item` (Object): The history item metadata (contains `pointerKey`, `watchedAt`, etc.).
  - `video` (Object): The associated video object.
  - `profile` (Object): The creator's profile object.
  - `variant` (String): UI variant (e.g., "compact").
- **Returns:** `HTMLElement` (an `<article>` tag).
- **Side effects:** Registers the created card in a local `historyCardRegistry` to manage moderation states dynamically.

### `createWatchHistoryRenderer(config = {})`
Factory function that creates a stateful renderer object to manage the history grid.
- **Parameters:**
  - `config` (Object): Overrides for DOM selectors, fetch strategies, and batch sizes.
- **Returns:** An object with lifecycle methods (`init`, `ensureInitialLoad`, `refresh`, `loadMore`, `destroy`) and event handlers (`handleRemove`).
- **Side effects:** Attaches global event listeners for moderation updates (`video:moderation-override`, `video:moderation-block`), DOM event listeners for clicks on the grid, and Intersection Observers for infinite scrolling.

### `initHistoryView()`
Entry point intended to be called when the watch history page/view is initialized.
- **Returns:** `Promise<void>`
- **Side effects:** Attaches an info popover to `#historyInfoTrigger` and calls `init()` on the default `watchHistoryRenderer`.

## Main Execution Paths

1. **Initialization (`initHistoryView` -> `renderer.init`)**
   - Resolves DOM elements via selectors.
   - Attaches event listeners (click handlers for actions, intersection observer for load more).
   - Subscribes to `fingerprint` updates from `watchHistoryService` and moderation events from `document`.
   - Checks feature flags (sync enabled, local only) to update the feature banner.
   - Triggers `refresh(force: true)` to fetch data.

2. **Fetching Data (`loadHistory`)**
   - Calls `fetchHistory` (which attempts the `watch-history` feed engine first, falling back to `watchHistoryService`).
   - Normalizes the retrieved items (`normalizeHistoryItems`), grouping and sorting by `watchedAt`.
   - Computes a `fingerprint` string to detect changes.

3. **Rendering Data (`renderInitial` -> `renderNextBatch`)**
   - Clears the existing grid.
   - Slices the normalized items based on `batchSize`.
   - Hydrates the batch (applies moderation decorators).
   - Groups items by day (Today, Yesterday, Date) and appends `buildHistoryCard` results to the DOM.

4. **User Interactions (Grid Click Handler)**
   - Catches click events bubbling up from the grid.
   - Dispatches based on `data-history-action`:
     - `"play"`: Calls `app.playVideoWithFallback()`.
     - `"channel"`: Calls `app.goToProfile()`.
     - `"remove"`: Calls `renderer.handleRemove()`, which removes the DOM node, updates the service, and optionally refreshes the view.

## Assumptions & Invariants
- Assumes the presence of a global application context accessible via `getApplication()`.
- Relies on DOM structure matching hardcoded selectors (e.g., `#watchHistoryGrid`, `#watchHistoryLoading`).
- Assumes `watchHistoryService` exposes `loadLatest`, `snapshot`, `subscribe`, and capability flags (`isEnabled`, `isLocalOnly`).
- Invariant: A card's moderation state is managed dynamically via `historyCardRegistry`; cards must be registered upon creation and cleaned up upon removal.

## Edge Cases & Error Paths
- **Feed Engine Failure:** If the primary feed engine fails or isn't registered, it gracefully falls back to a locally instantiated engine or directly to the `watchHistoryService`.
- **Empty/Disabled States:** Handles scenarios where history is empty or unsupported (e.g., guest users) by swapping visibility of grid, loading, and empty state containers.
- **Moderation Overrides:** Handles moderation overrides asynchronously. If an override fails, it resets the loading state of the override button and logs the error.

## Performance & Concurrency Considerations
- Infinite scrolling is implemented via `IntersectionObserver` to lazily render DOM elements in batches (`WATCH_HISTORY_BATCH_SIZE`).
- Uses `DocumentFragment` to batch DOM insertions during rendering.
- Prevents redundant renders by comparing the computed `fingerprint` of the item list before committing changes.

## When to Change
- Consider refactoring if the hardcoded DOM selectors become brittle during UI component migrations.
- Extract the complex moderation badge generation (`createHistoryCardBadge`, `applyHistoryCardModeration`) if moderation logic needs to be shared across other views (like feeds or search).

## Why it works this way
- The factory pattern (`createWatchHistoryRenderer`) allows the same logic to power the main page view and potentially smaller embedded views (like a modal variant) by passing different config selectors.
- Keeping a local `historyCardRegistry` prevents having to do expensive DOM queries to find and update video cards when moderation events (like blocking a user globally) occur.