From eca94a93cd4dc21876d0a7fe4955a5da35d613d0 Mon Sep 17 00:00:00 2001
From: Astro <coreyluke.cordwell@gmail.com>
Date: Sat, 13 Jun 2026 00:06:56 +1000
Subject: [PATCH 1/6] fix(021): feed-mode videos keep controls=false after
 source attach

VideoPlayer's attach effect ran video.controls = !prebufferOnly after the
JSX controls binding, overwriting feed mode's controls={false}. Extend the
011 suspension to that line and add controls to the effect deps.

Adds a native v.redd.it item plus a tiny playable mp4 to the E2E fixture so
the previously skipped chromeless and HAVE_CURRENT_DATA tests now execute.
Also stubs /api/reddit/search-subreddits and /api/reddit/related in E2E,
which still hit upstream and flaked runs with 403/429.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 frontend/src/components/VideoPlayer.jsx       |   4 +-
 frontend/tests/e2e/_helpers.js                |  29 +++++++++++
 .../tests/e2e/fixtures/subreddit-pics.json    |  39 +++++++++++++-
 frontend/tests/e2e/fixtures/tiny-video.mp4    | Bin 0 -> 1849 bytes
 issues/021-smoothness-fixes.md                |  49 ++++++++++++++++++
 5 files changed, 117 insertions(+), 4 deletions(-)
 create mode 100644 frontend/tests/e2e/fixtures/tiny-video.mp4
 create mode 100644 issues/021-smoothness-fixes.md

diff --git a/frontend/src/components/VideoPlayer.jsx b/frontend/src/components/VideoPlayer.jsx
index 1c31dbb..7a03ef3 100644
--- a/frontend/src/components/VideoPlayer.jsx
+++ b/frontend/src/components/VideoPlayer.jsx
@@ -459,7 +459,7 @@ const VideoPlayer = forwardRef(function VideoPlayer(
       video.muted = shouldStartMuted;
       video.playsInline = true;
       video.autoplay = autoPlay && !prebufferOnly;
-      video.controls = !prebufferOnly;
+      video.controls = !prebufferOnly && controls;
       video.poster = posterUrl || '';
 
       if (shouldUseCompanionAudio && companionAudio) {
@@ -536,7 +536,7 @@ const VideoPlayer = forwardRef(function VideoPlayer(
       }
       cleanupPlayers();
     };
-  }, [mp4Url, hlsUrl, dashUrl, sanitizedCompanionAudioUrls, hasAudio, sourceKind, posterUrl, autoPlay, loop, prebufferOnly, allowUnmutedAutoplay, preferredMuted, onMutedChange, onDiagnostics, reloadNonce, shouldUseCompanionAudio, directUrlOnly]);
+  }, [mp4Url, hlsUrl, dashUrl, sanitizedCompanionAudioUrls, hasAudio, sourceKind, posterUrl, autoPlay, loop, prebufferOnly, controls, allowUnmutedAutoplay, preferredMuted, onMutedChange, onDiagnostics, reloadNonce, shouldUseCompanionAudio, directUrlOnly]);
 
   if (prebufferOnly) {
     return <video ref={videoRef} playsInline preload="metadata" className={className} style={{ display: 'none' }} />;
diff --git a/frontend/tests/e2e/_helpers.js b/frontend/tests/e2e/_helpers.js
index 6a2f64f..5ac5aea 100644
--- a/frontend/tests/e2e/_helpers.js
+++ b/frontend/tests/e2e/_helpers.js
@@ -8,6 +8,7 @@ const subredditFixturePath = path.join(here, 'fixtures', 'subreddit-pics.json');
 const subredditFixture = JSON.parse(fs.readFileSync(subredditFixturePath, 'utf-8'));
 
 const MINIMAL_MP4_BODY = Buffer.alloc(0);
+const TINY_VIDEO_BODY = fs.readFileSync(path.join(here, 'fixtures', 'tiny-video.mp4'));
 
 export async function stubBackend(page) {
   await page.route('**/api/subreddit/**', async (route) => {
@@ -18,6 +19,24 @@ export async function stubBackend(page) {
     });
   });
 
+  // Ancillary Reddit endpoints still hit upstream and 403/429 under repeated
+  // runs, which flakes otherwise-deterministic specs. Stub them empty.
+  await page.route('**/api/reddit/search-subreddits*', async (route) => {
+    await route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ items: [] })
+    });
+  });
+
+  await page.route('**/api/reddit/related/*', async (route) => {
+    await route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ items: [] })
+    });
+  });
+
   await page.route('**/api/external/redgifs/*', async (route) => {
     if (route.request().url().includes('/stream')) return route.fallback();
     await route.fulfill({
@@ -34,4 +53,14 @@ export async function stubBackend(page) {
       body: MINIMAL_MP4_BODY
     });
   });
+
+  // The fixture's synthetic native-video item points here; serve a real
+  // playable clip so <video> can reach HAVE_CURRENT_DATA in playback tests.
+  await page.route('https://v.redd.it/e2enative001/**', async (route) => {
+    await route.fulfill({
+      status: 200,
+      contentType: 'video/mp4',
+      body: TINY_VIDEO_BODY
+    });
+  });
 }
diff --git a/frontend/tests/e2e/fixtures/subreddit-pics.json b/frontend/tests/e2e/fixtures/subreddit-pics.json
index 4a2e3ce..070059e 100644
--- a/frontend/tests/e2e/fixtures/subreddit-pics.json
+++ b/frontend/tests/e2e/fixtures/subreddit-pics.json
@@ -8,7 +8,7 @@
   "flair": null,
   "searchScope": "title",
   "after": "t3_1tnqcnp",
-  "count": 25,
+  "count": 26,
   "availableFlairs": [
     "Arts/Crafts"
   ],
@@ -48,6 +48,41 @@
       "isRedditHosted": false,
       "type": "video"
     },
+    {
+      "source": "reddit",
+      "id": "e2e_native_001",
+      "title": "[E2E fixture] native v.redd.it video for chromeless + playback tests",
+      "permalink": "https://www.reddit.com/r/test/comments/e2e_native_001/",
+      "author": "e2e_fixture",
+      "subreddit": "pics",
+      "createdUtc": 1779750825,
+      "score": 9999,
+      "numComments": 1,
+      "flair": null,
+      "nsfw": false,
+      "thumbnail": "https://placehold.co/600x400.png",
+      "mediaUrl": null,
+      "galleryItems": [],
+      "videoUrl": "https://v.redd.it/e2enative001/fallback.mp4",
+      "videoHlsUrl": null,
+      "videoDashUrl": null,
+      "videoHasAudio": false,
+      "videoAudioUrls": [],
+      "videoDurationSec": 1,
+      "videoSourceKind": "reddit",
+      "videoIsPreviewSource": false,
+      "canPlayFullAudioInApp": true,
+      "externalVideoProvider": null,
+      "externalVideoId": null,
+      "externalVideoEmbedUrl": null,
+      "externalVideoPageUrl": null,
+      "externalVideoPosterUrl": null,
+      "externalVideoWidth": null,
+      "externalVideoHeight": null,
+      "sourceHost": "v.redd.it",
+      "isRedditHosted": true,
+      "type": "video"
+    },
     {
       "source": "reddit",
       "id": "1tnp3ds",
@@ -1069,4 +1104,4 @@
       "type": "gallery"
     }
   ]
