bitvid/docs/shorts-plan.md

# Shorts (short-form vertical video) — Dev Plan

TODO ref: **#16b** in `todo/TODO_2026-06-20_pre-launch.md`.
Status: **DECISIONS LOCKED — ready to build** (D1–D5, D7, D8 locked; D6 is a
build-time implementation choice). Not started.

Short-form vertical video is **NIP-71 kind 22** (the short counterpart to kind 21
normal video), plus the addressable short kind **34236**. It is a *different*
feature from live streams (#16, NIP-53) — do not conflate them.

The good news: **bitvid already ingests kind 22.** The inbound NIP-71 adapter
(`js/nostr/nip71IngestAdapter.js`, `NIP71_KINDS = {21, 22, 34235, 34236}`) parses
short-form notes today and they already flow into the main feed. So this feature
is **not new ingest code** — it is (a) a single `isShort` discriminator (native
marker / foreign kind), (b) a dedicated **Shorts sidebar tab** with a vertical
UI, (c) a feed source that lists only shorts, (d) **exclusion of shorts from the
main/discovery feeds** (DECISION 3), and (e) a **publish-side content-type
selector** + native short marker (DECISION 7) so bitvid creators can post shorts.
Everything ships behind a config flag that leaves **no trace** when off.

---

## Decisions needed

> **DECISION 1 — Discovery scope. ✅ LOCKED: Option A (same whitelist scope).**
> Shorts pulls from the same whitelisted/WoT authors as the main feed and reuses
> the existing render-time moderation filter — no new moderation surface, no extra
> relay fan-out. Rationale (maintainer): the existing moderation + ingest system
> is already good; keep Shorts consistent with it. A broader/Explore-style scope
> can be added later if desired.

> **DECISION 2 — Moderation / NSFW. ✅ LOCKED: Option A (inherit, no special
> handling).** Shorts pass through the same render-time `filterVideos` path as
> every grid (event blacklist / author blacklist / WoT mute / NSFW / private).
> No short-specific moderation. Note: the NSFW gate already *excludes* NSFW from
> users who haven't opted in, so the immersive autoplay feed carries no extra
> NSFW-exposure risk — opted-in users chose to see it, everyone else never
> receives it. Rationale (maintainer): no reason to treat shorts differently.
> **One agreed safeguard:** even for opted-in users, an **NSFW short does NOT
> autoplay** in the immersive feed — it stays blurred/paused with a tap-to-play
> affordance (autoplay resumes on the next non-NSFW short). This is the only
> short-specific behavior; all *filtering* still inherits the shared pipeline.

> **DECISION 3 — Do shorts also appear in the main feed? ✅ LOCKED: Option B
> (Shorts tab ONLY; excluded from the main/discovery feeds).** Rationale
> (maintainer): shorts should not dilute the main feed at all — the Shorts tab is
> their only home.
> **Build implication:** add an `isShort` **exclusion** to the general feeds —
> Recent, For You, Explore, Trending, Kids — so kind-22/short videos never render
> there (they currently do via NIP-71 ingest). The Shorts feed is the inverse
> filter (`isShort` only). This touches each feed source/sorter, so verify no
> feed regressions (couples with #20/#21 feed-identity work).
> **Sub-point (recommend, not blocking):** a creator's shorts SHOULD still appear
> on their **Channel profile** page (it's their full catalogue) and in
> **Subscriptions** is TBD — default: exclude from Subscriptions too (it's a
> discovery feed), keep on Channel profile. Confirm during Phase 1.

> **DECISION 4 — What counts as a "short"? ✅ LOCKED: Option A (kind is the
> definer).** A video is a short iff its event kind is **22** or **34236**;
> kind 21/34235 = regular. No aspect-ratio heuristic — the publisher's declared
> kind decides. Rationale (maintainer): shorts are typically vertical, but the
> protocol kind is the source of truth; a vertical video mis-published as regular
> just renders in the 16:9 card (thumbnail center-cropped via `object-fit:cover`;
> the player letterboxes it via `object-fit:contain`, never distorts) and stays in
> the main feed — the publisher's choice. Aspect-ratio fallback can be added later
> if too many real shorts leak in as kind-21.

> **DECISION 5 — UI ambition for v1. ✅ LOCKED: Option C (phased).** Phase 1 ships
> the grid + portrait card + the main-feed exclusion (DECISION 3) so shorts are
> corralled into their own tab immediately (the maintainer's priority); Phase 2
> adds the full immersive autoplay/swipe feed later. Front-loads "shorts out of
> the main feed," defers the heavier immersive build.

> **DECISION 6 — Card design.** Shorts need a **new portrait (9:16) card** — the
> existing `js/ui/components/VideoCard.js` hardcodes a **16:9 landscape** media
> ratio (`ratio-16-9`), so it can't render shorts correctly as-is. Two options:
> (a) a **new `ShortCard` component** (portrait thumbnail, compact meta, its own
> `data-testid`); or (b) a **portrait "mode"/variant of `VideoCard`** driven by a
> flag (e.g. `variant: "short"` swapping the ratio class + layout).
> *Recommendation: (b) a portrait variant of `VideoCard` if the internals are
> clean enough to parameterize the ratio + layout — it inherits thumbnail
> binding, moderation badges, engagement controls, and the ⋯ menu for free;
> fall back to (a) a dedicated `ShortCard` only if forcing a variant makes
> `VideoCard` unwieldy or pushes it past its size cap.* Either way this is a
> **first-class deliverable**, not an afterthought — the grid can't ship without it.

> **DECISION 7 — Publish side: content-type selector + native short marker.
> ✅ AGREED (maintainer-proposed).** Add an **upload-modal content-type selector**
> (Regular video ⟷ Short) with **visual + text helpers** so creators pick the
> right type and understand placement — e.g. landscape/portrait icons + copy like
> *"Shorts appear only in the Shorts tab, not the main feed."* This is not just
> UX: bitvid's canonical event is **kind 30078** (not 21/22), and the schema has
> **no short marker today** (short is only inferred from dimensions at mirror
> time). So this decision also adds an explicit **`isShort` (or `format:
> "short"`) field to the v3 content schema**, set by the selector, which (a) lets
> the Shorts feed filter + main-feed exclusion catch bitvid-native shorts, and
> (b) forces the NIP-71 mirror to kind **34236**. Detection becomes: a video is a
> short iff `kind ∈ {22,34236}` (foreign/ingested) **OR** `isShort === true`
> (bitvid-native). *Open sub-choices for build time: default selection (recommend
> "Regular"), whether to auto-suggest "Short" when the uploaded file is portrait,
> and exact copy/icons.*

> **DECISION 8 — Native short representation. ⏳ LEANING: marker on kind 30078
> (both options mirror to 34236).** Hard requirement (maintainer): a native short
> MUST keep bitvid's WebTorrent advantage AND mirror to the standard NIP-71 short
> kind via the existing mirror system. Both viable options satisfy that — they
> produce the *same external result* (a WebTorrent-rich native event + a standard
> **34236** mirror carrying the magnet via `imeta`):
>
> - **Option 1 (recommended) — kind 30078 + `isShort` marker.** Native short = a
>   normal bitvid video flagged short; the *existing* mirror emits 34236. No new
>   kind. Reuses 100% of the publish/edit/delete/moderation/view-count/zap/mirror
>   pipeline (all keyed on 30078). Least code, least risk.
> - **Option 2 — a distinct bitvid-short kind that mirrors to 34236.** A separate
>   kind number for rich native shorts + the mirror to 34236 for interop.
>   *Trade-off:* the external result is identical to Option 1, but the distinct
>   *native* kind is non-standard (only the 34236 mirror is recognized by other
>   clients) and it forks every pipeline that's currently keyed on 30078 — i.e.
>   more work for the same outcome. A new kind buys a distinct native kind number;
>   it does **not** buy WebTorrent or interop that Option 1 lacks.
>
> Net: Option 1 already delivers "WebTorrent + mirror to the standard kind"
> without minting a kind. Only pick Option 2 if a distinct native kind number is
> itself a requirement.
>
> **✅ LOCKED: Option 1 (marker on kind 30078), provided shorts are reliably
> distinguishable.** They are: a single `isShort` boolean discriminates them
> everywhere — set from the `isShort`/`format:"short"` content field for native
> videos and from `kind ∈ {22,34236}` for ingested ones (see Field mapping). The
> Shorts feed filters `isShort === true`; the main feeds exclude it.

---

## Config flag (off = no trace)

Add `FEATURE_SHORTS` to `config/instance-config.js` (default `false`), threaded
through `js/config.js` → `js/constants.js` exactly like `FEATURE_NIP71_INGEST`.

When the flag is off, **all** of the following must be absent (the "as if it were
never added" requirement):
1. **Sidebar tab** — the Shorts link is not rendered in `components/sidebar.html`
   (not merely `hidden`).
2. **Feed registration** — `FEED_TYPES.SHORTS` is not registered in
   `js/app/feedCoordinator.js` (no pipeline, no sorter).
3. **Subscription/source** — no shorts-specific relay subscription is created.
4. **Route** — `#view=shorts` falls back to the default view (a stale bookmark
   can't resurrect the tab).
5. **Publish UI** — the upload-modal content-type selector (DECISION 7) is not
   rendered; uploads are plain regular videos exactly as today.
6. **Management UI** — no Shorts sub-tab in profile → My Videos (see below).
7. **Config surface** — the flag is the only footprint.

---

## Publish & management UI (flag-gated)

Both the publish and management surfaces must obey "off = no trace" (points 5–6
above), and reuse patterns already in the app.

- **Upload modal — content-type selector (DECISION 7).** Regular ⟷ Short, with
  visual + text placement helpers ("Shorts appear only in the Shorts tab").
  Rendered only when `FEATURE_SHORTS` is on; otherwise uploads are plain regular
  videos exactly as today.
- **Profile → My Videos — sub-tabs.** Reuse the **admin-pane sub-tab toolbar
  pattern** just shipped (`ProfileAdminController` sub-tabs) to split My Videos
  into **Videos / Shorts / Live** sub-tabs for easier content management. Each
  sub-tab appears **only when its feature flag is on**:
  - `FEATURE_SHORTS` off → no Shorts sub-tab.
  - Live sub-tab is tied to **publishing** live (**#16c** / `FEATURE_LIVE_PUBLISH`),
    NOT ingest (#16) — with ingest-only there is nothing of the user's to manage,
    so no Live sub-tab.
  - **All flags off → no sub-tab bar at all**, just the plain My Videos list
    exactly as today (true "no trace").
  - Videos sub-tab lists regular bitvid/NIP-71 videos (excludes `isShort`);
    Shorts sub-tab lists the user's `isShort` videos.

## Field mapping — detecting a "short"

Per DECISION 4 + 7 (locked), `isShort` is derived from **kind for foreign/ingested
videos** and from an **explicit marker for bitvid-native videos** (kind 30078):

| Signal | Applies to | Meaning |
|--------|-----------|---------|
| `kind === 22` | ingested foreign | NIP-71 regular short |
| `kind === 34236` | ingested foreign | NIP-71 **addressable** short |
| `isShort` / `format:"short"` in kind-30078 content | **bitvid-native** | set by the upload-modal content-type selector (DECISION 7) |
| `imeta dim` height > width | (future fallback) | portrait aspect; **not** used in v1 (DECISION 4) — kept only as a possible later fallback |

Plan: surface a single `isShort` boolean on the bitvid video object —
`nip71IngestAdapter.js` sets it from the source kind (it already tracks kind);
the native publish path sets it from the new content-schema field. The Shorts
feed filters `isShort === true`; the main feeds exclude `isShort === true`
(DECISION 3). No re-fetching needed.

---

## Architecture

Reuses the existing feed engine + ingest; new pieces are thin.

- **Flag:** `FEATURE_SHORTS` (instance-config → config → constants).
- **Feed type:** add `SHORTS: "shorts"` to `FEED_TYPES` (`js/constants.js`).
- **Feed source/registration:** register `FEED_TYPES.SHORTS` in
  `js/app/feedCoordinator.js`, sourced from the already-populated active-video
  cache filtered to `isShort` (per DECISION 1, scoped to the same authors as the
  main feed). A dedicated sorter can be chronological or reuse the For-You scorer
  — TBD, likely chronological for v1.
- **Sidebar tab:** add a Shorts link in `components/sidebar.html`, rendered only
  when the flag is on.
- **View:** `views/shorts.html` (a portrait-oriented grid container).
- **Card design (new):** a portrait **9:16** card — either a `variant: "short"`
  mode of `js/ui/components/VideoCard.js` (which is currently 16:9 / `ratio-16-9`)
  or a dedicated `ShortCard` (DECISION 6). Portrait thumbnail, compact title +
  author, reuse of thumbnail binding, moderation badges, engagement + ⋯ menu. New
  design tokens if needed (existing `--video-card-*` tokens live in
  `css/tokens.css`). A distinct `data-testid` for e2e selectors.
- **Player UI:** v1 opens a short in the existing player modal with a portrait
  layout; v2 adds a full-screen vertical swipe/next feed.
- **Diversity:** apply the existing `spreadAuthors` pass (feed sorters) so the
  Shorts tab doesn't cluster by creator, consistent with For You / Trending.

---

## Short-form UX best practices (researched July 2026)

Short-form is a **mobile-first** format (~70%+ of social video is watched on
phones, held vertically), but bitvid is a desktop-capable web app, so the Shorts
experience must be **responsive** — the same feed, two presentations. Sources at
the bottom of this doc.

### The immersive feed (both platforms)
- **One short at a time, full-height 9:16**, not a scroll-list of small cards.
  The grid (Phase 1) is the *entry point*; tapping/clicking a short drops into an
  immersive one-at-a-time feed (Phase 2).
- **Autoplay + loop.** The active short autoplays and loops. Browser autoplay
  policy requires **muted autoplay** — so start muted with an obvious unmute, and
  persist the user's mute choice across shorts. **Exception (agreed):** NSFW-
  flagged shorts do **not** autoplay even for opted-in users — blurred/paused with
  tap-to-play (see DECISION 2).
- **Preload the next 2–3.** Buffer upcoming shorts in the background so advancing
  is instant. "If your platform shows a loading spinner between videos, you've
  already lost the session." (This is the single most-cited make-or-break detail.)
- **Overlaid chrome, safe zones.** Title/author bottom-left, an **action rail**
  bottom-right, controls over the frame — keep them inside 9:16 safe zones so they
  don't collide with the video edges.
- **Action rail** (bitvid mapping): **Zap** (bitvid's primary engagement, via the
  existing NWC/zap system — replaces the generic "like"), **Comment**, **Share**,
  and **author avatar + follow/subscribe**. Reuse the existing engagement + ⋯
  menu wiring.
- **Captions/muted-friendliness.** A large share of viewing happens muted at some
  point; surface captions when a short provides them and make the mute state
  obvious. (bitvid can't generate captions — show them when present.)
- **Accessibility:** respect `prefers-reduced-motion` (no auto-advance / disable
  scroll-snap animation), full keyboard support, focus management on advance.

### Mobile presentation
- **Full-screen** vertical player; **swipe up/down = next/previous**; tap =
  pause/play; the action rail sits on the right thumb-reach edge.

### Desktop presentation
- **Centered vertical player with letterboxed / blurred side panels** — never
  stretch a 9:16 short to fill a wide viewport (this is the YouTube-Shorts-on-
  desktop pattern).
- **Keyboard navigation is a real differentiator.** YouTube Shorts on desktop has
  notoriously weak keyboard support (users install extensions to get it). bitvid
  should ship it natively: **↑/↓ = prev/next short**, **Space = pause/play**,
  **M = mute**, **←/→ = seek** (or prev/next — pick one and document it), Esc =
  exit to grid.
- **Action rail beside the player** (to the right of the letterboxed video) rather
  than overlaid, since desktop has the horizontal room.
- Advance via scroll-snap (wheel/trackpad) **and** the arrow keys; a subtle
  next/prev affordance for mouse users.

### bitvid-specific notes
- Playback rides the existing URL-first + WebTorrent pipeline (`playbackService`);
  shorts are ordinary videos (native kind-30078 + `isShort`, or ingested
  21/22/34235/34236), so **no new transport**.
- **WebTorrent + autoplay caution:** an autoplaying scroll feed must NOT spin up a
  torrent swarm per short as the user flies past. In the immersive feed, prefer
  **URL-first for the active/preloaded shorts** and only fall back to WebTorrent on
  demand (e.g. when the URL fails, or the short is dwelt on) — otherwise scrolling
  seeds dozens of swarms and thrashes the connection budget. (Risks section.)
- Zaps (not likes) are the headline action — a genuine differentiator vs the
  incumbents that already exists in bitvid.
- View counts, watch history, comments, and zaps reuse the existing per-video
  machinery — shorts are just videos to those systems.
- Everything still flows through the render-time moderation filter (DECISION 2).

## Phases (each flag-gated from day one)

- **Phase 0 — Detection + flag (small).** Add `FEATURE_SHORTS` (off), the
  `isShort` content-schema field (DECISION 7), and `isShort` derivation (foreign =
  kind, native = marker) in the ingest adapter + mirror, with unit tests. No UI.
- **Phase 0b — Publish-side selector (small–medium, DECISION 7).** Upload-modal
  content-type selector (Regular ⟷ Short) with visual + text placement helpers;
  wires the `isShort` marker + forces mirror kind 34236. Lets bitvid creators
  actually publish shorts (without it, the Shorts tab only shows ingested foreign
  shorts).
- **Phase 1 — Tab + feed + portrait card + main-feed exclusion (medium).**
  `FEED_TYPES.SHORTS`, sidebar link, `views/shorts.html`, feed registration
  filtered to `isShort`, route gated by flag, and the **new portrait 9:16 card**
  (DECISION 6). **Per DECISION 3 (B):** add the `isShort` **exclusion** to the
  main/discovery feeds (Recent, For You, Explore, Trending, Kids; likely
  Subscriptions) so shorts never appear outside the Shorts tab — with regression
  checks on each feed. Opens in the standard player for now.
- **Phase 2 — Immersive vertical feed (medium–large).** The one-at-a-time
  responsive feed described in "Short-form UX best practices": muted autoplay +
  loop, **preload next 2–3** (no spinner between shorts), overlaid action rail
  (Zap/Comment/Share/follow), captions-when-present, `prefers-reduced-motion`
  handling. **Mobile:** full-screen + swipe up/down. **Desktop:** centered
  letterboxed player + **native keyboard nav** (↑/↓ prev/next, Space, M, Esc) +
  side action rail. Grid (Phase 1) remains the entry point.
- **Phase 3 — Polish.** Mute toggle persistence, per-tab empty states, captions
  surfacing, seek affordance, and the URL-first-for-autoplay WebTorrent guard.

---

## Moderation, whitelist & NSFW

Per DECISION 2 (locked: inherit): shorts pass through the same render-time
`filterVideos` path (blacklist event ids, author blacklist, WoT mute, NSFW gate,
private exclusion) as every other grid. No new moderation surface. The admin
per-event block list (#25) already applies to any event id, shorts included. The
**one** short-specific behavior is that NSFW-flagged shorts do not autoplay in the
immersive feed (tap-to-play), even for opted-in users — a playback rule, not a
filtering change.

---

## Risks / watch-items

- **Main-feed exclusion touches every feed (DECISION 3).** Adding the `isShort`
  exclusion to Recent / For You / Explore / Trending / Kids (and likely
  Subscriptions) is the riskiest part — a bug drops the *wrong* videos or lets
  shorts leak. Regression-test each feed; couples with the #20/#21 feed-identity
  work. A single shared `isShort` predicate (used positively by Shorts, negatively
  by the others) keeps it consistent.
- **A native short missing its marker leaks into the main feed.** Since native
  detection is the `isShort` content field (not aspect ratio), a bitvid short must
  reliably carry the marker on publish AND on edit/re-publish, or it reappears in
  the main feed. Cover publish + edit paths; the marker must round-trip through the
  mirror/auto-sync.
- **WebTorrent swarm storm in the autoplay feed.** Preloading + autoplaying a
  scroll feed over WebTorrent would spin up many swarms at once. Prefer URL-first
  for active/preloaded shorts; fall back to WebTorrent on demand (see Architecture
  → bitvid notes). Respect the existing connection budget.
- **Empty tab** — a whitelist-scoped source (DECISION 1) on a small instance may
  have few shorts; ship a clear empty state.
- **Search scope (sub-decision, defer to build).** Should shorts appear in
  search? They're excluded from the *browse* feeds (DECISION 3) but a user
  searching a creator/topic arguably still wants their shorts. Recommend: shorts
  remain searchable and open in the Shorts player context; confirm during Phase 1.

---

## Sources

- NIP-71 (video events; kinds 21/22 regular, 34235/34236 addressable).
- Existing code: `js/nostr/nip71IngestAdapter.js`, `js/nostr/nip71Mirror.js`,
  `js/app/feedCoordinator.js`, `js/feedEngine/sorters.js`, `components/sidebar.html`,
  `js/ui/components/VideoCard.js` (16:9 card to variant/replace).
- `docs/nip71-migration-plan.md` (dual-event model, short=34236 heuristic).
- Short-form UX research (July 2026):
  - [Top 10 Features Every Short Video App Needs in 2026 — Primocys](https://primocys.com/blog/top-10-short-video-app-features-2026/) (full-screen player, autoplay/loop, swipe-next, preload next 2–3)
  - [Short-Form Video Strategy 2026 — Teleprompter](https://www.teleprompter.com/blog/short-form-video-strategy) (9:16 mobile-first, overlaid chrome/safe zones, captions)
  - [Why Vertical Video Is Becoming the Default Format — Oyelabs](https://oyelabs.com/why-vertical-video-is-default-content-format/) (mobile share, vertical engagement)
  - [Keyboard shortcuts for YouTube — YouTube Help](https://support.google.com/youtube/answer/7631406) & [YouTube Arrow Keys Fix (Chrome Web Store)](https://chromewebstore.google.com/detail/youtube-arrow-keys-fix/hbnlngeljeofecndhmebgpgpccfnkgjb) (desktop Shorts keyboard-nav gap → do it natively)