cursedbelt 3.0.2 → 4.0.0

package/src/react/media/denseGallery.css

@@ -71,6 +71,39 @@
 	color: var(--accent-solid-foreground);
 }
 
+/* ── Icon-only pills ───────────────────────────────────────────────────────────────────
+ *
+ * Owner, `ideas/collections-09-14.md`: *"Make it have icons only, instead of words in the
+ * strip of tools … Hovering over the tooltip can show the words."* Every pill in that strip
+ * already carried a `Tooltip` and most an `aria-label`, so the words were the redundant
+ * half — what this adds is the BOX an iconless pill needs.
+ *
+ * 🔴 The tap floor is the thing an icon-only strip loses first, and it is lost on the WIDTH,
+ * not the height. `.cbgd-order-btn` above only ever set `min-height`, because a pill with a
+ * word in it is wide by construction; strip the word and `padding-inline` is all that is
+ * left, which on a coarse pointer is a 42px-wide target under a 44px rule. So `min-width`
+ * is declared in all three places `min-height` is — see the two media queries at the foot of
+ * this file — and `e2e/touch-targets.spec.ts` measures the rendered rectangles rather than
+ * trusting this comment. cursedbelt has shipped this exact defect once already
+ * (`Checkbox`, task 69).
+ *
+ * `svg` rather than a class on the glyph: the pill is handed a lucide element by the gallery
+ * and by any consumer filling `detailActions`, and lucide sizes itself with width/height
+ * ATTRIBUTES (24 by default) that a CSS rule overrides. Sizing here is therefore the one
+ * place that cannot be forgotten at a call site. */
+.cbgd-order-btn.is-icon {
+	min-width: 28px;
+	padding-inline: 7px;
+	justify-content: center;
+}
+.cbgd-order-btn svg {
+	width: 15px;
+	height: 15px;
+	/* A glyph must never be the thing that shrinks when the row runs out of room — the pill
+	   is the flex item that gives way, and a squashed icon is unreadable rather than tight. */
+	flex: none;
+}
+
 /* ── The slideshow speed control ────────────────────────────────────────────────────────
  *
  * A `<label>` wrapping a `<select>`, shaped as one more action pill so the actions row stays
@@ -99,6 +132,14 @@
 .cbgd-dwell-label {
 	line-height: 1;
 }
+/* The label is an hourglass now rather than the word "Hold" (2026-09-16) — same 15px as the
+   pills beside it, and `block` so the line box does not add a descender's worth of slack
+   under a glyph that has none. The VALUE (`5s`) stays as text in the select. */
+.cbgd-dwell-label svg {
+	width: 15px;
+	height: 15px;
+	display: block;
+}
 .cbgd-dwell-select {
 	min-height: 24px;
 	padding: 0 4px;
@@ -408,56 +449,51 @@
 	height: var(--cbgd-stage-h, var(--cbgd-stage-fit, var(--cbgd-stage-default)));
 	max-width: calc(var(--cbgd-stage-h, var(--cbgd-stage-fit, var(--cbgd-stage-default))) * 16 / 9);
 	margin: 0 auto;
-	/* The anchor for the chrome that rides ON the frame — today that is the resize grip
-	   (`.cbmr-corner`). It must be positioned against the FRAME, which is constant, and
-	   never against the picture, which is not.
-	   HISTORY: the big overlay ⟨ ⟩ step arrows used to hang here too. They were removed on
-	   2026-08-25 — owner: *"Remove the big previous and next buttons off the sides of the
-	   video."* Stepping moved into `.cbgd-watch-step` in the titlebar, and for video into
-	   the player's own control bar. Do not put them back on the frame. */
+	/* 🔴 Nothing of OURS rides on the frame any more, and that is the 2026-09-14 fix.
+	   `position: relative` stays because a stage may be a player that positions its own
+	   layers against it, and because `.cbgd-stage-img` letterboxes inside it.
+	   HISTORY: the big overlay ⟨ ⟩ step arrows hung here until 2026-08-25 — owner: *"Remove
+	   the big previous and next buttons off the sides of the video."* Stepping moved into
+	   `.cbgd-watch-step` in the titlebar, and for video into the player's own control bar.
+	   The resize grip (`.cbmr-corner`) hung here until 2026-09-16 — owner: *"It should only
+	   be draggable when my mouse pointer is at the bottom right corner … just like mac
+	   windows"* — and is now in `.cbmr-rail`, a sibling BELOW this box. Do not put either
+	   back on the frame: everything drawn here competes with whatever the stage is, and for
+	   a video that is a full-bleed control bar. */
 	position: relative;
 }
 /* Whatever the stage turns out to be — a player, a letterboxed picture, a document
-   panel, an audio card, the loading placeholder — it is exactly the frame. */
-/* Every STAGE fills the frame — but the resize grip is chrome ON the frame, not a stage, and
-   a `height: 100%` grip is a 44px control stretched over the whole picture, swallowing every
-   click meant for the video under it. Excluded by name rather than left to stylesheet order,
-   which is what was deciding it. */
-.cbgd-watch-player-box > *:not(.cbmr-corner) {
+   panel, an audio card, the loading placeholder — it is exactly the frame. Nothing but
+   the stage is in this box now: the resize grip left it on 2026-09-16 for the rail
+   below (`mediaResize.css`), which is why this no longer excludes `.cbmr-corner`. */
+.cbgd-watch-player-box > * {
 	height: 100%;
 	min-height: 0;
 }
 
-/* ── Where the video's own controls may NOT lay out ──────────────────────────
- * Owner, 2026-08-25: *"make the corner expansion grabbable area bigger … for some
- * reason it's hard to grab, possibly the previous/next buttons are overlapping it."*
+/* ── 🔴 The control bar reserves NOTHING, and that is the 2026-09-14 fix ──────
+ * There was a gutter here — `padding-inline-end: var(--cbmr-corner-size)` on the
+ * player's last two `.vds-controls-group`s — so the buttons would not lay out under a
+ * 64px grip that hung inside this frame's bottom-right corner. It is deleted, along
+ * with the overlay that needed it.
  *
- * 🔴 It was not the arrows. Measured against `@vidstack/react` 1.15's own theme:
- * `[data-view-type='video'] .vds-controls` is `position:absolute; inset:0;
- * z-index:10`, and `[data-media-player]` sets only `contain: style`, which is NOT one
- * of the containment values that opens a stacking context. So the player's control
- * layer competes DIRECTLY with `.cbmr-corner` in this frame's stacking context and
- * wins on 10 > 3. Its bottom `.vds-controls-group` is `width:100%` with
- * `pointer-events:auto`, so the whole bottom strip of the frame — including the empty
- * space between the cog and the frame's edge — swallowed the grip's pointer events.
- * And it does so only when the bar is SHOWING, i.e. on hover, i.e. at the exact
- * moment somebody reaches for the corner. That is the whole of the report.
+ * Owner, `ideas/collections-09-14.md`: *"Fix the drag to resize area to no longer
+ * overlap part of the horizontal play timeline area that shows what part of the video
+ * is playing."*
  *
- * Raising the grip alone would have covered the player's own last button (fullscreen)
- * with a 64px slider, so the fix is symmetrical: the grip goes above the bar (see
- * `mediaResize.css`) AND the bar is told to stop short of the corner it now shares a
- * frame with. `padding-inline-end` rather than a narrower width because Vidstack's
- * groups are `width:100%` flex rows — the padding is what actually moves the buttons.
+ * 🔴 The gutter was not the bug — measured, in a browser, before it was touched: with
+ * it in place the corner's rect really did clear `.vds-time-slider`'s. What it could
+ * not do was reach `.cbmr-bar`, which ran the full width UNDER the slider rather than
+ * beside it; and it can only ever shorten a control bar this package styles, which a
+ * `nativeVideoStage` gallery's `<video controls>` is not. It also cost 64px of scrub
+ * bar to buy a corner, which is the other half of the sentence above.
  *
- * 🔴 Scoped to a player that is NOT fullscreen. In fullscreen the media element is the
- * top-level box and the gallery's frame — grip included — is not in its tree at all,
- * so reserving a corner there would be a permanent empty gutter beside the cog with
- * nothing in it.
+ * So the grips moved out of the frame instead (`mediaResize.css`) and the slider gets
+ * its full width back. `e2e/resize-grip-rail.spec.ts` measures every drag surface
+ * against the frame and against the slider, in a real player, and fails if any of them
+ * touches either; do not reintroduce a gutter here to "make room" for something drawn
+ * on the picture — put the something in the rail.
  */
-.cbgd-watch-player-box [data-media-player]:not([data-fullscreen]) .vds-controls-group:last-child,
-.cbgd-watch-player-box [data-media-player]:not([data-fullscreen]) .vds-controls-group:nth-last-child(2) {
-	padding-inline-end: var(--cbmr-corner-size, 64px);
-}
 
 /* ── Stepping in the titlebar ────────────────────────────────────────────────
  * The ⟨ ⟩ overlay pills that used to sit on the left and right edges of the frame are
@@ -471,7 +507,9 @@
 	gap: 2px;
 	margin-inline-end: 4px;
 }
-/* The glyph is a single chevron and would otherwise sit in a pill sized for a word. */
+/* The glyph is a single chevron and would otherwise sit in a pill sized for a word. Wider
+   than `.is-icon`'s 28px because these two are the pair a reader hits over and over while
+   walking a folder, and they are the only pills whose job is repetition. */
 .cbgd-watch-step .cbgd-order-btn {
 	min-width: 34px;
 	padding-inline: 8px;
@@ -637,6 +675,11 @@
 		min-height: 44px;
 		padding: 4px 14px;
 	}
+	/* The width half of the same floor — see `.is-icon` at the top of this file. */
+	.cbgd-order-btn.is-icon {
+		min-width: 44px;
+		padding-inline: 10px;
+	}
 	.cbgd-dwell {
 		min-height: 44px;
 	}
@@ -662,6 +705,18 @@
 	.cbgd-order-btn {
 		min-height: 44px;
 	}
+	/* 🔴 The width, which is what an icon-only pill is missing — a 15px glyph in 2×7px of
+	   padding is a 29px target on a phone however tall the pill is. */
+	.cbgd-order-btn.is-icon {
+		min-width: 44px;
+		padding-inline: 10px;
+	}
+	/* Bigger glyph to match the bigger target: 15px reads as a speck at arm's length. */
+	.cbgd-order-btn svg,
+	.cbgd-dwell-label svg {
+		width: 18px;
+		height: 18px;
+	}
 	.cbgd-search {
 		min-height: 44px;
 	}
@@ -673,12 +728,15 @@
 	}
 }
 