-}
\ No newline at end of file
+}
diff --git a/frontend/tests/e2e/fixtures/tiny-video.mp4 b/frontend/tests/e2e/fixtures/tiny-video.mp4
new file mode 100644
index 0000000000000000000000000000000000000000..104461d1a9b98f800532aaea83ea0fd7028cdb44
GIT binary patch
literal 1849
zcmah}-)kII6uz6-8bZ+qB1DOJYoqj`yP26y))+gGHH}87(1%(@gz?VI-OP07SMJ;-
zyG5xFqIvVJV9~ruOeqS!C_=FhzV#2Nfg-42D}p}SmuCIW>~6D$f|t2-etq9L=gzsi
zj4|HO?JUgGn6V*765A5%o*8E|CS$|j#A&+D7>nZdz=s@I!*>zC%Sw!%{q-LM?gRG1
zKJsDO5c;^Sm1rXPj&2q;hX;VYY*hQeI#B1Kbr-;)&DfOmbq+Zxqg)rBqEpH{((8HX
zT<nJeF&_H|&wc{#6YPy23uZa+Bh|~n)<a+Rb&}^{r^_PoBT1N2Ck~Sal=1brNIKZ|
zl;4d_`brXp7R8UOsfc&=(hs?IBj}KMe;|bUnuZ2RYcOZmvw&kSL#0it^u!t9YgWaY
ztC)ttqtI<xwV7_Pcu#aXkh4H7mV7qa`GrlaKwjHD{rrv77(9D~UT04&Uw*5^4hMh!
zcJtXA_wU^!?$J!-86>qqd)(Ek_l=+W4mPccTo>P;bi#}>N(d~DMRTFm=fCUiV}T<-
zW>m=Wp6uIXQoP6o`G4_(H;I~F!Q8LetHVwqcCi;D0sqh~$j7jc3~VYi=p!3v@lr@y
z=w<j<NO#TG0`l!x7LsDe2Ja8<oDx|^BYv>TVfT_gx1&=^__QwyGLkZeK{hZ*6OUoQ
z9%(3v8#wI5K%v{O4j<}tuHIhy<NEKr%imr;`4itg{@33$ZC>VHsw6jSvs_gztICa;
zIm2@e1ePlROuv41>DBTKub*E8(w80ri)q%5WJ7byFsfzCux8;5w9e+Ir#Ch>Ds=zT
zNF<e1txQvuN}%Him^9O2n&k7`6Rz-VljDxtRqjhSO1-9S&KvUv7m0}4xwMT|b>3*1
zW|ha%4rGhxYc8}Gc$T+8#oJN7ZB`7B@ZxdUlD<P3O)wlKk`-y2HSPr}jfDfM$+ePE
z6z0(8T64aqp?IsYZJ-6=UrZBeTjojA<PDK)C(D~*Mu={L)yzp7ja+KGY;heZFml`C
zQJOYI0K@6~OrA%fhhF*)gD0w};f1l#)JK?TsUiUo{BE?SMBDMwI1?JShfjpRzc4`x
z0F@w2Ly1`C_*kx!wV{VTYP*i`MMkG^9XAv?6$zCr&b1-Kl|Z|QrI}2el{7=N>&!rH
z$~JP_)~wM}9sDWTronShCemBe_KZPoDnXxA$vgmEdCr65Qe1hqry4xQk6Y5QVAxi*
zV(?WujBQkEP%}zgNYS!uFT#;)nb|Wu%rGQe2+R<<#46@b(_|mu1|O4~AF{E|-anhq
zSU1zpF5FUMcdnhg|H|<v<NQwJ`-$x~K%@05Q&Ii#y{m8jOqagC^>XXuONXwLUfL3R
z@zSI3b#?Co^!K43tzQXV`?4N<dS+y!v$ym4EPSK&t&f(*PQKLXGru4vp^;^qn3M&~
P9WWy>)6U-ZC!7BQ6X%+|

literal 0
HcmV?d00001

diff --git a/issues/021-smoothness-fixes.md b/issues/021-smoothness-fixes.md
new file mode 100644
index 0000000..8c7154a
--- /dev/null
+++ b/issues/021-smoothness-fixes.md
@@ -0,0 +1,49 @@
+# 021 — Smoothness fixes from the June 2026 audit
+
+Audit verdict: the grid is in good shape (virtualized, lazy images, reserved aspect ratios). The clunk concentrates in feed mode and startup. Four fixes, ordered by user-felt impact, each its own commit.
+
+## Scope
+
+### A. Feed-mode chromeless regression (P1, documented followup)
+
+`VideoPlayer.jsx:462` runs `video.controls = !prebufferOnly` inside the source-attach effect, after the JSX `controls={controls}` binding. Feed mode's `controls={false}` is overwritten back to `true` the moment the effect fires. This is the exact followup flagged in memory.md under issue 020 (surfaced bug 2).
+
+Fix: extend the 011 suspension to line 462: `video.controls = !prebufferOnly && controls;`. Add one native v.redd.it video item to `frontend/tests/e2e/fixtures/subreddit-pics.json` so the skipped "native video controls are absent" E2E test runs.
+
+### B. Mobile scroll-restore race (P1, documented followup)
+
+`useMode.js` restores grid scroll with a single `requestAnimationFrame(() => window.scrollTo(0, y))`. On mobile the grid has not finished layout at the new viewport height, so `scrollTo` silently caps at 0 and the user loses their place. This is surfaced bug 1 from issue 020.
+
+Fix: poll across frames until `document.documentElement.scrollHeight` can accommodate `y` (with a frame-count cap so it cannot spin forever), then scroll. Remove the `test.skip(isMobile, ...)` from the E2E spec.
+
+### C. Feed mode mounts everything (P0)
+
+`FeedMode.jsx` maps all items to full `FeedItem`s. Every video mounts a `VideoPlayer` with autoplay and loop; entering feed mode with a loaded grid starts dozens of simultaneous downloads and decodes. Modern vertical feeds mount a window around the active item and play only the active one.
+
+Fix: track the active index from container scroll position (items are exactly one viewport tall, so `round(scrollTop / clientHeight)` is exact and needs no IntersectionObserver). Mount real `FeedItem`s only for active ± 1; all other slots render an empty placeholder of identical height so scroll geometry and snap points are unchanged. Only the active item gets `autoPlay`.
+
+### D. hls.js in the main bundle (P2)
+
+`dashjs` is already dynamically imported; `hls.js` is static and lands ~400 KB in the main chunk (799 KB total, 246 KB gzip). Load it the same way dash is loaded.
+
+## Out of scope
+
+- File shrinks for `App.jsx`, `LightboxModal.jsx`, `styles.css` (tracked separately in memory.md).
+- README rewrite (stale SimpCity/Instagram copy) beyond a note in memory.md.
+- `FeedItem` image `loading="lazy"`: superseded by windowing (only ~3 items mount).
+
+## Acceptance criteria
+
+- [ ] Feed-mode videos render without native controls; the previously skipped chromeless E2E test runs (not skips) and passes.
+- [ ] Exiting feed mode restores grid scroll position on `chromium-mobile`; the `test.skip(isMobile, ...)` line is gone and the test passes.
+- [ ] With N items in feed mode, at most 3 are mounted as real `FeedItem`s; the rest are fixed-height placeholders. Unit test covers the window computation; component test covers placeholder rendering.
+- [ ] Only the active feed item has `autoPlay`; neighbours are mounted paused.
+- [ ] `hls.js` is no longer in the main chunk; main chunk drops below 500 KB minified.
+- [ ] `npm run lint`, `npm test` (both packages), `npm run test:e2e`, `npm run build` all pass.
+- [ ] Manual smoke: enter feed mode, swipe through image and video items, exit, confirm grid position kept.
+
+## Self-test instructions
+
+1. `npm run test:e2e` from the repo root; confirm the two previously-skipped tests now execute.
+2. `npm run build`; read the chunk table, confirm hls is its own chunk.
+3. `npm run dev`, open `http://localhost:5173`, load a video-heavy subreddit, enter feed mode, open devtools Network tab: only the active (and at most two neighbour) media requests should be in flight.

