From 08b7fa507caf33287eb47e022c4a8987ed2ced67 Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Thu, 6 Aug 2026 10:40:11 +0300
Subject: [PATCH 01/23] fix: keep the picture neutral until the viewer asks

A clean profile was showing a film that had already been adjusted. Stored
values are now range-checked: anything outside the range the panel can
produce, or of the wrong type, falls back to the neutral value rather than
tinting a film for reasons the viewer cannot see.
---
 src/lib/settings.js        | 26 ++++++++++++++++++++++++--
 test/unit/settings.test.js | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+), 2 deletions(-)
 create mode 100644 test/unit/settings.test.js

diff --git a/src/lib/settings.js b/src/lib/settings.js
index 66f72b6..985eb6b 100644
--- a/src/lib/settings.js
+++ b/src/lib/settings.js
@@ -19,13 +19,35 @@ export const DEFAULTS = Object.freeze({
 
 const KEYS = Object.keys(DEFAULTS);
 
+// The picture must start exactly as the site encoded it, so a stored value that
+// is not a number in range is not trusted: it falls back to the neutral one
+// rather than tinting somebody's first film for reasons they cannot see.
+const RANGES = {
+  warmth: { min: 0, max: 0.45 },
+  brightness: { min: 0.5, max: 1.5 },
+  contrast: { min: 0.5, max: 1.5 },
+  saturate: { min: 0, max: 2 },
+  subtitleScale: { min: 0.5, max: 2 },
+  doubleTapSeconds: { min: 5, max: 60 },
+  holdSpeed: { min: 1.5, max: 4 },
+};
+
+const inRange = (key, value) => {
+  const range = RANGES[key];
+  if (range === undefined) return value;
+  const isNumber = typeof value === 'number' && Number.isFinite(value);
+  if (!isNumber) return DEFAULTS[key];
+  if (value < range.min || value > range.max) return DEFAULTS[key];
+  return value;
+};
+
 // Rebuilt key by key so every settings object shares one hidden class, and so
 // unknown keys from a future version can never leak into the running state.
-const normalize = (stored) => {
+export const normalize = (stored) => {
   const settings = {};
   for (const key of KEYS) {
     const value = stored?.[key];
-    settings[key] = value === undefined ? DEFAULTS[key] : value;
+    settings[key] = value === undefined ? DEFAULTS[key] : inRange(key, value);
   }
   settings.schemaVersion = SCHEMA_VERSION;
   settings.disabledHosts = Array.isArray(settings.disabledHosts)
diff --git a/test/unit/settings.test.js b/test/unit/settings.test.js
new file mode 100644
index 0000000..5e9e4c4
--- /dev/null
+++ b/test/unit/settings.test.js
@@ -0,0 +1,36 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { DEFAULTS, normalize } from '../../src/lib/settings.js';
+
+test('a fresh profile starts with no colour treatment at all', () => {
+  const settings = normalize(null);
+  assert.equal(settings.brightness, 1);
+  assert.equal(settings.contrast, 1);
+  assert.equal(settings.saturate, 1);
+  assert.equal(settings.warmth, 0);
+});
+
+test('a stored value outside its range falls back to neutral', () => {
+  const settings = normalize({ contrast: 1.3e3, brightness: -4 });
+  assert.equal(settings.contrast, DEFAULTS.contrast);
+  assert.equal(settings.brightness, DEFAULTS.brightness);
+});
+
+test('a stored value of the wrong type falls back to neutral', () => {
+  const settings = normalize({ saturate: '1.5', warmth: null });
+  assert.equal(settings.saturate, DEFAULTS.saturate);
+  assert.equal(settings.warmth, DEFAULTS.warmth);
+});
+
+test('a value the user really chose is kept', () => {
+  const settings = normalize({ contrast: 1.15, warmth: 0.27 });
+  assert.equal(settings.contrast, 1.15);
+  assert.equal(settings.warmth, 0.27);
+});
+
+test('unknown keys never reach the running state', () => {
+  const settings = normalize({ contrast: 1.1, somethingElse: true });
+  assert.equal(settings.somethingElse, undefined);
+  assert.deepEqual(Object.keys(settings).sort(), Object.keys(DEFAULTS).sort());
+});

From 955a63ccafccc216dbdec15042f5bd3508ba521b Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Thu, 6 Aug 2026 10:40:29 +0300
Subject: [PATCH 02/23] fix(controls): move the launcher clear of the site's
 controls

The badge sat in the bottom corner of the video, on top of the play button
and the progress line the site draws there, and swallowed taps meant for
them. It now sits halfway up the right edge, which is the one part of a
video no player puts a control on, and is clamped to stay on screen.
---
 src/content/controls/badge.js | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/src/content/controls/badge.js b/src/content/controls/badge.js
index e302991..3b5009b 100644
--- a/src/content/controls/badge.js
+++ b/src/content/controls/badge.js
@@ -47,6 +47,19 @@ export const createBadge = () => {
     pinStyle(shell.host, { opacity: '0', 'pointer-events': 'none' });
   };
 
+  // Halfway up the right edge, which is the one part of a video that no player
+  // puts a control on: the bottom corner sat on top of the site's own buttons
+  // and swallowed taps meant for them.
+  const placement = (rect) => {
+    const left = rect.right - SIZE_PX - INSET_PX;
+    const top = rect.top + rect.height / 2 - SIZE_PX / 2;
+    const maxTop = window.innerHeight - SIZE_PX - INSET_PX;
+    return {
+      left: `${Math.max(INSET_PX, left)}px`,
+      top: `${Math.min(maxTop, Math.max(INSET_PX, top))}px`,
+    };
+  };
+
   // Teardown is the watcher's job: when the video goes away it reports a new
   // primary and calls hide(). Here we only stop drawing.
   const reposition = () => {
@@ -63,8 +76,7 @@ export const createBadge = () => {
     pinStyle(shell.host, {
       opacity: '1',
       'pointer-events': 'auto',
-      left: `${rect.right - SIZE_PX - INSET_PX}px`,
-      top: `${rect.bottom - SIZE_PX - INSET_PX}px`,
+      ...placement(rect),
     });
   };
 

From 2e73ed2f5d1adc064fb5294846033eb8385a3973 Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Thu, 6 Aug 2026 10:40:30 +0300
Subject: [PATCH 03/23] fix(gestures): pause on the button only and lift the
 seek band

Two sources of mis-taps, both from a target that was larger than what the
viewer could see.

The whole picture was a hidden pause button, so a thumb resting on the
screen stopped the film. Pausing is now the play button and nothing else;
a tap anywhere else brings the controls up or puts them away.

The seek band reached the bottom edge, where the Android home swipe starts,
so putting the app away threw the film into the middle. The band and the
bar it belongs to now sit above that strip, and the bar's centre is
measured rather than assumed so the precision curve follows it.

The chrome also gets one easing curve throughout, scrims and shadows under
the controls so they read over a bright picture, and a reduced-motion rule.
---
 src/content/controls/seekbar.js    |  12 ++-
 src/content/gestures/recognizer.js |   7 +-
 src/content/gestures/zones.js      |  25 +++--
 src/content/player.css             | 164 +++++++++++++++++++++++++----
 test/unit/zones.test.js            |  50 +++++++++
 5 files changed, 219 insertions(+), 39 deletions(-)
 create mode 100644 test/unit/zones.test.js

diff --git a/src/content/controls/seekbar.js b/src/content/controls/seekbar.js
index 2a17478..d78cad6 100644
--- a/src/content/controls/seekbar.js
+++ b/src/content/controls/seekbar.js
@@ -1,7 +1,6 @@
 import { formatClock, formatRemaining } from '../../lib/time.js';
 import { el } from '../shell.js';
 
-const BAR_CENTER_FROM_BOTTOM_PX = 34;
 const PREVIEW_INTERVAL_MS = 120;
 
 // Pull the finger away from the bar and the same swipe covers less time, so a
@@ -63,12 +62,19 @@ export const createSeekBar = (video) => {
     root.classList.add('is-scrubbing');
   };
 
+  // Measured rather than assumed: the bar sits a fifth of the way up the
+  // screen, and where exactly that lands depends on the phone.
+  const barCenter = (fallback) => {
+    const rect = track.getBoundingClientRect();
+    if (rect.height === 0) return fallback;
+    return rect.top + rect.height / 2;
+  };
+
   const move = ({ dx, y, width, height }) => {
     const total = duration();
     if (total === 0) return;
 
-    const barCenter = height - BAR_CENTER_FROM_BOTTOM_PX;
-    const step = precisionFor(Math.abs(y - barCenter));
+    const step = precisionFor(Math.abs(y - barCenter(height)));
     scrubTime += (dx / width) * total * step.factor;
     scrubTime = Math.min(total, Math.max(0, scrubTime));
     paint(scrubTime);
diff --git a/src/content/gestures/recognizer.js b/src/content/gestures/recognizer.js
index 402d54c..77c71db 100644
--- a/src/content/gestures/recognizer.js
+++ b/src/content/gestures/recognizer.js
@@ -60,9 +60,10 @@ export const createRecognizer = (surface, handlers) => {
   };
 
   const registerTap = (zone) => {
-    // A tap in the pause box acts at once; the side boxes have to wait out the
-    // window because a second tap there means "seek", not "show the controls".
-    if (zone === ZONE.PAUSE) {
+    // A tap on bare picture acts at once — it only brings the controls up or
+    // puts them away. The side boxes have to wait the window out, because a
+    // second tap there means "seek", not "show the controls".
+    if (zone === ZONE.DEAD) {
       emit('tap', { zone });
       return;
     }
diff --git a/src/content/gestures/zones.js b/src/content/gestures/zones.js
index 3e5deea..4edc5f6 100644
--- a/src/content/gestures/zones.js
+++ b/src/content/gestures/zones.js
@@ -1,18 +1,23 @@
 export const ZONE = {
   SEEK: 'seek',
-  PAUSE: 'pause',
   HOLD_LEFT: 'holdLeft',
   HOLD_RIGHT: 'holdRight',
   DEAD: 'dead',
 };
 
-// Bounded targets with dead space between them: a thumb landing off-target
-// does nothing rather than triggering the nearest control.
-const SEEK_BAND_PX = 72;
+// Every gesture target is a bounded box with dead space around it. A thumb that
+// lands off-target does nothing at all, which is the only way to stop the
+// player from acting on a touch that was never meant for it.
+//
+// The bottom fifth of the screen belongs to Android: that is where the home
+// swipe starts, and a seek band reaching into it turned "put the app away" into
+// "jump to the middle of the film". Everything of ours stays above it.
+const SEEK_TOP = 0.72;
+const SEEK_BOTTOM = 0.88;
 
 const BOXES = [
-  { zone: ZONE.HOLD_LEFT, center: 0.23, width: 0.18, top: 0.2, bottom: 0.74 },
-  { zone: ZONE.HOLD_RIGHT, center: 0.8, width: 0.18, top: 0.2, bottom: 0.74 },
+  { zone: ZONE.HOLD_LEFT, center: 0.23, width: 0.18, top: 0.18, bottom: 0.56 },
+  { zone: ZONE.HOLD_RIGHT, center: 0.8, width: 0.18, top: 0.18, bottom: 0.56 },
 ];
 
 const isInsideBox = (box, x, y, width, height) => {
@@ -22,15 +27,15 @@ const isInsideBox = (box, x, y, width, height) => {
   return y >= box.top * height && y <= box.bottom * height;
 };
 
-// Pause is the fallback rather than a box of its own: it is the hidden button
-// the whole picture acts as, so it cannot be missed.
+// Pausing is not a zone any more. It is the play button and nothing else, so a
+// tap on the picture can only ever bring the controls up or put them away.
 export const hitTest = (x, y, width, height) => {
-  if (y >= height - SEEK_BAND_PX) return ZONE.SEEK;
+  if (y >= SEEK_TOP * height && y <= SEEK_BOTTOM * height) return ZONE.SEEK;
 
   for (const box of BOXES) {
     if (isInsideBox(box, x, y, width, height)) return box.zone;
   }
-  return ZONE.PAUSE;
+  return ZONE.DEAD;
 };
 
 export const isDragZone = (zone) => zone === ZONE.SEEK;
diff --git a/src/content/player.css b/src/content/player.css
index e3efc6b..c64f6c0 100644
--- a/src/content/player.css
+++ b/src/content/player.css
@@ -11,6 +11,19 @@
   -webkit-tap-highlight-color: transparent;
   -webkit-touch-callout: none;
   user-select: none;
+
+  /* One curve for everything that moves: slow to leave, quick to arrive, the
+     way a sheet slides on a phone. */
+  --ease: cubic-bezier(0.32, 0.72, 0, 1);
+  --chrome-fade: 280ms;
+  --glass: rgba(20, 19, 26, 0.62);
+  --shadow-soft: 0 10px 34px rgba(0, 0, 0, 0.42);
+  --shadow-deep: 0 18px 52px rgba(0, 0, 0, 0.55);
+  --icon-shadow: drop-shadow(0 2px 5px rgba(0, 0, 0, 0.65));
+
+  /* The seek bar and everything that lines up with it stay clear of the
+     strip along the bottom where the Android home swipe lives. */
+  --seek-lift: 12%;
 }
 
 .layer {
@@ -32,9 +45,33 @@
   transition: opacity 200ms ease;
 }
 
+/* Depth under the controls rather than a flat wash: the film keeps playing
+   underneath, and the buttons still have to be legible over a white scene. */
+.scrim {
+  background:
+    linear-gradient(
+      to bottom,
+      rgba(0, 0, 0, 0.5) 0%,
+      rgba(0, 0, 0, 0.16) 16%,
+      rgba(0, 0, 0, 0) 34%
+    ),
+    linear-gradient(
+      to top,
+      rgba(0, 0, 0, 0.62) 0%,
+      rgba(0, 0, 0, 0.22) 22%,
+      rgba(0, 0, 0, 0) 46%
+    ),
+    radial-gradient(
+      ellipse 70% 55% at 50% 50%,
+      rgba(0, 0, 0, 0.26) 0%,
+      rgba(0, 0, 0, 0) 100%
+    );
+  pointer-events: none;
+}
+
 .chrome {
   opacity: 1;
-  transition: opacity 220ms ease;
+  transition: opacity var(--chrome-fade) var(--ease);
 }
 
 .chrome[hidden] {
@@ -43,6 +80,26 @@
   pointer-events: none;
 }
 
+/* Each band leaves in the direction it came from, so bringing the controls
+   back reads as one movement instead of a flash. */
+.topbar,
+.seekbar,
+.centre-row {
+  transition: transform 340ms var(--ease);
+}
+
+.chrome[hidden] .topbar {
+  transform: translateY(-12px);
+}
+
+.chrome[hidden] .seekbar {
+  transform: translateY(16px);
+}
+
+.chrome[hidden] .centre-row {
+  transform: translate(-50%, -50%) scale(0.94);
+}
+
 .topbar {
   position: absolute;
   top: 0;
@@ -54,7 +111,6 @@
   padding: 14px 0;
   padding-left: max(30px, env(safe-area-inset-left));
   padding-right: max(30px, env(safe-area-inset-right));
-  background: linear-gradient(to bottom, rgba(0, 0, 0, 0.55), transparent);
   pointer-events: auto;
 }
 
@@ -73,11 +129,11 @@
   background: none;
   color: #fff;
   cursor: pointer;
-  transition: transform 160ms ease;
+  transition: transform 220ms var(--ease);
 }
 
 .button:active {
-  transform: scale(0.92);
+  transform: scale(0.88);
 }
 
 .button[aria-pressed='true'] {
@@ -94,6 +150,7 @@
   stroke-width: 1.9;
   stroke-linecap: round;
   stroke-linejoin: round;
+  filter: var(--icon-shadow);
 }
 
 .surface {
@@ -107,8 +164,8 @@
   position: absolute;
   left: 0;
   right: 0;
-  bottom: 0;
-  padding: 0 max(30px, env(safe-area-inset-right)) 26px
+  bottom: var(--seek-lift);
+  padding: 0 max(30px, env(safe-area-inset-right)) 0
     max(30px, env(safe-area-inset-left));
   pointer-events: none;
 }
@@ -123,7 +180,7 @@
   min-width: 58px;
   font-size: 13px;
   font-variant-numeric: tabular-nums;
-  text-shadow: 0 1px 3px rgba(0, 0, 0, 0.85);
+  text-shadow: 0 1px 4px rgba(0, 0, 0, 0.9);
 }
 
 .time:last-child {
@@ -135,7 +192,10 @@
   flex: 1;
   height: 14px;
   border-radius: 999px;
-  background: rgba(255, 255, 255, 0.3);
+  background: rgba(255, 255, 255, 0.26);
+  box-shadow:
+    0 2px 10px rgba(0, 0, 0, 0.4),
+    inset 0 0 0 0.5px rgba(255, 255, 255, 0.18);
   overflow: hidden;
 }
 
@@ -151,18 +211,19 @@
   position: absolute;
   top: 50%;
   left: 50%;
-  transform: translate(-50%, -50%) scale(0.9);
+  transform: translate(-50%, -50%) scale(0.92);
   padding: 10px 18px;
-  border-radius: 14px;
-  background: rgba(20, 19, 26, 0.62);
+  border-radius: 16px;
+  background: var(--glass);
+  box-shadow: var(--shadow-soft);
   backdrop-filter: blur(18px);
   font-size: 16px;
   font-variant-numeric: tabular-nums;
   opacity: 0;
   pointer-events: none;
   transition:
-    opacity 160ms ease,
-    transform 160ms ease;
+    opacity 200ms var(--ease),
+    transform 260ms var(--ease);
 }
 
 .toast.is-visible {
@@ -177,17 +238,31 @@
   right: max(30px, env(safe-area-inset-right));
   width: min(330px, 50vw);
   padding: 10px 12px;
-  border-radius: 16px;
+  border-radius: 18px;
   background: rgba(20, 19, 26, 0.66);
+  box-shadow: var(--shadow-deep);
   backdrop-filter: blur(22px);
   display: none;
   flex-direction: column;
   gap: 6px;
   pointer-events: auto;
+  transform-origin: top right;
 }
 
 .panel.is-open {
   display: flex;
+  animation: panel-in 260ms var(--ease);
+}
+
+@keyframes panel-in {
+  from {
+    opacity: 0;
+    transform: translateY(-6px) scale(0.96);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
 }
 
 .step-row {
@@ -222,11 +297,15 @@
   font-size: 20px;
   line-height: 1;
   cursor: pointer;
+  transition:
+    background 160ms var(--ease),
+    transform 200ms var(--ease);
 }
 
 .step-button:active {
   background: rgba(236, 236, 242, 0.9);
   color: #16151c;
+  transform: scale(0.94);
 }
 
 .step-button:disabled {
@@ -291,6 +370,13 @@
   font: inherit;
   font-size: 13px;
   cursor: pointer;
+  transition:
+    background 160ms var(--ease),
+    transform 200ms var(--ease);
+}
+
+.chip:active {
+  transform: scale(0.94);
 }
 
 .chip[aria-pressed='true'] {
@@ -312,7 +398,7 @@
   position: absolute;
   left: 8%;
   right: 8%;
-  bottom: 78px;
+  bottom: calc(var(--seek-lift) + 46px);
   text-align: center;
   font-size: calc(20px * var(--cue-scale));
   line-height: 1.35;
@@ -322,13 +408,16 @@
     0 0 2px rgba(0, 0, 0, 0.9);
   opacity: 0;
   pointer-events: none;
+  transition: opacity 180ms var(--ease);
 }
 
 .cue.is-visible {
   opacity: 1;
 }
 
-/* A flex child of the centre row, so it lines up with the skip buttons. */
+/* A flex child of the centre row, so it lines up with the skip buttons. The
+   pause target is this button and nothing else — tapping the picture only
+   brings the controls up or puts them away. */
 .play-button {
   width: 114px;
   height: 114px;
@@ -342,7 +431,7 @@
   color: #fff;
   cursor: pointer;
   pointer-events: auto;
-  transition: transform 160ms ease;
+  transition: transform 220ms var(--ease);
 }
 
 .play-button svg {
@@ -354,7 +443,7 @@
   stroke-width: 2.4;
   stroke-linejoin: round;
   stroke-linecap: round;
-  stroke-linejoin: round;
+  filter: var(--icon-shadow);
 }
 
 .centre-row {
@@ -378,7 +467,10 @@
   pointer-events: none;
 }
 
-.play-button:active,
+.play-button:active {
+  transform: scale(0.92);
+}
+
 .skip-button:active {
   transform: scale(0.9);
 }
@@ -394,7 +486,7 @@
   background: none;
   color: #fff;
   cursor: pointer;
-  transition: transform 160ms ease;
+  transition: transform 220ms var(--ease);
 }
 
 .seek-area {
@@ -411,20 +503,24 @@
   position: absolute;
   bottom: calc(100% + 12px);
   left: var(--progress);
-  transform: translateX(-50%);
+  transform: translateX(-50%) scale(0.94);
   padding: 4px 10px;
-  border-radius: 8px;
+  border-radius: 10px;
   background: rgba(20, 19, 26, 0.82);
+  box-shadow: var(--shadow-soft);
   font-size: 14px;
   font-variant-numeric: tabular-nums;
   white-space: nowrap;
   opacity: 0;
-  transition: opacity 140ms ease;
+  transition:
+    opacity 160ms var(--ease),
+    transform 220ms var(--ease);
   pointer-events: none;
 }
 
 .seekbar.is-scrubbing .seek-time {
   opacity: 1;
+  transform: translateX(-50%) scale(1);
 }
 
 .skip-button svg {
@@ -435,8 +531,30 @@
   stroke: currentColor;
   stroke-width: 1.7;
   stroke-linecap: round;
+  filter: var(--icon-shadow);
 }
 
 .skip-button text {
   font-family: inherit;
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .chrome,
+  .topbar,
+  .seekbar,
+  .centre-row,
+  .toast,
+  .cue,
+  .button,
+  .chip,
+  .step-button,
+  .play-button,
+  .skip-button,
+  .seek-time {
+    transition-duration: 1ms;
+  }
+
+  .panel.is-open {
+    animation: none;
+  }
+}
diff --git a/test/unit/zones.test.js b/test/unit/zones.test.js
new file mode 100644
index 0000000..065dbd3
--- /dev/null
+++ b/test/unit/zones.test.js
@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import {
+  hitTest,
+  isDragZone,
+  isHoldZone,
+  ZONE,
+} from '../../src/content/gestures/zones.js';
+
+const WIDTH = 800;
+const HEIGHT = 360;
+
+const zoneAt = (xRatio, yRatio) =>
+  hitTest(xRatio * WIDTH, yRatio * HEIGHT, WIDTH, HEIGHT);
+
+test('the bottom of the screen belongs to the system, not the player', () => {
+  for (const yRatio of [0.89, 0.94, 0.99]) {
+    assert.equal(zoneAt(0.5, yRatio), ZONE.DEAD);
+    assert.equal(zoneAt(0.05, yRatio), ZONE.DEAD);
+    assert.equal(zoneAt(0.95, yRatio), ZONE.DEAD);
+  }
+});
+
+test('the seek band sits above the home gesture', () => {
+  assert.equal(zoneAt(0.5, 0.73), ZONE.SEEK);
+  assert.equal(zoneAt(0.5, 0.87), ZONE.SEEK);
+  assert.equal(zoneAt(0.02, 0.8), ZONE.SEEK);
+});
+
+test('the middle of the picture is not a pause button', () => {
+  assert.equal(zoneAt(0.5, 0.5), ZONE.DEAD);
+  assert.equal(zoneAt(0.5, 0.1), ZONE.DEAD);
+  assert.equal(ZONE.PAUSE, undefined);
+});
+
+test('the hold boxes stay clear of the seek band', () => {
+  assert.equal(zoneAt(0.23, 0.4), ZONE.HOLD_LEFT);
+  assert.equal(zoneAt(0.8, 0.4), ZONE.HOLD_RIGHT);
+  assert.equal(zoneAt(0.23, 0.8), ZONE.SEEK);
+  assert.equal(zoneAt(0.8, 0.8), ZONE.SEEK);
+});
+
+test('only the seek band drags and only the side boxes hold', () => {
+  assert.ok(isDragZone(ZONE.SEEK));
+  assert.ok(!isDragZone(ZONE.DEAD));
+  assert.ok(isHoldZone(ZONE.HOLD_LEFT));
+  assert.ok(isHoldZone(ZONE.HOLD_RIGHT));
+  assert.ok(!isHoldZone(ZONE.DEAD));
+});

From c22b08721d4c1a54ab967b6f02550978c8af7adc Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Thu, 6 Aug 2026 10:40:46 +0300
Subject: [PATCH 04/23] feat(video): quality, site captions and
 picture-in-picture
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Everything a site's own player knows about itself lives in the page's
JavaScript. Firefox lets a content script read that through waived Xray
wrappers, so the extension asks the player rather than re-implementing it:
no code is injected into the page and nothing is evaluated from a string.

Quality is an adapter per engine — <source> lists, YouTube, hls.js,
dash.js, Shaka — probed again each time the sheet opens, because a stream
only learns its ladder after the first segments land. A player that exposes
no way in reports the resolution it is playing instead of offering a choice
that would do nothing.

Captions cover the players that paint their own instead of exposing a text
track. YouTube's list comes from its player API and the text it renders is
mirrored into our cue layer, which is why subtitles were missing there.

The picture used to slide to an edge or stretch across the screen because
the site kept rewriting the video's inline style. Position and offsets are
now pinned with the size and re-pinned whenever the site writes over them,
and the zoom is re-derived from the viewer's intent on every relayout.

Losing fullscreen while the app is on its way to the background is what
Android's floating-window hand-off looks like, so it is no longer read as
the viewer leaving the player. The button uses the standard API where Gecko
has one, and a Fullscreen switch in the sheet runs the player as an overlay
for anyone who would rather keep the ordinary single swipe home.

Pausing no longer fades the picture to grey: people pause to look at it.
And the subtitle file button now has the handler it was always missing.
---
 eslint.config.js                     |   9 +-
 src/content/controls/menu.js         | 145 ++++++++----
 src/content/session.js               | 176 +++++++++++++--
 src/content/ui.js                    |  89 +++++---
 src/content/video/pageapi.js         | 109 +++++++++
 src/content/video/quality.js         |  75 ++++---
 src/content/video/qualityadapters.js | 318 +++++++++++++++++++++++++++
 src/content/video/sitecaptions.js    | 183 +++++++++++++++
 src/content/video/tracks.js          |  51 ++++-
 src/content/video/visuals.js         | 111 ++++++----
 10 files changed, 1089 insertions(+), 177 deletions(-)
 create mode 100644 src/content/video/pageapi.js
 create mode 100644 src/content/video/qualityadapters.js
 create mode 100644 src/content/video/sitecaptions.js

diff --git a/eslint.config.js b/eslint.config.js
index 7d48fb6..6fae826 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -19,7 +19,14 @@ export default [
   {
     files: ['src/**/*.js'],
     languageOptions: {
-      globals: { ...globals.browser, ...globals.webextensions },
+      globals: {
+        ...globals.browser,
+        ...globals.webextensions,
+        // Firefox gives content scripts these for talking to the page's own
+        // compartment; they are not part of the standard browser globals.
+        cloneInto: 'readonly',
+        exportFunction: 'readonly',
+      },
     },
   },
   {
diff --git a/src/content/controls/menu.js b/src/content/controls/menu.js
index 7aa2037..26495b4 100644
--- a/src/content/controls/menu.js
+++ b/src/content/controls/menu.js
@@ -4,7 +4,19 @@ const SPEEDS = [0.5, 0.75, 1, 1.25, 1.5, 2];
 const SUBTITLE_SCALES = [0.8, 1, 1.25, 1.6];
 const SYNC_STEP_SECONDS = 0.5;
 
-const buildChips = (label, options, onSelect) => {
+// A row of chips whose contents are repainted rather than rebuilt, because a
+// streaming site only learns what it can offer after the film has started and
+// the sheet has to be able to say so the next time it opens.
+const buildChipRow = (label) => {
+  const chips = el('div', { class: 'chips' });
+  const row = el('div', { class: 'menu-row' }, [
+    el('span', { class: 'menu-label', text: label }),
+    chips,
+  ]);
+  return { row, chips };
+};
+
+const paintChips = (holder, options, onSelect) => {
   const chips = options.map((option) =>
     el('button', {
       class: 'chip',
@@ -14,15 +26,9 @@ const buildChips = (label, options, onSelect) => {
     }),
   );
 
-  const row = el('div', { class: 'menu-row' }, [
-    el('span', { class: 'menu-label', text: label }),
-    el('div', { class: 'chips' }, chips),
-  ]);
-
   const setActive = (id) => {
     for (const chip of chips) {
-      const isActive = chip.dataset.id === String(id);
-      chip.setAttribute('aria-pressed', String(isActive));
+      chip.setAttribute('aria-pressed', String(chip.dataset.id === String(id)));
     }
   };
 
@@ -35,9 +41,12 @@ const buildChips = (label, options, onSelect) => {
     });
   }
 
-  return { row, setActive };
+  holder.chips.replaceChildren(...chips);
+  return setActive;
 };
 
+const buildNote = (text) => el('span', { class: 'menu-note', text });
+
 const buildStepper = (label, onStep, initial) => {
   const value = el('span', { class: 'step-value', text: initial });
   const minus = el('button', {
@@ -64,29 +73,64 @@ const buildStepper = (label, onStep, initial) => {
   ]);
 };
 
+const buildToggle = (label, isOn, onToggle) => {
+  const chip = el('button', { class: 'chip', type: 'button', text: label });
+  chip.setAttribute('aria-pressed', String(isOn));
+  chip.addEventListener('click', () => {
+    const next = chip.getAttribute('aria-pressed') !== 'true';
+    chip.setAttribute('aria-pressed', String(next));
+    onToggle(next);
+  });
+  return chip;
+};
+
 export const createMenu = ({
   video,
   tracks,
   quality,
+  settings,
   onStyle,
   onPickFile,
   onRate,
+  onImmersive,
 }) => {
-  const speed = buildChips(
-    'Speed',
+  const speedRow = buildChipRow('Speed');
+  const setSpeed = paintChips(
+    speedRow,
     SPEEDS.map((rate) => ({ id: rate, label: `${rate}x` })),
     (rate) => {
       video.playbackRate = rate;
       onRate(rate);
     },
   );
-  speed.setActive(video.playbackRate);
+  setSpeed(video.playbackRate);
 
-  const subtitleOptions = [{ id: -1, label: 'Off' }, ...tracks.list()];
-  const subtitles = buildChips('Subtitles', subtitleOptions, (id) => {
-    tracks.select(id);
-  });
-  subtitles.setActive(tracks.getSelected());
+  const subtitleRow = buildChipRow('Subtitles');
+  let setSubtitle = () => {};
+
+  const paintSubtitles = () => {
+    const options = [{ id: -1, label: 'Off' }, ...tracks.list()];
+    setSubtitle = paintChips(subtitleRow, options, (id) => tracks.select(id));
+    setSubtitle(tracks.getSelected());
+  };
+
+  const qualityRow = buildChipRow('Quality');
+
+  // The site keeps the ladder; all we do is ask for a rung. When there is no
+  // way in, the row says what is playing instead of pretending to offer a
+  // choice that would do nothing.
+  const paintQuality = () => {
+    quality.refresh();
+    const options = quality.getOptions();
+    if (options.length === 0) {
+      qualityRow.chips.replaceChildren(buildNote(quality.describe()));
+      return;
+    }
+    const setQuality = paintChips(qualityRow, options, (id) => {
+      quality.select(id);
+    });
+    setQuality(quality.getCurrent());
+  };
 
   let scaleIndex = SUBTITLE_SCALES.indexOf(1);
   const sizeRow = buildStepper(
@@ -119,51 +163,58 @@ export const createMenu = ({
   });
   loadButton.addEventListener('click', onPickFile);
 
-  const nativeToggle = el('button', {
-    class: 'chip',
-    type: 'button',
-    text: 'Native rendering',
-  });
-  nativeToggle.addEventListener('click', () => {
-    const next = !tracks.isNative();
-    tracks.setNative(next);
-    nativeToggle.setAttribute('aria-pressed', String(next));
+  const nativeToggle = buildToggle('Native', tracks.isNative(), () => {
+    tracks.setNative(!tracks.isNative());
   });
 
-  const qualityRow = quality.isSwitchable()
-    ? buildChips('Quality', quality.options, (id) => quality.select(id)).row
-    : el('div', { class: 'menu-row' }, [
-        el('span', { class: 'menu-label', text: 'Quality' }),
-        el('span', { class: 'menu-note', text: quality.describe() }),
-      ]);
+  const immersiveToggle = buildToggle(
+    'Fullscreen',
+    settings.isFullscreenTakeoverOn,
+    onImmersive,
+  );
+
+  paintSubtitles();
+  paintQuality();
 
   const root = el('div', { class: 'panel menu' }, [
-    speed.row,
-    subtitles.row,
+    speedRow.row,
+    subtitleRow.row,
     sizeRow,
     syncRow,
     el('div', { class: 'menu-row' }, [
       el('span', { class: 'menu-label', text: 'Source' }),
       el('div', { class: 'chips' }, [loadButton, nativeToggle]),
     ]),
-    qualityRow,
+    qualityRow.row,
+    el('div', { class: 'menu-row' }, [
+      el('span', { class: 'menu-label', text: 'Screen' }),
+      el('div', { class: 'chips' }, [immersiveToggle]),
+    ]),
   ]);
 
+  // Both lists can grow while the film plays — a caption track switched on in
+  // the site's own player, a quality ladder that finished loading — so they are
+  // read again every time the sheet is opened.
+  const refresh = () => {
+    paintSubtitles();
+    paintQuality();
+  };
+
+  const open = () => {
+    refresh();
+    root.classList.add('is-open');
+  };
+
   return {
     root,
-    toggle: () => root.classList.toggle('is-open'),
+    refresh,
+    open,
+    toggle: () => {
+      if (root.classList.contains('is-open')) root.classList.remove('is-open');
+      else open();
+    },
     close: () => root.classList.remove('is-open'),
     isOpen: () => root.classList.contains('is-open'),
-    setSubtitle: (id) => subtitles.setActive(id),
-    refreshSubtitles: (id) => {
-      const options = [{ id: -1, label: 'Off' }, ...tracks.list()];
-      const rebuilt = buildChips('Subtitles', options, (next) =>
-        tracks.select(next),
-      );
-      subtitles.row.replaceWith(rebuilt.row);
-      subtitles.row = rebuilt.row;
-      subtitles.setActive = rebuilt.setActive;
-      rebuilt.setActive(id);
-    },
+    setSubtitle: (id) => setSubtitle(id),
   };
 };
diff --git a/src/content/session.js b/src/content/session.js
index 1fdd185..1e2efdb 100644
--- a/src/content/session.js
+++ b/src/content/session.js
@@ -3,6 +3,8 @@ import { createShadowHost, el, pinStyle } from './shell.js';
 import playerCss from './player.css';
 
 const STALL_GRACE_MS = 400;
+const EMPTIED_GRACE_MS = 600;
+const RECOVER_DELAY_MS = 250;
 
 const STAGE_STYLE = {
   position: 'fixed',
@@ -20,7 +22,19 @@ const STAGE_STYLE = {
   'z-index': '2147483646',
 };
 
+// A site's own player keeps rewriting the video's inline style — YouTube sets
+// a pixel width, height and offset on every layout pass — which is what used to
+// leave the picture stuck against the left edge or stretched across the screen
+// after coming back from another app. Position and offsets are pinned here too,
+// not only the size, and re-pinned whenever the site writes over them.
 const VIDEO_STYLE = {
+  inset: 'auto',
+  position: 'relative',
+  left: '0',
+  top: '0',
+  right: 'auto',
+  bottom: 'auto',
+  float: 'none',
   width: '100%',
   height: '100%',
   'max-width': 'none',
@@ -29,12 +43,16 @@ const VIDEO_STYLE = {
   'min-height': '0',
   margin: '0',
   padding: '0',
+  border: '0',
   display: 'block',
   'object-fit': 'contain',
+  'object-position': '50% 50%',
   background: '#000',
   'transform-origin': 'center center',
 };
 
+const VIDEO_STYLE_KEYS = Object.keys(VIDEO_STYLE);
+
 const captureVideoState = (video) => ({
   cssText: video.style.cssText,
   hasControlsAttribute: video.hasAttribute('controls'),
@@ -66,10 +84,22 @@ const auditRestore = (video, state) => {
   return false;
 };
 
+// Written only when it has actually been disturbed, so re-pinning cannot chase
+// its own mutation record round in a loop.
+const isPinned = (video) =>
+  VIDEO_STYLE_KEYS.every(
+    (name) =>
+      video.style.getPropertyValue(name) === VIDEO_STYLE[name] &&
+      video.style.getPropertyPriority(name) === 'important',
+  );
+
+// navigationUI is deliberately left at its default. Asking Gecko to hide it put
+// Android into sticky immersive mode, where the first swipe up only brings the
+// system bars back and a second one is needed to leave the app.
 const requestFullscreen = async (element) => {
   if (!document.fullscreenEnabled) return false;
   try {
-    await element.requestFullscreen({ navigationUI: 'hide' });
+    await element.requestFullscreen();
     return true;
   } catch (error) {
     console.warn('Nocturne: fullscreen refused', error);
@@ -94,6 +124,12 @@ const unlockOrientation = () => {
   }
 };
 
+// Losing fullscreen is how the user leaves the player, and it is also how
+// Android announces that it is taking the video into a floating window. The two
+// look identical at the moment they happen and only differ a beat later, when
+// an app that has gone into the background is no longer the focused one.
+const isBackgrounded = () => document.hidden || !document.hasFocus();
+
 export const createSession = (video, { onExit, settings, onPersist }) => {
   const state = captureVideoState(video);
   const anchor = document.createComment('nocturne-player');
@@ -101,11 +137,14 @@ export const createSession = (video, { onExit, settings, onPersist }) => {
   const ui = createShadowHost(playerCss);
 
   const teardown = [];
+  const timers = new Set();
 
   let isActive = false;
   let isOrientationLocked = false;
-  let stallTimer = null;
+  let isFullscreenWanted = settings.isFullscreenTakeoverOn;
+  let styleGuard = null;
   let overlay = null;
+  let relayoutFrame = 0;
 
   const layers = {
     warm: el('div', { class: 'layer warm' }),
@@ -117,13 +156,46 @@ export const createSession = (video, { onExit, settings, onPersist }) => {
     teardown.push(() => target.removeEventListener(type, handler, options));
   };
 
+  const later = (handler, delay) => {
+    const timer = setTimeout(() => {
+      timers.delete(timer);
+      handler();
+    }, delay);
+    timers.add(timer);
+    return timer;
+  };
+
+  const pinVideo = () => {
+    if (isPinned(video)) return;
+    pinStyle(video, VIDEO_STYLE);
+  };
+
+  const relayout = () => {
+    relayoutFrame = 0;
+    pinVideo();
+    if (overlay) overlay.relayout();
+  };
+
+  const scheduleRelayout = () => {
+    if (relayoutFrame !== 0) return;
+    relayoutFrame = requestAnimationFrame(relayout);
+  };
+
   const mount = () => {
     stage.dataset.nocturnePlayer = '';
     pinStyle(stage, STAGE_STYLE);
 
     video.replaceWith(anchor);
     video.removeAttribute('controls');
-    pinStyle(video, VIDEO_STYLE);
+    pinVideo();
+
+    // The site is free to keep laying its player out; it just does not get to
+    // move the picture we are showing.
+    styleGuard = new MutationObserver(pinVideo);
+    styleGuard.observe(video, {
+      attributes: true,
+      attributeFilter: ['style', 'width', 'height'],
+    });
 
     stage.append(video, ui.host);
     ui.shadow.append(layers.warm, layers.dim);
@@ -131,6 +203,8 @@ export const createSession = (video, { onExit, settings, onPersist }) => {
   };
 
   const unmount = () => {
+    if (styleGuard) styleGuard.disconnect();
+    styleGuard = null;
     if (overlay) overlay.destroy();
     overlay = null;
     stage.remove();
@@ -143,8 +217,10 @@ export const createSession = (video, { onExit, settings, onPersist }) => {
     if (!isActive) return;
     isActive = false;
 
-    if (stallTimer !== null) clearTimeout(stallTimer);
-    stallTimer = null;
+    for (const timer of timers) clearTimeout(timer);
+    timers.clear();
+    if (relayoutFrame !== 0) cancelAnimationFrame(relayoutFrame);
+    relayoutFrame = 0;
 
     for (const undo of teardown) undo();
     teardown.length = 0;
@@ -160,18 +236,71 @@ export const createSession = (video, { onExit, settings, onPersist }) => {
     onExit();
   };
 
+  // Gecko keeps a media element playing across a re-parent, but a site shim
+  // that reloads it leaves us holding an empty player. A quality switch empties
+  // the element too, so the verdict waits until the dust settles.
+  const watchForTeardown = () => {
+    listen(video, 'emptied', () => {
+      later(() => {
+        const hasSource = video.currentSrc !== '' || video.srcObject !== null;
+        if (hasSource || video.readyState > 0) return;
+        console.warn('Nocturne: the video was torn down, backing out');
+        exit();
+      }, EMPTIED_GRACE_MS);
+    });
+  };
+
+  const applyLandscape = async () => {
+    if (!settings.isAutoLandscapeOn) return;
+    const isLocked = await lockLandscape();
+    if (isLocked) isOrientationLocked = true;
+  };
+
+  const restoreFullscreen = () => {
+    if (!isFullscreenWanted) return;
+    if (document.fullscreenElement === stage) return;
+    // Gecko may refuse this without a fresh gesture. The stage covers the
+    // viewport on its own, so the player stays usable either way.
+    requestFullscreen(stage).then((isOn) => {
+      if (isOn) applyLandscape();
+      scheduleRelayout();
+    });
+  };
+
+  const watchForReturn = () => {
+    listen(document, 'fullscreenchange', () => {
+      if (document.fullscreenElement === stage) return;
+      later(() => {
+        if (!isActive) return;
+        if (isBackgrounded()) return;
+        exit();
+      }, RECOVER_DELAY_MS);
+    });
+
+    // Coming back from a floating window or from another app: re-take the
+    // screen and re-fit the picture to whatever shape it is now.
+    listen(document, 'visibilitychange', () => {
+      if (document.hidden) return;
+      later(() => {
+        if (!isActive) return;
+        restoreFullscreen();
+        scheduleRelayout();
+      }, RECOVER_DELAY_MS);
+    });
+
+    listen(window, 'resize', scheduleRelayout);
+    listen(window, 'orientationchange', scheduleRelayout);
+    listen(video, 'loadedmetadata', scheduleRelayout);
+    listen(video, 'resize', scheduleRelayout);
+  };
+
   const enter = async () => {
     if (isActive) return false;
     isActive = true;
 
-    // Gecko keeps a media element playing across a re-parent, but if some site
-    // shim reloads it we back out rather than leave the page in a broken state.
-    listen(video, 'emptied', () => {
-      console.warn('Nocturne: the video reloaded when moved, backing out');
-      exit();
-    });
-
+    watchForTeardown();
     mount();
+
     overlay = createOverlay({
       video,
       stage,
@@ -180,20 +309,27 @@ export const createSession = (video, { onExit, settings, onPersist }) => {
       onExit: exit,
       settings,
       onPersist,
-      wasPlaying: state.wasPlaying,
+      onImmersiveChange: (isOn) => {
+        isFullscreenWanted = isOn;
+        if (isOn) {
+          restoreFullscreen();
+        } else if (document.fullscreenElement === stage) {
+          document.exitFullscreen().catch(() => {});
+        }
+      },
     });
 
-    stallTimer = setTimeout(() => {
-      stallTimer = null;
+    later(() => {
       if (state.wasPlaying && video.paused) video.play().catch(() => {});
     }, STALL_GRACE_MS);
 
-    listen(document, 'fullscreenchange', () => {
-      if (document.fullscreenElement !== stage) exit();
-    });
+    watchForReturn();
 
-    await requestFullscreen(stage);
-    isOrientationLocked = await lockLandscape();
+    if (isFullscreenWanted) {
+      const isOn = await requestFullscreen(stage);
+      if (isOn) await applyLandscape();
+    }
+    scheduleRelayout();
     return true;
   };
 
diff --git a/src/content/ui.js b/src/content/ui.js
index e537bf5..325f9b3 100644
--- a/src/content/ui.js
+++ b/src/content/ui.js
@@ -12,6 +12,7 @@ const CHROME_IDLE_MS = 3000;
 const SCRUB_STEP_SECONDS = 0.2;
 const SCRUB_TICK_MS = 100;
 const TOAST_MS = 900;
+const HINT_MS = 2200;
 const SKIP_SECONDS = 10;
 const FILL_RETRY_MS = 400;
 
@@ -19,7 +20,7 @@ const ICON = {
   exit: 'M6 6l12 12M18 6L6 18',
   colour:
     'M12 3a9 9 0 1 0 0 18 2.5 2.5 0 0 0 0-5h-1a2 2 0 0 1 0-4h3a5 5 0 0 0 0-9z',
-  pip: 'M3 5h18v14H3zM12 12h7v5h-7z',
+  pip: 'M4 5h16v14H4zM12.5 12.5h6v5h-6z',
   menu: 'M4 7h16M4 12h16M4 17h16',
   play: 'M8 5 19 12 8 19z',
   pause: 'M6 5h3.6v14H6zM14.4 5h3.6v14h-3.6z',
@@ -72,9 +73,10 @@ export const createOverlay = ({
   onExit,
   settings,
   onPersist,
-  wasPlaying,
+  onImmersiveChange,
 }) => {
   const surface = el('div', { class: 'layer surface' });
+  const scrim = el('div', { class: 'layer scrim' });
   const toast = el('div', { class: 'toast' });
   const topbar = el('div', { class: 'topbar' });
   const chrome = el('div', { class: 'chrome' });
@@ -94,7 +96,7 @@ export const createOverlay = ({
   // were watching, not to the next one.
   video.playbackRate = 1;
 
-  const visuals = createVisuals(video, stage, wasPlaying);
+  const visuals = createVisuals(video, stage);
   const quality = createQuality(video);
   const tracks = createTrackManager(
     video,
@@ -113,14 +115,14 @@ export const createOverlay = ({
   let pinchBase = 1;
   let wasPlayingBeforeScrub = false;
 
-  const showToast = (text) => {
+  const showToast = (text, duration = TOAST_MS) => {
     toast.textContent = text;
     toast.classList.add('is-visible');
     if (toastTimer !== null) clearTimeout(toastTimer);
     toastTimer = setTimeout(() => {
       toastTimer = null;
       toast.classList.remove('is-visible');
-    }, TOAST_MS);
+    }, duration);
   };
 
   const applyWarmth = (value) => {
@@ -137,12 +139,17 @@ export const createOverlay = ({
     video,
     tracks,
     quality,
+    settings,
     onStyle: ({ scale }) => {
       cueBox.style.setProperty('--cue-scale', String(scale));
       onPersist({ subtitleScale: scale });
     },
     onPickFile: () => filePicker.click(),
     onRate: () => {},
+    onImmersive: (isOn) => {
+      onImmersiveChange(isOn);
+      onPersist({ isFullscreenTakeoverOn: isOn });
+    },
   });
 
   menuRef.setSubtitle = menu.setSubtitle;
@@ -165,7 +172,6 @@ export const createOverlay = ({
   const closePanels = () => {
     colorPanel.close();
     menu.close();
-    visuals.suppressFade(false);
     buttons.colour?.setAttribute('aria-pressed', 'false');
     buttons.menu?.setAttribute('aria-pressed', 'false');
     setChromeVisible(true);
@@ -190,7 +196,6 @@ export const createOverlay = ({
     if (scrubTimer === null) return;
     clearInterval(scrubTimer);
     scrubTimer = null;
-    visuals.suppressFade(false);
     if (wasPlayingBeforeScrub) video.play().catch(() => {});
   };
 
@@ -201,7 +206,6 @@ export const createOverlay = ({
     stopScrub();
     wasPlayingBeforeScrub = !video.paused;
     video.pause();
-    visuals.suppressFade(true);
     scrubTimer = setInterval(() => {
       const limit = Number.isFinite(video.duration)
         ? video.duration
@@ -214,13 +218,12 @@ export const createOverlay = ({
   const dragTargets = { [ZONE.SEEK]: seekBar };
 
   const recognizer = createRecognizer(surface, {
-    tap: ({ zone }) => {
+    tap: () => {
       if (isPanelOpen()) {
         closePanels();
         return;
       }
-      if (zone === ZONE.PAUSE) togglePlay();
-      else setChromeVisible(chrome.hasAttribute('hidden'));
+      setChromeVisible(chrome.hasAttribute('hidden'));
     },
     multiTap: ({ zone, count }) => {
       if (isPanelOpen()) {
@@ -283,43 +286,78 @@ export const createOverlay = ({
     menu.close();
     buttons.menu.setAttribute('aria-pressed', 'false');
     colorPanel.toggle();
-    const isOpen = colorPanel.isOpen();
-    buttons.colour.setAttribute('aria-pressed', String(isOpen));
-    visuals.suppressFade(isOpen);
+    buttons.colour.setAttribute('aria-pressed', String(colorPanel.isOpen()));
     setChromeVisible(true);
   });
 
   buttons.menu = buildButton('Settings', ICON.menu, () => {
     colorPanel.close();
-    visuals.suppressFade(false);
     buttons.colour.setAttribute('aria-pressed', 'false');
     menu.toggle();
     buttons.menu.setAttribute('aria-pressed', String(menu.isOpen()));
     setChromeVisible(true);
   });
 
+  // Where a thumb already is when the phone is held in landscape. Gecko has no
+  // web API for the floating window on Android — the system offers it when you
+  // leave the app with a video playing — so the button uses the standard API
+  // where it exists and otherwise sets the video up and says what to do.
+  const enterPictureInPicture = () => {
+    setChromeVisible(true);
+    if (video.paused) video.play().catch(() => {});
+    if (typeof video.requestPictureInPicture !== 'function') {
+      showToast('Swipe up to keep it floating', HINT_MS);
+      return;
+    }
+    video.requestPictureInPicture().catch(() => {
+      showToast('Swipe up to keep it floating', HINT_MS);
+    });
+  };
+
   topbar.append(
     buildButton('Exit player', ICON.exit, () => onExit()),
     el('div', { class: 'spacer' }),
     buttons.colour,
     buttons.menu,
+    buildButton('Picture in picture', ICON.pip, enterPictureInPicture),
   );
 
-  // Firefox for Android has no Picture-in-Picture API yet, so the button
-  // appears on its own once Gecko ships one.
-  if (document.pictureInPictureEnabled) {
-    const pip = buildButton('Picture in picture', ICON.pip, () => {
-      video.requestPictureInPicture().catch(() => {});
-    });
-    topbar.insertBefore(pip, buttons.colour);
-  }
+  chrome.append(
+    scrim,
+    topbar,
+    centreRow,
+    colorPanel.root,
+    menu.root,
+    seekBar.root,
+  );
 
-  chrome.append(topbar, centreRow, colorPanel.root, menu.root, seekBar.root);
+  // Reading a file the user picked themselves, straight into the cue list.
+  // Nothing leaves the device and nothing is parsed as markup.
+  const loadSubtitleFile = async () => {
+    const file = filePicker.files?.[0];
+    if (!file) return;
+    const text = await file.text();
+    filePicker.value = '';
+    const id = tracks.addCues(file.name.replace(/\.(srt|vtt)$/i, ''), text);
+    if (id === null) {
+      showToast('No subtitles in that file', HINT_MS);
+      return;
+    }
+    tracks.select(id);
+    menu.refresh();
+    showToast('Subtitles loaded', HINT_MS);
+  };
+
+  filePicker.addEventListener('change', () => {
+    loadSubtitleFile().catch((error) => {
+      console.error('Nocturne: could not read the subtitle file', error);
+      showToast('Could not read that file', HINT_MS);
+    });
+  });
 
   // Only the path data changes, so swapping play for pause cannot make the
   // button flicker or shift.
   const handlePlaybackChange = () => {
-    visuals.setPaused(video.paused);
     playPath.setAttribute('d', video.paused ? ICON.play : ICON.pause);
     setChromeVisible(true);
   };
@@ -351,6 +389,7 @@ export const createOverlay = ({
   setChromeVisible(true);
 
   return {
+    relayout: () => visuals.relayout(),
     destroy: () => {
       recognizer.destroy();
       seekBar.destroy();
diff --git a/src/content/video/pageapi.js b/src/content/video/pageapi.js
new file mode 100644
index 0000000..c29ebec
--- /dev/null
+++ b/src/content/video/pageapi.js
@@ -0,0 +1,109 @@
+// Everything a site's own player knows about itself — the quality ladder, the
+// caption list — lives in the page's JavaScript, which a content script sees
+// only through Gecko's Xray wrappers. Waiving those wrappers is the supported
+// way in on Firefox, and it stays a read of objects the page already made: no
+// code is injected into the page and nothing is evaluated from a string.
+//
+// Nothing here can throw at the caller. A site is free to have a getter that
+// raises, a method that is missing, or a value from a compartment we cannot
+// touch; every one of those means "this player cannot do that", not "the
+// player is broken".
+const MAX_SCANNED_KEYS = 500;
+
+export const pageWindow = () => window.wrappedJSObject ?? window;
+
+// Structured-cloned into the page's compartment so a page function can read it.
+// Falls back to the plain value where the helper is absent, which is a context
+// that already shares one compartment with the page.
+export const toPage = (value) => {
+  if (typeof cloneInto !== 'function') return value;
+  try {
+    return cloneInto(value, pageWindow());
+  } catch {
+    return value;
+  }
+};
+
+export const read = (object, key) => {
+  if (object === null || typeof object !== 'object') return null;
+  try {
+    const value = object[key];
+    return value === undefined ? null : value;
+  } catch {
+    return null;
+  }
+};
+
+export const call = (object, name, ...args) => {
+  if (object === null || typeof object !== 'object') return null;
+  let method = null;
+  try {
+    method = object[name];
+  } catch {
+    return null;
+  }
+  if (typeof method !== 'function') return null;
+  try {
+    const value = method.apply(object, args);
+    return value === undefined ? null : value;
+  } catch (error) {
+    console.warn(`Nocturne: ${name}() failed on the site's player`, error);
+    return null;
+  }
+};
+
+export const write = (object, key, value) => {
+  if (object === null || typeof object !== 'object') return false;
+  try {
+    object[key] = value;
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// Page arrays come from another compartment, so they are walked by index
+// rather than spread: an iterator that throws must not take the player down.
+export const toArray = (value) => {
+  const length = read(value, 'length');
+  if (typeof length !== 'number' || !Number.isFinite(length)) return [];
+  const items = [];
+  for (let index = 0; index < length; index++) {
+    items.push(read(value, index));
+  }
+  return items;
+};
+
+export const isFunction = (object, name) => {
+  if (object === null || typeof object !== 'object') return false;
+  try {
+    return typeof object[name] === 'function';
+  } catch {
+    return false;
+  }
+};
+
+// A last resort for players that keep their engine on a global under a name
+// only they know. Bounded, and every property read is guarded, because a getter
+// on a page global can throw or be expensive.
+export const findGlobal = (matches) => {
+  const scope = pageWindow();
+  let keys = [];
+  try {
+    keys = Object.keys(scope);
+  } catch {
+    return null;
+  }
+
+  const limit = Math.min(keys.length, MAX_SCANNED_KEYS);
+  for (let index = 0; index < limit; index++) {
+    const value = read(scope, keys[index]);
+    if (value === null || typeof value !== 'object') continue;
+    try {
+      if (matches(value)) return value;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+};
diff --git a/src/content/video/quality.js b/src/content/video/quality.js
index 97b8066..72aa908 100644
--- a/src/content/video/quality.js
+++ b/src/content/video/quality.js
@@ -1,50 +1,55 @@
-const labelFor = (source, index) => {
-  const explicit = source.dataset.label || source.getAttribute('title');
-  if (explicit) return explicit;
-  const match = /(\d{3,4})[pP]/.exec(source.src);
-  return match ? `${match[1]}p` : `Source ${index + 1}`;
-};
+import { ADAPTERS, AUTO_ID } from './qualityadapters.js';
+
+export { AUTO_ID };
 
-// Only what can honestly be offered: a site streaming HLS or DASH picks the
-// quality in its own JavaScript, out of reach from here.
+// A streaming player builds its quality ladder after the first segments land,
+// so the ladder is looked up again every time the sheet is opened rather than
+// once when the session starts.
 export const createQuality = (video) => {
-  const sources = Array.from(video.querySelectorAll('source'));
+  let adapter = null;
+  let options = [];
+
+  const detect = () => {
+    for (const create of ADAPTERS) {
+      try {
+        const candidate = create(video);
+        if (candidate !== null) return candidate;
+      } catch (error) {
+        console.warn('Nocturne: a quality adapter threw while probing', error);
+      }
+    }
+    return null;
+  };
 
-  const options = sources.map((source, index) => ({
-    id: index,
-    label: labelFor(source, index),
-    src: source.src,
-  }));
+  const refresh = () => {
+    adapter = detect();
+    if (adapter === null) {
+      options = [];
+      return options;
+    }
+    const listed = adapter.list();
+    const auto = adapter.hasAuto ? [{ id: AUTO_ID, label: 'Auto' }] : [];
+    options = listed.length > 0 ? auto.concat(listed) : [];
+    return options;
+  };
 
   const describe = () => {
     if (video.videoWidth === 0) return 'Set by the site';
     return `${video.videoWidth}×${video.videoHeight} · set by the site`;
   };
 
-  const select = (id) => {
-    const option = options[id];
-    if (!option || video.currentSrc === option.src) return;
-
-    const resumeAt = video.currentTime;
-    const wasPlaying = !video.paused;
-
-    const restore = () => {
-      video.removeEventListener('loadedmetadata', restore);
-      video.currentTime = resumeAt;
-      if (wasPlaying) video.play().catch(() => {});
-    };
-
-    video.addEventListener('loadedmetadata', restore);
-    video.src = option.src;
-    video.load();
-  };
+  refresh();
 
   return {
-    options,
+    refresh,
     describe,
-    select,
+    getOptions: () => options,
+    getEngine: () => (adapter === null ? null : adapter.name),
     isSwitchable: () => options.length > 1,
-    getCurrent: () =>
-      options.findIndex((option) => option.src === video.currentSrc),
+    getCurrent: () => (adapter === null ? null : adapter.current()),
+    select: (id) => {
+      if (adapter === null) return false;
+      return adapter.select(String(id)) === true;
+    },
   };
 };
diff --git a/src/content/video/qualityadapters.js b/src/content/video/qualityadapters.js
new file mode 100644
index 0000000..db523e3
--- /dev/null
+++ b/src/content/video/qualityadapters.js
@@ -0,0 +1,318 @@
+import {
+  call,
+  findGlobal,
+  isFunction,
+  read,
+  toArray,
+  toPage,
+  write,
+} from './pageapi.js';
+
+export const AUTO_ID = 'auto';
+
+const YOUTUBE_LABELS = {
+  tiny: '144p',
+  small: '240p',
+  medium: '360p',
+  large: '480p',
+  hd720: '720p',
+  hd1080: '1080p',
+  hd1440: '1440p',
+  hd2160: '2160p',
+  highres: '4320p',
+};
+
+const YOUTUBE_LOWEST = 'tiny';
+const YOUTUBE_HIGHEST = 'highres';
+
+const heightLabel = (height, fallback) =>
+  typeof height === 'number' && height > 0 ? `${height}p` : fallback;
+
+// Highest first: the reason anyone opens this list is to force a better
+// picture, so the answer they want is the first chip.
+const byHeightDescending = (first, second) => second.height - first.height;
+
+// --- Plain <source> children -------------------------------------------------
+
+const sourceLabel = (source, index) => {
+  const explicit = source.dataset.label || source.getAttribute('title');
+  if (explicit) return explicit;
+  const match = /(\d{3,4})[pP]/.exec(source.src);
+  return match ? `${match[1]}p` : `Source ${index + 1}`;
+};
+
+const createSourceAdapter = (video) => {
+  const sources = Array.from(video.querySelectorAll('source'));
+  if (sources.length < 2) return null;
+
+  const options = sources.map((source, index) => ({
+    id: String(index),
+    label: sourceLabel(source, index),
+    src: source.src,
+  }));
+
+  return {
+    name: 'sources',
+    hasAuto: false,
+    list: () => options.map(({ id, label }) => ({ id, label })),
+    current: () => {
+      const found = options.find((option) => option.src === video.currentSrc);
+      return found ? found.id : null;
+    },
+    // The element is reloaded, so the position and the playing state are
+    // carried across by hand.
+    select: (id) => {
+      const option = options.find((entry) => entry.id === id);
+      if (!option || video.currentSrc === option.src) return false;
+
+      const resumeAt = video.currentTime;
+      const wasPlaying = !video.paused;
+      const restore = () => {
+        video.removeEventListener('loadedmetadata', restore);
+        video.currentTime = resumeAt;
+        if (wasPlaying) video.play().catch(() => {});
+      };
+
+      video.addEventListener('loadedmetadata', restore);
+      video.src = option.src;
+      video.load();
+      return true;
+    },
+  };
+};
+
+// --- YouTube -----------------------------------------------------------------
+
+const findYouTubePlayer = () => {
+  const element = document.querySelector('#movie_player, .html5-video-player');
+  if (element === null) return null;
+  const player = element.wrappedJSObject ?? element;
+  return isFunction(player, 'getAvailableQualityLevels') ? player : null;
+};
+
+const createYouTubeAdapter = () => {
+  const player = findYouTubePlayer();
+  if (player === null) return null;
+
+  // YouTube reports the quality it is actually playing, which on auto keeps
+  // moving. The chip should show what the user asked for, so the choice is
+  // remembered here and the played value is only the opening guess.
+  let chosen = null;
+
+  const levels = () =>
+    toArray(call(player, 'getAvailableQualityLevels')).filter(
+      (level) => typeof level === 'string' && level !== AUTO_ID,
+    );
+
+  return {
+    name: 'youtube',
+    hasAuto: true,
+    list: () =>
+      levels().map((level) => ({
+        id: level,
+        label: YOUTUBE_LABELS[level] ?? level,
+      })),
+    current: () => {
+      if (chosen !== null) return chosen;
+      const quality = call(player, 'getPlaybackQuality');
+      return typeof quality === 'string' ? quality : null;
+    },
+    // Both calls together: the range is what pins the ladder for the rest of
+    // the video, while setPlaybackQuality is what older players listen to.
+    select: (id) => {
+      chosen = id;
+      if (id === AUTO_ID) {
+        call(
+          player,
+          'setPlaybackQualityRange',
+          YOUTUBE_LOWEST,
+          YOUTUBE_HIGHEST,
+        );
+        call(player, 'setPlaybackQuality', AUTO_ID);
+        return true;
+      }
+      call(player, 'setPlaybackQualityRange', id, id);
+      call(player, 'setPlaybackQuality', id);
+      return true;
+    },
+  };
+};
+
+// --- hls.js ------------------------------------------------------------------
+
+const isHlsEngine = (value) =>
+  Array.isArray(read(value, 'levels')) &&
+  typeof read(value, 'currentLevel') === 'number';
+
+const findHls = (video) => {
+  const attached = ['hls', '_hls', '__hls', 'hlsPlayer'];
+  const element = video.wrappedJSObject ?? video;
+  for (const key of attached) {
+    const candidate = read(element, key);
+    if (candidate && isHlsEngine(candidate)) return candidate;
+  }
+  return findGlobal(isHlsEngine);
+};
+
+const createHlsAdapter = (video) => {
+  const engine = findHls(video);
+  if (engine === null) return null;
+
+  const levels = () =>
+    toArray(read(engine, 'levels')).map((level, index) => ({
+      index,
+      height: read(level, 'height') ?? 0,
+      bitrate: read(level, 'bitrate') ?? 0,
+    }));
+
+  return {
+    name: 'hls.js',
+    hasAuto: true,
+    list: () =>
+      levels()
+        .sort(byHeightDescending)
+        .map((level) => ({
+          id: String(level.index),
+          label: heightLabel(
+            level.height,
+            `${Math.round(level.bitrate / 1000)}k`,
+          ),
+        })),
+    current: () => {
+      const level = read(engine, 'currentLevel');
+      return typeof level === 'number' && level >= 0 ? String(level) : AUTO_ID;
+    },
+    select: (id) => {
+      const index = id === AUTO_ID ? -1 : Number(id);
+      if (Number.isNaN(index)) return false;
+      write(engine, 'nextLevel', index);
+      return write(engine, 'currentLevel', index);
+    },
+  };
+};
+
+// --- dash.js -----------------------------------------------------------------
+
+const isDashPlayer = (value) =>
+  isFunction(value, 'getBitrateInfoListFor') &&
+  isFunction(value, 'setQualityFor');
+
+const createDashAdapter = () => {
+  const player = findGlobal(isDashPlayer);
+  if (player === null) return null;
+
+  const setAuto = (isOn) => {
+    call(
+      player,
+      'updateSettings',
+      toPage({ streaming: { abr: { autoSwitchBitrate: { video: isOn } } } }),
+    );
+  };
+
+  const levels = () =>
+    toArray(call(player, 'getBitrateInfoListFor', 'video')).map((info) => ({
+      index: read(info, 'qualityIndex') ?? 0,
+      height: read(info, 'height') ?? 0,
+      bitrate: read(info, 'bitrate') ?? 0,
+    }));
+
+  return {
+    name: 'dash.js',
+    hasAuto: true,
+    list: () =>
+      levels()
+        .sort(byHeightDescending)
+        .map((level) => ({
+          id: String(level.index),
+          label: heightLabel(
+            level.height,
+            `${Math.round(level.bitrate / 1000)}k`,
+          ),
+        })),
+    current: () => {
+      const index = call(player, 'getQualityFor', 'video');
+      return typeof index === 'number' ? String(index) : null;
+    },
+    select: (id) => {
+      if (id === AUTO_ID) {
+        setAuto(true);
+        return true;
+      }
+      const index = Number(id);
+      if (Number.isNaN(index)) return false;
+      setAuto(false);
+      call(player, 'setQualityFor', 'video', index, true);
+      return true;
+    },
+  };
+};
+
+// --- Shaka Player ------------------------------------------------------------
+
+const isShakaPlayer = (value) =>
+  isFunction(value, 'getVariantTracks') &&
+  isFunction(value, 'selectVariantTrack');
+
+const createShakaAdapter = () => {
+  const player = findGlobal(isShakaPlayer);
+  if (player === null) return null;
+
+  // The originals are handed back to selectVariantTrack untouched: a track is
+  // a page object, and only the page's own object is accepted there.
+  let known = new Map();
+
+  const collect = () => {
+    known = new Map();
+    return toArray(call(player, 'getVariantTracks')).map((track) => {
+      const id = String(read(track, 'id'));
+      known.set(id, track);
+      return {
+        id,
+        height: read(track, 'height') ?? 0,
+        bandwidth: read(track, 'bandwidth') ?? 0,
+        isActive: read(track, 'active') === true,
+      };
+    });
+  };
+
+  return {
+    name: 'shaka',
+    hasAuto: true,
+    list: () =>
+      collect()
+        .sort(byHeightDescending)
+        .map((track) => ({
+          id: track.id,
+          label: heightLabel(
+            track.height,
+            `${Math.round(track.bandwidth / 1000)}k`,
+          ),
+        })),
+    current: () => {
+      const active = collect().find((track) => track.isActive);
+      return active ? active.id : null;
+    },
+    select: (id) => {
+      if (id === AUTO_ID) {
+        call(player, 'configure', toPage({ abr: { enabled: true } }));
+        return true;
+      }
+      if (known.size === 0) collect();
+      const track = known.get(id);
+      if (track === undefined) return false;
+      call(player, 'configure', toPage({ abr: { enabled: false } }));
+      call(player, 'selectVariantTrack', track, true);
+      return true;
+    },
+  };
+};
+
+// Cheapest and most certain first: a <source> list is unambiguous, a named
+// player is next, and the global scan is the last thing tried.
+export const ADAPTERS = [
+  createSourceAdapter,
+  createYouTubeAdapter,
+  createHlsAdapter,
+  createDashAdapter,
+  createShakaAdapter,
+];
diff --git a/src/content/video/sitecaptions.js b/src/content/video/sitecaptions.js
new file mode 100644
index 0000000..9600d91
--- /dev/null
+++ b/src/content/video/sitecaptions.js
@@ -0,0 +1,183 @@
+import { call, isFunction, read, toArray, toPage } from './pageapi.js';
+
+const PROBE_INTERVAL_MS = 1000;
+
+// Players that paint their own captions instead of exposing a text track. The
+// element the site draws into is still updated while the video sits on our
+// stage, so its text is mirrored into the player's own cue layer.
+const CONTAINER_SELECTORS = [
+  '.ytp-caption-window-container',
+  '.shaka-text-container',
+  '.vjs-text-track-display',
+  '.jw-captions',
+  '.plyr__captions',
+  '.pjscaptions',
+];
+
+// Tried in order; the first selector that matches something decides how the
+// lines are split, so a nested wrapper cannot repeat the same words twice.
+const LINE_SELECTORS = [
+  '.ytp-caption-segment',
+  '.caption-visual-line',
+  '.vjs-text-track-cue',
+  '.jw-text-track-cue',
+  '.shaka-text-wrapper span',
+];
+
+const readLines = (container) => {
+  for (const selector of LINE_SELECTORS) {
+    const lines = container.querySelectorAll(selector);
+    if (lines.length === 0) continue;
+    return Array.from(lines)
+      .map((line) => line.textContent.trim())
+      .filter((line) => line !== '')
+      .join('\n');
+  }
+  return container.textContent.trim();
+};
+
+const findContainer = () => {
+  for (const selector of CONTAINER_SELECTORS) {
+    const found = document.querySelector(selector);
+    if (found !== null) return found;
+  }
+  return null;
+};
+
+const findYouTubePlayer = () => {
+  const element = document.querySelector('#movie_player, .html5-video-player');
+  if (element === null) return null;
+  const player = element.wrappedJSObject ?? element;
+  return isFunction(player, 'getOption') ? player : null;
+};
+
+// YouTube keeps its caption list behind the player API rather than in
+// video.textTracks, so the list comes from there and the text comes from the
+// mirror above. Other players expose the mirror only, which is still enough to
+// show whatever the site has switched on.
+const createYouTubeTracks = () => {
+  const player = findYouTubePlayer();
+  if (player === null) return null;
+
+  const tracklist = () => {
+    const list = toArray(call(player, 'getOption', 'captions', 'tracklist'));
+    if (list.length > 0) return list;
+    call(player, 'loadModule', 'captions');
+    return toArray(call(player, 'getOption', 'captions', 'tracklist'));
+  };
+
+  const describe = (track, index) => {
+    const name = read(track, 'displayName') ?? read(track, 'languageName');
+    if (typeof name === 'string' && name !== '') return name;
+    const code = read(track, 'languageCode');
+    const isNamed = typeof code === 'string' && code !== '';
+    return isNamed ? code : `Track ${index + 1}`;
+  };
+
+  return {
+    list: () => tracklist().map((track, index) => describe(track, index)),
+    isOn: () => {
+      const track = call(player, 'getOption', 'captions', 'track');
+      const code = read(track, 'languageCode');
+      return typeof code === 'string' && code !== '';
+    },
+    activeIndex: () => {
+      const current = call(player, 'getOption', 'captions', 'track');
+      const code = read(current, 'languageCode');
+      if (typeof code !== 'string' || code === '') return -1;
+      return tracklist().findIndex(
+        (track) => read(track, 'languageCode') === code,
+      );
+    },
+    select: (index) => {
+      const track = tracklist()[index];
+      if (track === undefined) return false;
+      call(player, 'setOption', 'captions', 'track', track);
+      return true;
+    },
+    disable: () => {
+      call(player, 'setOption', 'captions', 'track', toPage({}));
+    },
+  };
+};
+
+export const createSiteCaptions = (onText) => {
+  const youtube = createYouTubeTracks();
+
+  let container = null;
+  let observer = null;
+  let probeTimer = null;
+  let isMirroring = false;
+  let lastText = '';
+
+  const emit = (text) => {
+    if (!isMirroring || text === lastText) return;
+    lastText = text;
+    onText(text);
+  };
+
+  const readNow = () => {
+    if (container === null || !container.isConnected) return;
+    emit(readLines(container));
+  };
+
+  const watch = (found) => {
+    container = found;
+    observer = new MutationObserver(readNow);
+    observer.observe(container, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+    readNow();
+  };
+
+  const unwatch = () => {
+    if (observer !== null) observer.disconnect();
+    observer = null;
+    container = null;
+  };
+
+  // The container is created the moment captions are first switched on, which
+  // may be long after the player opened, so it is looked for on a slow tick.
+  const probe = () => {
+    probeTimer = null;
+    if (container !== null && !container.isConnected) unwatch();
+    if (container === null) {
+      const found = findContainer();
+      if (found !== null) watch(found);
+    } else {
+      readNow();
+    }
+    probeTimer = setTimeout(probe, PROBE_INTERVAL_MS);
+  };
+
+  probe();
+
+  return {
+    // A site source is worth offering when the site can actually produce one.
+    list: () => (youtube === null ? [] : youtube.list()),
+    hasContainer: () => container !== null,
+    isOn: () => (youtube === null ? container !== null : youtube.isOn()),
+    activeIndex: () => (youtube === null ? 0 : youtube.activeIndex()),
+    select: (index) => {
+      isMirroring = true;
+      lastText = '';
+      if (youtube !== null) youtube.select(index);
+      readNow();
+    },
+    // The site's own caption layer sits behind the stage where nobody can see
+    // it, so turning ours off is a matter of no longer mirroring it.
+    disable: () => {
+      isMirroring = false;
+      lastText = '';
+      if (youtube !== null) youtube.disable();
+      onText('');
+    },
+    destroy: () => {
+      if (probeTimer !== null) clearTimeout(probeTimer);
+      probeTimer = null;
+      unwatch();
+    },
+  };
+};
diff --git a/src/content/video/tracks.js b/src/content/video/tracks.js
index 8f99195..346531e 100644
--- a/src/content/video/tracks.js
+++ b/src/content/video/tracks.js
@@ -1,9 +1,15 @@
+import { createSiteCaptions } from './sitecaptions.js';
 import { findCueText, parseSubtitles } from '../../lib/subtitles.js';
 
 const CUE_LOAD_RETRY_MS = 300;
 const CUE_LOAD_ATTEMPTS = 10;
 const ADOPT_RETRY_MS = 600;
 
+const FILE_ID_BASE = 1000;
+const SITE_ID_BASE = 2000;
+
+const isSiteId = (id) => id >= SITE_ID_BASE;
+
 const describe = (track, index) =>
   track.label || track.language || `Track ${index + 1}`;
 
@@ -53,11 +59,23 @@ export const createTrackManager = (video, onCue, onSelection) => {
     onCue(text);
   };
 
+  // Only the site source may paint while it is the selected one; a stale
+  // mutation arriving after a switch must not put its line back on screen.
+  const site = createSiteCaptions((text) => {
+    if (isSiteId(selected)) emit(text);
+  });
+
   const update = () => {
-    if (selected === -1 || isNative) return;
+    if (selected === -1 || isNative || isSiteId(selected)) return;
     emit(findCueText(cues, video.currentTime + offset));
   };
 
+  const siteOptions = () =>
+    site.list().map((label, index) => ({
+      id: SITE_ID_BASE + index,
+      label,
+    }));
+
   const list = () => {
     const items = nativeTracks().map((track, index) => ({
       id: index,
@@ -66,15 +84,31 @@ export const createTrackManager = (video, onCue, onSelection) => {
     for (const entry of loaded) {
       items.push({ id: entry.id, label: entry.label });
     }
+    const fromSite = siteOptions();
+    if (fromSite.length > 0) return items.concat(fromSite);
+    // A player that paints captions without naming them still deserves a way
+    // to turn them on.
+    if (site.hasContainer()) {
+      items.push({ id: SITE_ID_BASE, label: 'Site captions' });
+    }
     return items;
   };
 
   const select = (id) => {
+    const wasSite = isSiteId(selected);
     selected = id;
     cues = [];
     emit('');
     onSelection(id);
 
+    if (isSiteId(id)) {
+      silenceAll();
+      site.select(id - SITE_ID_BASE);
+      return;
+    }
+
+    if (wasSite) site.disable();
+
     if (id === -1) {
       silenceAll();
       return;
@@ -105,13 +139,14 @@ export const createTrackManager = (video, onCue, onSelection) => {
   const addCues = (label, text) => {
     const parsed = parseSubtitles(text);
     if (parsed.length === 0) return null;
-    const id = 1000 + loaded.length;
+    const id = FILE_ID_BASE + loaded.length;
     loaded.push({ id, label, cues: parsed });
     return id;
   };
 
-  // A site that ships <track default> already has Gecko painting cues. Adopt
-  // that track so it renders through our own layer instead of underneath the
+  // A site that ships <track default> already has Gecko painting cues, and a
+  // site with its own caption layer already has them on screen. Either way the
+  // track is adopted so it renders through our layer instead of underneath the
   // controls, and so the menu tells the truth about what is on.
   const adoptShowingTrack = () => {
     if (selected !== -1) return true;
@@ -121,6 +156,10 @@ export const createTrackManager = (video, onCue, onSelection) => {
       select(index);
       return true;
     }
+    if (site.isOn()) {
+      select(SITE_ID_BASE + Math.max(0, site.activeIndex()));
+      return true;
+    }
     return false;
   };
 
@@ -145,9 +184,13 @@ export const createTrackManager = (video, onCue, onSelection) => {
       if (selected !== -1) select(selected);
     },
     isNative: () => isNative,
+    // The site paints its own captions, so ours are the only ones with a
+    // timing offset or a size to speak of.
+    isSiteSelected: () => isSiteId(selected),
     destroy: () => {
       video.removeEventListener('timeupdate', update);
       video.removeEventListener('seeked', update);
+      site.destroy();
       silenceAll();
     },
   };
diff --git a/src/content/video/visuals.js b/src/content/video/visuals.js
index 88c1b82..37164f4 100644
--- a/src/content/video/visuals.js
+++ b/src/content/video/visuals.js
@@ -1,44 +1,37 @@
 import { clampPan, clampScale, computeCoverScale, snapScale } from './zoom.js';
 
-const PAUSE_GRAYSCALE = 0.85;
-const PAUSE_BRIGHTNESS = 0.7;
-const FILTER_TRANSITION = 'filter 350ms ease';
-const TRANSFORM_TRANSITION = 'transform 220ms ease';
+const TRANSFORM_TRANSITION = 'transform 260ms cubic-bezier(0.32, 0.72, 0, 1)';
+const FILTER_TRANSITION = 'filter 320ms ease';
 
 // Every filter function is always present and always in the same order, so the
-// browser can interpolate between two states and the pause fade stays smooth.
-const buildFilter = ({ grayscale, saturate, contrast, brightness }) => {
+// browser can interpolate between two states smoothly.
+const buildFilter = ({ saturate, contrast, brightness }) => {
   // Untouched settings mean no filter at all, so the film is passed through
   // exactly as the site encoded it.
-  const isNeutral =
-    grayscale === 0 && saturate === 1 && contrast === 1 && brightness === 1;
+  const isNeutral = saturate === 1 && contrast === 1 && brightness === 1;
   if (isNeutral) return 'none';
-  return (
-    `grayscale(${grayscale}) saturate(${saturate}) ` +
-    `contrast(${contrast}) brightness(${brightness})`
-  );
+  const tone = `contrast(${contrast}) brightness(${brightness})`;
+  return `saturate(${saturate}) ${tone}`;
 };
 
-export const createVisuals = (video, stage, wasPlaying) => {
+// What the zoom means, rather than the number it currently works out to. The
+// stage changes size whenever the phone rotates, the system takes the video
+// into a floating window, or the app comes back from the background — and the
+// same intent has to survive all three.
+const FIT = 'fit';
+const FILL = 'fill';
+const FREE = 'free';
+
+export const createVisuals = (video, stage) => {
   const colour = { saturate: 1, contrast: 1, brightness: 1 };
   const view = { scale: 1, x: 0, y: 0 };
 
-  // Gecko reports the element as paused for a moment while it is re-parented,
-  // which would otherwise flash the pause fade over a film that is playing.
-  let isPaused = wasPlaying ? false : video.paused;
+  let intent = FIT;
+  let freeFactor = 1;
   let isPinching = false;
-  let isFadeSuppressed = false;
 
   const apply = () => {
-    // While the colour panel is open the fade is held off, otherwise the user
-    // would be tuning colours against a grey picture.
-    const isFaded = isPaused && !isFadeSuppressed;
-    const filter = buildFilter({
-      grayscale: isFaded ? PAUSE_GRAYSCALE : 0,
-      saturate: colour.saturate,
-      contrast: colour.contrast,
-      brightness: colour.brightness * (isFaded ? PAUSE_BRIGHTNESS : 1),
-    });
+    const filter = buildFilter(colour);
     const isUnzoomed = view.scale === 1 && view.x === 0 && view.y === 0;
     const offset = `translate(${view.x}px, ${view.y}px)`;
     const transform = isUnzoomed ? 'none' : `${offset} scale(${view.scale})`;
@@ -56,7 +49,17 @@ export const createVisuals = (video, stage, wasPlaying) => {
     return { width: rect.width, height: rect.height };
   };
 
-  const setScale = (scale) => {
+  const coverScale = () => {
+    const size = stageSize();
+    return computeCoverScale(
+      video.videoWidth,
+      video.videoHeight,
+      size.width,
+      size.height,
+    );
+  };
+
+  const place = (scale) => {
     const size = stageSize();
     const cover = computeCoverScale(
       video.videoWidth,
@@ -72,31 +75,49 @@ export const createVisuals = (video, stage, wasPlaying) => {
     return view.scale;
   };
 
-  apply();
+  const remember = (scale) => {
+    const cover = coverScale();
+    if (scale === 1) {
+      intent = FIT;
+    } else if (scale === cover) {
+      intent = FILL;
+    } else {
+      intent = FREE;
+      freeFactor = cover > 0 ? scale / cover : 1;
+    }
+  };
 
-  const coverScale = () => {
-    const size = stageSize();
-    return computeCoverScale(
-      video.videoWidth,
-      video.videoHeight,
-      size.width,
-      size.height,
-    );
+  const setScale = (scale) => {
+    const applied = place(scale);
+    remember(applied);
+    return applied;
   };
 
+  // Re-derives the scale the intent asks for at the current stage size. This is
+  // what stops the picture from being left at yesterday's crop — blown up and
+  // stretched — after the window has changed shape underneath it.
+  const relayout = () => {
+    if (video.videoWidth === 0) return false;
+    const cover = coverScale();
+    if (intent === FIT) {
+      place(1);
+    } else if (intent === FILL) {
+      place(cover);
+    } else {
+      place(freeFactor * cover);
+    }
+    return true;
+  };
+
+  apply();
+
   return {
-    setPaused: (value) => {
-      isPaused = value;
-      apply();
-    },
-    suppressFade: (value) => {
-      isFadeSuppressed = value;
-      apply();
-    },
+    relayout,
     // Crops the letterbox away, which is what most people want on a phone.
     fillScreen: () => {
       if (video.videoWidth === 0) return false;
-      setScale(coverScale());
+      intent = FILL;
+      place(coverScale());
       return true;
     },
     setColour: (patch) => {

From a877f2670a0148808dc9064e6b0a4c7465a5d636 Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Thu, 6 Aug 2026 10:40:55 +0300
Subject: [PATCH 05/23] docs: record what changed in 0.3.0

Also corrects the parts of the README that no longer described the
extension: YouTube is in scope now, the pause fade is gone, and the volume
strip and gesture lock were never built.
---
 CHANGELOG.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++-
 README.md    | 63 +++++++++++++++++++++++++++++++---------------------
 2 files changed, 98 insertions(+), 26 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 78329ef..0058257 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased][unreleased]
 
+## [0.3.0][] - 2026-08-06
+
+Everything in this release comes from watching real films on a real phone with
+0.2.0 installed.
+
+### Added
+
+- **Quality selection.** The site keeps its ladder; the sheet asks for a rung.
+  Adapters for `<source>` lists, YouTube, hls.js, dash.js and Shaka, read
+  through the page's own objects — no code is injected into the page and nothing
+  is evaluated from a string. Where a player exposes no way in, the row reports
+  the resolution being played instead of offering a choice that does nothing.
+- **Captions from players that paint their own.** YouTube's caption list is read
+  through its player API and the text it renders is mirrored into the player's
+  cue layer, which is why subtitles were missing there before. The same mirror
+  covers Shaka, video.js, JW Player, Plyr and Playerjs.
+- **Picture-in-picture button**, at the top right. Gecko ships no Web API for it
+  on Android, so it uses the standard call where that exists and otherwise
+  prepares the video and says what to do.
+- **Fullscreen switch** in the settings sheet. Off runs the player as an overlay
+  instead of taking the screen, which leaves Android's ordinary single swipe
+  home working.
+- Loading an `.srt` / `.vtt` file now actually loads it: the file input had no
+  handler, so the button did nothing.
+
+### Changed
+
+- **Pausing is the play button and nothing else.** The invisible pause zone that
+  covered the whole picture is gone; a tap anywhere else brings the controls up
+  or puts them away.
+- **The seek band sits above the bottom of the screen**, clear of the Android
+  home swipe, which used to be read as a scrub and threw the film into the
+  middle.
+- **The badge sits halfway up the right edge** of an inline video rather than in
+  the bottom corner, where it covered the site's own controls.
+- Motion follows one easing curve throughout, with scrims and shadows under the
+  controls so they stay legible over a bright picture.
+- The launcher no longer asks Gecko to hide the navigation UI, which is what put
+  Android into sticky immersive mode.
+
+### Fixed
+
+- **The picture stays centred and keeps its shape.** A site that rewrites the
+  video's inline style — YouTube does it on every layout pass — could push the
+  picture against an edge or stretch it across the screen after a return from
+  another app. Position and offsets are pinned along with the size and re-pinned
+  whenever the site writes over them, and the zoom is re-derived from what the
+  viewer asked for whenever the stage changes shape.
+- **Colour starts neutral.** Values stored out of range, or of the wrong type,
+  now fall back to the neutral one instead of tinting a film for reasons the
+  viewer cannot see.
+- **No more fade to grey while paused.** People pause to look at the picture.
+- Leaving the app no longer tears the session down. Losing fullscreen while the
+  app is on its way to the background is what Android's floating-window hand-off
+  looks like, and it is now told apart from the viewer leaving the player.
+- A quality switch that empties the media element no longer backs the player
+  out; the check waits to see whether the element really was torn down.
+
 ## [0.2.0][] - 2026-08-02
 
 First release submitted to addons.mozilla.org.
@@ -51,5 +109,6 @@ First release submitted to addons.mozilla.org.
   There is no sound while scrubbing.
 - Volume is left to the phone's own buttons.
 
-[unreleased]: https://github.com/kvachikk/nocturne-player/compare/v0.2.0...HEAD
+[unreleased]: https://github.com/kvachikk/nocturne-player/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/kvachikk/nocturne-player/releases/tag/v0.3.0
 [0.2.0]: https://github.com/kvachikk/nocturne-player/releases/tag/v0.2.0
diff --git a/README.md b/README.md
index 19c1488..dd8af96 100644
--- a/README.md
+++ b/README.md
@@ -22,9 +22,11 @@ adds them.
 Built for **ordinary sites that play video through a plain `<video>` element** —
 the kind of site you use to watch a film or a series.
 
-**Not** for YouTube, Vimeo or TikTok. They ship their own player layers, and
-overriding those is a fundamentally different (and much larger) problem. This
-extension deliberately does not try.
+It also works on **YouTube**, which was not the original plan: the site's own
+player keeps running underneath, and the extension drives it through the API the
+page already exposes — the quality ladder, the caption track — rather than
+re-implementing it. Sites that hide their player behind a proprietary layer with
+no such API still fall back to the plain controls.
 
 ## Features
 
@@ -35,11 +37,10 @@ your finger, like the scrubber in Safari on iOS. Moving your finger away from
 the bar vertically reduces the scrubbing speed, so you can land on an exact
 moment instead of overshooting.
 
-**Volume** — a vertical strip on the right edge, same relative-drag feel.
-
-**Tap to pause** — a large invisible zone in the middle of the screen, plus a
-visible button when the controls are showing. When paused, the picture fades to
-grey, like Netflix.
+**Tap to pause** — the play button and nothing else. Tapping anywhere else on
+the picture brings the controls up or puts them away, so a thumb landing on the
+screen can never stop the film by accident. Pausing leaves the colour alone, for
+when you paused to look at something.
 
 **Hold for 2x** — hold the right zone to play at double speed, hold the left
 zone to rewind. Double-tap either zone for ±10 seconds.
@@ -52,12 +53,19 @@ dark, with adjustable intensity.
 
 **Colour** — brightness, contrast and saturation. Three sliders, nothing more.
 
-**Subtitles** — use the site's own tracks or load an `.srt` / `.vtt` file from
-your phone. Adjustable size, background, position, and a sync offset for when
-the subtitles drift.
+**Subtitles** — the site's own text tracks, the captions a player like
+YouTube's paints for itself, or an `.srt` / `.vtt` file from your phone.
+Adjustable size and a sync offset for when the subtitles drift.
+
+**Quality** — pick the rung of the ladder rather than letting the site choose
+for you. Works with `<source>` lists, YouTube, hls.js, dash.js and Shaka; where
+a player exposes nothing, the sheet says what is playing instead of offering a
+choice that would do nothing.
 
-**Lock** — locks all gestures so your palm cannot pause the film. Unlocking
-takes two deliberate gestures.
+**Picture in picture** — the button at the top right hands the film to the
+system's floating window where the platform allows it, and the player survives
+being sent to the background so Android's own hand-off works when you swipe
+away.
 
 ## Privacy
 
@@ -89,22 +97,27 @@ See [PRIVACY.md](PRIVACY.md).
 
 These are platform limits, not oversights:
 
-- **Picture-in-Picture does not work on Android.** Firefox for Android has no
-  PiP Web API — `requestPictureInPicture()` rejects with `NotSupportedError`
-  because the underlying GeckoView support does not exist yet. The button is
-  written and feature-detected, so it stays hidden on Android and will appear on
-  its own when Gecko ships support.
-- **Video quality usually cannot be changed.** Sites that stream over HLS or
-  DASH pick the quality in their own JavaScript, and no extension can reach into
-  that generically. Where a site offers several `<source>` elements, the quality
-  menu switches between them; otherwise it shows the current resolution as
-  read-only information.
-- **Volume is the video's volume, not the system volume.** The web platform has
-  no access to the device volume.
+- **There is no Web API for Picture-in-Picture on Android.** Gecko does not
+  ship `requestPictureInPicture()` there. What Android does offer is its own
+  hand-off: leave the app while a video is playing and the system floats it. The
+  button uses the standard API where it exists and otherwise prepares the video
+  and says what to do, and the session now survives being backgrounded so the
+  system hand-off is not torn down halfway through.
+- **Quality depends on what the site's player exposes.** A player that keeps its
+  engine in a closure cannot be reached from an extension. The common ones —
+  `<source>` lists, YouTube, hls.js, dash.js, Shaka — are covered; anything else
+  reports the resolution it is playing and leaves the choice to the site.
+- **Volume is left to the phone's own buttons.** The web platform has no access
+  to the device volume.
 - **Rewind is not "negative 2x".** `playbackRate` cannot go below zero, so
   holding the left zone seeks backwards continuously at roughly 2x instead.
 - **Landscape lock is best-effort.** Gecko may refuse the request; the player
   carries on without it.
+- **Android asks for a second swipe to leave a fullscreen app.** That is the
+  system's sticky-immersive behaviour, not something a page can turn off. The
+  player no longer asks Gecko to hide the navigation UI, and the settings sheet
+  has a **Fullscreen** switch: turn it off and the player runs as an overlay,
+  which leaves the ordinary single swipe home.
 
 ## Install
 

From b8a71048c8c37f314bc0128b7a3e9c3998acb223 Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Thu, 6 Aug 2026 10:40:56 +0300
Subject: [PATCH 06/23] chore: release 0.3.0

---
 package.json      | 2 +-
 src/manifest.json | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/package.json b/package.json
index dcaf8ae..7989df9 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "nocturne-player",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "description": "A touch-first video player for Firefox on Android",
   "license": "MPL-2.0",
diff --git a/src/manifest.json b/src/manifest.json
index 5b9ad2f..f603539 100644
--- a/src/manifest.json
+++ b/src/manifest.json
@@ -1,8 +1,8 @@
 {
   "manifest_version": 2,
   "name": "Nocturne Player",
-  "version": "0.2.0",
-  "description": "A touch-first video player for ordinary streaming sites: thick seek bar, gesture controls, night light and colour tuning.",
+  "version": "0.3.0",
+  "description": "A touch-first video player for streaming sites and YouTube: thick seek bar, gesture controls, quality and subtitle picker, night light and colour tuning.",
   "author": "Vlad Pohorilets",
   "homepage_url": "https://github.com/kvachikk/nocturne-player",
   "browser_specific_settings": {

From b4d344118448d7e231dfb92149b04b973f381bd5 Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Thu, 6 Aug 2026 10:58:00 +0300
Subject: [PATCH 07/23] fix(session): stop the style guard chasing its own
 writes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The guard compared the video's inline style against the values it had been
asked to write, but the browser serialises them differently — `left: 0`
reads back as `0px` — so it never once found the style already pinned. Every
mutation record, including the ones its own writes produced, triggered
twenty more !important writes: an unbounded loop of style recalculation that
made the player crawl, the picture stutter and fullscreen arrive late.

It now compares against what the browser serialised, which converges after a
single write, and gives up after a bounded number of re-pins so a site that
insists on !important of its own cannot trade writes with us all film long.
---
 src/content/session.js | 45 ++++++++++++++++++++++++++++++++----------
 1 file changed, 35 insertions(+), 10 deletions(-)

diff --git a/src/content/session.js b/src/content/session.js
index 1e2efdb..1c61d5c 100644
--- a/src/content/session.js
+++ b/src/content/session.js
@@ -5,6 +5,7 @@ import playerCss from './player.css';
 const STALL_GRACE_MS = 400;
 const EMPTIED_GRACE_MS = 600;
 const RECOVER_DELAY_MS = 250;
+const MAX_REPINS = 240;
 
 const STAGE_STYLE = {
   position: 'fixed',
@@ -28,7 +29,6 @@ const STAGE_STYLE = {
 // after coming back from another app. Position and offsets are pinned here too,
 // not only the size, and re-pinned whenever the site writes over them.
 const VIDEO_STYLE = {
-  inset: 'auto',
   position: 'relative',
   left: '0',
   top: '0',
@@ -84,14 +84,23 @@ const auditRestore = (video, state) => {
   return false;
 };
 
-// Written only when it has actually been disturbed, so re-pinning cannot chase
-// its own mutation record round in a loop.
-const isPinned = (video) =>
-  VIDEO_STYLE_KEYS.every(
-    (name) =>
-      video.style.getPropertyValue(name) === VIDEO_STYLE[name] &&
-      video.style.getPropertyPriority(name) === 'important',
-  );
+// The style is compared against what the browser serialised, never against
+// what we asked for: setting `left: 0` reads back as `0px`, so comparing with
+// the input would find a difference every time and re-pin on the strength of
+// its own mutation record — a loop that recalculates style until the phone
+// crawls.
+const readStyle = (video) => {
+  const seen = {};
+  for (const name of VIDEO_STYLE_KEYS) {
+    seen[name] = video.style.getPropertyValue(name);
+  }
+  return seen;
+};
+
+const isSameStyle = (first, second) => {
+  if (first === null) return false;
+  return VIDEO_STYLE_KEYS.every((name) => first[name] === second[name]);
+};
 
 // navigationUI is deliberately left at its default. Asking Gecko to hide it put
 // Android into sticky immersive mode, where the first swipe up only brings the
@@ -143,6 +152,8 @@ export const createSession = (video, { onExit, settings, onPersist }) => {
   let isOrientationLocked = false;
   let isFullscreenWanted = settings.isFullscreenTakeoverOn;
   let styleGuard = null;
+  let pinnedStyle = null;
+  let repinCount = 0;
   let overlay = null;
   let relayoutFrame = 0;
 
@@ -165,9 +176,23 @@ export const createSession = (video, { onExit, settings, onPersist }) => {
     return timer;
   };
 
+  // Re-pinning is bounded: a site that fights back with !important of its own
+  // would otherwise trade writes with us for as long as the film lasts. After
+  // the budget runs out the guard steps aside and the picture is re-fitted on
+  // the ordinary relayout events instead.
   const pinVideo = () => {
-    if (isPinned(video)) return;
+    if (isSameStyle(pinnedStyle, readStyle(video))) return;
+
+    repinCount += 1;
+    if (repinCount > MAX_REPINS) {
+      if (styleGuard) styleGuard.disconnect();
+      styleGuard = null;
+      console.warn('Nocturne: the site keeps rewriting the video, leaving it');
+      return;
+    }
+
     pinStyle(video, VIDEO_STYLE);
+    pinnedStyle = readStyle(video);
   };
 
   const relayout = () => {

From dca9900e55fd5b744a7dd533701bc22edcf9149c Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Thu, 6 Aug 2026 10:58:01 +0300
Subject: [PATCH 08/23] fix: drop colour left over from schema 1 on upgrade

Range-checking was not enough: a saturation of zero is a value the panel can
produce, so a profile that had been left there kept playing every film in
black and white, and a contrast of 1.3 kept every film tinted. Neither is
something a viewer would connect to a setting they touched once. Schema 2
drops the four colour values once on upgrade; after that they are theirs
again.
---
 src/lib/settings.js        | 20 ++++++++++++++++++--
 test/unit/settings.test.js | 30 +++++++++++++++++++++++++++++-
 2 files changed, 47 insertions(+), 3 deletions(-)

diff --git a/src/lib/settings.js b/src/lib/settings.js
index 985eb6b..c3c625b 100644
--- a/src/lib/settings.js
+++ b/src/lib/settings.js
@@ -1,5 +1,5 @@
 const STORAGE_KEY = 'nocturne';
-const SCHEMA_VERSION = 1;
+const SCHEMA_VERSION = 2;
 
 export const DEFAULTS = Object.freeze({
   schemaVersion: SCHEMA_VERSION,
@@ -41,9 +41,25 @@ const inRange = (key, value) => {
   return value;
 };
 
+const COLOUR_KEYS = ['warmth', 'brightness', 'contrast', 'saturate'];
+
+// Schema 1 kept whatever colour the panel was last left on, including values
+// somebody had only been trying out. They came back on the next film — on what
+// looked like a clean profile — as a picture that was already tinted, or in one
+// case with the colour drained out of it entirely. The upgrade drops them once;
+// after that they are the viewer's again.
+const migrate = (stored) => {
+  if (stored === null || typeof stored !== 'object') return stored;
+  if (stored.schemaVersion === SCHEMA_VERSION) return stored;
+  const migrated = { ...stored };
+  for (const key of COLOUR_KEYS) delete migrated[key];
+  return migrated;
+};
+
 // Rebuilt key by key so every settings object shares one hidden class, and so
 // unknown keys from a future version can never leak into the running state.
-export const normalize = (stored) => {
+export const normalize = (raw) => {
+  const stored = migrate(raw);
   const settings = {};
   for (const key of KEYS) {
     const value = stored?.[key];
diff --git a/test/unit/settings.test.js b/test/unit/settings.test.js
index 5e9e4c4..307d8c2 100644
--- a/test/unit/settings.test.js
+++ b/test/unit/settings.test.js
@@ -24,7 +24,11 @@ test('a stored value of the wrong type falls back to neutral', () => {
 });
 
 test('a value the user really chose is kept', () => {
-  const settings = normalize({ contrast: 1.15, warmth: 0.27 });
+  const settings = normalize({
+    schemaVersion: 2,
+    contrast: 1.15,
+    warmth: 0.27,
+  });
   assert.equal(settings.contrast, 1.15);
   assert.equal(settings.warmth, 0.27);
 });
@@ -34,3 +38,27 @@ test('unknown keys never reach the running state', () => {
   assert.equal(settings.somethingElse, undefined);
   assert.deepEqual(Object.keys(settings).sort(), Object.keys(DEFAULTS).sort());
 });
+
+test('an upgrade from schema 1 drops the colour it was left on', () => {
+  const settings = normalize({
+    schemaVersion: 1,
+    contrast: 1.3,
+    saturate: 0,
+    warmth: 0.36,
+    subtitleScale: 1.25,
+    disabledHosts: ['example.com'],
+  });
+  assert.equal(settings.contrast, 1);
+  assert.equal(settings.saturate, 1);
+  assert.equal(settings.warmth, 0);
+  // Everything that is not colour survives the upgrade.
+  assert.equal(settings.subtitleScale, 1.25);
+  assert.deepEqual(settings.disabledHosts, ['example.com']);
+  assert.equal(settings.schemaVersion, 2);
+});
+
+test('colour set on the current schema is kept', () => {
+  const settings = normalize({ schemaVersion: 2, saturate: 0, contrast: 1.2 });
+  assert.equal(settings.saturate, 0);
+  assert.equal(settings.contrast, 1.2);
+});

From 6c2211954ab4a504a252dbe049dea4137dd3e7ae Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Thu, 6 Aug 2026 10:58:02 +0300
Subject: [PATCH 09/23] perf(video): keep the work out of the moment the player
 opens
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Opening the player walked the page's globals once per streaming engine,
through cross-compartment wrappers, before fullscreen was even requested.
The three sweeps are now one, and the ladder is only looked up when the
sheet is opened rather than while the viewer waits for the picture.

Also: the caption mirror no longer reads the site's caption layer while
nothing is being mirrored, the fill retry gives up instead of ticking for
the length of the film on a stream that never reports its dimensions, and
the vignette is lighter — it was washing the picture out.
---
 src/content/controls/menu.js         |  2 +-
 src/content/player.css               |  2 +-
 src/content/ui.js                    |  8 ++++-
 src/content/video/pageapi.js         | 17 +++++++---
 src/content/video/quality.js         |  2 --
 src/content/video/qualityadapters.js | 50 +++++++++++++++++-----------
 src/content/video/sitecaptions.js    |  2 +-
 7 files changed, 53 insertions(+), 30 deletions(-)

diff --git a/src/content/controls/menu.js b/src/content/controls/menu.js
index 26495b4..3b3cdb4 100644
--- a/src/content/controls/menu.js
+++ b/src/content/controls/menu.js
@@ -174,7 +174,7 @@ export const createMenu = ({
   );
 
   paintSubtitles();
-  paintQuality();
+  qualityRow.chips.replaceChildren(buildNote('Reading the site…'));
 
   const root = el('div', { class: 'panel menu' }, [
     speedRow.row,
diff --git a/src/content/player.css b/src/content/player.css
index c64f6c0..1ae7bc7 100644
--- a/src/content/player.css
+++ b/src/content/player.css
@@ -63,7 +63,7 @@
     ),
     radial-gradient(
       ellipse 70% 55% at 50% 50%,
-      rgba(0, 0, 0, 0.26) 0%,
+      rgba(0, 0, 0, 0.12) 0%,
       rgba(0, 0, 0, 0) 100%
     );
   pointer-events: none;
diff --git a/src/content/ui.js b/src/content/ui.js
index 325f9b3..5930f45 100644
--- a/src/content/ui.js
+++ b/src/content/ui.js
@@ -15,6 +15,7 @@ const TOAST_MS = 900;
 const HINT_MS = 2200;
 const SKIP_SECONDS = 10;
 const FILL_RETRY_MS = 400;
+const FILL_ATTEMPTS = 25;
 
 const ICON = {
   exit: 'M6 6l12 12M18 6L6 18',
@@ -377,9 +378,14 @@ export const createOverlay = ({
     cueBox.style.setProperty('--cue-scale', String(settings.subtitleScale));
   };
 
-  // Black bars cropped from the start; metadata may not have arrived yet.
+  // Black bars cropped from the start; metadata may not have arrived yet. The
+  // retry gives up rather than ticking for as long as the film lasts on a
+  // stream that never reports its dimensions.
+  let fillAttempts = 0;
   const fillWhenReady = () => {
     if (visuals.fillScreen()) return;
+    fillAttempts += 1;
+    if (fillAttempts >= FILL_ATTEMPTS) return;
     setTimeout(fillWhenReady, FILL_RETRY_MS);
   };
 
diff --git a/src/content/video/pageapi.js b/src/content/video/pageapi.js
index c29ebec..24d6c88 100644
--- a/src/content/video/pageapi.js
+++ b/src/content/video/pageapi.js
@@ -86,7 +86,12 @@ export const isFunction = (object, name) => {
 // A last resort for players that keep their engine on a global under a name
 // only they know. Bounded, and every property read is guarded, because a getter
 // on a page global can throw or be expensive.
-export const findGlobal = (matches) => {
+//
+// Every matcher is tried against each global in one sweep. Sweeping once per
+// engine instead meant walking the page's globals three times over, through
+// cross-compartment wrappers, in the moment the viewer was waiting for the
+// player to open.
+export const findGlobalMatch = (matchers) => {
   const scope = pageWindow();
   let keys = [];
   try {
@@ -99,10 +104,12 @@ export const findGlobal = (matches) => {
   for (let index = 0; index < limit; index++) {
     const value = read(scope, keys[index]);
     if (value === null || typeof value !== 'object') continue;
-    try {
-      if (matches(value)) return value;
-    } catch {
-      continue;
+    for (const matcher of matchers) {
+      try {
+        if (matcher.matches(value)) return { name: matcher.name, value };
+      } catch {
+        continue;
+      }
     }
   }
   return null;
diff --git a/src/content/video/quality.js b/src/content/video/quality.js
index 72aa908..d43577e 100644
--- a/src/content/video/quality.js
+++ b/src/content/video/quality.js
@@ -38,8 +38,6 @@ export const createQuality = (video) => {
     return `${video.videoWidth}×${video.videoHeight} · set by the site`;
   };
 
-  refresh();
-
   return {
     refresh,
     describe,
diff --git a/src/content/video/qualityadapters.js b/src/content/video/qualityadapters.js
index db523e3..d5e3990 100644
--- a/src/content/video/qualityadapters.js
+++ b/src/content/video/qualityadapters.js
@@ -1,6 +1,6 @@
 import {
   call,
-  findGlobal,
+  findGlobalMatch,
   isFunction,
   read,
   toArray,
@@ -144,20 +144,17 @@ const isHlsEngine = (value) =>
   Array.isArray(read(value, 'levels')) &&
   typeof read(value, 'currentLevel') === 'number';
 
-const findHls = (video) => {
+const findHlsOnElement = (video) => {
   const attached = ['hls', '_hls', '__hls', 'hlsPlayer'];
   const element = video.wrappedJSObject ?? video;
   for (const key of attached) {
     const candidate = read(element, key);
     if (candidate && isHlsEngine(candidate)) return candidate;
   }
-  return findGlobal(isHlsEngine);
+  return null;
 };
 
-const createHlsAdapter = (video) => {
-  const engine = findHls(video);
-  if (engine === null) return null;
-
+const buildHlsAdapter = (engine) => {
   const levels = () =>
     toArray(read(engine, 'levels')).map((level, index) => ({
       index,
@@ -197,10 +194,7 @@ const isDashPlayer = (value) =>
   isFunction(value, 'getBitrateInfoListFor') &&
   isFunction(value, 'setQualityFor');
 
-const createDashAdapter = () => {
-  const player = findGlobal(isDashPlayer);
-  if (player === null) return null;
-
+const buildDashAdapter = (player) => {
   const setAuto = (isOn) => {
     call(
       player,
@@ -253,10 +247,7 @@ const isShakaPlayer = (value) =>
   isFunction(value, 'getVariantTracks') &&
   isFunction(value, 'selectVariantTrack');
 
-const createShakaAdapter = () => {
-  const player = findGlobal(isShakaPlayer);
-  if (player === null) return null;
-
+const buildShakaAdapter = (player) => {
   // The originals are handed back to selectVariantTrack untouched: a track is
   // a page object, and only the page's own object is accepted there.
   let known = new Map();
@@ -307,12 +298,33 @@ const createShakaAdapter = () => {
   };
 };
 
+const BUILDERS = {
+  hls: buildHlsAdapter,
+  dash: buildDashAdapter,
+  shaka: buildShakaAdapter,
+};
+
+const MATCHERS = [
+  { name: 'hls', matches: isHlsEngine },
+  { name: 'dash', matches: isDashPlayer },
+  { name: 'shaka', matches: isShakaPlayer },
+];
+
+// One sweep of the page's globals for all three streaming engines, after the
+// cheap check of whether the engine is hanging off the element itself.
+const createStreamAdapter = (video) => {
+  const attached = findHlsOnElement(video);
+  if (attached !== null) return buildHlsAdapter(attached);
+
+  const found = findGlobalMatch(MATCHERS);
+  if (found === null) return null;
+  return BUILDERS[found.name](found.value);
+};
+
 // Cheapest and most certain first: a <source> list is unambiguous, a named
-// player is next, and the global scan is the last thing tried.
+// player is next, and the sweep of page globals is the last thing tried.
 export const ADAPTERS = [
   createSourceAdapter,
   createYouTubeAdapter,
-  createHlsAdapter,
-  createDashAdapter,
-  createShakaAdapter,
+  createStreamAdapter,
 ];
diff --git a/src/content/video/sitecaptions.js b/src/content/video/sitecaptions.js
index 9600d91..91ef64a 100644
--- a/src/content/video/sitecaptions.js
+++ b/src/content/video/sitecaptions.js
@@ -117,7 +117,7 @@ export const createSiteCaptions = (onText) => {
   };
 
   const readNow = () => {
-    if (container === null || !container.isConnected) return;
+    if (!isMirroring || container === null || !container.isConnected) return;
     emit(readLines(container));
   };
 

From 71fae25da3256a2dda3ecdf26dc97c31354e4001 Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Thu, 6 Aug 2026 10:58:14 +0300
Subject: [PATCH 10/23] docs: note the colour reset in the 0.3.0 changes

---
 CHANGELOG.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0058257..b691eac 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -55,9 +55,12 @@ Everything in this release comes from watching real films on a real phone with
   another app. Position and offsets are pinned along with the size and re-pinned
   whenever the site writes over them, and the zoom is re-derived from what the
   viewer asked for whenever the stage changes shape.
-- **Colour starts neutral.** Values stored out of range, or of the wrong type,
-  now fall back to the neutral one instead of tinting a film for reasons the
-  viewer cannot see.
+- **Colour starts neutral.** Settings move to schema 2, which drops the four
+  colour values once on upgrade: a profile left on zero saturation was playing
+  every film in black and white, and one left on 1.3 contrast kept every film
+  tinted, neither of them anything a viewer would connect to a setting they
+  touched once. Values stored out of range or of the wrong type now fall back
+  to the neutral one as well.
 - **No more fade to grey while paused.** People pause to look at the picture.
 - Leaving the app no longer tears the session down. Losing fullscreen while the
   app is on its way to the background is what Android's floating-window hand-off

From c7b03011cda5d485f79f0b16b36b014ba99c356e Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Thu, 6 Aug 2026 14:28:34 +0300
Subject: [PATCH 11/23] feat(controls): a fullscreen button and a badge that
 hides

Two changes to the thing that sits on an inline video.

There is now a second button under the launcher: plain fullscreen on the
site's own player, for a film you are happy to watch with the site's own
controls and only want bigger.

And both of them fade out when nothing has happened for a few seconds. Two
buttons parked on somebody's video are two buttons in the way; a touch
anywhere on the page brings them back.
---
 src/content/controls/badge.css |  28 ++++++++-
 src/content/controls/badge.js  | 107 ++++++++++++++++++++++++---------
 src/content/index.js           |  16 +++++
 3 files changed, 118 insertions(+), 33 deletions(-)

diff --git a/src/content/controls/badge.css b/src/content/controls/badge.css
index be07eee..c098ec1 100644
--- a/src/content/controls/badge.css
+++ b/src/content/controls/badge.css
@@ -1,17 +1,29 @@
-.badge {
+/* Two buttons in a column against the right edge of the video: open the
+   player, or just make the small window fullscreen and leave the site's own
+   controls in charge. */
+.stack {
   position: absolute;
   inset: 0;
   display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.badge {
+  flex: none;
+  display: flex;
   align-items: center;
   justify-content: center;
-  width: 100%;
-  height: 100%;
+  width: 44px;
+  height: 44px;
   padding: 0;
   border: 0;
   border-radius: 999px;
   background: rgba(22, 21, 28, 0.5);
   box-shadow: 0 2px 10px rgba(0, 0, 0, 0.45);
   backdrop-filter: blur(6px);
+  color: rgba(244, 241, 255, 0.92);
   cursor: pointer;
   -webkit-tap-highlight-color: transparent;
   transition:
@@ -28,3 +40,13 @@
   height: 22px;
   display: block;
 }
+
+.badge.expand svg {
+  width: 20px;
+  height: 20px;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
diff --git a/src/content/controls/badge.js b/src/content/controls/badge.js
index 3b5009b..feb948c 100644
--- a/src/content/controls/badge.js
+++ b/src/content/controls/badge.js
@@ -2,39 +2,54 @@ import { createShadowHost, el, pinStyle } from '../shell.js';
 import badgeCss from './badge.css';
 
 const SIZE_PX = 44;
+const GAP_PX = 10;
+const STACK_HEIGHT_PX = SIZE_PX * 2 + GAP_PX;
 const INSET_PX = 12;
 const MIN_VISIBLE_RATIO = 0.35;
+const IDLE_MS = 3200;
 
-const buildButton = () =>
-  el(
-    'button',
-    { class: 'badge', type: 'button', title: 'Open in Nocturne Player' },
-    [
-      el('svg', { viewBox: '0 0 24 24', 'aria-hidden': 'true' }, [
-        el('path', {
-          d: 'M8 6.5 17 12l-9 5.5z',
-          fill: 'rgba(244,241,255,0.92)',
-        }),
-        el('path', {
-          d: 'M20.5 3.2a3.2 3.2 0 1 0 .6 5.9 3.6 3.6 0 0 1-.6-5.9z',
-          fill: 'rgba(244,241,255,0.5)',
-        }),
-      ]),
-    ],
-  );
+const buildOpenButton = () =>
+  el('button', { class: 'badge', type: 'button', title: 'Open in Nocturne' }, [
+    el('svg', { viewBox: '0 0 24 24', 'aria-hidden': 'true' }, [
+      el('path', {
+        d: 'M8 6.5 17 12l-9 5.5z',
+        fill: 'rgba(244,241,255,0.92)',
+      }),
+      el('path', {
+        d: 'M20.5 3.2a3.2 3.2 0 1 0 .6 5.9 3.6 3.6 0 0 1-.6-5.9z',
+        fill: 'rgba(244,241,255,0.5)',
+      }),
+    ]),
+  ]);
+
+// The site's own fullscreen button is often tiny, buried in a control bar, or
+// missing altogether. This one is for the film you are already watching in the
+// little window and simply want bigger.
+const buildExpandButton = () =>
+  el('button', { class: 'badge expand', type: 'button', title: 'Fullscreen' }, [
+    el('svg', { viewBox: '0 0 24 24', 'aria-hidden': 'true' }, [
+      el('path', { d: 'M4 9V4h5M20 9V4h-5M4 15v5h5M20 15v5h-5' }),
+    ]),
+  ]);
 
 export const createBadge = () => {
   const shell = createShadowHost(badgeCss, {
     width: `${SIZE_PX}px`,
-    height: `${SIZE_PX}px`,
+    height: `${STACK_HEIGHT_PX}px`,
     'pointer-events': 'auto',
   });
 
-  const button = buildButton();
-  shell.shadow.append(button);
+  const openButton = buildOpenButton();
+  const expandButton = buildExpandButton();
+  shell.shadow.append(
+    el('div', { class: 'stack' }, [openButton, expandButton]),
+  );
+
   let target = null;
   let frame = 0;
   let isMounted = false;
+  let isAwake = true;
+  let idleTimer = null;
 
   const isMostlyVisible = (rect) => {
     const visibleTop = Math.max(rect.top, 0);
@@ -52,8 +67,8 @@ export const createBadge = () => {
   // and swallowed taps meant for them.
   const placement = (rect) => {
     const left = rect.right - SIZE_PX - INSET_PX;
-    const top = rect.top + rect.height / 2 - SIZE_PX / 2;
-    const maxTop = window.innerHeight - SIZE_PX - INSET_PX;
+    const top = rect.top + rect.height / 2 - STACK_HEIGHT_PX / 2;
+    const maxTop = window.innerHeight - STACK_HEIGHT_PX - INSET_PX;
     return {
       left: `${Math.max(INSET_PX, left)}px`,
       top: `${Math.min(maxTop, Math.max(INSET_PX, top))}px`,
@@ -64,7 +79,7 @@ export const createBadge = () => {
   // primary and calls hide(). Here we only stop drawing.
   const reposition = () => {
     frame = 0;
-    if (!target?.isConnected) {
+    if (!target?.isConnected || !isAwake) {
       conceal();
       return;
     }
@@ -85,15 +100,32 @@ export const createBadge = () => {
     frame = requestAnimationFrame(reposition);
   };
 
+  // Two buttons parked on somebody's video are two buttons in the way, so they
+  // step aside when nothing has happened for a moment and come back on the next
+  // touch anywhere on the page.
+  const sleep = () => {
+    idleTimer = null;
+    isAwake = false;
+    scheduleReposition();
+  };
+
+  const wake = () => {
+    isAwake = true;
+    if (idleTimer !== null) clearTimeout(idleTimer);
+    idleTimer = setTimeout(sleep, IDLE_MS);
+    scheduleReposition();
+  };
+
   const show = (video) => {
     target = video;
     if (!isMounted) {
       document.body.append(shell.host);
       window.addEventListener('scroll', scheduleReposition, true);
       window.addEventListener('resize', scheduleReposition);
+      document.addEventListener('pointerdown', wake, true);
       isMounted = true;
     }
-    reposition();
+    wake();
   };
 
   const hide = () => {
@@ -101,19 +133,34 @@ export const createBadge = () => {
     if (!isMounted) return;
     window.removeEventListener('scroll', scheduleReposition, true);
     window.removeEventListener('resize', scheduleReposition);
+    document.removeEventListener('pointerdown', wake, true);
+    if (idleTimer !== null) clearTimeout(idleTimer);
+    idleTimer = null;
     if (frame !== 0) cancelAnimationFrame(frame);
     frame = 0;
     shell.host.remove();
     isMounted = false;
   };
 
-  const api = { show, hide, refresh: scheduleReposition, onActivate: null };
+  const api = {
+    show,
+    hide,
+    refresh: scheduleReposition,
+    onActivate: null,
+    onExpand: null,
+  };
 
-  button.addEventListener('click', (event) => {
-    event.preventDefault();
-    event.stopPropagation();
-    if (target && api.onActivate) api.onActivate(target);
-  });
+  const wire = (button, name) => {
+    button.addEventListener('click', (event) => {
+      event.preventDefault();
+      event.stopPropagation();
+      wake();
+      if (target && api[name]) api[name](target);
+    });
+  };
+
+  wire(openButton, 'onActivate');
+  wire(expandButton, 'onExpand');
 
   return api;
 };
diff --git a/src/content/index.js b/src/content/index.js
index 144c6f1..808cb76 100644
--- a/src/content/index.js
+++ b/src/content/index.js
@@ -56,6 +56,22 @@ const start = async () => {
     }, PERSIST_DELAY_MS);
   };
 
+  // Fullscreen without the takeover, for a film you are happy to watch with the
+  // site's own controls and only want bigger.
+  badge.onExpand = async (video) => {
+    try {
+      await video.requestFullscreen();
+    } catch (error) {
+      console.warn('Nocturne: the site refused fullscreen', error);
+      return;
+    }
+    try {
+      await screen.orientation.lock('landscape');
+    } catch {
+      // The lock is a nicety, not a requirement.
+    }
+  };
+
   badge.onActivate = async (video) => {
     if (session) return;
     badge.hide();

From f206ff54b9bf5c9efb6bff38cd8864f000da6fa5 Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Thu, 6 Aug 2026 14:28:35 +0300
Subject: [PATCH 12/23] feat(video): chapter markers on the seek bar

YouTube ships its chapter list inside the data it renders the page from.
The shape of that blob differs between the phone and desktop sites and
changes without notice, so the renderer is looked for by name rather than
followed down one path, with a node budget so a page that turns out to be a
maze cannot cost more than a moment.

The bar gets a divider at each chapter and the name of the section being
played sits above it.
---
 src/content/controls/seekbar.js | 41 +++++++++++++++++-
 src/content/video/chapters.js   | 77 +++++++++++++++++++++++++++++++++
 test/unit/chapters.test.js      | 22 ++++++++++
 3 files changed, 139 insertions(+), 1 deletion(-)
 create mode 100644 src/content/video/chapters.js
 create mode 100644 test/unit/chapters.test.js

diff --git a/src/content/controls/seekbar.js b/src/content/controls/seekbar.js
index d78cad6..65152e9 100644
--- a/src/content/controls/seekbar.js
+++ b/src/content/controls/seekbar.js
@@ -1,3 +1,4 @@
+import { chapterAt } from '../video/chapters.js';
 import { formatClock, formatRemaining } from '../../lib/time.js';
 import { el } from '../shell.js';
 
@@ -23,24 +24,56 @@ export const createSeekBar = (video) => {
   const elapsed = el('span', { class: 'time', text: '0:00' });
   const remaining = el('span', { class: 'time', text: '--:--' });
   const fill = el('div', { class: 'seek-fill' });
-  const track = el('div', { class: 'seek-track' }, [fill]);
+  const marks = el('div', { class: 'seek-marks' });
+  const track = el('div', { class: 'seek-track' }, [fill, marks]);
   const headTime = el('span', { class: 'seek-time', text: '0:00' });
   const area = el('div', { class: 'seek-area' }, [track, headTime]);
+  const chapterLabel = el('div', { class: 'chapter' });
   const root = el('div', { class: 'seekbar' }, [
+    chapterLabel,
     el('div', { class: 'seek-row' }, [elapsed, area, remaining]),
   ]);
 
   let isScrubbing = false;
   let scrubTime = 0;
   let lastPreviewAt = 0;
+  let chapters = [];
+  let arePlaced = false;
 
   const duration = () => (Number.isFinite(video.duration) ? video.duration : 0);
 
+  // The dividers can only be placed once the film has told us how long it is,
+  // so placing them is retried from the paint that follows.
+  const placeMarks = () => {
+    const total = duration();
+    if (arePlaced || chapters.length === 0 || total === 0) return;
+    const dividers = chapters
+      .filter((chapter) => chapter.start > 0 && chapter.start < total)
+      .map((chapter) => {
+        const mark = el('span', { class: 'seek-mark' });
+        mark.style.left = `${(chapter.start / total) * 100}%`;
+        return mark;
+      });
+    marks.replaceChildren(...dividers);
+    arePlaced = true;
+  };
+
+  const showChapter = (time) => {
+    if (chapters.length === 0) return;
+    const chapter = chapterAt(chapters, time);
+    const title = chapter === null ? '' : chapter.title;
+    if (chapterLabel.textContent === title) return;
+    chapterLabel.textContent = title;
+    chapterLabel.classList.toggle('is-visible', title !== '');
+  };
+
   // While scrubbing the left label holds the moment the drag started, so the
   // target time on the line is not simply repeated back to the user and they
   // can see where to return to.
   const paint = (time) => {
     const total = duration();
+    placeMarks();
+    showChapter(time);
     const ratio = total > 0 ? Math.min(1, Math.max(0, time / total)) : 0;
     fill.style.transform = `scaleX(${ratio})`;
     area.style.setProperty('--progress', `${ratio * 100}%`);
@@ -103,6 +136,12 @@ export const createSeekBar = (video) => {
     start,
     move,
     end,
+    setChapters: (list) => {
+      chapters = list;
+      arePlaced = false;
+      placeMarks();
+      showChapter(video.currentTime);
+    },
     destroy: () => {
       video.removeEventListener('timeupdate', sync);
       video.removeEventListener('durationchange', sync);
diff --git a/src/content/video/chapters.js b/src/content/video/chapters.js
new file mode 100644
index 0000000..458b292
--- /dev/null
+++ b/src/content/video/chapters.js
@@ -0,0 +1,77 @@
+import { pageWindow, read } from './pageapi.js';
+
+// YouTube ships the chapter list inside the blob of data it renders the page
+// from. The shape of that blob differs between the phone and desktop sites and
+// changes without notice, so rather than following one path down it we look for
+// the renderer by name — bounded, so a page that turns out to be a maze of
+// objects cannot cost more than a moment.
+const MAX_NODES = 20000;
+const MS_PER_SECOND = 1000;
+
+const readChapter = (node) => {
+  const renderer = read(node, 'chapterRenderer');
+  if (renderer === null) return null;
+
+  const title = read(read(renderer, 'title'), 'simpleText');
+  const startMs = read(renderer, 'timeRangeStartMillis');
+  const start = Number(startMs);
+  if (typeof title !== 'string' || title === '') return null;
+  if (!Number.isFinite(start)) return null;
+
+  return { title, start: start / MS_PER_SECOND };
+};
+
+const collect = (root) => {
+  const found = [];
+  const stack = [root];
+  let budget = MAX_NODES;
+
+  while (stack.length > 0 && budget > 0) {
+    const node = stack.pop();
+    budget -= 1;
+    if (node === null || typeof node !== 'object') continue;
+
+    const chapter = readChapter(node);
+    if (chapter !== null) {
+      found.push(chapter);
+      continue;
+    }
+
+    let keys = [];
+    try {
+      keys = Object.keys(node);
+    } catch {
+      continue;
+    }
+    for (const key of keys) stack.push(read(node, key));
+  }
+
+  return found;
+};
+
+// One chapter is not a chapter list, it is the whole film with a label on it.
+const MIN_CHAPTERS = 2;
+
+export const readSiteChapters = () => {
+  const data = read(pageWindow(), 'ytInitialData');
+  if (data === null) return [];
+
+  const byStart = new Map();
+  for (const chapter of collect(data)) {
+    if (!byStart.has(chapter.start)) byStart.set(chapter.start, chapter);
+  }
+
+  const chapters = Array.from(byStart.values()).sort(
+    (first, second) => first.start - second.start,
+  );
+  return chapters.length >= MIN_CHAPTERS ? chapters : [];
+};
+
+export const chapterAt = (chapters, time) => {
+  let current = null;
+  for (const chapter of chapters) {
+    if (chapter.start > time) break;
+    current = chapter;
+  }
+  return current;
+};
diff --git a/test/unit/chapters.test.js b/test/unit/chapters.test.js
new file mode 100644
index 0000000..4185fe9
--- /dev/null
+++ b/test/unit/chapters.test.js
@@ -0,0 +1,22 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { chapterAt } from '../../src/content/video/chapters.js';
+
+const CHAPTERS = [
+  { title: 'Intro', start: 0 },
+  { title: 'The plan', start: 65 },
+  { title: 'The heist', start: 240 },
+];
+
+test('the chapter is the last one that has started', () => {
+  assert.equal(chapterAt(CHAPTERS, 0).title, 'Intro');
+  assert.equal(chapterAt(CHAPTERS, 64.9).title, 'Intro');
+  assert.equal(chapterAt(CHAPTERS, 65).title, 'The plan');
+  assert.equal(chapterAt(CHAPTERS, 1200).title, 'The heist');
+});
+
+test('a time before the first chapter has no chapter', () => {
+  assert.equal(chapterAt([{ title: 'Later', start: 30 }], 10), null);
+  assert.equal(chapterAt([], 10), null);
+});

From d996194e17c4fa250f943ed00d34295cba7c2b63 Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Thu, 6 Aug 2026 14:28:51 +0300
Subject: [PATCH 13/23] fix(video): find the site's player before the video
 moves
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Quality could not be changed anywhere, and this is the likeliest reason: the
adapters looked for the site's player object by searching the document, but
by then the video had already been lifted out of it and onto our stage.

The player API is now read from the video's own ancestors at the moment the
session starts, before anything is moved, and handed to the quality adapters
and the caption reader. The document search stays as the fallback.

The sheet also says which of the two things happened — no player found, or a
player that is offering nothing — rather than the same flat note for both.
---
 src/content/session.js               | 11 +++++++++++
 src/content/video/pageapi.js         | 15 +++++++++++++++
 src/content/video/quality.js         | 15 +++++++++++----
 src/content/video/qualityadapters.js | 13 +++++++++----
 src/content/video/sitecaptions.js    | 11 ++++++-----
 src/content/video/tracks.js          |  4 ++--
 6 files changed, 54 insertions(+), 15 deletions(-)

diff --git a/src/content/session.js b/src/content/session.js
index 1c61d5c..6e2e16b 100644
--- a/src/content/session.js
+++ b/src/content/session.js
@@ -1,7 +1,16 @@
 import { createOverlay } from './ui.js';
 import { createShadowHost, el, pinStyle } from './shell.js';
+import { findApiAncestor } from './video/pageapi.js';
 import playerCss from './player.css';
 
+// The names a site's own player hangs off the element wrapping the video.
+const PLAYER_API_MARKERS = [
+  'getAvailableQualityLevels',
+  'setPlaybackQualityRange',
+  'getOption',
+  'levels',
+];
+
 const STALL_GRACE_MS = 400;
 const EMPTIED_GRACE_MS = 600;
 const RECOVER_DELAY_MS = 250;
@@ -141,6 +150,7 @@ const isBackgrounded = () => document.hidden || !document.hasFocus();
 
 export const createSession = (video, { onExit, settings, onPersist }) => {
   const state = captureVideoState(video);
+  const playerHost = findApiAncestor(video, PLAYER_API_MARKERS);
   const anchor = document.createComment('nocturne-player');
   const stage = document.createElement('div');
   const ui = createShadowHost(playerCss);
@@ -334,6 +344,7 @@ export const createSession = (video, { onExit, settings, onPersist }) => {
       onExit: exit,
       settings,
       onPersist,
+      playerHost,
       onImmersiveChange: (isOn) => {
         isFullscreenWanted = isOn;
         if (isOn) {
diff --git a/src/content/video/pageapi.js b/src/content/video/pageapi.js
index 24d6c88..56635db 100644
--- a/src/content/video/pageapi.js
+++ b/src/content/video/pageapi.js
@@ -83,6 +83,21 @@ export const isFunction = (object, name) => {
   }
 };
 
+// A site's player API usually lives on an ancestor of the video: YouTube puts
+// it on #movie_player. This has to be read before the video is moved onto our
+// stage, because afterwards the chain of ancestors is ours, not theirs.
+export const findApiAncestor = (element, names) => {
+  let node = element.parentElement;
+  while (node !== null) {
+    const waived = node.wrappedJSObject ?? node;
+    for (const name of names) {
+      if (isFunction(waived, name)) return waived;
+    }
+    node = node.parentElement;
+  }
+  return null;
+};
+
 // A last resort for players that keep their engine on a global under a name
 // only they know. Bounded, and every property read is guarded, because a getter
 // on a page global can throw or be expensive.
diff --git a/src/content/video/quality.js b/src/content/video/quality.js
index d43577e..cbffc0b 100644
--- a/src/content/video/quality.js
+++ b/src/content/video/quality.js
@@ -5,14 +5,14 @@ export { AUTO_ID };
 // A streaming player builds its quality ladder after the first segments land,
 // so the ladder is looked up again every time the sheet is opened rather than
 // once when the session starts.
-export const createQuality = (video) => {
+export const createQuality = (video, host = null) => {
   let adapter = null;
   let options = [];
 
   const detect = () => {
     for (const create of ADAPTERS) {
       try {
-        const candidate = create(video);
+        const candidate = create(video, host);
         if (candidate !== null) return candidate;
       } catch (error) {
         console.warn('Nocturne: a quality adapter threw while probing', error);
@@ -33,9 +33,16 @@ export const createQuality = (video) => {
     return options;
   };
 
+  // Says which of the two things went wrong, because "no quality here" and
+  // "found the player, it is offering nothing yet" want different answers from
+  // whoever is looking at it.
   const describe = () => {
-    if (video.videoWidth === 0) return 'Set by the site';
-    return `${video.videoWidth}×${video.videoHeight} · set by the site`;
+    const size =
+      video.videoWidth === 0
+        ? ''
+        : `${video.videoWidth}×${video.videoHeight} · `;
+    if (adapter !== null) return `${size}${adapter.name}: no levels yet`;
+    return `${size}set by the site`;
   };
 
   return {
diff --git a/src/content/video/qualityadapters.js b/src/content/video/qualityadapters.js
index d5e3990..38a7069 100644
--- a/src/content/video/qualityadapters.js
+++ b/src/content/video/qualityadapters.js
@@ -83,15 +83,18 @@ const createSourceAdapter = (video) => {
 
 // --- YouTube -----------------------------------------------------------------
 
-const findYouTubePlayer = () => {
+const findYouTubePlayer = (host) => {
+  if (host !== null && isFunction(host, 'getAvailableQualityLevels')) {
+    return host;
+  }
   const element = document.querySelector('#movie_player, .html5-video-player');
   if (element === null) return null;
   const player = element.wrappedJSObject ?? element;
   return isFunction(player, 'getAvailableQualityLevels') ? player : null;
 };
 
-const createYouTubeAdapter = () => {
-  const player = findYouTubePlayer();
+const createYouTubeAdapter = (video, host) => {
+  const player = findYouTubePlayer(host);
   if (player === null) return null;
 
   // YouTube reports the quality it is actually playing, which on auto keeps
@@ -312,7 +315,9 @@ const MATCHERS = [
 
 // One sweep of the page's globals for all three streaming engines, after the
 // cheap check of whether the engine is hanging off the element itself.
-const createStreamAdapter = (video) => {
+const createStreamAdapter = (video, host) => {
+  if (host !== null && isHlsEngine(host)) return buildHlsAdapter(host);
+
   const attached = findHlsOnElement(video);
   if (attached !== null) return buildHlsAdapter(attached);
 
diff --git a/src/content/video/sitecaptions.js b/src/content/video/sitecaptions.js
index 91ef64a..b08a19d 100644
--- a/src/content/video/sitecaptions.js
+++ b/src/content/video/sitecaptions.js
@@ -44,7 +44,8 @@ const findContainer = () => {
   return null;
 };
 
-const findYouTubePlayer = () => {
+const findYouTubePlayer = (host) => {
+  if (host !== null && isFunction(host, 'getOption')) return host;
   const element = document.querySelector('#movie_player, .html5-video-player');
   if (element === null) return null;
   const player = element.wrappedJSObject ?? element;
@@ -55,8 +56,8 @@ const findYouTubePlayer = () => {
 // video.textTracks, so the list comes from there and the text comes from the
 // mirror above. Other players expose the mirror only, which is still enough to
 // show whatever the site has switched on.
-const createYouTubeTracks = () => {
-  const player = findYouTubePlayer();
+const createYouTubeTracks = (host) => {
+  const player = findYouTubePlayer(host);
   if (player === null) return null;
 
   const tracklist = () => {
@@ -101,8 +102,8 @@ const createYouTubeTracks = () => {
   };
 };
 
-export const createSiteCaptions = (onText) => {
-  const youtube = createYouTubeTracks();
+export const createSiteCaptions = (onText, host = null) => {
+  const youtube = createYouTubeTracks(host);
 
   let container = null;
   let observer = null;
diff --git a/src/content/video/tracks.js b/src/content/video/tracks.js
index 346531e..ae4a618 100644
--- a/src/content/video/tracks.js
+++ b/src/content/video/tracks.js
@@ -38,7 +38,7 @@ const loadTrackCues = (track, onReady) => {
   poll();
 };
 
-export const createTrackManager = (video, onCue, onSelection) => {
+export const createTrackManager = (video, onCue, onSelection, host = null) => {
   const loaded = [];
 
   let cues = [];
@@ -63,7 +63,7 @@ export const createTrackManager = (video, onCue, onSelection) => {
   // mutation arriving after a switch must not put its line back on screen.
   const site = createSiteCaptions((text) => {
     if (isSiteId(selected)) emit(text);
-  });
+  }, host);
 
   const update = () => {
     if (selected === -1 || isNative || isSiteId(selected)) return;

From c66baba302eb8bfaf40f315ce5df022b921f719e Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Thu, 6 Aug 2026 14:28:52 +0300
Subject: [PATCH 14/23] feat(controls): picture-in-picture leaves for the home
 screen

Android floats a video when the app it is playing in goes to the background,
and Gecko gives a page no way to ask for that directly. It does leave one
way to go to the background: an intent URL for the launcher, loaded in a
throwaway frame so a browser that does not handle the scheme fails quietly
instead of navigating the film away.

Also in this change: the button order at the top is picture-in-picture,
colour, settings; the scrim behind the controls is heavier, because the film
keeps playing underneath and the buttons have to stay legible; choosing a
quality now says so, since the change itself takes a second to show; and the
chapter list is read once the picture is up rather than in the way of it.
---
 src/content/controls/menu.js |  6 +++-
 src/content/player.css       | 61 +++++++++++++++++++++++++++-------
 src/content/ui.js            | 63 ++++++++++++++++++++++++++++++------
 3 files changed, 108 insertions(+), 22 deletions(-)

diff --git a/src/content/controls/menu.js b/src/content/controls/menu.js
index 3b3cdb4..12383f2 100644
--- a/src/content/controls/menu.js
+++ b/src/content/controls/menu.js
@@ -93,6 +93,7 @@ export const createMenu = ({
   onPickFile,
   onRate,
   onImmersive,
+  onNotice,
 }) => {
   const speedRow = buildChipRow('Speed');
   const setSpeed = paintChips(
@@ -127,7 +128,10 @@ export const createMenu = ({
       return;
     }
     const setQuality = paintChips(qualityRow, options, (id) => {
-      quality.select(id);
+      const chosen = options.find((option) => String(option.id) === String(id));
+      const label = chosen ? chosen.label : String(id);
+      const isDone = quality.select(id);
+      onNotice(isDone ? `Quality: ${label}` : 'The site would not change it');
     });
     setQuality(quality.getCurrent());
   };
diff --git a/src/content/player.css b/src/content/player.css
index 1ae7bc7..97a5c58 100644
--- a/src/content/player.css
+++ b/src/content/player.css
@@ -51,21 +51,17 @@
   background:
     linear-gradient(
       to bottom,
-      rgba(0, 0, 0, 0.5) 0%,
-      rgba(0, 0, 0, 0.16) 16%,
-      rgba(0, 0, 0, 0) 34%
+      rgba(0, 0, 0, 0.72) 0%,
+      rgba(0, 0, 0, 0.34) 14%,
+      rgba(0, 0, 0, 0) 38%
     ),
     linear-gradient(
       to top,
-      rgba(0, 0, 0, 0.62) 0%,
-      rgba(0, 0, 0, 0.22) 22%,
-      rgba(0, 0, 0, 0) 46%
+      rgba(0, 0, 0, 0.82) 0%,
+      rgba(0, 0, 0, 0.42) 20%,
+      rgba(0, 0, 0, 0) 50%
     ),
-    radial-gradient(
-      ellipse 70% 55% at 50% 50%,
-      rgba(0, 0, 0, 0.12) 0%,
-      rgba(0, 0, 0, 0) 100%
-    );
+    linear-gradient(rgba(0, 0, 0, 0.28), rgba(0, 0, 0, 0.28));
   pointer-events: none;
 }
 
@@ -199,6 +195,40 @@
   overflow: hidden;
 }
 
+/* Chapter dividers sit inside the track, so the fill runs under them. */
+.seek-marks {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+
+.seek-mark {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 3px;
+  margin-left: -1.5px;
+  background: rgba(10, 9, 14, 0.75);
+}
+
+/* The name of the section being played, above the bar and out of the way. */
+.chapter {
+  margin: 0 0 8px 58px;
+  font-size: 13px;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+  text-shadow: 0 2px 6px rgba(0, 0, 0, 0.9);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  opacity: 0;
+  transition: opacity 220ms var(--ease);
+}
+
+.chapter.is-visible {
+  opacity: 0.92;
+}
+
 .seek-fill {
   position: absolute;
   inset: 0;
@@ -384,6 +414,15 @@
   color: #16151c;
 }
 
+.hidden-frame {
+  position: absolute;
+  width: 0;
+  height: 0;
+  border: 0;
+  opacity: 0;
+  pointer-events: none;
+}
+
 .file-picker {
   position: absolute;
   width: 1px;
diff --git a/src/content/ui.js b/src/content/ui.js
index 5930f45..eadd07f 100644
--- a/src/content/ui.js
+++ b/src/content/ui.js
@@ -1,3 +1,4 @@
+import { readSiteChapters } from './video/chapters.js';
 import { createColorPanel } from './controls/colorpanel.js';
 import { createMenu } from './controls/menu.js';
 import { createQuality } from './video/quality.js';
@@ -15,6 +16,16 @@ const TOAST_MS = 900;
 const HINT_MS = 2200;
 const SKIP_SECONDS = 10;
 const FILL_RETRY_MS = 400;
+const FRAME_LIFE_MS = 2000;
+const CHAPTER_DELAY_MS = 1200;
+const HANDOFF_GRACE_MS = 900;
+
+// The Android launcher, asked for by intent. Nothing is loaded from anywhere:
+// the URL names an activity on the phone, and the browser either hands it to
+// the system or ignores it.
+const HOME_INTENT =
+  'intent://#Intent;action=android.intent.action.MAIN;' +
+  'category=android.intent.category.HOME;end';
 const FILL_ATTEMPTS = 25;
 
 const ICON = {
@@ -74,6 +85,7 @@ export const createOverlay = ({
   onExit,
   settings,
   onPersist,
+  playerHost,
   onImmersiveChange,
 }) => {
   const surface = el('div', { class: 'layer surface' });
@@ -98,7 +110,7 @@ export const createOverlay = ({
   video.playbackRate = 1;
 
   const visuals = createVisuals(video, stage);
-  const quality = createQuality(video);
+  const quality = createQuality(video, playerHost);
   const tracks = createTrackManager(
     video,
     (text) => {
@@ -106,6 +118,7 @@ export const createOverlay = ({
       cueBox.classList.toggle('is-visible', text !== '');
     },
     (id) => menuRef.setSubtitle(id),
+    playerHost,
   );
 
   const seekBar = createSeekBar(video);
@@ -147,6 +160,7 @@ export const createOverlay = ({
     },
     onPickFile: () => filePicker.click(),
     onRate: () => {},
+    onNotice: (text) => showToast(text, HINT_MS),
     onImmersive: (isOn) => {
       onImmersiveChange(isOn);
       onPersist({ isFullscreenTakeoverOn: isOn });
@@ -299,28 +313,49 @@ export const createOverlay = ({
     setChromeVisible(true);
   });
 
-  // Where a thumb already is when the phone is held in landscape. Gecko has no
-  // web API for the floating window on Android — the system offers it when you
-  // leave the app with a video playing — so the button uses the standard API
-  // where it exists and otherwise sets the video up and says what to do.
+  // Gecko has no Web API for the floating window on Android. What Android has
+  // is a rule: a video playing in a fullscreen app keeps playing, floating,
+  // once that app goes to the background. So the button does the one thing
+  // that reliably triggers it — it goes to the home screen.
+  //
+  // The launcher is asked for through an intent URL in a throwaway frame. In a
+  // frame, a browser that does not handle the scheme fails quietly instead of
+  // navigating the film away, which is what would happen from the top window.
+  const leaveForHomeScreen = () => {
+    const attributes = { class: 'hidden-frame', 'aria-hidden': 'true' };
+    const frame = el('iframe', attributes);
+    document.body.append(frame);
+    try {
+      frame.src = HOME_INTENT;
+    } catch (error) {
+      console.warn('Nocturne: could not reach the home screen', error);
+    }
+    setTimeout(() => frame.remove(), FRAME_LIFE_MS);
+  };
+
   const enterPictureInPicture = () => {
     setChromeVisible(true);
     if (video.paused) video.play().catch(() => {});
-    if (typeof video.requestPictureInPicture !== 'function') {
-      showToast('Swipe up to keep it floating', HINT_MS);
+
+    if (typeof video.requestPictureInPicture === 'function') {
+      video.requestPictureInPicture().catch(leaveForHomeScreen);
       return;
     }
-    video.requestPictureInPicture().catch(() => {
+
+    leaveForHomeScreen();
+    // If nothing took us away, say what does.
+    setTimeout(() => {
+      if (document.hidden) return;
       showToast('Swipe up to keep it floating', HINT_MS);
-    });
+    }, HANDOFF_GRACE_MS);
   };
 
   topbar.append(
     buildButton('Exit player', ICON.exit, () => onExit()),
     el('div', { class: 'spacer' }),
+    buildButton('Picture in picture', ICON.pip, enterPictureInPicture),
     buttons.colour,
     buttons.menu,
-    buildButton('Picture in picture', ICON.pip, enterPictureInPicture),
   );
 
   chrome.append(
@@ -389,6 +424,13 @@ export const createOverlay = ({
     setTimeout(fillWhenReady, FILL_RETRY_MS);
   };
 
+  // Walking the site's page data is not free, so it happens after the picture
+  // is up rather than in the way of it.
+  const chapterTimer = setTimeout(() => {
+    const chapters = readSiteChapters();
+    if (chapters.length > 0) seekBar.setChapters(chapters);
+  }, CHAPTER_DELAY_MS);
+
   restoreSettings();
   fillWhenReady();
   shadow.append(surface, cueBox, chrome, toast, filePicker);
@@ -403,6 +445,7 @@ export const createOverlay = ({
       stopScrub();
       if (chromeTimer !== null) clearTimeout(chromeTimer);
       if (toastTimer !== null) clearTimeout(toastTimer);
+      clearTimeout(chapterTimer);
       video.removeEventListener('pause', handlePlaybackChange);
       video.removeEventListener('play', handlePlaybackChange);
     },

From 9fd758e72d19c46ede52660be782ea347b33d6c7 Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Thu, 6 Aug 2026 14:42:05 +0300
Subject: [PATCH 15/23] fix(video): read the quality ladder off the video's own
 formats
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The phone's YouTube player answers getAvailableQualityLevels() with an empty
list, which is why the sheet kept saying it had found the player but had
nothing to offer. The ladder is now worked out from the formats the video
actually has — each one carries the height it was encoded at, which is the
same thing the quality names stand for — and the note says which of the two
ways in produced something.

Chapters are read from the player's own response first, then from the two
page blobs, in both the shapes YouTube writes them in, and the read is tried
again twice: a page navigated to from the feed fills its data in late.

The badge is one button again, wearing the fullscreen arrows: what it does
is make this video fill the screen, and that is what a viewer looks for.
---
 src/content/controls/badge.css       |  26 ++----
 src/content/controls/badge.js        |  63 ++++-----------
 src/content/index.js                 |  16 ----
 src/content/ui.js                    |  17 ++--
 src/content/video/chapters.js        | 113 ++++++++++++++++++++-------
 src/content/video/quality.js         |   5 +-
 src/content/video/qualityadapters.js |  56 ++++++++++++-
 7 files changed, 175 insertions(+), 121 deletions(-)

diff --git a/src/content/controls/badge.css b/src/content/controls/badge.css
index c098ec1..ad9245a 100644
--- a/src/content/controls/badge.css
+++ b/src/content/controls/badge.css
@@ -1,22 +1,11 @@
-/* Two buttons in a column against the right edge of the video: open the
-   player, or just make the small window fullscreen and leave the site's own
-   controls in charge. */
-.stack {
+.badge {
   position: absolute;
   inset: 0;
   display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: space-between;
-}
-
-.badge {
-  flex: none;
-  display: flex;
   align-items: center;
   justify-content: center;
-  width: 44px;
-  height: 44px;
+  width: 100%;
+  height: 100%;
   padding: 0;
   border: 0;
   border-radius: 999px;
@@ -36,14 +25,9 @@
 }
 
 .badge svg {
-  width: 22px;
-  height: 22px;
+  width: 21px;
+  height: 21px;
   display: block;
-}
-
-.badge.expand svg {
-  width: 20px;
-  height: 20px;
   fill: none;
   stroke: currentColor;
   stroke-width: 2;
diff --git a/src/content/controls/badge.js b/src/content/controls/badge.js
index feb948c..ad541df 100644
--- a/src/content/controls/badge.js
+++ b/src/content/controls/badge.js
@@ -2,31 +2,14 @@ import { createShadowHost, el, pinStyle } from '../shell.js';
 import badgeCss from './badge.css';
 
 const SIZE_PX = 44;
-const GAP_PX = 10;
-const STACK_HEIGHT_PX = SIZE_PX * 2 + GAP_PX;
 const INSET_PX = 12;
 const MIN_VISIBLE_RATIO = 0.35;
 const IDLE_MS = 3200;
 
-const buildOpenButton = () =>
-  el('button', { class: 'badge', type: 'button', title: 'Open in Nocturne' }, [
-    el('svg', { viewBox: '0 0 24 24', 'aria-hidden': 'true' }, [
-      el('path', {
-        d: 'M8 6.5 17 12l-9 5.5z',
-        fill: 'rgba(244,241,255,0.92)',
-      }),
-      el('path', {
-        d: 'M20.5 3.2a3.2 3.2 0 1 0 .6 5.9 3.6 3.6 0 0 1-.6-5.9z',
-        fill: 'rgba(244,241,255,0.5)',
-      }),
-    ]),
-  ]);
-
-// The site's own fullscreen button is often tiny, buried in a control bar, or
-// missing altogether. This one is for the film you are already watching in the
-// little window and simply want bigger.
-const buildExpandButton = () =>
-  el('button', { class: 'badge expand', type: 'button', title: 'Fullscreen' }, [
+// Fullscreen arrows rather than a logo: what the button does is make this
+// video fill the screen, and that is what a viewer is looking for.
+const buildButton = () =>
+  el('button', { class: 'badge', type: 'button', title: 'Fullscreen' }, [
     el('svg', { viewBox: '0 0 24 24', 'aria-hidden': 'true' }, [
       el('path', { d: 'M4 9V4h5M20 9V4h-5M4 15v5h5M20 15v5h-5' }),
     ]),
@@ -35,15 +18,12 @@ const buildExpandButton = () =>
 export const createBadge = () => {
   const shell = createShadowHost(badgeCss, {
     width: `${SIZE_PX}px`,
-    height: `${STACK_HEIGHT_PX}px`,
+    height: `${SIZE_PX}px`,
     'pointer-events': 'auto',
   });
 
-  const openButton = buildOpenButton();
-  const expandButton = buildExpandButton();
-  shell.shadow.append(
-    el('div', { class: 'stack' }, [openButton, expandButton]),
-  );
+  const button = buildButton();
+  shell.shadow.append(button);
 
   let target = null;
   let frame = 0;
@@ -67,8 +47,8 @@ export const createBadge = () => {
   // and swallowed taps meant for them.
   const placement = (rect) => {
     const left = rect.right - SIZE_PX - INSET_PX;
-    const top = rect.top + rect.height / 2 - STACK_HEIGHT_PX / 2;
-    const maxTop = window.innerHeight - STACK_HEIGHT_PX - INSET_PX;
+    const top = rect.top + rect.height / 2 - SIZE_PX / 2;
+    const maxTop = window.innerHeight - SIZE_PX - INSET_PX;
     return {
       left: `${Math.max(INSET_PX, left)}px`,
       top: `${Math.min(maxTop, Math.max(INSET_PX, top))}px`,
@@ -142,25 +122,14 @@ export const createBadge = () => {
     isMounted = false;
   };
 
-  const api = {
-    show,
-    hide,
-    refresh: scheduleReposition,
-    onActivate: null,
-    onExpand: null,
-  };
-
-  const wire = (button, name) => {
-    button.addEventListener('click', (event) => {
-      event.preventDefault();
-      event.stopPropagation();
-      wake();
-      if (target && api[name]) api[name](target);
-    });
-  };
+  const api = { show, hide, refresh: scheduleReposition, onActivate: null };
 
-  wire(openButton, 'onActivate');
-  wire(expandButton, 'onExpand');
+  button.addEventListener('click', (event) => {
+    event.preventDefault();
+    event.stopPropagation();
+    wake();
+    if (target && api.onActivate) api.onActivate(target);
+  });
 
   return api;
 };
diff --git a/src/content/index.js b/src/content/index.js
index 808cb76..144c6f1 100644
--- a/src/content/index.js
+++ b/src/content/index.js
@@ -56,22 +56,6 @@ const start = async () => {
     }, PERSIST_DELAY_MS);
   };
 
-  // Fullscreen without the takeover, for a film you are happy to watch with the
-  // site's own controls and only want bigger.
-  badge.onExpand = async (video) => {
-    try {
-      await video.requestFullscreen();
-    } catch (error) {
-      console.warn('Nocturne: the site refused fullscreen', error);
-      return;
-    }
-    try {
-      await screen.orientation.lock('landscape');
-    } catch {
-      // The lock is a nicety, not a requirement.
-    }
-  };
-
   badge.onActivate = async (video) => {
     if (session) return;
     badge.hide();
diff --git a/src/content/ui.js b/src/content/ui.js
index eadd07f..c6f4f09 100644
--- a/src/content/ui.js
+++ b/src/content/ui.js
@@ -17,7 +17,7 @@ const HINT_MS = 2200;
 const SKIP_SECONDS = 10;
 const FILL_RETRY_MS = 400;
 const FRAME_LIFE_MS = 2000;
-const CHAPTER_DELAY_MS = 1200;
+const CHAPTER_TRIES_MS = [1200, 4000, 10000];
 const HANDOFF_GRACE_MS = 900;
 
 // The Android launcher, asked for by intent. Nothing is loaded from anywhere:
@@ -425,11 +425,14 @@ export const createOverlay = ({
   };
 
   // Walking the site's page data is not free, so it happens after the picture
-  // is up rather than in the way of it.
-  const chapterTimer = setTimeout(() => {
-    const chapters = readSiteChapters();
-    if (chapters.length > 0) seekBar.setChapters(chapters);
-  }, CHAPTER_DELAY_MS);
+  // is up rather than in the way of it — and more than once, because a page
+  // that was navigated to fills its data in some time after the video starts.
+  const chapterTimers = CHAPTER_TRIES_MS.map((delay) =>
+    setTimeout(() => {
+      const chapters = readSiteChapters(playerHost);
+      if (chapters.length > 0) seekBar.setChapters(chapters);
+    }, delay),
+  );
 
   restoreSettings();
   fillWhenReady();
@@ -445,7 +448,7 @@ export const createOverlay = ({
       stopScrub();
       if (chromeTimer !== null) clearTimeout(chromeTimer);
       if (toastTimer !== null) clearTimeout(toastTimer);
-      clearTimeout(chapterTimer);
+      for (const timer of chapterTimers) clearTimeout(timer);
       video.removeEventListener('pause', handlePlaybackChange);
       video.removeEventListener('play', handlePlaybackChange);
     },
diff --git a/src/content/video/chapters.js b/src/content/video/chapters.js
index 458b292..aecf31e 100644
--- a/src/content/video/chapters.js
+++ b/src/content/video/chapters.js
@@ -1,24 +1,68 @@
-import { pageWindow, read } from './pageapi.js';
-
-// YouTube ships the chapter list inside the blob of data it renders the page
-// from. The shape of that blob differs between the phone and desktop sites and
-// changes without notice, so rather than following one path down it we look for
-// the renderer by name — bounded, so a page that turns out to be a maze of
-// objects cannot cost more than a moment.
-const MAX_NODES = 20000;
+import { call, pageWindow, read, toArray } from './pageapi.js';
+
+// YouTube ships its chapter list inside the blob of data it renders the page
+// from. It sits in a different place on the phone site than on the desktop one,
+// under a different renderer, and moves without notice — so rather than
+// following one path down, the renderers are looked for by name, in every blob
+// the page is willing to show us, with a node budget so a page that turns out
+// to be a maze cannot cost more than a moment.
+const MAX_NODES = 30000;
+const MAX_RENDERER_NODES = 400;
 const MS_PER_SECOND = 1000;
+const MIN_CHAPTERS = 2;
 
-const readChapter = (node) => {
-  const renderer = read(node, 'chapterRenderer');
-  if (renderer === null) return null;
+const RENDERER_KEYS = ['chapterRenderer', 'macroMarkersListItemRenderer'];
 
-  const title = read(read(renderer, 'title'), 'simpleText');
-  const startMs = read(renderer, 'timeRangeStartMillis');
-  const start = Number(startMs);
-  if (typeof title !== 'string' || title === '') return null;
-  if (!Number.isFinite(start)) return null;
+const readTitle = (renderer) => {
+  const title = read(renderer, 'title');
+  const simple = read(title, 'simpleText');
+  if (typeof simple === 'string' && simple !== '') return simple;
 
-  return { title, start: start / MS_PER_SECOND };
+  const runs = toArray(read(title, 'runs'))
+    .map((run) => read(run, 'text'))
+    .filter((text) => typeof text === 'string');
+  return runs.join('');
+};
+
+// The start time is spelled two ways and buried at a different depth in each
+// shape, so it is searched for within the renderer rather than reached for.
+const readStart = (renderer) => {
+  const stack = [renderer];
+  let budget = MAX_RENDERER_NODES;
+
+  while (stack.length > 0 && budget > 0) {
+    const node = stack.pop();
+    budget -= 1;
+    if (node === null || typeof node !== 'object') continue;
+
+    const millis = Number(read(node, 'timeRangeStartMillis'));
+    if (Number.isFinite(millis)) return millis / MS_PER_SECOND;
+
+    const seconds = Number(read(node, 'startTimeSeconds'));
+    if (Number.isFinite(seconds)) return seconds;
+
+    let keys = [];
+    try {
+      keys = Object.keys(node);
+    } catch {
+      continue;
+    }
+    for (const key of keys) stack.push(read(node, key));
+  }
+  return null;
+};
+
+const readChapter = (node) => {
+  for (const key of RENDERER_KEYS) {
+    const renderer = read(node, key);
+    if (renderer === null) continue;
+
+    const title = readTitle(renderer);
+    const start = readStart(renderer);
+    if (title === '' || start === null) continue;
+    return { title, start };
+  }
+  return null;
 };
 
 const collect = (root) => {
@@ -49,22 +93,35 @@ const collect = (root) => {
   return found;
 };
 
-// One chapter is not a chapter list, it is the whole film with a label on it.
-const MIN_CHAPTERS = 2;
-
-export const readSiteChapters = () => {
-  const data = read(pageWindow(), 'ytInitialData');
-  if (data === null) return [];
-
+const tidy = (chapters) => {
   const byStart = new Map();
-  for (const chapter of collect(data)) {
+  for (const chapter of chapters) {
     if (!byStart.has(chapter.start)) byStart.set(chapter.start, chapter);
   }
-
-  const chapters = Array.from(byStart.values()).sort(
+  const sorted = Array.from(byStart.values()).sort(
     (first, second) => first.start - second.start,
   );
-  return chapters.length >= MIN_CHAPTERS ? chapters : [];
+  // One chapter is not a chapter list, it is the whole film with a label on it.
+  return sorted.length >= MIN_CHAPTERS ? sorted : [];
+};
+
+// The player's own answer comes first: it is the only source that is certainly
+// about the video playing right now, rather than about whatever page happened
+// to be loaded before the viewer clicked through to this one.
+export const readSiteChapters = (playerHost = null) => {
+  const scope = pageWindow();
+  const sources = [
+    call(playerHost, 'getPlayerResponse'),
+    read(scope, 'ytInitialData'),
+    read(scope, 'ytInitialPlayerResponse'),
+  ];
+
+  for (const source of sources) {
+    if (source === null) continue;
+    const chapters = tidy(collect(source));
+    if (chapters.length > 0) return chapters;
+  }
+  return [];
 };
 
 export const chapterAt = (chapters, time) => {
diff --git a/src/content/video/quality.js b/src/content/video/quality.js
index cbffc0b..09d39b1 100644
--- a/src/content/video/quality.js
+++ b/src/content/video/quality.js
@@ -41,7 +41,10 @@ export const createQuality = (video, host = null) => {
       video.videoWidth === 0
         ? ''
         : `${video.videoWidth}×${video.videoHeight} · `;
-    if (adapter !== null) return `${size}${adapter.name}: no levels yet`;
+    if (adapter !== null) {
+      const detail = adapter.diagnose ? adapter.diagnose() : 'no levels yet';
+      return `${size}${adapter.name}: ${detail}`;
+    }
     return `${size}set by the site`;
   };
 
diff --git a/src/content/video/qualityadapters.js b/src/content/video/qualityadapters.js
index 38a7069..a3e4755 100644
--- a/src/content/video/qualityadapters.js
+++ b/src/content/video/qualityadapters.js
@@ -25,6 +25,30 @@ const YOUTUBE_LABELS = {
 const YOUTUBE_LOWEST = 'tiny';
 const YOUTUBE_HIGHEST = 'highres';
 
+// Best first, which is both the order the chips want and the order the ladder
+// is read in.
+const YOUTUBE_LADDER = [
+  { key: 'highres', height: 4320 },
+  { key: 'hd2160', height: 2160 },
+  { key: 'hd1440', height: 1440 },
+  { key: 'hd1080', height: 1080 },
+  { key: 'hd720', height: 720 },
+  { key: 'large', height: 480 },
+  { key: 'medium', height: 360 },
+  { key: 'small', height: 240 },
+  { key: 'tiny', height: 144 },
+];
+
+const youtubeKeyFor = (height) => {
+  for (const rung of YOUTUBE_LADDER) {
+    if (height >= rung.height) return rung.key;
+  }
+  return 'tiny';
+};
+
+const inLadderOrder = (keys) =>
+  YOUTUBE_LADDER.filter((rung) => keys.has(rung.key)).map((rung) => rung.key);
+
 const heightLabel = (height, fallback) =>
   typeof height === 'number' && height > 0 ? `${height}p` : fallback;
 
@@ -102,14 +126,44 @@ const createYouTubeAdapter = (video, host) => {
   // remembered here and the played value is only the opening guess.
   let chosen = null;
 
-  const levels = () =>
+  const advertised = () =>
     toArray(call(player, 'getAvailableQualityLevels')).filter(
       (level) => typeof level === 'string' && level !== AUTO_ID,
     );
 
+  // The phone player answers getAvailableQualityLevels() with nothing at all,
+  // so the ladder is worked out from the formats the video actually has. Every
+  // one of them carries the height it was encoded at, which is the same thing
+  // the quality names stand for.
+  const fromFormats = () => {
+    const response = call(player, 'getPlayerResponse');
+    const streaming = read(response, 'streamingData');
+    const formats = toArray(read(streaming, 'adaptiveFormats')).concat(
+      toArray(read(streaming, 'formats')),
+    );
+
+    const keys = new Set();
+    for (const format of formats) {
+      const height = read(format, 'height');
+      if (typeof height === 'number' && height > 0) {
+        keys.add(youtubeKeyFor(height));
+      }
+    }
+    return inLadderOrder(keys);
+  };
+
+  const levels = () => {
+    const listed = advertised();
+    return listed.length > 0 ? listed : fromFormats();
+  };
+
   return {
     name: 'youtube',
     hasAuto: true,
+    // Which of the two ways in produced something, in the words of whoever has
+    // to work out why a film is not offering the rung they want.
+    diagnose: () =>
+      `${advertised().length} listed, ${fromFormats().length} in formats`,
     list: () =>
       levels().map((level) => ({
         id: level,

From 6c493e072fed9db98b7f7731877eb4724091f2b7 Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Fri, 7 Aug 2026 08:34:20 +0300
Subject: [PATCH 16/23] docs: notes for reviewers and the rest of the 0.3.0
 story

The changelog stopped at the middle of the release: the home-screen
hand-off, the chapters, the button on the site's own player and the
ladder read off the formats all landed after it was written.

Reviewers get build instructions, because a bundled package without
them is a package that waits in the queue.
---
 CHANGELOG.md | 30 +++++++++++++++++++++++----
 README.md    | 23 +++++++++++++--------
 REVIEWERS.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 98 insertions(+), 12 deletions(-)
 create mode 100644 REVIEWERS.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b691eac..0ebd253 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,7 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased][unreleased]
 
-## [0.3.0][] - 2026-08-06
+## [0.3.0][] - 2026-08-07
 
 Everything in this release comes from watching real films on a real phone with
 0.2.0 installed.
@@ -23,9 +23,18 @@ Everything in this release comes from watching real films on a real phone with
   through its player API and the text it renders is mirrored into the player's
   cue layer, which is why subtitles were missing there before. The same mirror
   covers Shaka, video.js, JW Player, Plyr and Playerjs.
-- **Picture-in-picture button**, at the top right. Gecko ships no Web API for it
-  on Android, so it uses the standard call where that exists and otherwise
-  prepares the video and says what to do.
+- **Picture-in-picture button**, last in the top row after colour and settings,
+  where a thumb reaches it. Gecko ships no Web API for it on Android, so the
+  button does what a viewer does by hand: it asks Android for the home screen
+  and leaves Firefox playing behind it, which is the hand-off Android already
+  knows how to float.
+- **Chapters on the seek bar.** Where a site publishes sections — YouTube does —
+  the bar is cut at each one and the title of the section under the finger is
+  named above it.
+- **A fullscreen button on the inline video.** One button, drawn as the
+  fullscreen arrows, sitting on the site's own small player. It fades out after
+  a few seconds untouched and comes back on any tap, so it is there when it is
+  wanted and gone when it is not.
 - **Fullscreen switch** in the settings sheet. Off runs the player as an overlay
   instead of taking the screen, which leaves Android's ordinary single swipe
   home working.
@@ -42,6 +51,8 @@ Everything in this release comes from watching real films on a real phone with
   middle.
 - **The badge sits halfway up the right edge** of an inline video rather than in
   the bottom corner, where it covered the site's own controls.
+- **The scrim is heavier** where the controls sit, so they stay readable when
+  they come up over a bright, playing picture rather than over a paused one.
 - Motion follows one easing curve throughout, with scrims and shadows under the
   controls so they stay legible over a bright picture.
 - The launcher no longer asks Gecko to hide the navigation UI, which is what put
@@ -67,6 +78,17 @@ Everything in this release comes from watching real films on a real phone with
   looks like, and it is now told apart from the viewer leaving the player.
 - A quality switch that empties the media element no longer backs the player
   out; the check waits to see whether the element really was torn down.
+- **YouTube on the phone offers a quality ladder again.** Its player answers
+  `getAvailableQualityLevels()` with an empty list there, so the rungs are read
+  off the heights of the formats the video itself carries, and the row says
+  which of the two ways in produced them.
+- The site's player object is captured before the video is moved, so the
+  quality, caption and chapter readers still have something to ask once the
+  element no longer sits inside it.
+- The style guard no longer answers its own writes. It compared what it had
+  asked for against what the browser had stored, never matched, and rewrote
+  twenty properties on every mutation it caused — which is what made the player
+  crawl and fullscreen take seconds to arrive.
 
 ## [0.2.0][] - 2026-08-02
 
diff --git a/README.md b/README.md
index dd8af96..8065222 100644
--- a/README.md
+++ b/README.md
@@ -62,10 +62,16 @@ for you. Works with `<source>` lists, YouTube, hls.js, dash.js and Shaka; where
 a player exposes nothing, the sheet says what is playing instead of offering a
 choice that would do nothing.
 
-**Picture in picture** — the button at the top right hands the film to the
-system's floating window where the platform allows it, and the player survives
-being sent to the background so Android's own hand-off works when you swipe
-away.
+**Picture in picture** — the last button in the top row asks Android for the
+home screen and leaves the film playing behind it, which is the hand-off the
+system already knows how to float. The player survives being backgrounded, so
+coming back finds it where you left it.
+
+**Chapters** — where a site publishes sections, the seek bar is cut at each one
+and names the section your finger is over.
+
+**On the site's own player** — a single fullscreen button sits on an inline
+video. It fades out when it is left alone and comes back on any tap.
 
 ## Privacy
 
@@ -99,10 +105,11 @@ These are platform limits, not oversights:
 
 - **There is no Web API for Picture-in-Picture on Android.** Gecko does not
   ship `requestPictureInPicture()` there. What Android does offer is its own
-  hand-off: leave the app while a video is playing and the system floats it. The
-  button uses the standard API where it exists and otherwise prepares the video
-  and says what to do, and the session now survives being backgrounded so the
-  system hand-off is not torn down halfway through.
+  hand-off: leave the app while a video is playing and the system floats it. So
+  the button does exactly what a viewer would do by hand — it asks Android for
+  the home screen — and the session survives being backgrounded so the hand-off
+  is not torn down halfway through. Whether the window actually floats is the
+  system's decision, not the extension's.
 - **Quality depends on what the site's player exposes.** A player that keeps its
   engine in a closure cannot be reached from an extension. The common ones —
   `<source>` lists, YouTube, hls.js, dash.js, Shaka — are covered; anything else
diff --git a/REVIEWERS.md b/REVIEWERS.md
new file mode 100644
index 0000000..ebc3bd3
--- /dev/null
+++ b/REVIEWERS.md
@@ -0,0 +1,57 @@
+# Notes for add-on reviewers
+
+The submitted package is built from this source with esbuild. Nothing is
+minified, obfuscated, or fetched at build time, so the bundle in the package
+reads the same as the files here.
+
+## Build environment
+
+- Node.js 26.3.1 (any Node >= 20 produces the same output)
+- npm 10.5.0
+- Fedora Linux, x86_64 — the build has no platform-specific steps
+
+## Steps to reproduce the submitted package
+
+```sh
+npm ci                  # installs only devDependencies; the add-on ships none
+npm run build:clean     # esbuild -> dist/, unminified, no sourcemaps
+npx web-ext build -s dist -a artifacts --overwrite-dest
+```
+
+The result is `artifacts/nocturne_player-0.3.0.zip`. Its contents match the
+submitted file; only the zip's own timestamps differ between runs.
+
+## What the build does
+
+`esbuild.config.mjs` bundles two entry points — the content script and the
+popup — with `minify: false`, `format: 'iife'`, and `bundle: true`, then copies
+`src/manifest.json`, the icons, and the popup's HTML and CSS into `dist/`. The
+player's own CSS is bundled into the content script as text (esbuild's `text`
+loader) so it can be attached to a closed shadow root. There is no code
+generation, no template step, and no download.
+
+## Checks you can run
+
+```sh
+npm run lint          # eslint + prettier + web-ext lint + the privacy check
+npm test              # unit tests
+npm run lint:privacy  # fails on any network, sensor, analytics or eval-like API
+```
+
+`tools/check-privacy.mjs` is the one worth a look: it fails the build if the
+source contains `fetch`, `XMLHttpRequest`, `sendBeacon`, `WebSocket`,
+`EventSource`, `importScripts`, `eval(`, `new Function(`, `storage.sync`,
+`navigator.geolocation`, `navigator.mediaDevices`, `document.cookie`, any
+analytics identifier, or any `http(s)://` URL other than links to github.com and the W3C SVG
+namespace identifier.
+It also asserts that the manifest requests exactly `storage` and `activeTab`
+and declares no host permissions.
+
+## Notes on the page interaction
+
+The content script reads the site's own player object through Firefox's
+`wrappedJSObject` waiver in order to ask it for quality levels, caption tracks
+and chapter lists (`src/content/video/pageapi.js` is the only place this
+happens, and every read is guarded). It never assigns code into the page, never
+evaluates a string, and passes objects into the page compartment only through
+`cloneInto`.

From c83ad639e53fe5b7cefaa3d85e2d5182a46880df Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Fri, 7 Aug 2026 09:37:41 +0300
Subject: [PATCH 17/23] fix(video): the site's player was refusing every call
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every call into a site's player failed with "Permission denied to access
property length", which is why the quality ladder, the caption list and
the chapter list all came back empty on YouTube: method.apply reaches
the page's own Function.prototype.apply, and the page — the less
privileged side — cannot read the length of an array built in our
compartment.

Reflect.apply is ours. The arguments are unpacked on this side and the
page only ever sees the values.

Found in the phone's log, after the sheet had spent three versions
politely reporting that YouTube offers no quality levels at all.
---
 src/content/video/pageapi.js | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/src/content/video/pageapi.js b/src/content/video/pageapi.js
index 56635db..2f0f936 100644
--- a/src/content/video/pageapi.js
+++ b/src/content/video/pageapi.js
@@ -44,7 +44,14 @@ export const call = (object, name, ...args) => {
   }
   if (typeof method !== 'function') return null;
   try {
-    const value = method.apply(object, args);
+    // Reflect.apply, not method.apply: the latter reaches the page's own
+    // Function.prototype.apply, which then tries to read `length` off an array
+    // built in our compartment and is refused — "Permission denied to access
+    // property length". Every call into a site's player failed that way, which
+    // is why the quality ladder, the caption list and the chapter list all came
+    // back empty on YouTube. Reflect is ours, so the arguments are unpacked on
+    // this side and the page only ever sees the values.
+    const value = Reflect.apply(method, object, args);
     return value === undefined ? null : value;
   } catch (error) {
     console.warn(`Nocturne: ${name}() failed on the site's player`, error);

From 9b2d3cec7ccafffd021c18df12e901eeeb3af7de Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Fri, 7 Aug 2026 09:37:54 +0300
Subject: [PATCH 18/23] fix(session): keep the player standing through a scrub
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three things took the player down or left it looking broken, all found
by driving the emulator rather than by reading the code:

A drag along the seek bar threw the viewer back to the page. YouTube
removes its <video> element outright when it is told a seek is final,
and a drag was telling it that every 120ms. Seeks now go through the
site's own seekTo where it has one, and a preview says so: isFinal is
true only when the finger comes off. The teardown watch is slower and
harder to convince as well — any sign of life cancels it, and only
NETWORK_EMPTY counts as empty.

The picture stopped filling the screen after a quality switch. The crop
lives in `transform`, which the style guard knew nothing about, so the
first time the site rewrote the video's inline style the picture fell
back into its letterbox and stayed there.

The fullscreen button did not go fullscreen. It obeyed a stored switch
that a stray tap could turn off for good. A button drawn as a fullscreen
icon takes the screen; the switch in the sheet still drops back to the
overlay, for this session only, the way playback speed does.

Also gone: the toast on every quality tap and the stale swipe-up hint.
The chip lighting up already says the choice was taken.
---
 src/content/controls/seekbar.js |  6 ++--
 src/content/session.js          | 63 ++++++++++++++++++++++++++++-----
 src/content/ui.js               | 32 ++++++-----------
 src/content/video/seek.js       | 26 ++++++++++++++
 src/content/video/visuals.js    |  5 +++
 src/lib/settings.js             |  1 -
 6 files changed, 98 insertions(+), 35 deletions(-)
 create mode 100644 src/content/video/seek.js

diff --git a/src/content/controls/seekbar.js b/src/content/controls/seekbar.js
index 65152e9..b93cff0 100644
--- a/src/content/controls/seekbar.js
+++ b/src/content/controls/seekbar.js
@@ -20,7 +20,7 @@ const precisionFor = (distancePx) => {
   return PRECISION_STEPS[PRECISION_STEPS.length - 1];
 };
 
-export const createSeekBar = (video) => {
+export const createSeekBar = (video, seek) => {
   const elapsed = el('span', { class: 'time', text: '0:00' });
   const remaining = el('span', { class: 'time', text: '--:--' });
   const fill = el('div', { class: 'seek-fill' });
@@ -115,14 +115,14 @@ export const createSeekBar = (video) => {
     const now = performance.now();
     if (now - lastPreviewAt < PREVIEW_INTERVAL_MS) return;
     lastPreviewAt = now;
-    video.currentTime = scrubTime;
+    seek(scrubTime, false);
   };
 
   const end = () => {
     if (!isScrubbing) return;
     isScrubbing = false;
     root.classList.remove('is-scrubbing');
-    if (duration() > 0) video.currentTime = scrubTime;
+    if (duration() > 0) seek(scrubTime);
     paint(scrubTime);
   };
 
diff --git a/src/content/session.js b/src/content/session.js
index 6e2e16b..df153b9 100644
--- a/src/content/session.js
+++ b/src/content/session.js
@@ -12,7 +12,13 @@ const PLAYER_API_MARKERS = [
 ];
 
 const STALL_GRACE_MS = 400;
-const EMPTIED_GRACE_MS = 600;
+// Long enough for a site to finish re-attaching its stream. A scrub past the
+// buffer makes YouTube tear its stream down and build it again, which on a slow
+// connection takes seconds — and the player used to back out from under the
+// finger that was scrubbing. A few seconds of black is a far smaller price than
+// being thrown out of the film.
+const EMPTIED_GRACE_MS = 6000;
+const NETWORK_EMPTY = 0;
 const RECOVER_DELAY_MS = 250;
 const MAX_REPINS = 240;
 
@@ -60,7 +66,13 @@ const VIDEO_STYLE = {
   'transform-origin': 'center center',
 };
 
-const VIDEO_STYLE_KEYS = Object.keys(VIDEO_STYLE);
+// The crop and the colour are written by the visuals rather than pinned from
+// the table above, but they are watched all the same: a site that rewrites the
+// video's style wipes them, and the guard has to notice that it did.
+const VIDEO_STYLE_KEYS = Object.keys(VIDEO_STYLE).concat([
+  'transform',
+  'filter',
+]);
 
 const captureVideoState = (video) => ({
   cssText: video.style.cssText,
@@ -160,7 +172,7 @@ export const createSession = (video, { onExit, settings, onPersist }) => {
 
   let isActive = false;
   let isOrientationLocked = false;
-  let isFullscreenWanted = settings.isFullscreenTakeoverOn;
+  let isFullscreenWanted = true;
   let styleGuard = null;
   let pinnedStyle = null;
   let repinCount = 0;
@@ -202,6 +214,7 @@ export const createSession = (video, { onExit, settings, onPersist }) => {
     }
 
     pinStyle(video, VIDEO_STYLE);
+    if (overlay) overlay.repin();
     pinnedStyle = readStyle(video);
   };
 
@@ -275,10 +288,40 @@ export const createSession = (video, { onExit, settings, onPersist }) => {
   // that reloads it leaves us holding an empty player. A quality switch empties
   // the element too, so the verdict waits until the dust settles.
   const watchForTeardown = () => {
+    let pending = null;
+
+    // Any sign of life cancels the verdict. An element that is loading again is
+    // an element the site is still using, whatever its readyState says at the
+    // moment we happen to look.
+    const revive = () => {
+      if (pending === null) return;
+      clearTimeout(pending);
+      timers.delete(pending);
+      pending = null;
+    };
+
+    const LIFE_SIGNS = [
+      'loadstart',
+      'loadedmetadata',
+      'progress',
+      'seeked',
+      'canplay',
+      'playing',
+    ];
+
+    for (const name of LIFE_SIGNS) {
+      listen(video, name, revive);
+    }
+
     listen(video, 'emptied', () => {
-      later(() => {
+      revive();
+      pending = later(() => {
+        pending = null;
         const hasSource = video.currentSrc !== '' || video.srcObject !== null;
-        if (hasSource || video.readyState > 0) return;
+        // networkState is the honest one: NETWORK_EMPTY means the element has
+        // no source at all, where a seek in progress reads as loading.
+        const isEmpty = video.networkState === NETWORK_EMPTY;
+        if (hasSource || video.readyState > 0 || !isEmpty) return;
         console.warn('Nocturne: the video was torn down, backing out');
         exit();
       }, EMPTIED_GRACE_MS);
@@ -361,10 +404,12 @@ export const createSession = (video, { onExit, settings, onPersist }) => {
 
     watchForReturn();
 
-    if (isFullscreenWanted) {
-      const isOn = await requestFullscreen(stage);
-      if (isOn) await applyLandscape();
-    }
+    // The button that opens the player is drawn as a fullscreen icon, so it
+    // takes the screen — every time, not only when a switch left over from a
+    // previous session happens to agree. The switch in the sheet still drops
+    // back to the overlay, for the rest of this session.
+    const isOn = await requestFullscreen(stage);
+    if (isOn) await applyLandscape();
     scheduleRelayout();
     return true;
   };
diff --git a/src/content/ui.js b/src/content/ui.js
index c6f4f09..5b7aba1 100644
--- a/src/content/ui.js
+++ b/src/content/ui.js
@@ -4,6 +4,7 @@ import { createMenu } from './controls/menu.js';
 import { createQuality } from './video/quality.js';
 import { createRecognizer } from './gestures/recognizer.js';
 import { createSeekBar } from './controls/seekbar.js';
+import { createSeeker } from './video/seek.js';
 import { createTrackManager } from './video/tracks.js';
 import { createVisuals } from './video/visuals.js';
 import { el } from './shell.js';
@@ -18,7 +19,6 @@ const SKIP_SECONDS = 10;
 const FILL_RETRY_MS = 400;
 const FRAME_LIFE_MS = 2000;
 const CHAPTER_TRIES_MS = [1200, 4000, 10000];
-const HANDOFF_GRACE_MS = 900;
 
 // The Android launcher, asked for by intent. Nothing is loaded from anywhere:
 // the URL names an activity on the phone, and the browser either hands it to
@@ -121,7 +121,8 @@ export const createOverlay = ({
     playerHost,
   );
 
-  const seekBar = createSeekBar(video);
+  const seek = createSeeker(video, playerHost);
+  const seekBar = createSeekBar(video, seek);
 
   let chromeTimer = null;
   let scrubTimer = null;
@@ -153,7 +154,6 @@ export const createOverlay = ({
     video,
     tracks,
     quality,
-    settings,
     onStyle: ({ scale }) => {
       cueBox.style.setProperty('--cue-scale', String(scale));
       onPersist({ subtitleScale: scale });
@@ -161,10 +161,10 @@ export const createOverlay = ({
     onPickFile: () => filePicker.click(),
     onRate: () => {},
     onNotice: (text) => showToast(text, HINT_MS),
-    onImmersive: (isOn) => {
-      onImmersiveChange(isOn);
-      onPersist({ isFullscreenTakeoverOn: isOn });
-    },
+    // Deliberately not persisted, the way playback speed is not: it belongs to
+    // the film being watched now, and a viewer who dropped out of fullscreen
+    // once should still get fullscreen from a button that says fullscreen.
+    onImmersive: onImmersiveChange,
   });
 
   menuRef.setSubtitle = menu.setSubtitle;
@@ -199,11 +199,7 @@ export const createOverlay = ({
   };
 
   const skip = (seconds) => {
-    const limit = Number.isFinite(video.duration)
-      ? video.duration
-      : video.currentTime;
-    const target = video.currentTime + seconds;
-    video.currentTime = Math.min(limit, Math.max(0, target));
+    seek(video.currentTime + seconds);
     showToast(`${seconds > 0 ? '+' : ''}${seconds}s`);
   };
 
@@ -222,11 +218,7 @@ export const createOverlay = ({
     wasPlayingBeforeScrub = !video.paused;
     video.pause();
     scrubTimer = setInterval(() => {
-      const limit = Number.isFinite(video.duration)
-        ? video.duration
-        : video.currentTime;
-      const target = video.currentTime + direction * SCRUB_STEP_SECONDS;
-      video.currentTime = Math.min(limit, Math.max(0, target));
+      seek(video.currentTime + direction * SCRUB_STEP_SECONDS);
     }, SCRUB_TICK_MS);
   };
 
@@ -343,11 +335,6 @@ export const createOverlay = ({
     }
 
     leaveForHomeScreen();
-    // If nothing took us away, say what does.
-    setTimeout(() => {
-      if (document.hidden) return;
-      showToast('Swipe up to keep it floating', HINT_MS);
-    }, HANDOFF_GRACE_MS);
   };
 
   topbar.append(
@@ -441,6 +428,7 @@ export const createOverlay = ({
 
   return {
     relayout: () => visuals.relayout(),
+    repin: () => visuals.repin(),
     destroy: () => {
       recognizer.destroy();
       seekBar.destroy();
diff --git a/src/content/video/seek.js b/src/content/video/seek.js
new file mode 100644
index 0000000..6e70cc8
--- /dev/null
+++ b/src/content/video/seek.js
@@ -0,0 +1,26 @@
+import { call, isFunction } from './pageapi.js';
+
+// Writing to currentTime asks the browser to move a stream the site is still in
+// charge of. A site feeding the element through Media Source Extensions can
+// answer by tearing its stream down and building a new one — YouTube does,
+// leaving the element empty for seconds, which looked to the player like the
+// video had been taken away and threw the viewer out mid-scrub.
+//
+// Where the site publishes its own seek, that is the one to ask: it moves the
+// same picture and leaves the site's own machinery in step with it.
+// isFinal is the difference between "show me this moment" and "go there". A
+// drag asks for the first, every frame it passes over; only the finger coming
+// off asks for the second. Telling YouTube that every preview was final made it
+// rebuild its stream — and its <video> element — under a finger that was still
+// moving, which took the player down with it.
+export const createSeeker = (video, host) => {
+  const isSiteSeekable = isFunction(host, 'seekTo');
+
+  return (seconds, isFinal = true) => {
+    const limit = Number.isFinite(video.duration) ? video.duration : seconds;
+    const time = Math.min(limit, Math.max(0, seconds));
+    if (isSiteSeekable) call(host, 'seekTo', time, isFinal);
+    else video.currentTime = time;
+    return time;
+  };
+};
diff --git a/src/content/video/visuals.js b/src/content/video/visuals.js
index 37164f4..127d4d7 100644
--- a/src/content/video/visuals.js
+++ b/src/content/video/visuals.js
@@ -113,6 +113,11 @@ export const createVisuals = (video, stage) => {
 
   return {
     relayout,
+    // The site rewrites the video's inline style and the guard puts the
+    // position and the size back — but the crop lives in `transform`, which
+    // the guard knows nothing about, so it has to be written again here or the
+    // picture drops back into its letterbox the moment the site touches it.
+    repin: apply,
     // Crops the letterbox away, which is what most people want on a phone.
     fillScreen: () => {
       if (video.videoWidth === 0) return false;
diff --git a/src/lib/settings.js b/src/lib/settings.js
index c3c625b..47589be 100644
--- a/src/lib/settings.js
+++ b/src/lib/settings.js
@@ -10,7 +10,6 @@ export const DEFAULTS = Object.freeze({
   doubleTapSeconds: 10,
   holdSpeed: 2,
   isAutoLandscapeOn: true,
-  isFullscreenTakeoverOn: true,
   areEffectsReduced: false,
   subtitleScale: 1,
   areSubtitlesNative: false,

From 09202643e25c76579aa44d052266f5e96ee954bf Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Fri, 7 Aug 2026 09:38:05 +0300
Subject: [PATCH 19/23] feat(controls): quality first, and a sheet that fits
 the screen
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Quality leads the sheet now. It is the row people open it for, it is the
longest, and on a phone held sideways the sheet scrolls — so anything
below the first two rows was a row somebody had to go looking for.

The rows themselves were climbing over each other: a fixed row height
with a nine-rung quality ladder that wraps meant the second line of
chips lay across the row beneath. Rows are as tall as their chips, a
hairline separates them, and the sheet is bounded above the seek bar
rather than running off the bottom of the screen. It also opens at the
top, instead of wherever a chip left the focus last time.
---
 src/content/controls/menu.js | 24 +++++++++++++-----------
 src/content/player.css       | 26 +++++++++++++++++++++-----
 2 files changed, 34 insertions(+), 16 deletions(-)

diff --git a/src/content/controls/menu.js b/src/content/controls/menu.js
index 12383f2..de4a078 100644
--- a/src/content/controls/menu.js
+++ b/src/content/controls/menu.js
@@ -88,7 +88,6 @@ export const createMenu = ({
   video,
   tracks,
   quality,
-  settings,
   onStyle,
   onPickFile,
   onRate,
@@ -128,10 +127,10 @@ export const createMenu = ({
       return;
     }
     const setQuality = paintChips(qualityRow, options, (id) => {
-      const chosen = options.find((option) => String(option.id) === String(id));
-      const label = chosen ? chosen.label : String(id);
-      const isDone = quality.select(id);
-      onNotice(isDone ? `Quality: ${label}` : 'The site would not change it');
+      // Only the refusal is worth a word. The chip lighting up already says
+      // the choice was taken, and a message over the film for every tap is
+      // noise the viewer did not ask for.
+      if (!quality.select(id)) onNotice('The site would not change it');
     });
     setQuality(quality.getCurrent());
   };
@@ -171,16 +170,16 @@ export const createMenu = ({
     tracks.setNative(!tracks.isNative());
   });
 
-  const immersiveToggle = buildToggle(
-    'Fullscreen',
-    settings.isFullscreenTakeoverOn,
-    onImmersive,
-  );
+  const immersiveToggle = buildToggle('Fullscreen', true, onImmersive);
 
   paintSubtitles();
   qualityRow.chips.replaceChildren(buildNote('Reading the site…'));
 
+  // Quality leads. It is the row people open this sheet for, it is the longest,
+  // and on a phone held sideways the sheet scrolls — so anything below the
+  // first two rows is a row somebody has to go looking for.
   const root = el('div', { class: 'panel menu' }, [
+    qualityRow.row,
     speedRow.row,
     subtitleRow.row,
     sizeRow,
@@ -189,7 +188,6 @@ export const createMenu = ({
       el('span', { class: 'menu-label', text: 'Source' }),
       el('div', { class: 'chips' }, [loadButton, nativeToggle]),
     ]),
-    qualityRow.row,
     el('div', { class: 'menu-row' }, [
       el('span', { class: 'menu-label', text: 'Screen' }),
       el('div', { class: 'chips' }, [immersiveToggle]),
@@ -207,6 +205,10 @@ export const createMenu = ({
   const open = () => {
     refresh();
     root.classList.add('is-open');
+    // Opened at the top, always. The sheet scrolls, and a chip that still has
+    // focus from the last time drags the view down to itself, which hides the
+    // row the sheet was opened for.
+    root.scrollTop = 0;
   };
 
   return {
diff --git a/src/content/player.css b/src/content/player.css
index 97a5c58..69832b3 100644
--- a/src/content/player.css
+++ b/src/content/player.css
@@ -359,21 +359,36 @@
   right: max(30px, env(safe-area-inset-right));
   left: auto;
   width: min(560px, 68vw);
-  max-height: calc(100% - 120px);
+  /* Ends where the seek bar begins: the sheet is anchored 60px down and the
+   * bar rides 12vh off the bottom, so the two can never meet. Viewport units
+   * rather than percentages — the sheet's parent is a stretched box with no
+   * height of its own, against which a percentage means nothing. */
+  max-height: calc(100vh - 96px - 18vh);
   overflow-y: auto;
-  gap: 8px;
+  overscroll-behavior: contain;
+  gap: 0;
 }
 
+/* A row is as tall as its chips, however many lines they take: the quality
+ * ladder runs to nine rungs and wraps on a phone held sideways, and a row with
+ * a fixed height would have left it lying across the row beneath. */
 .menu-row {
   display: flex;
-  align-items: center;
+  align-items: flex-start;
   gap: 10px;
-  min-height: 40px;
+  padding: 7px 0;
+}
+
+/* A hairline instead of a gap: with rows of different heights, a line is what
+ * makes it plain which chips belong to which label. */
+.menu-row + .menu-row {
+  border-top: 1px solid rgba(255, 255, 255, 0.08);
 }
 
 .menu-label {
   flex: none;
   width: 84px;
+  padding-top: 9px;
   font-size: 13px;
 }
 
@@ -386,7 +401,8 @@
   display: flex;
   flex-wrap: wrap;
   align-items: center;
-  gap: 6px;
+  row-gap: 8px;
+  column-gap: 6px;
 }
 
 .chip {

From 0017f296f3e74cc64996f99e124cc8d8f3586e31 Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Fri, 7 Aug 2026 09:38:29 +0300
Subject: [PATCH 20/23] docs: what the emulator turned up

The release notes described three features that did not work on a phone
and a fullscreen switch that outlived its session. They now describe
what the build does.
---
 CHANGELOG.md | 29 ++++++++++++++++++++++++-----
 README.md    |  8 ++++----
 2 files changed, 28 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0ebd253..58b9d41 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,9 +35,14 @@ Everything in this release comes from watching real films on a real phone with
   fullscreen arrows, sitting on the site's own small player. It fades out after
   a few seconds untouched and comes back on any tap, so it is there when it is
   wanted and gone when it is not.
+- **Quality leads the settings sheet**, above speed and subtitles. The rows are
+  as tall as their chips with a hairline between them, and the sheet ends above
+  the seek bar — a nine-rung quality ladder used to wrap across the row beneath
+  it and run off the bottom of the screen.
 - **Fullscreen switch** in the settings sheet. Off runs the player as an overlay
   instead of taking the screen, which leaves Android's ordinary single swipe
-  home working.
+  home working. It applies to the session it is used in and is deliberately not
+  remembered, the way playback speed is not.
 - Loading an `.srt` / `.vtt` file now actually loads it: the file input had no
   handler, so the button did nothing.
 
@@ -73,15 +78,29 @@ Everything in this release comes from watching real films on a real phone with
   touched once. Values stored out of range or of the wrong type now fall back
   to the neutral one as well.
 - **No more fade to grey while paused.** People pause to look at the picture.
+- **Quieter.** Choosing a quality no longer prints a message over the film; the
+  chip lighting up says it. Only a refusal is worth a word.
 - Leaving the app no longer tears the session down. Losing fullscreen while the
   app is on its way to the background is what Android's floating-window hand-off
   looks like, and it is now told apart from the viewer leaving the player.
 - A quality switch that empties the media element no longer backs the player
   out; the check waits to see whether the element really was torn down.
-- **YouTube on the phone offers a quality ladder again.** Its player answers
-  `getAvailableQualityLevels()` with an empty list there, so the rungs are read
-  off the heights of the formats the video itself carries, and the row says
-  which of the two ways in produced them.
+- **Every call into a site's player was being refused.** `method.apply()`
+  reaches the page's own `Function.prototype.apply`, and the page — the less
+  privileged side — cannot read the `length` of an array built in the content
+  script's compartment, so each call died with "Permission denied to access
+  property length" before it arrived. Calls go through `Reflect.apply` now.
+  This one bug is why quality, captions and chapters were all missing on
+  YouTube; all three work.
+- **A drag along the seek bar no longer throws the viewer back to the page.**
+  YouTube removes its `<video>` element when it is told a seek is final, and a
+  drag was telling it so every 120ms. Seeks go through the site's own `seekTo`
+  where there is one, and only the finger coming off counts as final. The watch
+  that decides a video has been torn down is slower and harder to convince too.
+- **The fullscreen button takes the screen.** It used to obey a stored switch
+  that a stray tap could turn off for good, after which the button looked
+  broken. The switch in the sheet still drops back to the overlay, for the
+  session it is used in.
 - The site's player object is captured before the video is moved, so the
   quality, caption and chapter readers still have something to ask once the
   element no longer sits inside it.
diff --git a/README.md b/README.md
index 8065222..3a67855 100644
--- a/README.md
+++ b/README.md
@@ -57,10 +57,10 @@ dark, with adjustable intensity.
 YouTube's paints for itself, or an `.srt` / `.vtt` file from your phone.
 Adjustable size and a sync offset for when the subtitles drift.
 
-**Quality** — pick the rung of the ladder rather than letting the site choose
-for you. Works with `<source>` lists, YouTube, hls.js, dash.js and Shaka; where
-a player exposes nothing, the sheet says what is playing instead of offering a
-choice that would do nothing.
+**Quality** — the first row of the sheet: pick the rung of the ladder rather
+than letting the site choose for you. Works with `<source>` lists, YouTube,
+hls.js, dash.js and Shaka; where a player exposes nothing, the sheet says what
+is playing instead of offering a choice that would do nothing.
 
 **Picture in picture** — the last button in the top row asks Android for the
 home screen and leaves the film playing behind it, which is the hand-off the

From 4ff3a8e6a1ea39a741bf4e9aa806ee3971fbf310 Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Fri, 7 Aug 2026 09:50:39 +0300
Subject: [PATCH 21/23] feat(controls): brightness worth pressing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

40% to 200% in steps of ten, rather than 50% to 150% in steps of five.
Measured on the emulator, the old control did move the picture — a full
sweep took the frame from 20 to 85 mean luminance — but it took ten
presses to do anything a viewer would call brightening, and a control
that needs ten presses reads as a control that does not work.

A film mastered dark for a cinema can now be lifted far enough to watch
on a phone.
---
 CHANGELOG.md                       |  4 ++++
 src/content/controls/colorpanel.js | 10 +++++++---
 src/lib/settings.js                |  2 +-
 3 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 58b9d41..8b38890 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -80,6 +80,10 @@ Everything in this release comes from watching real films on a real phone with
 - **No more fade to grey while paused.** People pause to look at the picture.
 - **Quieter.** Choosing a quality no longer prints a message over the film; the
   chip lighting up says it. Only a refusal is worth a word.
+- **Brightness reaches further and moves faster**: 40%–200% in steps of ten,
+  rather than 50%–150% in steps of five. A film mastered dark can now actually
+  be lifted, and one press does something you can see — at five percent a press
+  the control read as one that did nothing.
 - Leaving the app no longer tears the session down. Losing fullscreen while the
   app is on its way to the background is what Android's floating-window hand-off
   looks like, and it is now told apart from the viewer leaving the player.
diff --git a/src/content/controls/colorpanel.js b/src/content/controls/colorpanel.js
index b40114f..67f2eb4 100644
--- a/src/content/controls/colorpanel.js
+++ b/src/content/controls/colorpanel.js
@@ -8,12 +8,16 @@ const asWarmth = (value) =>
 // Steppers rather than sliders: a thumb can hit a 44px button while holding the
 // phone, which is not true of a slider handle.
 const ROWS = [
+  // A wider reach and a bigger step than the rest: brightness is the one people
+  // come here for, on a dark film in a dark room, and at 5% a press with a
+  // ceiling of 150% it took ten presses to do anything you would call
+  // brightening — which reads as a control that does not work.
   {
     key: 'brightness',
     label: 'Brightness',
-    min: 0.5,
-    max: 1.5,
-    step: 0.05,
+    min: 0.4,
+    max: 2,
+    step: 0.1,
     value: 1,
     format: asPercent,
   },
diff --git a/src/lib/settings.js b/src/lib/settings.js
index 47589be..ea978c1 100644
--- a/src/lib/settings.js
+++ b/src/lib/settings.js
@@ -23,7 +23,7 @@ const KEYS = Object.keys(DEFAULTS);
 // rather than tinting somebody's first film for reasons they cannot see.
 const RANGES = {
   warmth: { min: 0, max: 0.45 },
-  brightness: { min: 0.5, max: 1.5 },
+  brightness: { min: 0.4, max: 2 },
   contrast: { min: 0.5, max: 1.5 },
   saturate: { min: 0, max: 2 },
   subtitleScale: { min: 0.5, max: 2 },

From f8aed2ae000920bd49c8c3f49736fdabf013b586 Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Fri, 7 Aug 2026 09:50:40 +0300
Subject: [PATCH 22/23] docs: listing copy for the add-on store
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The store page has to answer one question — what does this do that the
browser does not — and the old summary did not. Every claim is
checkable against the source, the limits are stated up front rather than
discovered, and the privacy section says what is enforced by the build
instead of what is promised.
---
 AMO-LISTING.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 AMO-LISTING.md

diff --git a/AMO-LISTING.md b/AMO-LISTING.md
new file mode 100644
index 0000000..abb4848
--- /dev/null
+++ b/AMO-LISTING.md
@@ -0,0 +1,97 @@
+# Listing copy for addons.mozilla.org
+
+Ready to paste into the AMO submission form. Everything here is checkable
+against the source; nothing claims a capability the build does not have.
+
+## Summary (250 characters)
+
+Touch-first video controls for Firefox on Android: seek from anywhere with a
+thumb, pick the quality the site hid, read subtitles the site paints itself,
+and warm the picture down for a dark room. No network access at all.
+
+## What it does that the built-in controls do not
+
+These are the reasons to install it. Each one is a thing Firefox for Android,
+or the site's own mobile player, does not give you.
+
+- **Seek from anywhere on the screen, at the precision you choose.** Put a
+  thumb anywhere in the lower band and drag: the film moves with it. Pull the
+  thumb away from the bar and the same swipe covers less time — 1x on the bar,
+  down to a tenth of that at the top of the band — so a two-hour film can be
+  landed on the exact scene without pinching or a stylus. The left label holds
+  the moment the drag began, so you can always find your way back.
+- **The quality the mobile site will not offer you.** YouTube's mobile web
+  player publishes no quality menu at all; the sheet reads the ladder out of
+  the player and lets you pin a rung. The same row covers `<source>` lists,
+  hls.js, dash.js and Shaka, so it is not a YouTube trick.
+- **Chapters on the seek bar, on a site that does not draw them there.** Where
+  a video publishes sections, the bar is cut at each one and the section under
+  the finger is named above it. YouTube's mobile site does not show them.
+- **Subtitles from players that paint their own.** A player like YouTube's
+  draws captions itself, outside the browser's text-track machinery, so
+  nothing can restyle or shift them. They are mirrored into the player's own
+  cue layer, where they get a size control and a **sync offset** — the fix for
+  subtitles that run half a second ahead, which the web platform gives you no
+  way to correct.
+- **Load an `.srt` or `.vtt` from the phone** onto a video that has no
+  subtitles of its own.
+- **Night light, brightness, contrast and saturation, live on the film.**
+  A warm layer for watching in the dark, and a picture that can be lifted when
+  a film is mastered too dark for a phone screen. With every value left alone,
+  no filter is applied at all — the film is passed through exactly as encoded.
+- **Fill the screen, without stretching.** The letterbox is cropped away by
+  default; a pinch moves between the whole frame and the cropped one and goes
+  no further, and a pan can never expose an edge. The crop is re-derived
+  whenever the screen changes shape, so it survives a rotation, a return from
+  another app, and a quality switch.
+- **Hold either side to scrub at 2x**, double-tap to skip ten seconds, and a
+  play button that is the only place a tap pauses — so no misfires while
+  reaching across the picture.
+- **It leaves the Android home swipe alone.** The player does not put the
+  system into sticky immersive mode, so one swipe still leaves the app, and the
+  seek band sits clear of the gesture strip at the bottom of the screen.
+- **It works on any site with a `<video>`**, not a list of supported ones.
+
+## Privacy, stated plainly
+
+- **No network access whatsoever.** There is no `fetch`, no `XMLHttpRequest`,
+  no beacon, no WebSocket and no remote URL anywhere in the source. A check in
+  the build (`npm run lint:privacy`) fails on any of them, so this is enforced
+  rather than promised.
+- **Two permissions**: `storage`, to keep your settings on the device, and
+  `activeTab`, so the popup can name the site you are on. No host permissions.
+- **Nothing is collected, logged or transmitted.** `data_collection_permissions`
+  is declared as `{ required: ["none"] }`, which makes the absence
+  machine-checkable rather than a claim in a paragraph.
+- Settings never use `storage.sync`, so they are not tied to an account.
+- **The published build is not minified.** What you read in the source is what
+  runs on the phone.
+- It works fully offline.
+
+## Why it needs to run on all sites
+
+The content script matches `<all_urls>` because it has to notice a `<video>`
+element on whatever site you open — there is no way to detect a video on a site
+without being allowed to run there. It reads nothing else from the page and
+sends nothing anywhere, and it can be switched off per site from the popup.
+
+## Known limits, said up front
+
+- There is no Web API for picture-in-picture on Firefox for Android. The button
+  asks Android for the home screen and leaves the film playing behind it, which
+  is the hand-off the system already knows how to float — whether it floats is
+  Android's decision, not the extension's.
+- Quality depends on what the site's player exposes. A player that keeps its
+  engine in a closure cannot be reached from an extension; the sheet then
+  reports the resolution being played rather than offering a choice that would
+  do nothing.
+- Volume is left to the phone's own buttons: the web platform has no access to
+  the system volume.
+- Hold-to-scrub steps the clock rather than raising `playbackRate`, which
+  Firefox for Android accepts but does not appear to honour. There is no sound
+  while scrubbing.
+
+## Notes for reviewers
+
+See [REVIEWERS.md](REVIEWERS.md) — build environment, the exact commands that
+reproduce the submitted package, and what the privacy check enforces.

From 3eb26d16c21a6437c0107e4de30f8862c685d627 Mon Sep 17 00:00:00 2001
From: Vlad Pohorilets <pohoriletts@gmail.com>
Date: Fri, 7 Aug 2026 10:13:41 +0300
Subject: [PATCH 23/23] docs: say why quality stops at some sites

Playerjs, which many film sites embed, publishes the hls.js constructor
and a player object with one opaque method. The instance holding the
ladder never leaves the closure, so there is no way in from an
extension. Better said in the notes than discovered in the sheet.
---
 AMO-LISTING.md |  8 +++++---
 CHANGELOG.md   |  8 ++++++++
 README.md      | 13 +++++++++----
 3 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/AMO-LISTING.md b/AMO-LISTING.md
index abb4848..6fbfdd8 100644
--- a/AMO-LISTING.md
+++ b/AMO-LISTING.md
@@ -82,9 +82,11 @@ sends nothing anywhere, and it can be switched off per site from the popup.
   is the hand-off the system already knows how to float — whether it floats is
   Android's decision, not the extension's.
 - Quality depends on what the site's player exposes. A player that keeps its
-  engine in a closure cannot be reached from an extension; the sheet then
-  reports the resolution being played rather than offering a choice that would
-  do nothing.
+  engine inside a closure cannot be reached from an extension at all — Playerjs,
+  which many film sites embed, hands out nothing but an opaque method — and the
+  sheet then reports the resolution being played rather than offering a choice
+  that would do nothing. YouTube, `<source>` lists, hls.js, dash.js and Shaka
+  are covered.
 - Volume is left to the phone's own buttons: the web platform has no access to
   the system volume.
 - Hold-to-scrub steps the clock rather than raising `playbackRate`, which
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8b38890..9e8dee3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -113,6 +113,14 @@ Everything in this release comes from watching real films on a real phone with
   twenty properties on every mutation it caused — which is what made the player
   crawl and fullscreen take seconds to arrive.
 
+### Notes
+
+- Quality on a site that embeds Playerjs — common on film sites — is still the
+  site's to choose. The page publishes the hls.js constructor and a player
+  object with one opaque method; the instance that holds the ladder never
+  leaves the closure. Driving the player's own menu is the way in, and it is
+  left for a later version.
+
 ## [0.2.0][] - 2026-08-02
 
 First release submitted to addons.mozilla.org.
diff --git a/README.md b/README.md
index 3a67855..5658658 100644
--- a/README.md
+++ b/README.md
@@ -110,10 +110,15 @@ These are platform limits, not oversights:
   the home screen — and the session survives being backgrounded so the hand-off
   is not torn down halfway through. Whether the window actually floats is the
   system's decision, not the extension's.
-- **Quality depends on what the site's player exposes.** A player that keeps its
-  engine in a closure cannot be reached from an extension. The common ones —
-  `<source>` lists, YouTube, hls.js, dash.js, Shaka — are covered; anything else
-  reports the resolution it is playing and leaves the choice to the site.
+- **Quality depends on what the site's player exposes.** The common ones are
+  covered — `<source>` lists, YouTube, hls.js, dash.js, Shaka — but a player
+  that keeps its engine inside a closure cannot be reached from an extension at
+  all. Playerjs, which many film sites embed, is the case in point: the page
+  publishes the hls.js _constructor_ and a player object with one opaque
+  method, and the instance holding the quality ladder is never handed out.
+  There the row reports the resolution being played instead of offering a
+  choice that would do nothing. Reaching those players by driving their own
+  menus is being looked at for a later version.
 - **Volume is left to the phone's own buttons.** The web platform has no access
   to the device volume.
 - **Rewind is not "negative 2x".** `playbackRate` cannot go below zero, so