-/* ── The stage resize grips ──────────────────────────────────────────────────
- * They are `mediaResize.css`'s (`.cbmr-corner` on the frame, `.cbmr-bar` under it),
- * shared with the focus viewer since 2026-08-25 — the day a handle that existed only
- * here was reported as a feature that did not exist. Only the BAR's width is this
- * module's business, because only this module knows the frame is 16:9-capped. */
-.cbgd-watch-player > .cbmr-bar {
+/* ── The stage resize rail ───────────────────────────────────────────────────
+ * It is `mediaResize.css`'s (`.cbmr-rail`, holding the corner grip and — on coarse
+ * pointers — the bar), shared with the focus viewer since 2026-08-25, the day a handle
+ * that existed only here was reported as a feature that did not exist. Only its WIDTH is
+ * this module's business, because only this module knows the frame is 16:9-capped: the
+ * rail has to end exactly where the picture does, or its bottom-right corner is not the
+ * picture's bottom-right corner and *"the bottom right corner of the video player"* stops
+ * being true. */
+.cbgd-watch-player > .cbmr-rail {
 	max-width: calc(var(--cbgd-stage-h, var(--cbgd-stage-fit, var(--cbgd-stage-default))) * 16 / 9);
 	margin-inline: auto;
 }

package/src/react/media/hlsSource.recovery.spec.ts

@@ -0,0 +1,213 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { attachHlsSource, HLS_CONFIG, RECOVERY_BUDGET } from './hlsSource';
+
+/** A `<video>` that reports no native HLS, so every test here takes the hls.js branch. */
+function videoEl(canPlayHls = false): HTMLVideoElement {
+  const el = document.createElement('video');
+  el.canPlayType = ((type: string) =>
+    canPlayHls && type === 'application/vnd.apple.mpegurl' ? 'maybe' : '') as HTMLVideoElement['canPlayType'];
+  return el;
+}
+
+const LADDER = 'https://example.test/clip.hls/master.m3u8';
+const REMUX = 'https://example.test/clip.web.mp4';
+
+//
+// *"sometimes a video is playing and starts buffering and ends up pausing instead of trying
+// to wait it out"* (2026-09-17). An hls.js with no ERROR listener stops permanently on any
+// fatal error — the library retries a fragment six times, gives up, emits fatal, and the
+// application is expected to decide what happens next. This module listened to nothing, so
+// "what happens next" was nothing, for ever.
+//
+// These specs drive a FAKE hls.js because the real one needs MediaSource, which happy-dom
+// does not have — and because what is under test is our decision tree, not the library's.
+
+/** The calls a test wants to assert on, shared by every instance the fake constructs. */
+const calls: string[] = [];
+let emit: ((data: { fatal?: boolean; type?: string; details?: string }) => void) | null = null;
+let configSeen: Record<string, unknown> | null = null;
+let supported = true;
+
+function installFakeHls(): void {
+  class Hls {
+    static Events = { ERROR: 'hlsError' } as const;
+    static ErrorTypes = { NETWORK_ERROR: 'networkError', MEDIA_ERROR: 'mediaError', MUX_ERROR: 'muxError' } as const;
+    static isSupported = (): boolean => supported;
+    constructor(config: Record<string, unknown>) {
+      configSeen = config;
+    }
+    on(_event: string, handler: (e: unknown, d: { fatal?: boolean; type?: string }) => void): void {
+      emit = (d) => handler('hlsError', d);
+    }
+    loadSource(url: string): void {
+      calls.push(`loadSource:${url}`);
+    }
+    attachMedia(): void {
+      calls.push('attachMedia');
+    }
+    startLoad(): void {
+      calls.push('startLoad');
+    }
+    recoverMediaError(): void {
+      calls.push('recoverMediaError');
+    }
+    swapAudioCodec(): void {
+      calls.push('swapAudioCodec');
+    }
+    destroy(): void {
+      calls.push('destroy');
+    }
+  }
+  mock.module('hls.js', () => ({ default: Hls }));
+}
+
+/** Let the dynamic import resolve and the `.then` run. */
+const settle = async (): Promise<void> => {
+  for (let i = 0; i < 4; i++) await new Promise((r) => setTimeout(r, 0));
+};
+
+describe('attachHlsSource — recovering instead of stopping', () => {
+  afterEach(() => {
+    calls.length = 0;
+    emit = null;
+    configSeen = null;
+    supported = true;
+  });
+
+  test('🔴 a fatal network error reloads rather than leaving the video stopped', async () => {
+    installFakeHls();
+    const el = videoEl(false);
+    const detach = attachHlsSource(el, { hlsUrl: LADDER, streamUrl: REMUX });
+    await settle();
+    expect(calls).toContain(`loadSource:${LADDER}`);
+
+    emit?.({ fatal: true, type: 'networkError', details: 'fragLoadError' });
+    // The first retry is immediate; later ones back off. Either way it must actually happen.
+    await new Promise((r) => setTimeout(r, 20));
+    expect(calls).toContain('startLoad');
+    // And it did NOT abandon the ladder on the first blip — that is the whole point.
+    expect(el.src).not.toBe(REMUX);
+    detach();
+  });
+
+  test('a NON-fatal error is hls.js retrying on its own and must not be touched', async () => {
+    installFakeHls();
+    const el = videoEl(false);
+    const detach = attachHlsSource(el, { hlsUrl: LADDER, streamUrl: REMUX });
+    await settle();
+    emit?.({ fatal: false, type: 'networkError', details: 'fragLoadError' });
+    await new Promise((r) => setTimeout(r, 20));
+    expect(calls).not.toContain('startLoad');
+    detach();
+  });
+
+  test('a media error recovers, and the SECOND one swaps the audio codec', async () => {
+    // hls.js's own guidance: calling recoverMediaError() twice for one stall recovers
+    // nothing. The codec swap is what clears the recurring case.
+    installFakeHls();
+    const el = videoEl(false);
+    const detach = attachHlsSource(el, { hlsUrl: LADDER, streamUrl: REMUX });
+    await settle();
+    emit?.({ fatal: true, type: 'mediaError' });
+    expect(calls.filter((c) => c === 'recoverMediaError').length).toBe(1);
+    expect(calls).not.toContain('swapAudioCodec');
+    emit?.({ fatal: true, type: 'mediaError' });
+    expect(calls).toContain('swapAudioCodec');
+    expect(calls.filter((c) => c === 'recoverMediaError').length).toBe(2);
+    detach();
+  });
+
+  test('🔴 the recovery budget is spent, then the progressive copy takes over', async () => {
+    installFakeHls();
+    const el = videoEl(false);
+    const detach = attachHlsSource(el, { hlsUrl: LADDER, streamUrl: REMUX });
+    await settle();
+    for (let i = 0; i <= RECOVERY_BUDGET; i++) emit?.({ fatal: true, type: 'mediaError' });
+    expect(calls).toContain('destroy');
+    expect(el.src).toBe(REMUX);
+    detach();
+  });
+
+  test('🔴 the fallback resumes where playback was, not from zero', async () => {
+    // A fallback forty minutes into a film that restarts it from the beginning is a fallback
+    // the owner would rather not have had — and it happens exactly when things are already
+    // going badly.
+    installFakeHls();
+    const el = videoEl(false);
+    Object.defineProperty(el, 'currentTime', { value: 2400, writable: true, configurable: true });
+    const detach = attachHlsSource(el, { hlsUrl: LADDER, streamUrl: REMUX });
+    await settle();
+    for (let i = 0; i <= RECOVERY_BUDGET; i++) emit?.({ fatal: true, type: 'mediaError' });
+    expect(el.src).toBe(REMUX);
+    el.dispatchEvent(new Event('loadedmetadata'));
+    expect(el.currentTime).toBe(2400);
+    detach();
+  });
+
+  test('an unrecognised fatal error goes straight to the remux — a reload does not fix a mux error', async () => {
+    installFakeHls();
+    const el = videoEl(false);
+    const detach = attachHlsSource(el, { hlsUrl: LADDER, streamUrl: REMUX });
+    await settle();
+    emit?.({ fatal: true, type: 'muxError' });
+    expect(el.src).toBe(REMUX);
+    expect(calls).not.toContain('startLoad');
+    detach();
+  });
+
+  test('🔴 a teardown cancels a retry that has not fired yet', async () => {
+    // The backoff means a retry can be in a timer when React unmounts the stage. Firing it
+    // would call into a destroyed engine — and keep a timer alive on a dead element.
+    installFakeHls();
+    const el = videoEl(false);
+    const detach = attachHlsSource(el, { hlsUrl: LADDER, streamUrl: REMUX });
+    await settle();
+    emit?.({ fatal: true, type: 'networkError' }); // attempt 0 — no backoff
+    await new Promise((r) => setTimeout(r, 20));
+    expect(calls.filter((c) => c === 'startLoad').length).toBe(1);
+
+    emit?.({ fatal: true, type: 'networkError' }); // attempt 1 — 1 s backoff, still pending
+    detach();
+    await new Promise((r) => setTimeout(r, 1200));
+    // Still one. The pending retry was cancelled rather than firing into a destroyed engine.
+    expect(calls.filter((c) => c === 'startLoad').length).toBe(1);
+  });
+
+  test('an unsupported hls.js still lands on the remux, and never builds an engine', async () => {
+    installFakeHls();
+    supported = false;
+    const el = videoEl(false);
+    const detach = attachHlsSource(el, { hlsUrl: LADDER, streamUrl: REMUX });
+    await settle();
+    expect(el.src).toBe(REMUX);
+    expect(calls).toEqual([]);
+    detach();
+  });
+});
+
+describe('HLS_CONFIG — tuned for a home Mac behind a tunnel, not a CDN', () => {
+  test('🔴 the forward buffer is far wider than hls.js\'s 30 s default', () => {
+    // A cold segment is up to 2.6 s for 4 s of video (measured 2026-09-17), so 30 s of buffer
+    // survives about a dozen slow fetches back to back. That is the stall being reported.
+    expect(HLS_CONFIG.maxBufferLength).toBeGreaterThanOrEqual(60);
+  });
+
+  test('🔴 the starting bandwidth estimate is not the 500 kbit stranger default', () => {
+    // Everyone here is on the household network and the top rung is capped at 5,000 kbit by
+    // the encoder ladder. Starting low means the first thing anyone sees is 480p.
+    expect(HLS_CONFIG.abrEwmaDefaultEstimate).toBeGreaterThanOrEqual(3_000_000);
+  });
+
+  test('the back buffer is bounded — unbounded is how a long film loses its MediaSource', () => {
+    expect(HLS_CONFIG.backBufferLength).toBeGreaterThan(0);
+    expect(HLS_CONFIG.backBufferLength).toBeLessThanOrEqual(120);
+  });
+
+  test('the config actually reaches the engine', async () => {
+    installFakeHls();
+    const detach = attachHlsSource(videoEl(false), { hlsUrl: LADDER, streamUrl: REMUX });
+    await settle();
+    expect(configSeen?.maxBufferLength).toBe(HLS_CONFIG.maxBufferLength);
+    detach();
+  });
+});

package/src/react/media/hlsSource.spec.ts

@@ -1,6 +1,14 @@
 import { describe, expect, test } from 'bun:test';
 import { attachHlsSource, canPlayHlsNatively } from './hlsSource';
 
+// 🔴 The RECOVERY specs are a separate file, and the reason is a Bun behaviour rather than a
+// taste: `mock.module('hls.js', …)` is applied at FILE scope no matter where it is called, so
+// a fake engine registered inside one test is the engine every other test in the file gets.
+// Measured here — "a ladder is preferred over the remux only where it can actually play"
+// passed alone and failed beside the mocking tests, because the fake reports `isSupported()`.
+// This file therefore proves the branches that need hls.js to be genuinely ABSENT;
+// `hlsSource.recovery.spec.ts` proves the ones that need it present.
+
 /** A `<video>` with a browser's answer to "can you play HLS?" stubbed onto it. */
 function videoEl(canPlayHls: boolean): HTMLVideoElement {
   const el = document.createElement('video');

package/src/react/media/hlsSource.ts

@@ -30,9 +30,54 @@
  * ⇧→ mounts one per clip, and thirty clips is thirty live engines still fetching segments for
  * videos nobody is watching. The `destroyed` flag covers the same leak on the async path —
  * an unmount that happens while the dynamic import is in flight.
+ *
+ * ── 🔴 An hls.js with no ERROR handler stops for good, and that was this file ────────────
+ * Owner report, 2026-09-17: *"sometimes a video is playing and starts buffering and ends up
+ * pausing instead of trying to wait it out."* That is not a description of a slow network —
+ * it is the documented behaviour of an unattended hls.js. The library retries a failing
+ * fragment on its own (six times, backing off to ~64 s in total) and then emits a FATAL error
+ * and **stops the loop**. Recovery is the application's job and always has been; this module
+ * was constructing the engine with `new Hls({ enableWorker: true })` and listening to
+ * nothing, so every fatal error was permanent.
+ *
+ * Three of them are recoverable and are handled here rather than surfaced:
+ *
+ * | fatal type | what it actually is here | what we do |
+ * |---|---|---|
+ * | `networkError` on a fragment | the tunnel blinked, or the segment was slow off a cold cache | `startLoad()` from where playback is, with a widening backoff |
+ * | `networkError` on the manifest | the ladder token expired mid-film, or bs is down | reload once, then fall back |
+ * | `mediaError` | a buffer-append or decode stall | `recoverMediaError()`, then the audio-codec-swap variant, then fall back |
+ *
+ * 🔴 And every road STILL ends at something playable: once the recoveries are spent, the
+ * engine is destroyed and the element is pointed at `streamUrl` **at the time it had reached**
+ * — a fallback that restarts a two-hour film from zero is a fallback the owner would rather
+ * not have had. That is the property `RECOVERY_BUDGET` bounds; without a budget a genuinely
+ * dead ladder becomes an infinite reload loop, which is the same spinner with more requests.
+ *
+ * ── 🔴 The config is tuned for a HIGH-LATENCY origin, which is what this fleet has ───────
+ * hls.js's defaults assume a CDN. These segments come off a home Mac through a tunnel when
+ * the edge does not hold them: measured 2026-09-17, a cold segment is 1,215–2,613 ms against
+ * ~150 ms warm, for four seconds of video. Two defaults are actively wrong at that latency —
+ * a 30 s forward buffer gives the player no room to absorb one slow fetch, and a 500 kbps
+ * starting bandwidth estimate makes it open on the bottom rung and climb. Both are widened
+ * below, each with its number's reason on the line.
  */
 import { useEffect } from 'react';
 
+/**
+ * The shape of an hls.js `ERROR` payload this module reads.
+ *
+ * Declared locally rather than imported: `hls.js` is a DYNAMIC import in exactly one branch
+ * (~525 KB), and a type-only import from it at the top of the file is the kind of thing a
+ * bundler resolves into a static one. Only three fields are read, and all three have been
+ * stable across the library's 1.x line.
+ */
+interface HlsErrorData {
+  fatal?: boolean;
+  type?: string;
+  details?: string;
+}
+
 /** Which URLs a surface has for one video. `streamUrl` is the one that always exists. */
 export interface HlsSourceUrls {
   /** The adaptive ladder's MASTER playlist, when one has been built. */
@@ -58,9 +103,105 @@ export function canPlayHlsNatively(el: HTMLVideoElement): boolean {
  * Synchronous for the native and progressive paths; the hls.js path resolves a dynamic
  * import first, so the returned teardown has to be safe to call before that lands.
  */
+/**
+ * How many times a fatal error may be recovered before the ladder is abandoned for the
+ * progressive copy.
+ *
+ * Four is two more than a transient blip needs and far fewer than a dead ladder would consume.
+ * The bound is the point: a `startLoad()` in an unbounded error handler is an infinite reload
+ * loop against a URL that is never going to answer — a spinner that also hammers the origin,
+ * which is strictly worse than the stall it replaced.
+ */
+export const RECOVERY_BUDGET = 4;
+
+/** Backoff before each retry, in ms. Read by index, clamped to the last entry. */
+const RECOVERY_BACKOFF_MS = [0, 1_000, 3_000, 8_000];
+
+/**
+ * hls.js settings for an origin that is a home Mac behind a tunnel, not a CDN.
+ *
+ * Exported so the specs can assert the two numbers that actually matter and so a surface with
+ * a genuinely different origin can spread this rather than re-derive it.
+ */
+export const HLS_CONFIG = {
+  enableWorker: true,
+  /**
+   * 🔴 90 s of forward buffer, against a default of 30.
+   *
+   * The player stalls when the buffer empties, and what empties it here is one slow fetch:
+   * a cold segment is up to 2.6 s for 4 s of video, so 30 s of buffer survives about a dozen
+   * of them back to back. Ninety gives the fetch loop room to fall behind and catch up
+   * without the viewer seeing it — which is the whole of *"buffers, plays a few seconds,
+   * buffers"*. It is a CEILING, not an allocation: a warm ladder fills it in seconds and a
+   * short clip never reaches it.
+   */
+  maxBufferLength: 90,
+  /** The hard ceiling hls.js will stretch to when bandwidth is plentiful. */
+  maxMaxBufferLength: 600,
+  /** Bytes, not seconds, and the real limit on a 1080p rung. 120 MB ≈ 90 s at 5 Mbit. */
+  maxBufferSize: 120 * 1000 * 1000,
+  /**
+   * 🔴 Keep 30 s behind the playhead instead of hls.js's default of everything.
+   *
+   * Stepping back a few seconds is the commonest thing the owner does with a video and it
+   * should never re-fetch. Unbounded back-buffer is the other failure though: a two-hour film
+   * accumulates until the browser evicts the whole MediaSource, which presents as the video
+   * stopping for no reason.
+   */
+  backBufferLength: 30,
+  /**
+   * 🔴 Start at 5 Mbit rather than hls.js's 500 kbit.
+   *
+   * The default assumes an unknown internet connection and opens on the bottom rung while it
+   * measures. Every viewer here is on the household's own network or a phone on it, the top
+   * rung is capped at 5,000 kbit by the encoder ladder, and starting low means the first
+   * thing anyone sees is 480p that visibly sharpens. One wrong guess costs one segment.
+   */
+  abrEwmaDefaultEstimate: 5_000_000,
+  /** A cold segment off the tunnel can take seconds; 20 s (the default) times out a fetch
+   *  that was going to succeed, and a timeout counts against the retry budget. */
+  fragLoadingTimeOut: 60_000,
+  manifestLoadingTimeOut: 30_000,
+  levelLoadingTimeOut: 30_000,
+} as const;
+
 export function attachHlsSource(el: HTMLVideoElement, urls: HlsSourceUrls): () => void {
   let destroyed = false;
   let engine: { destroy: () => void } | null = null;
+  let pendingRetry: ReturnType<typeof setTimeout> | null = null;
+
+  /**
+   * Abandon the ladder for the progressive copy, AT THE POSITION PLAYBACK HAD REACHED.
+   *
+   * 🔴 The seek is not a nicety. Without it, a fallback forty minutes into a film restarts it
+   * from zero — and because a fallback happens exactly when things are already going badly,
+   * that is the moment the owner is least likely to forgive it. `currentTime` is read before
+   * the engine is destroyed, because destroying it detaches the MediaSource and resets it.
+   */
+  const fallBackToProgressive = (): void => {
+    if (destroyed) return;
+    const at = Number.isFinite(el.currentTime) ? el.currentTime : 0;
+    const wasPlaying = !el.paused;
+    engine?.destroy();
+    engine = null;
+    el.src = urls.streamUrl;
+    if (at > 0) {
+      // `loadedmetadata` is the first moment a seek on a fresh source is honoured; setting
+      // `currentTime` before it is silently dropped.
+      el.addEventListener(
+        'loadedmetadata',
+        () => {
+          try {
+            el.currentTime = at;
+          } catch {
+            /* a source that refuses the seek still plays, from the start */
+          }
+          if (wasPlaying) void el.play?.().catch(() => {});
+        },
+        { once: true },
+      );
+    }
+  };
 
   if (urls.hlsUrl && canPlayHlsNatively(el)) {
     el.src = urls.hlsUrl;
@@ -74,8 +215,53 @@ export function attachHlsSource(el: HTMLVideoElement, urls: HlsSourceUrls): () =
           el.src = urls.streamUrl;
           return;
         }
-        const hls = new Hls({ enableWorker: true });
+        const hls = new Hls(HLS_CONFIG);
         engine = hls;
+        let spent = 0;
+        hls.on(Hls.Events.ERROR, (_event: unknown, data: HlsErrorData) => {
+          // Non-fatal errors are hls.js's own retry machinery working. Reacting to them would
+          // restart a load that is already in progress.
+          if (destroyed || !data?.fatal) return;
+          if (spent >= RECOVERY_BUDGET) {
+            fallBackToProgressive();
+            return;
+          }
+          const attempt = spent++;
+          if (data.type === Hls.ErrorTypes.MEDIA_ERROR) {
+            // 🔴 The SECOND media recovery must be the codec-swap variant, per hls.js's own
+            // guidance: calling `recoverMediaError()` twice for the same stall recovers
+            // nothing, and the audio-codec swap is what clears the case that keeps recurring.
+            if (attempt === 0) hls.recoverMediaError();
+            else hls.swapAudioCodec?.(), hls.recoverMediaError();
+            return;
+          }
+          if (data.type === Hls.ErrorTypes.NETWORK_ERROR) {
+            const delay = RECOVERY_BACKOFF_MS[Math.min(attempt, RECOVERY_BACKOFF_MS.length - 1)] ?? 0;
+            // 🔴 Backed off, because the commonest cause is an origin that is briefly
+            // unreachable — a tunnel reconnecting, this Mac waking. Retrying instantly turns
+            // one blip into four and spends the whole budget inside a second.
+            //
+            // 🔴 And the previous timer is cleared first. Fatal errors arrive in bursts, so
+            // without this each one leaks a timer that `detach()` cannot reach — only the
+            // last handle was ever held — and a burst of four leaves three of them to fire
+            // into an engine React has already unmounted.
+            if (pendingRetry) clearTimeout(pendingRetry);
+            pendingRetry = setTimeout(() => {
+              pendingRetry = null;
+              if (destroyed) return;
+              try {
+                hls.startLoad();
+              } catch {
+                fallBackToProgressive();
+              }
+            }, delay);
+            pendingRetry.unref?.();
+            return;
+          }
+          // Anything else fatal (a mux error, an unknown type) is not something a reload
+          // fixes. The remux is the answer and it is the answer immediately.
+          fallBackToProgressive();
+        });
         hls.loadSource(urls.hlsUrl as string);
         hls.attachMedia(el);
       })
@@ -89,6 +275,8 @@ export function attachHlsSource(el: HTMLVideoElement, urls: HlsSourceUrls): () =
 
   return () => {
     destroyed = true;
+    if (pendingRetry) clearTimeout(pendingRetry);
+    pendingRetry = null;
     engine?.destroy();
     engine = null;
   };