From 5646aba472b4ea5d6a11ceae6ff4c06bb6e921ea Mon Sep 17 00:00:00 2001
From: Astro <coreyluke.cordwell@gmail.com>
Date: Sat, 13 Jun 2026 00:29:44 +1000
Subject: [PATCH 2/6] fix(021): make feed-exit scroll restore robust and unskip
 mobile E2E

Tracing the 020-surfaced mobile failure showed the documented diagnosis was
wrong. The grid restores fine after a real tap; the flake was Playwright's
pre-click actionability scroll, which treats the sticky topbar button as
living at its flow position (document top) and zeroes the scroll position
before useMode captures it. The spec now enters feed mode via
dispatchEvent('click'), matching what a real tap does.

The restore itself still moves from a single requestAnimationFrame to
restoreScrollWhenReady, which waits until layout can accommodate the target
and polls with timers because browsers throttle rAF on occluded pages
(observed in headless Chromium during tracing). Unit tested; the mobile
scroll-restore E2E is no longer skipped and passes 6/6 repeats.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 frontend/src/hooks/useMode.js            | 10 ++--
 frontend/src/utils/scrollRestore.js      | 29 +++++++++++
 frontend/src/utils/scrollRestore.test.js | 65 ++++++++++++++++++++++++
 frontend/tests/e2e/feed-mode.spec.js     | 17 +++----
 4 files changed, 107 insertions(+), 14 deletions(-)
 create mode 100644 frontend/src/utils/scrollRestore.js
 create mode 100644 frontend/src/utils/scrollRestore.test.js

diff --git a/frontend/src/hooks/useMode.js b/frontend/src/hooks/useMode.js
index bacff1b..e35b102 100644
--- a/frontend/src/hooks/useMode.js
+++ b/frontend/src/hooks/useMode.js
@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
+import { restoreScrollWhenReady } from '../utils/scrollRestore';
 
 const MODE_KEY = 'nightfeed:mode';
 const VALID_MODES = new Set(['grid', 'feed']);
@@ -62,12 +63,13 @@ export function useMode() {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
-  // Restore scroll when returning to grid from feed.
+  // Restore scroll when returning to grid from feed. Waits for the grid to
+  // lay out tall enough first; see restoreScrollWhenReady for why.
   useEffect(() => {
-    if (mode !== 'grid') return;
+    if (mode !== 'grid') return undefined;
     const y = gridScrollYRef.current;
-    if (y <= 0) return;
-    requestAnimationFrame(() => window.scrollTo(0, y));
+    if (y <= 0) return undefined;
+    return restoreScrollWhenReady(y);
   }, [mode]);
 
   const setMode = useCallback((next) => {
diff --git a/frontend/src/utils/scrollRestore.js b/frontend/src/utils/scrollRestore.js
new file mode 100644
index 0000000..bfcd131
--- /dev/null
+++ b/frontend/src/utils/scrollRestore.js
@@ -0,0 +1,29 @@
+const POLL_INTERVAL_MS = 50;
+const DEFAULT_DEADLINE_MS = 1000;
+
+function canAccommodate(y) {
+  return document.documentElement.scrollHeight - window.innerHeight >= y;
+}
+
+// Restores window scroll to y once layout is tall enough to land there.
+// A single requestAnimationFrame is not enough on mobile: the grid has not
+// finished laying out at the new viewport height when feed mode unmounts,
+// so an immediate scrollTo silently caps at 0. Polls with timers rather
+// than requestAnimationFrame because browsers throttle rAF on occluded or
+// backgrounded pages and the restore would then never fire. Scrolls
+// best-effort at the deadline. Returns a cancel function.
+export function restoreScrollWhenReady(y, { deadlineMs = DEFAULT_DEADLINE_MS } = {}) {
+  if (canAccommodate(y)) {
+    window.scrollTo(0, y);
+    return () => {};
+  }
+
+  const deadline = Date.now() + deadlineMs;
+  const timer = setInterval(() => {
+    if (!canAccommodate(y) && Date.now() < deadline) return;
+    clearInterval(timer);
+    window.scrollTo(0, y);
+  }, POLL_INTERVAL_MS);
+
+  return () => clearInterval(timer);
+}
diff --git a/frontend/src/utils/scrollRestore.test.js b/frontend/src/utils/scrollRestore.test.js
new file mode 100644
index 0000000..af07db5
--- /dev/null
+++ b/frontend/src/utils/scrollRestore.test.js
@@ -0,0 +1,65 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { restoreScrollWhenReady } from '@/utils/scrollRestore';
+
+function setScrollHeight(value) {
+  Object.defineProperty(document.documentElement, 'scrollHeight', {
+    configurable: true,
+    value
+  });
+}
+
+describe('restoreScrollWhenReady', () => {
+  let scrollToSpy;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    scrollToSpy = vi.fn();
+    vi.stubGlobal('scrollTo', scrollToSpy);
+    Object.defineProperty(window, 'innerHeight', {
+      configurable: true,
+      value: 800
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  it('scrolls immediately when the page is already tall enough', () => {
+    setScrollHeight(2000);
+    restoreScrollWhenReady(600);
+    expect(scrollToSpy).toHaveBeenCalledWith(0, 600);
+  });
+
+  it('waits until layout can accommodate the target, then scrolls', () => {
+    setScrollHeight(800);
+    restoreScrollWhenReady(600);
+    expect(scrollToSpy).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(120);
+    expect(scrollToSpy).not.toHaveBeenCalled();
+
+    setScrollHeight(2000);
+    vi.advanceTimersByTime(60);
+    expect(scrollToSpy).toHaveBeenCalledWith(0, 600);
+    expect(scrollToSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('gives up at the deadline and scrolls best-effort', () => {
+    setScrollHeight(800);
+    restoreScrollWhenReady(600, { deadlineMs: 300 });
+    vi.advanceTimersByTime(1000);
+    expect(scrollToSpy).toHaveBeenCalledTimes(1);
+    expect(scrollToSpy).toHaveBeenCalledWith(0, 600);
+  });
+
+  it('cancel stops a pending restore', () => {
+    setScrollHeight(800);
+    const cancel = restoreScrollWhenReady(600);
+    cancel();
+    setScrollHeight(2000);
+    vi.advanceTimersByTime(5000);
+    expect(scrollToSpy).not.toHaveBeenCalled();
+  });
+});
diff --git a/frontend/tests/e2e/feed-mode.spec.js b/frontend/tests/e2e/feed-mode.spec.js
index 522ac66..ecbdee9 100644
--- a/frontend/tests/e2e/feed-mode.spec.js
+++ b/frontend/tests/e2e/feed-mode.spec.js
@@ -73,15 +73,7 @@ test.describe('feed mode', () => {
     await expect(page).toHaveURL(/mode=feed/);
   });
 
-  test('exiting feed mode restores grid scroll position', async ({ page, isMobile }) => {
-    // Followup: 020 surfaced a real bug where useMode's scroll restoration runs
-    // before the grid finishes laying out under mobile-viewport emulation, so
-    // window.scrollTo(0, capturedY) silently caps at 0. The test is the right
-    // assertion; the production fix belongs in useMode.js (likely: wait for
-    // grid DOM to be tall enough before restoring). Tracked for a separate
-    // issue rather than fixing as part of 020.
-    test.skip(isMobile, 'mobile scroll restore needs a layout-ready wait in useMode (followup)');
-
+  test('exiting feed mode restores grid scroll position', async ({ page }) => {
     await page.goto('/?r=pics');
     await waitForGrid(page);
 
@@ -92,7 +84,12 @@ test.describe('feed mode', () => {
       test.skip(true, 'grid not tall enough to scroll meaningfully in this viewport');
     }
 
-    await enterFeed(page);
+    // dispatchEvent instead of click: Playwright's pre-click actionability
+    // scroll treats the sticky topbar button as living at its flow position
+    // (top of document) and scrolls there first, which zeroes the scroll
+    // position this test is asserting on. A real tap does not do that.
+    await page.locator(ENTER_FEED).dispatchEvent('click');
+    await expect(page.locator(FEED_REGION)).toBeVisible();
     await page.keyboard.press('Escape');
     await expect(page.locator(FEED_REGION)).toBeHidden();
 

From 0a7556bf116cfdaf7e54c5cc269858d78a3b2006 Mon Sep 17 00:00:00 2001
From: Astro <coreyluke.cordwell@gmail.com>
Date: Sat, 13 Jun 2026 00:32:41 +1000
Subject: [PATCH 3/6] feat(021): window feed mode to the active item plus one
 neighbour

FeedMode previously mounted every item at once, so each video item got a
full VideoPlayer downloading and autoplaying simultaneously. It now tracks
the active index from container scroll position (items are exactly one
viewport tall with mandatory snap, so plain division replaces an
IntersectionObserver) and mounts real FeedItems only for active plus or
minus one. Slots outside the window render as empty same-height
placeholders, keeping scroll geometry and snap points identical.

Only the active item autoplays; mounted neighbours sit paused and start
when scrolled to. Window computation is a pure function with unit tests;
component tests cover slot count, window movement, and end clipping.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 frontend/src/components/FeedItem.jsx      |  3 +-
 frontend/src/components/FeedMode.jsx      | 34 ++++++++++--
 frontend/src/components/FeedMode.test.jsx | 67 +++++++++++++++++++++++
 frontend/src/utils/feedWindow.js          | 11 ++++
 frontend/src/utils/feedWindow.test.js     | 33 +++++++++++
 5 files changed, 143 insertions(+), 5 deletions(-)
 create mode 100644 frontend/src/components/FeedMode.test.jsx
 create mode 100644 frontend/src/utils/feedWindow.js
 create mode 100644 frontend/src/utils/feedWindow.test.js

diff --git a/frontend/src/components/FeedItem.jsx b/frontend/src/components/FeedItem.jsx
index dbb8461..de4e53d 100644
--- a/frontend/src/components/FeedItem.jsx
+++ b/frontend/src/components/FeedItem.jsx
@@ -1,7 +1,7 @@
 import VideoPlayer from './VideoPlayer';
 import { getModalItems } from '../utils/media';
 
-function FeedItem({ item }) {
+function FeedItem({ item, isActive = false }) {
   const modalItems = getModalItems(item);
   const first = modalItems[0];
   if (!first) return null;
@@ -18,6 +18,7 @@ function FeedItem({ item }) {
           posterUrl={item?.thumbnail || ''}
           className="feed-item__video"
           controls={false}
+          autoPlay={isActive}
         />
       </div>
     );
diff --git a/frontend/src/components/FeedMode.jsx b/frontend/src/components/FeedMode.jsx
index 3197202..1020843 100644
--- a/frontend/src/components/FeedMode.jsx
+++ b/frontend/src/components/FeedMode.jsx
@@ -1,12 +1,38 @@
+import { useRef, useState } from 'react';
 import FeedItem from './FeedItem';
+import { computeFeedWindow } from '../utils/feedWindow';
 import '../styles/feed.css';
 
 function FeedMode({ items }) {
+  const containerRef = useRef(null);
+  const [activeIndex, setActiveIndex] = useState(0);
+
+  // Each item is exactly one viewport tall with mandatory snap, so the
+  // active index is plain division; no IntersectionObserver needed.
+  function handleScroll() {
+    const node = containerRef.current;
+    if (!node || node.clientHeight === 0) return;
+    const index = Math.round(node.scrollTop / node.clientHeight);
+    setActiveIndex(Math.max(0, Math.min(items.length - 1, index)));
+  }
+
+  const { start, end } = computeFeedWindow(activeIndex, items.length);
+
   return (
-    <div className="feed-mode" role="region" aria-label="Feed mode">
-      {items.map((item) => (
-        <FeedItem key={item.id} item={item} />
-      ))}
+    <div
+      className="feed-mode"
+      role="region"
+      aria-label="Feed mode"
+      ref={containerRef}
+      onScroll={handleScroll}
+    >
+      {items.map((item, index) =>
+        index >= start && index <= end ? (
+          <FeedItem key={item.id} item={item} isActive={index === activeIndex} />
+        ) : (
+          <div key={item.id} className="feed-item" aria-hidden="true" />
+        )
+      )}
     </div>
   );
 }
diff --git a/frontend/src/components/FeedMode.test.jsx b/frontend/src/components/FeedMode.test.jsx
new file mode 100644
index 0000000..1befff6
--- /dev/null
+++ b/frontend/src/components/FeedMode.test.jsx
@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { render, fireEvent } from '@testing-library/react';
+import FeedMode from '@/components/FeedMode';
+
+function imageItems(count) {
+  return Array.from({ length: count }, (_, i) => ({
+    id: `img_${i}`,
+    type: 'image',
+    mediaUrl: `https://example.test/${i}.jpg`
+  }));
+}
+
+function getContainer(view) {
+  return view.getByRole('region', { name: 'Feed mode' });
+}
+
+function scrollToIndex(container, index, viewportHeight = 700) {
+  Object.defineProperty(container, 'clientHeight', {
+    configurable: true,
+    value: viewportHeight
+  });
+  Object.defineProperty(container, 'scrollTop', {
+    configurable: true,
+    writable: true,
+    value: index * viewportHeight
+  });
+  fireEvent.scroll(container);
+}
+
+describe('FeedMode windowing', () => {
+  it('keeps one slot per item so scroll geometry is unchanged', () => {
+    const view = render(<FeedMode items={imageItems(8)} />);
+    expect(getContainer(view).children.length).toBe(8);
+  });
+
+  it('mounts media only for the active item and its neighbours', () => {
+    const view = render(<FeedMode items={imageItems(8)} />);
+    // Active index 0 on entry: items 0 and 1 are real, the rest placeholders.
+    expect(view.container.querySelectorAll('img').length).toBe(2);
+  });
+
+  it('moves the window as the user scrolls', () => {
+    const view = render(<FeedMode items={imageItems(8)} />);
+    const container = getContainer(view);
+
+    scrollToIndex(container, 4);
+    const imgs = [...view.container.querySelectorAll('img')];
+    expect(imgs.map((el) => el.getAttribute('src'))).toEqual([
+      'https://example.test/3.jpg',
+      'https://example.test/4.jpg',
+      'https://example.test/5.jpg'
+    ]);
+  });
+
+  it('clips the window at the end of the list', () => {
+    const view = render(<FeedMode items={imageItems(8)} />);
+    const container = getContainer(view);
+
+    scrollToIndex(container, 7);
+    expect(view.container.querySelectorAll('img').length).toBe(2);
+  });
+
+  it('renders nothing special for an empty list', () => {
+    const view = render(<FeedMode items={[]} />);
+    expect(getContainer(view).children.length).toBe(0);
+  });
+});
diff --git a/frontend/src/utils/feedWindow.js b/frontend/src/utils/feedWindow.js
new file mode 100644
index 0000000..686bba4
--- /dev/null
+++ b/frontend/src/utils/feedWindow.js
@@ -0,0 +1,11 @@
+// The range of feed items worth mounting: the active one plus `radius`
+// neighbours on each side, clipped to the list. Everything outside renders
+// as an empty same-height placeholder so scroll geometry stays intact.
+export function computeFeedWindow(activeIndex, itemCount, radius = 1) {
+  if (itemCount <= 0) return { start: 0, end: -1 };
+  const clamped = Math.max(0, Math.min(itemCount - 1, activeIndex));
+  return {
+    start: Math.max(0, clamped - radius),
+    end: Math.min(itemCount - 1, clamped + radius)
+  };
+}
diff --git a/frontend/src/utils/feedWindow.test.js b/frontend/src/utils/feedWindow.test.js
new file mode 100644
index 0000000..fe1362b
--- /dev/null
+++ b/frontend/src/utils/feedWindow.test.js
@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import { computeFeedWindow } from '@/utils/feedWindow';
+
+describe('computeFeedWindow', () => {
+  it('windows around a middle item', () => {
+    expect(computeFeedWindow(5, 10)).toEqual({ start: 4, end: 6 });
+  });
+
+  it('clips at the start of the list', () => {
+    expect(computeFeedWindow(0, 10)).toEqual({ start: 0, end: 1 });
+  });
+
+  it('clips at the end of the list', () => {
+    expect(computeFeedWindow(9, 10)).toEqual({ start: 8, end: 9 });
+  });
+
+  it('handles a single-item list', () => {
+    expect(computeFeedWindow(0, 1)).toEqual({ start: 0, end: 0 });
+  });
+
+  it('returns an empty range for an empty list', () => {
+    expect(computeFeedWindow(0, 0)).toEqual({ start: 0, end: -1 });
+  });
+
+  it('clamps an out-of-range active index', () => {
+    expect(computeFeedWindow(99, 10)).toEqual({ start: 8, end: 9 });
+    expect(computeFeedWindow(-5, 10)).toEqual({ start: 0, end: 1 });
+  });
+
+  it('honours a custom radius', () => {
+    expect(computeFeedWindow(5, 10, 2)).toEqual({ start: 3, end: 7 });
+  });
+});

From bbddc5064cab29af95dfc545e63a5222c0679568 Mon Sep 17 00:00:00 2001
From: Astro <coreyluke.cordwell@gmail.com>
Date: Sat, 13 Jun 2026 00:34:52 +1000
Subject: [PATCH 4/6] perf(021): load hls.js dynamically, halving the main
 bundle

hls.js was the only statically imported media engine; dashjs was already
dynamic. A loadHls helper in utils/videoLoaders.js (the extraction target
CLAUDE.md names for VideoPlayer's planned shrink) awaits the import inside
the HLS branch. Main chunk drops from 799 KB (246 KB gzip) to 277 KB
(84 KB gzip); hls.js becomes a 524 KB lazy chunk fetched on first HLS play.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 frontend/src/components/VideoPlayer.jsx |  6 ++++--
 frontend/src/utils/videoLoaders.js      | 11 +++++++++++
 frontend/src/utils/videoLoaders.test.js | 14 ++++++++++++++
 3 files changed, 29 insertions(+), 2 deletions(-)
 create mode 100644 frontend/src/utils/videoLoaders.js
 create mode 100644 frontend/src/utils/videoLoaders.test.js

diff --git a/frontend/src/components/VideoPlayer.jsx b/frontend/src/components/VideoPlayer.jsx
index 7a03ef3..7d1de65 100644
--- a/frontend/src/components/VideoPlayer.jsx
+++ b/frontend/src/components/VideoPlayer.jsx
@@ -1,4 +1,4 @@
-import Hls from 'hls.js';
+import { loadHls } from '../utils/videoLoaders';
 import { forwardRef, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
 
 const isDev = import.meta.env.DEV;
@@ -481,7 +481,9 @@ const VideoPlayer = forwardRef(function VideoPlayer(
           return;
         }
 
-        if (Hls.isSupported()) {
+        const Hls = await loadHls();
+        if (cancelled) return;
+        if (Hls && Hls.isSupported()) {
           if (isDev) console.log('[VideoPlayer] using HLS');
           updateDiagnostics({ playbackMode: 'hls', audioTracksDetected: 0, autoplayAttempted: true, loadingState: 'loading' });
           const hls = new Hls();
diff --git a/frontend/src/utils/videoLoaders.js b/frontend/src/utils/videoLoaders.js
new file mode 100644
index 0000000..427cb2f
--- /dev/null
+++ b/frontend/src/utils/videoLoaders.js
@@ -0,0 +1,11 @@
+// Media engine loaders, dynamically imported so the libraries stay out of
+// the main bundle (hls.js alone is ~400 KB minified). Mirrors the dashjs
+// dynamic import that already lives in VideoPlayer's DASH path.
+export async function loadHls() {
+  try {
+    const mod = await import('hls.js');
+    return mod.default || mod;
+  } catch {
+    return null;
+  }
+}
diff --git a/frontend/src/utils/videoLoaders.test.js b/frontend/src/utils/videoLoaders.test.js
new file mode 100644
index 0000000..efd4a91
--- /dev/null
+++ b/frontend/src/utils/videoLoaders.test.js
@@ -0,0 +1,14 @@
+import { describe, it, expect, vi } from 'vitest';
+import { loadHls } from '@/utils/videoLoaders';
+
+vi.mock('hls.js', () => ({
+  default: { isSupported: () => true, marker: 'mock-hls' }
+}));
+
+describe('loadHls', () => {
+  it('resolves the hls.js default export', async () => {
+    const Hls = await loadHls();
+    expect(Hls.marker).toBe('mock-hls');
+    expect(Hls.isSupported()).toBe(true);
+  });
+});

From e4650bfa7a8a40431c7c6c5dce530bec16ba43ce Mon Sep 17 00:00:00 2001
From: Astro <coreyluke.cordwell@gmail.com>
Date: Sat, 13 Jun 2026 00:42:01 +1000
Subject: [PATCH 5/6] feat(021): play RedGIFs natively in feed mode, filter
 unplayable items

Smoke testing the windowed feed surfaced an interaction bug: embed items
rendered null with no slot div, so the scroll-position index math
misaligned and the wrong item was marked active. RedGIFs embeds now play
through the backend stream proxy exactly like the lightbox does, which
also means RedGIFs items appear in the feed instead of silently vanishing.
Anything else unplayable (audio, non-RedGIFs embeds) is filtered out by
isFeedRenderable before windowing so every slot is exactly one viewport.

Smoke verified against the fixture: active item plays, neighbour mounts
paused, swiping flips them, no controls, exit restores scroll exactly.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 frontend/src/components/FeedItem.jsx      | 15 ++++++++
 frontend/src/components/FeedItem.test.jsx | 45 +++++++++++++++++++++++
 frontend/src/components/FeedMode.jsx      |  6 ++-
 frontend/src/components/FeedMode.test.jsx | 17 +++++++++
 frontend/src/utils/media.js               | 12 ++++++
 frontend/src/utils/media.test.js          | 45 +++++++++++++++++++++++
 6 files changed, 138 insertions(+), 2 deletions(-)
 create mode 100644 frontend/src/components/FeedItem.test.jsx
 create mode 100644 frontend/src/utils/media.test.js

diff --git a/frontend/src/components/FeedItem.jsx b/frontend/src/components/FeedItem.jsx
index de4e53d..1029e0d 100644
--- a/frontend/src/components/FeedItem.jsx
+++ b/frontend/src/components/FeedItem.jsx
@@ -1,5 +1,6 @@
 import VideoPlayer from './VideoPlayer';
 import { getModalItems } from '../utils/media';
+import { getRedgifsStreamUrl } from '../utils/api';
 
 function FeedItem({ item, isActive = false }) {
   const modalItems = getModalItems(item);
@@ -24,6 +25,20 @@ function FeedItem({ item, isActive = false }) {
     );
   }
 
+  if (first.kind === 'embed' && first.provider === 'RedGIFs' && first.id) {
+    return (
+      <div className="feed-item">
+        <VideoPlayer
+          mp4Url={getRedgifsStreamUrl(first.id)}
+          posterUrl={first.posterUrl || item?.thumbnail || ''}
+          className="feed-item__video"
+          controls={false}
+          autoPlay={isActive}
+        />
+      </div>
+    );
+  }
+
   if (first.kind === 'image') {
     return (
       <div className="feed-item">
diff --git a/frontend/src/components/FeedItem.test.jsx b/frontend/src/components/FeedItem.test.jsx
new file mode 100644
index 0000000..f0b2706
--- /dev/null
+++ b/frontend/src/components/FeedItem.test.jsx
@@ -0,0 +1,45 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render } from '@testing-library/react';
+import FeedItem from '@/components/FeedItem';
+
+vi.mock('@/components/VideoPlayer', () => ({
+  default: (props) => <div data-testid="video-player" data-props={JSON.stringify(props)} />
+}));
+
+function playerProps(view) {
+  return JSON.parse(view.getByTestId('video-player').dataset.props);
+}
+
+describe('FeedItem', () => {
+  it('plays RedGIFs embeds through the stream proxy like the lightbox does', () => {
+    const view = render(
+      <FeedItem
+        isActive
+        item={{
+          id: 'rg1',
+          type: 'video',
+          thumbnail: 'https://thumb.test/p.png',
+          externalVideoProvider: 'RedGIFs',
+          externalVideoId: 'clipid',
+          externalVideoEmbedUrl: 'https://www.redgifs.com/ifr/clipid',
+          externalVideoPosterUrl: 'https://poster.test/p.png'
+        }}
+      />
+    );
+    const props = playerProps(view);
+    expect(props.mp4Url).toContain('/api/external/redgifs/clipid/stream');
+    expect(props.posterUrl).toBe('https://poster.test/p.png');
+    expect(props.controls).toBe(false);
+    expect(props.autoPlay).toBe(true);
+  });
+
+  it('only autoplays the active item', () => {
+    const view = render(
+      <FeedItem
+        isActive={false}
+        item={{ id: 'v1', type: 'video', videoUrl: 'https://v.redd.it/x/fallback.mp4' }}
+      />
+    );
+    expect(playerProps(view).autoPlay).toBe(false);
+  });
+});
diff --git a/frontend/src/components/FeedMode.jsx b/frontend/src/components/FeedMode.jsx
index 1020843..68e2298 100644
--- a/frontend/src/components/FeedMode.jsx
+++ b/frontend/src/components/FeedMode.jsx
@@ -1,11 +1,13 @@
-import { useRef, useState } from 'react';
+import { useMemo, useRef, useState } from 'react';
 import FeedItem from './FeedItem';
 import { computeFeedWindow } from '../utils/feedWindow';
+import { isFeedRenderable } from '../utils/media';
 import '../styles/feed.css';
 
-function FeedMode({ items }) {
+function FeedMode({ items: allItems }) {
   const containerRef = useRef(null);
   const [activeIndex, setActiveIndex] = useState(0);
+  const items = useMemo(() => allItems.filter(isFeedRenderable), [allItems]);
 
   // Each item is exactly one viewport tall with mandatory snap, so the
   // active index is plain division; no IntersectionObserver needed.
diff --git a/frontend/src/components/FeedMode.test.jsx b/frontend/src/components/FeedMode.test.jsx
index 1befff6..5a8fc14 100644
--- a/frontend/src/components/FeedMode.test.jsx
+++ b/frontend/src/components/FeedMode.test.jsx
@@ -64,4 +64,21 @@ describe('FeedMode windowing', () => {
     const view = render(<FeedMode items={[]} />);
     expect(getContainer(view).children.length).toBe(0);
   });
+
+  it('excludes unplayable items so every slot can render', () => {
+    const items = [
+      ...imageItems(2),
+      { id: 'aud_0', type: 'audio', mediaUrl: 'https://example.test/a.mp3' },
+      {
+        id: 'yt_0',
+        type: 'video',
+        externalVideoProvider: 'YouTube',
+        externalVideoId: 'ytid',
+        externalVideoEmbedUrl: 'https://www.youtube.com/embed/ytid'
+      }
+    ];
+    const view = render(<FeedMode items={items} />);
+    expect(getContainer(view).children.length).toBe(2);
+    expect(view.container.querySelectorAll('img').length).toBe(2);
+  });
 });
diff --git a/frontend/src/utils/media.js b/frontend/src/utils/media.js
index db40196..a3e131f 100644
--- a/frontend/src/utils/media.js
+++ b/frontend/src/utils/media.js
@@ -80,6 +80,18 @@ export function getModalItems(post) {
   return [{ kind: 'image', url: post.mediaUrl }];
 }
 
+// Whether feed mode can put this item on screen. Embeds only qualify for
+// RedGIFs, which plays natively through the backend stream proxy (the same
+// path the lightbox uses). Items failing this are filtered out before
+// windowing so every feed slot is exactly one viewport tall.
+export function isFeedRenderable(post) {
+  const first = getModalItems(post)[0];
+  if (!first) return false;
+  if (first.kind === 'embed') return first.provider === 'RedGIFs' && Boolean(first.id);
+  if (first.kind === 'audio') return false;
+  return Boolean(first.url);
+}
+
 export function canDownloadUrl(url) {
   if (!url) return false;
   try {
diff --git a/frontend/src/utils/media.test.js b/frontend/src/utils/media.test.js
new file mode 100644
index 0000000..5e7951b
--- /dev/null
+++ b/frontend/src/utils/media.test.js
@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { isFeedRenderable } from '@/utils/media';
+
+describe('isFeedRenderable', () => {
+  it('accepts native video items', () => {
+    expect(
+      isFeedRenderable({ type: 'video', videoUrl: 'https://v.redd.it/x/fallback.mp4' })
+    ).toBe(true);
+  });
+
+  it('accepts image items', () => {
+    expect(isFeedRenderable({ type: 'image', mediaUrl: 'https://i.redd.it/x.jpg' })).toBe(true);
+  });
+
+  it('accepts RedGIFs embeds, which play through the stream proxy', () => {
+    expect(
+      isFeedRenderable({
+        type: 'video',
+        externalVideoProvider: 'RedGIFs',
+        externalVideoId: 'clipid',
+        externalVideoEmbedUrl: 'https://www.redgifs.com/ifr/clipid'
+      })
+    ).toBe(true);
+  });
+
+  it('rejects non-RedGIFs embeds', () => {
+    expect(
+      isFeedRenderable({
+        type: 'video',
+        externalVideoProvider: 'YouTube',
+        externalVideoId: 'ytid',
+        externalVideoEmbedUrl: 'https://www.youtube.com/embed/ytid'
+      })
+    ).toBe(false);
+  });
+
+  it('rejects audio items', () => {
+    expect(isFeedRenderable({ type: 'audio', mediaUrl: 'https://x.test/a.mp3' })).toBe(false);
+  });
+
+  it('rejects items with nothing to show', () => {
+    expect(isFeedRenderable({ type: 'image', mediaUrl: null })).toBe(false);
+    expect(isFeedRenderable(null)).toBe(false);
+  });
+});

From c1b880961fb983b9f66e92cebe2beeae3b8343ea Mon Sep 17 00:00:00 2001
From: Astro <coreyluke.cordwell@gmail.com>
Date: Sat, 13 Jun 2026 00:43:01 +1000
Subject: [PATCH 6/6] docs(021): record smoothness audit decisions and
 corrected 020 diagnosis

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 issues/021-smoothness-fixes.md | 18 +++++++++++-------
 memory.md                      | 13 ++++++++++++-
 2 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/issues/021-smoothness-fixes.md b/issues/021-smoothness-fixes.md
index 8c7154a..829dfba 100644
--- a/issues/021-smoothness-fixes.md
+++ b/issues/021-smoothness-fixes.md
@@ -34,13 +34,17 @@ Fix: track the active index from container scroll position (items are exactly on
 
 ## Acceptance criteria
 
-- [ ] Feed-mode videos render without native controls; the previously skipped chromeless E2E test runs (not skips) and passes.
-- [ ] Exiting feed mode restores grid scroll position on `chromium-mobile`; the `test.skip(isMobile, ...)` line is gone and the test passes.
-- [ ] With N items in feed mode, at most 3 are mounted as real `FeedItem`s; the rest are fixed-height placeholders. Unit test covers the window computation; component test covers placeholder rendering.
-- [ ] Only the active feed item has `autoPlay`; neighbours are mounted paused.
-- [ ] `hls.js` is no longer in the main chunk; main chunk drops below 500 KB minified.
-- [ ] `npm run lint`, `npm test` (both packages), `npm run test:e2e`, `npm run build` all pass.
-- [ ] Manual smoke: enter feed mode, swipe through image and video items, exit, confirm grid position kept.
+- [x] Feed-mode videos render without native controls; the previously skipped chromeless E2E test runs (not skips) and passes.
+- [x] Exiting feed mode restores grid scroll position on `chromium-mobile`; the `test.skip(isMobile, ...)` line is gone and the test passes (6/6 repeats).
+- [x] With N items in feed mode, at most 3 are mounted as real `FeedItem`s; the rest are fixed-height placeholders. Unit test covers the window computation; component test covers placeholder rendering.
+- [x] Only the active feed item has `autoPlay`; neighbours are mounted paused. Verified by scripted browser smoke: swiping flips active/paused correctly.
+- [x] `hls.js` is no longer in the main chunk; main chunk dropped 799 KB to 277 KB minified (246 KB to 84 KB gzip).
+- [x] `npm run lint`, `npm test` (both packages), `npm run test:e2e`, `npm run build` all pass.
+- [x] Smoke: scripted real-browser pass against fixture stubs (enter feed, video plays chromeless, swipe, exit restores scroll exactly). Real-Reddit click-through was blocked by an upstream 403 rate-limit lockout during the session; a phone smoke with live data is the remaining follow-through.
+
+## Surfaced during smoke (fixed in this issue)
+
+Embed items rendered `null` in feed mode with no slot div, so the windowing index math misaligned and the wrong item was marked active. Fixed by playing RedGIFs through the backend stream proxy (lightbox parity, so RedGIFs items now appear in the feed at all) and filtering remaining unplayable kinds via `isFeedRenderable` before windowing.
 
 ## Self-test instructions
 
diff --git a/memory.md b/memory.md
index 7e0add5..5d8dcf3 100644
--- a/memory.md
+++ b/memory.md
@@ -25,7 +25,7 @@ This file is for the human + the AI assistant. Keep entries dated. Newest at top
 - CI on push + PR (`.github/workflows/ci.yml`, Node 22; `npm install`, lint, test, build)
 
 **Broken / out of date:**
-- `README.md` describes SimpCity + Instagram (both removed) and omits Coomer / Eporner / YouTube
+- `README.md` describes SimpCity + Instagram (both removed) and omits Coomer / Eporner / YouTube; also predates feed-mode windowing and RedGIFs-in-feed (021)
 - localStorage keys still use `subreddit-media-viewer:*` prefix (acceptable; migration is a future task)
 - `App.jsx` is ~1000 lines with 40 useStates (down from 1733/47, still too large)
 - `LightboxModal.jsx` is ~880 lines
@@ -42,6 +42,17 @@ This file is for the human + the AI assistant. Keep entries dated. Newest at top
 
 Append-only. Newest at top.
 
+### 2026-06-13: Smoothness audit shipped (issue 021)
+- **Scope.** Full-stack audit ranked user-felt clunk; five fixes landed on `feat/021-smoothness-fixes`: feed windowing, chromeless-controls bug, scroll-restore robustness, hls.js code split, RedGIFs-in-feed.
+- **Feed mode is windowed.** `FeedMode` mounts real `FeedItem`s only for active plus or minus one; other slots are empty same-height divs so snap geometry is unchanged. Active index is `round(scrollTop / clientHeight)` (items are exactly one viewport tall), no IntersectionObserver. Only the active item autoplays; neighbours mount paused and start when scrolled to (the attach effect re-runs on the `autoPlay` prop change).
+- **RedGIFs plays natively in feed mode.** `FeedItem` feeds `getRedgifsStreamUrl(id)` to `VideoPlayer` exactly like the lightbox does. Before this, embed items returned `null` with no slot div, which both hid RedGIFs from the feed entirely and, once windowing landed, misaligned the index math so the wrong item activated. Remaining unplayable kinds (audio, non-RedGIFs embeds) are filtered by `isFeedRenderable` in `utils/media.js` before windowing.
+- **020's scroll-restore diagnosis was wrong.** Tracing showed the mobile E2E flake was not "restore runs before layout": Playwright's pre-click actionability scroll treats the sticky topbar button as living at its flow position (document top) and zeroes scroll before `useMode` captures it, so the restore had a target of 0 and correctly did nothing. The spec now enters feed via `dispatchEvent('click')`, which matches a real tap. The restore was still hardened (`utils/scrollRestore.js`): waits until layout can accommodate the target, polling with timers because headless and occluded pages throttle rAF (observed directly during tracing).
+- **hls.js is a lazy chunk.** `loadHls()` in `utils/videoLoaders.js` (the extraction target CLAUDE.md already named for VideoPlayer's shrink) dynamic-imports it inside the HLS branch. Main chunk: 799 KB to 277 KB minified (246 KB to 84 KB gzip).
+- **VideoPlayer suspension extended by one line (the documented 020 followup).** Line ~462 `video.controls = !prebufferOnly` became `!prebufferOnly && controls`, and `controls` joined the attach effect deps. The fixture gained a native v.redd.it item plus a real 1.8 KB playable mp4 (`tiny-video.mp4`, served by the route stub) so the chromeless and HAVE_CURRENT_DATA tests execute instead of skipping.
+- **E2E now stubs `search-subreddits` and `related`.** They still hit real Reddit and 403/429ed mid-session, flaking otherwise-deterministic specs and halving suite speed (60s to 30s once stubbed). Consistent with the 020 fixtures-mode decision.
+- **Reddit anonymous-API lockout is real.** After the session's E2E volume, all live `/api/subreddit` calls 403ed, exactly as the 020 entry warned. Live-data manual smoke on the phone is the remaining 021 follow-through once the lockout expires.
+- **E2E desktop scroll-restore test skips on fixture height.** With the default videos media filter, the 26-item fixture yields 2 cards; the desktop viewport cannot scroll 600px, so that variant self-skips ("grid not tall enough"). Pre-existing, unchanged by 021; a taller fixture or more video items would unblock it.
+
 ### 2026-05-26: Playwright E2E layer added (issue 020)
 - **Why now.** Three sessions (010, 011, 005) shipped bugs that lint and unit tests did not catch and manual smoke did. The cost of repeating that pattern across 012-019 is higher than the cost of adding a real-browser layer once.
 - **Layer 3 is E2E.** `TESTING.md` now describes four layers: static checks, automated unit tests, E2E (Playwright), manual smoke. The old "Layer 3 manual smoke" is now Layer 4. `npm run test:e2e` from the repo root spins up backend + frontend and drives headless Chromium.