cursedbelt 5.97.0 → 5.99.0

package/src/react/media/imageOriginal.ts

@@ -0,0 +1,114 @@
+/**
+ * A picture's ORIGINAL, reached past its web copy — the image half of "Max" (forge task 3873).
+ *
+ * ── Why (forge task 3868, the owner's ruling of 2026-10-28) ─────────────────────────────
+ * binary-server keeps every image original now, but the web copy every viewer draws is a JPEG
+ * capped at 2560 px on its longest edge (`DEFAULT_IMAGE_SIZES`). A 48 MP photograph zoomed to
+ * read a face was still the 2560-px JPEG, and the original was reachable only as a download.
+ * The video player's answer was a menu (Auto · Max · each rung); a picture has two copies, so
+ * its answer is two choices:
+ *
+ * | choice | what the viewer draws |
+ * |---|---|
+ * | auto (the default) | the web copy, and the original the moment the picture is drawn with more device pixels than the web copy has — a zoom, or a 5K screen |
+ * | original | the original, always |
+ *
+ * ── 🔴 The web copy stays on screen until the original has DECODED ──────────────────────
+ * A 48 MP JPEG is 10–20 MB and a second or more to decode. Pointing the `<img>` at it at once
+ * blanks the picture, mid-zoom, for that long. `useImageOriginal` decodes it off-screen
+ * (`HTMLImageElement.decode()`) and swaps only then, so the swap is one frame.
+ *
+ * ── 🔴 Only a type the browser can draw ─────────────────────────────────────────────────
+ * A DNG, a HEIC or a TIFF original is exactly what the web copy exists FOR. The control stays
+ * visible and disabled with that reason (the fleet's one-UI rule), and the viewer keeps the
+ * JPEG.
+ *
+ * ── Remembered per VIEWER, in `localStorage` ────────────────────────────────────────────
+ * The same reasoning as `cb.video-quality` (`videoQuality.ts`): a phone on cellular and the
+ * desk's 5K screen want different answers, and every image viewer reads the one key.
+ */
+
+/** The one key every image viewer reads and writes: `'original'`, or absent for auto. */
+export const IMAGE_ORIGINAL_KEY = 'cb.image-quality';
+
+/**
+ * Drawn with this many more device pixels than the web copy holds before the original is
+ * fetched. A hair over 1: a picture filling a 2560-px screen exactly gains nothing from 20 MB.
+ */
+export const ORIGINAL_NEED_RATIO = 1.1;
+
+export const ORIGINAL_FAILED_REASON = 'The original did not load — the web copy is showing';
+
+/**
+ * Why no browser can draw this original, or null when one can.
+ *
+ * 🔴 The mime list mirrors cursedbelt-server's `isUnviewableStill`
+ * (`src/server/storage/derivatives.ts`) and binary-server's `isUnviewableOriginal` — the
+ * stills bs makes a web copy for no matter how small, because nothing else can show them —
+ * and adds the camera RAWs bs never draws either. The NAME is read too: a `.DNG` or a `.HEIC`
+ * is often cataloged as `application/octet-stream`, for the reason that file gives.
+ */
+export function originalUndrawableReason(mime: string | null | undefined, name?: string | null): string | null {
+  const bare = (mime ?? '').split(';')[0]?.trim().toLowerCase() ?? '';
+  const extension = (name ?? '').toLowerCase().match(/\.([a-z0-9]+)$/)?.[1] ?? '';
+  const kind = /^image\/(heic|heif)(-sequence)?$/.test(bare) || ['heic', 'heif'].includes(extension)
+    ? 'HEIC'
+    : bare === 'image/tiff' || ['tif', 'tiff'].includes(extension)
+      ? 'TIFF'
+      : bare === 'image/x-adobe-dng' || RAW_EXTENSIONS.includes(extension)
+        ? 'camera RAW'
+        : null;
+  return kind ? `The original is a ${kind}, which this browser cannot draw — Download has it` : null;
+}
+
+const RAW_EXTENSIONS = ['dng', 'cr2', 'cr3', 'nef', 'arw', 'raf', 'orf', 'rw2', 'pef', 'srw'];
+
+/**
+ * Does a picture drawn `drawnWidth` CSS pixels wide (zoom included) need more than a web copy
+ * `webWidth` pixels wide holds, on a screen of `devicePixelRatio`?
+ */
+export function originalNeeded(drawnWidth: number, webWidth: number, devicePixelRatio = 1): boolean {
+  if (!(drawnWidth > 0) || !(webWidth > 0)) return false;
+  return drawnWidth * Math.max(1, devicePixelRatio) > webWidth * ORIGINAL_NEED_RATIO;
+}
+
+/** Guarded: storage throws in a private window, and is absent in a worker or on the server. */
+function store(): Storage | null {
+  try {
+    return globalThis.localStorage ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** True when this viewer chose "always the original". */
+export function readImageOriginalPinned(): boolean {
+  try {
+    return store()?.getItem(IMAGE_ORIGINAL_KEY) === 'original';
+  } catch {
+    return false;
+  }
+}
+
+export function writeImageOriginalPinned(pinned: boolean): void {
+  try {
+    if (pinned) store()?.setItem(IMAGE_ORIGINAL_KEY, 'original');
+    else store()?.removeItem(IMAGE_ORIGINAL_KEY);
+  } catch {
+    /* a full or refused store only means the choice lasts this picture */
+  }
+}
+
+/** What a viewer's control shows, and the one way to change it. */
+export interface ImageOriginalControl {
+  /** The remembered "always the original". */
+  pinned: boolean;
+  /** The original is the picture on screen right now. */
+  showing: boolean;
+  /** The original is being fetched and decoded; the web copy is still on screen. */
+  loading: boolean;
+  /** Why the original cannot be drawn here, or null when it can. */
+  unavailable: string | null;
+  /** Flip the remembered choice, and apply it. */
+  toggle: () => void;
+}

package/src/react/media/imageOriginalEntry.ts

@@ -0,0 +1,8 @@
+/**
+ * `cursedbelt/react/media/image-original` — a picture's original past its web copy (forge task
+ * 3873), for an app that draws its own `<img>` and must not bundle the media barrel's optional
+ * peers (photos' zoomable asset page). The gallery stage uses the same three modules.
+ */
+export { type ImageOriginalControl, originalUndrawableReason } from './imageOriginal.js';
+export { ImageOriginalToggle, type ImageOriginalToggleProps } from './ImageOriginalToggle.js';
+export { type ImageOriginal, type UseImageOriginalOptions, useImageOriginal } from './useImageOriginal.js';

package/src/react/media/index.ts

@@ -164,6 +164,15 @@ export { useObjectUrl } from './useObjectUrl.js';
 // element rather than Vidstack and each was carrying its own copy of the decision.
 export { attachHlsSource, canPlayHlsNatively, type HlsSourceUrls, useHlsSource } from './hlsSource.js';
 export { PLAYBACK_RATES, preferBundledHls, VideoPlayer, type VideoPlayerProps } from './VideoPlayer.js';
+// The quality menu — Auto · Max · each rung, remembered per viewer (forge task 3868); every
+// player surface in this package draws it, and a control is what a surface hands it.
+export type { VideoQualityControl } from './videoQuality.js';
+export { VideoQualitySelect, type VideoQualitySelectProps } from './VideoQualitySelect.js';
+// The image half of it — the web copy, and the original past it, remembered per viewer
+// (forge task 3873); an image viewer draws the `src` the hook answers and hands it the toggle.
+export { type ImageOriginalControl, originalUndrawableReason } from './imageOriginal.js';
+export { ImageOriginalToggle, type ImageOriginalToggleProps } from './ImageOriginalToggle.js';
+export { type ImageOriginal, type UseImageOriginalOptions, useImageOriginal } from './useImageOriginal.js';
 // The focus viewer — look closely at PART of a video, and keep what you find. Lifted out
 // of apps/collections in unit 15 so binary-server's inspector can mount the same one.
 export {

package/src/react/media/useImageOriginal.ts

@@ -0,0 +1,97 @@
+/**
+ * The web copy, and the original past it — `imageOriginal.ts` says what the choices mean.
+ *
+ * A viewer hands this what it already knows — the two URLs, the picture's type, how wide it is
+ * DRAWN right now (zoom included), and how wide the web copy is — and draws the `src` it
+ * answers. Nothing here measures the DOM: the gallery stage measures its `<img>`, photos' zoom
+ * multiplies its fit by its scale, and either way the decision is the same pure comparison.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import {
+  type ImageOriginalControl,
+  ORIGINAL_FAILED_REASON,
+  originalNeeded,
+  originalUndrawableReason,
+  readImageOriginalPinned,
+  writeImageOriginalPinned,
+} from './imageOriginal.js';
+
+export interface UseImageOriginalOptions {
+  /** The web copy — what is drawn until the original is wanted AND decoded. */
+  src: string;
+  /** The original, signed for inline viewing. Absent: there is no original to reach, and no control. */
+  originalSrc?: string | null | undefined;
+  mime?: string | null | undefined;
+  name?: string | null | undefined;
+  /** The picture's width on screen in CSS pixels, zoom included; 0 while unknown. */
+  drawnWidth: number;
+  /** The web copy's own pixel width (`naturalWidth`); 0 while unknown. */
+  webWidth: number;
+}
+
+export interface ImageOriginal {
+  /** The URL to draw. */
+  src: string;
+  /** Null when the item carries no original. */
+  control: ImageOriginalControl | null;
+}
+
+/** Off-screen fetch AND decode, so the swap is one frame. The browser's cache serves the `<img>` after. */
+function decodeOff(url: string): Promise<void> {
+  const image = new Image();
+  image.decoding = 'async';
+  image.src = url;
+  return image.decode();
+}
+
+export function useImageOriginal({ src, originalSrc, mime, name, drawnWidth, webWidth }: UseImageOriginalOptions): ImageOriginal {
+  const [pinned, setPinned] = useState(readImageOriginalPinned);
+  /** The original that has decoded and may be drawn — keyed by URL, so a new picture starts over. */
+  const [ready, setReady] = useState<string | null>(null);
+  const [failed, setFailed] = useState<string | null>(null);
+  /**
+   * 🔴 Latched per original: once a zoom has fetched it, zooming back out keeps it. The bytes
+   * are already here, and swapping back to the web copy would only flicker.
+   */
+  const [reached, setReached] = useState<string | null>(null);
+
+  const original = originalSrc || null;
+  const undrawable = original ? originalUndrawableReason(mime, name) : null;
+  const unavailable = undrawable ?? (original && failed === original ? ORIGINAL_FAILED_REASON : null);
+  const ratio = typeof window === 'undefined' ? 1 : window.devicePixelRatio || 1;
+  const needed = originalNeeded(drawnWidth, webWidth, ratio);
+  const wanted = Boolean(original) && !unavailable && (pinned || needed || reached === original);
+
+  useEffect(() => {
+    if (wanted && original && reached !== original) setReached(original);
+  }, [wanted, original, reached]);
+
+  useEffect(() => {
+    if (!wanted || !original || ready === original) return;
+    let live = true;
+    decodeOff(original).then(
+      () => live && setReady(original),
+      () => live && setFailed(original),
+    );
+    return () => {
+      live = false;
+    };
+  }, [wanted, original, ready]);
+
+  const toggle = useCallback(() => {
+    setPinned((was) => {
+      writeImageOriginalPinned(!was);
+      return !was;
+    });
+    // Un-pinning returns to the web copy unless the zoom still needs the original.
+    setReached(null);
+  }, []);
+
+  const showing = Boolean(original) && wanted && ready === original;
+  return {
+    src: showing && original ? original : src,
+    control: original
+      ? { pinned, showing, loading: wanted && !showing, unavailable, toggle }
+      : null,
+  };
+}

package/src/react/media/videoPlayer.css

@@ -70,3 +70,26 @@
 		--media-sm-fullscreen-button-size: 44px;
 	}
 }
+
+/*
+ * ── The quality menu (forge task 3868) ────────────────────────────────────────────────
+ * cursedbelt's own (`VideoQualitySelect`, in the bar beside the cog) REPLACES Vidstack's
+ * quality submenu: that one offers no Max and remembers nothing, and two menus choosing the
+ * same thing would disagree. This stylesheet ships only with `VideoPlayer`, which always
+ * draws the replacement, so hiding Vidstack's here cannot leave a player with neither.
+ */
+.vds-quality-menu {
+	display: none;
+}
+.cbvp-quality {
+	align-self: center;
+	color: inherit;
+	font-size: 13px;
+}
+/* The trigger is as tall as the bar's own buttons — 44px on a finger (the coarse block above
+   sets `--media-button-size`), so the chip clears the same tap floor they do. */
+.cbvp-quality button {
+	min-height: var(--media-button-size, 40px);
+	min-width: 44px;
+	padding-inline: 6px;
+}

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

@@ -0,0 +1,135 @@
+/**
+ * 🔴 The quality choice (forge task 3868): Auto is capped at the player's size, Max lifts the cap,
+ * a rung is fixed — and the choice is remembered as a HEIGHT, so it means the same on every film.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import {
+  bindHlsQuality,
+  createVideoQualityStore,
+  type HlsQualityEngine,
+  levelIndexFor,
+  NO_LADDER_REASON,
+  parseVideoQuality,
+  readVideoQuality,
+  rungLabel,
+  rungLevels,
+  VIDEO_QUALITY_KEY,
+  type VideoQualityControl,
+  writeVideoQuality,
+} from './videoQuality.js';
+
+afterEach(() => localStorage.removeItem(VIDEO_QUALITY_KEY));
+
+/** binary-server's ladder as hls.js parses it: three encoded rungs and the original's copy. */
+const LADDER = [
+  { height: 360, uri: 'https://bs.test/f.hls/360/playlist.m3u8?t=x' },
+  { height: 720, uri: 'https://bs.test/f.hls/720/playlist.m3u8?t=x' },
+  { height: 1080, uri: 'https://bs.test/f.hls/1080/playlist.m3u8?t=x' },
+  { height: 2160, uri: 'https://bs.test/f.hls/o2160/playlist.m3u8?t=x' },
+];
+
+function fakeHls(levels = LADDER) {
+  const handlers = new Map<string, ((...args: unknown[]) => void)[]>();
+  const engine = {
+    levels,
+    currentLevel: -1,
+    nextLevel: -1,
+    capLevelToPlayerSize: true,
+    on: (event: string, fn: (...args: never[]) => void) =>
+      handlers.set(event, [...(handlers.get(event) ?? []), fn as (...args: unknown[]) => void]),
+    off: (event: string, fn: (...args: never[]) => void) =>
+      handlers.set(event, (handlers.get(event) ?? []).filter((h) => h !== fn)),
+    fire: (event: string, data?: unknown) => {
+      for (const h of handlers.get(event) ?? []) h(event, data);
+    },
+  };
+  return engine as typeof engine & HlsQualityEngine;
+}
+
+describe('the remembered choice', () => {
+  test('round-trips auto, max and a height; anything unreadable is auto', () => {
+    expect(parseVideoQuality('max')).toBe('max');
+    expect(parseVideoQuality('1080')).toBe(1080);
+    for (const junk of [null, '', 'auto', '-5', '1.5', 'NaN', 'huge']) expect(parseVideoQuality(junk)).toBe('auto');
+    writeVideoQuality(720);
+    expect(readVideoQuality()).toBe(720);
+    writeVideoQuality('max');
+    expect(readVideoQuality()).toBe('max');
+  });
+});
+
+describe('a height means the same rung on every film', () => {
+  test('the exact rung, else the tallest below it, else the shortest — and -1 for adaptive', () => {
+    expect(levelIndexFor(LADDER, 1080)).toBe(2);
+    expect(levelIndexFor(LADDER, 1440)).toBe(2);
+    expect(levelIndexFor(LADDER, 240)).toBe(0);
+    expect(levelIndexFor(LADDER, 'auto')).toBe(-1);
+    expect(levelIndexFor(LADDER, 'max')).toBe(-1);
+    expect(levelIndexFor([], 720)).toBe(-1);
+  });
+
+  test("the o<height> rung is named the original's own stream", () => {
+    const levels = rungLevels(LADDER);
+    expect(levels.map((l) => l.height)).toEqual([2160, 1080, 720, 360]);
+    expect(levels.map(rungLabel)).toEqual(['2160p · Original', '1080p', '720p', '360p']);
+    // An encoded master (m<height>) is not the original.
+    expect(rungLevels([{ height: 2160, uri: 'f.hls/m2160/playlist.m3u8' }])[0]?.original).toBe(false);
+  });
+});
+
+describe('bindHlsQuality drives hls.js by the choice', () => {
+  test('auto keeps the size cap; a remembered rung is applied when the manifest is parsed', () => {
+    const hls = fakeHls();
+    const seen: VideoQualityControl[] = [];
+    bindHlsQuality(hls, (c) => seen.push(c));
+    expect(hls.capLevelToPlayerSize).toBe(true);
+
+    writeVideoQuality(720);
+    const fixed = fakeHls();
+    bindHlsQuality(fixed, (c) => seen.push(c));
+    expect(fixed.capLevelToPlayerSize).toBe(false);
+    fixed.fire('hlsManifestParsed');
+    expect(fixed.currentLevel).toBe(1);
+  });
+
+  test('🔴 Max lifts the cap and stays adaptive; the choice is remembered; a switch reports its rung', () => {
+    const hls = fakeHls();
+    const seen: { last?: VideoQualityControl } = {};
+    bindHlsQuality(hls, (c) => {
+      seen.last = c;
+    });
+    hls.fire('hlsManifestParsed');
+    seen.last?.select('max');
+    expect(hls.capLevelToPlayerSize).toBe(false);
+    expect(hls.nextLevel).toBe(-1);
+    expect(readVideoQuality()).toBe('max');
+    seen.last?.select(1080);
+    expect(hls.nextLevel).toBe(2);
+    seen.last?.select('auto');
+    expect(hls.capLevelToPlayerSize).toBe(true);
+    expect(hls.nextLevel).toBe(-1);
+    hls.fire('hlsLevelSwitched', { level: 3 });
+    expect(seen.last?.playingHeight).toBe(2160);
+    expect(seen.last?.unavailable).toBeNull();
+  });
+
+  test('a one-rung stream can choose nothing, and says why', () => {
+    const hls = fakeHls([{ height: 720, uri: 'only/playlist.m3u8' }]);
+    const seen: { last?: VideoQualityControl } = {};
+    bindHlsQuality(hls, (c) => {
+      seen.last = c;
+    });
+    hls.fire('hlsManifestParsed');
+    expect(seen.last?.unavailable).toBe(NO_LADDER_REASON);
+  });
+});
+
+test('the store notifies its readers and nothing else', () => {
+  const store = createVideoQualityStore();
+  let calls = 0;
+  const off = store.subscribe(() => calls++);
+  store.set(null);
+  off();
+  store.set(null);
+  expect(calls).toBe(1);
+});

package/src/react/media/videoQuality.ts

@@ -0,0 +1,248 @@
+/**
+ * A video's quality choice — YouTube's menu: Auto · Max · each rung — remembered per viewer.
+ *
+ * ── Why the choice exists (forge task 3868, the owner's ruling of 2026-10-28) ─────────────
+ * A ladder's top rung is now the ORIGINAL's own stream wherever the browser can play it
+ * (binary-server's `planLadder`: an `o<height>` rung is a stream copy, no loss). hls.js was
+ * capped to the player's size (`capLevelToPlayerSize`, task 3219 — *"lower bandwidth usage"*),
+ * so a windowed player played 480/720 on any connection, which is the blur the owner kept
+ * seeing. Both wishes stand, so they became two choices instead of one setting:
+ *
+ * | choice | what hls.js does |
+ * |---|---|
+ * | `auto` | adapts to bandwidth, never above what the player can show (the cap ON) |
+ * | `max`  | adapts to bandwidth, up to the original, whatever the player's size (the cap OFF) |
+ * | a height | that rung, fixed — the nearest rung at or below it on a film without it |
+ *
+ * ── 🔴 Remembered as a HEIGHT, never as a level index ──────────────────────────────────
+ * Every film has its own ladder: index 3 is 1080p on one and the 2160 original on the next.
+ * A height means the same thing on every film, and a film whose ladder has no such rung takes
+ * the nearest one below it (`levelIndexFor`) — "1080p" on a 720p film is its 720p, not
+ * nothing.
+ *
+ * ── 🔴 Per VIEWER, so `localStorage` ───────────────────────────────────────────────────
+ * A phone on cellular and the TV want different answers, and a viewer's device is where the
+ * answer belongs; a server-side preference would hand the TV's "Max" to the phone. Every
+ * surface reads the one key, so a choice made in the gallery stage carries into the focus
+ * viewer and the next film.
+ *
+ * ── Native HLS cannot choose ────────────────────────────────────────────────────────────
+ * Safari and every iPhone play the ladder with no library, and a page has no API to pick a
+ * rung there — the browser adapts by itself. The control stays VISIBLE and disabled, with the
+ * reason (`NATIVE_HLS_REASON`), per the fleet's one-UI rule.
+ */
+
+/** `auto`, `max`, or a rung's height in pixels. */
+export type VideoQualityChoice = 'auto' | 'max' | number;
+
+/** The one key every player reads and writes. */
+export const VIDEO_QUALITY_KEY = 'cb.video-quality';
+
+export const NATIVE_HLS_REASON =
+  'This browser plays the stream itself and picks the quality on its own — Safari and iPhone let a page choose nothing';
+export const NO_LADDER_REASON = 'This video has one quality: it is playing the file itself, not a ladder';
+
+/** The stored string back into a choice. Anything unreadable is `auto`, the safe default. */
+export function parseVideoQuality(raw: string | null | undefined): VideoQualityChoice {
+  if (raw === 'max') return 'max';
+  const height = Number(raw);
+  return Number.isInteger(height) && height > 0 ? height : 'auto';
+}
+
+export function serializeVideoQuality(choice: VideoQualityChoice): string {
+  return typeof choice === 'number' ? String(choice) : choice;
+}
+
+/** Guarded: storage throws in a private window, and is absent in a worker or on the server. */
+function store(): Storage | null {
+  try {
+    return globalThis.localStorage ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function readVideoQuality(): VideoQualityChoice {
+  try {
+    return parseVideoQuality(store()?.getItem(VIDEO_QUALITY_KEY));
+  } catch {
+    return 'auto';
+  }
+}
+
+export function writeVideoQuality(choice: VideoQualityChoice): void {
+  try {
+    store()?.setItem(VIDEO_QUALITY_KEY, serializeVideoQuality(choice));
+  } catch {
+    /* a full or refused store only means the choice lasts this film */
+  }
+}
+
+/** One rung, as a menu offers it. */
+export interface VideoQualityLevel {
+  height: number;
+  /** The original's own stream (binary-server's `o<height>` rung), not an encode. */
+  original: boolean;
+}
+
+/** The fields this module reads off an hls.js `Level` — declared here so hls.js stays a lazy chunk. */
+export interface HlsLevelLike {
+  height?: number;
+  uri?: string;
+  url?: readonly string[];
+}
+
+/** A rung playlist under an `o<height>/` directory is the original's stream copy. */
+const ORIGINAL_RUNG = /(^|\/)o\d+\/[^/]*$/;
+
+/** The ladder's rungs, tallest first, one per height. */
+export function rungLevels(levels: readonly HlsLevelLike[]): VideoQualityLevel[] {
+  const byHeight = new Map<number, VideoQualityLevel>();
+  for (const level of levels) {
+    const height = level.height ?? 0;
+    if (height <= 0) continue;
+    const uri = (level.uri ?? level.url?.[0] ?? '').split('?')[0] ?? '';
+    const original = ORIGINAL_RUNG.test(uri);
+    const had = byHeight.get(height);
+    byHeight.set(height, { height, original: original || (had?.original ?? false) });
+  }
+  return [...byHeight.values()].sort((a, b) => b.height - a.height);
+}
+
+/**
+ * The hls.js level a choice plays: `-1` (adaptive) for `auto` and `max`, else the rung of that
+ * height — or the tallest below it, or the shortest when every rung is taller.
+ */
+export function levelIndexFor(levels: readonly HlsLevelLike[], choice: VideoQualityChoice): number {
+  if (typeof choice !== 'number' || levels.length === 0) return -1;
+  let best = -1;
+  let shortest = -1;
+  levels.forEach((level, index) => {
+    const height = level.height ?? 0;
+    if (shortest === -1 || height < (levels[shortest]?.height ?? 0)) shortest = index;
+    if (height <= choice && (best === -1 || height > (levels[best]?.height ?? 0))) best = index;
+  });
+  return best === -1 ? shortest : best;
+}
+
+/** What a player surface shows, and the one way to change it. */
+export interface VideoQualityControl {
+  /** The ladder's rungs, tallest first. Empty when nothing can be chosen. */
+  levels: VideoQualityLevel[];
+  choice: VideoQualityChoice;
+  /** The rung on screen right now, when known — what "Auto" is showing. */
+  playingHeight: number | null;
+  /** Why nothing can be chosen here, or null when the menu works. */
+  unavailable: string | null;
+  /** Apply AND remember. */
+  select: (choice: VideoQualityChoice) => void;
+}
+
+/** A control that can choose nothing, with the reason. */
+export function unavailableQuality(reason: string): VideoQualityControl {
+  return { levels: [], choice: readVideoQuality(), playingHeight: null, unavailable: reason, select: writeVideoQuality };
+}
+
+/** The slice of an hls.js instance this module drives. */
+export interface HlsQualityEngine {
+  levels: readonly HlsLevelLike[] | undefined;
+  currentLevel: number;
+  nextLevel: number;
+  capLevelToPlayerSize: boolean;
+  on: (event: string, listener: (...args: never[]) => void) => void;
+  off: (event: string, listener: (...args: never[]) => void) => void;
+}
+
+/** hls.js's event names, as strings, so this module never imports the library. */
+const MANIFEST_PARSED = 'hlsManifestParsed';
+const LEVEL_SWITCHED = 'hlsLevelSwitched';
+
+/**
+ * Drive `hls` by the viewer's remembered choice, and report it.
+ *
+ * The cap is set before the first fragment (a `max` viewer never loads a capped first rung),
+ * and a fixed rung is applied when the manifest is parsed — the first moment the levels exist.
+ * A later choice switches with `nextLevel`: the next fragment plays the new rung, and what is
+ * already buffered still plays, so changing quality never stalls the picture.
+ *
+ * Returns the unbind. `engine.destroy()` drops the listeners too; the unbind is for a surface
+ * that keeps the engine.
+ */
+export function bindHlsQuality(
+  hls: HlsQualityEngine,
+  onChange: (control: VideoQualityControl) => void,
+): () => void {
+  let choice = readVideoQuality();
+  let playingHeight: number | null = null;
+  // Read through this: an engine that has not parsed a manifest (or a spec's fake) has none.
+  const levels = (): readonly HlsLevelLike[] => hls.levels ?? [];
+  hls.capLevelToPlayerSize = choice === 'auto';
+
+  const emit = (): void =>
+    onChange({
+      levels: rungLevels(levels()),
+      choice,
+      playingHeight,
+      unavailable: levels().length > 1 ? null : NO_LADDER_REASON,
+      select,
+    });
+
+  const select = (next: VideoQualityChoice): void => {
+    choice = next;
+    writeVideoQuality(next);
+    hls.capLevelToPlayerSize = next === 'auto';
+    hls.nextLevel = levelIndexFor(levels(), next);
+    emit();
+  };
+
+  const onParsed = (): void => {
+    const index = levelIndexFor(levels(), choice);
+    if (index !== -1) hls.currentLevel = index;
+    emit();
+  };
+  const onSwitched = (_event: unknown, data: { level?: number }): void => {
+    const level = typeof data?.level === 'number' ? levels()[data.level] : undefined;
+    playingHeight = level?.height ?? null;
+    emit();
+  };
+  hls.on(MANIFEST_PARSED, onParsed);
+  hls.on(LEVEL_SWITCHED, onSwitched as (...args: never[]) => void);
+  if (levels().length > 0) emit();
+  return () => {
+    hls.off(MANIFEST_PARSED, onParsed);
+    hls.off(LEVEL_SWITCHED, onSwitched as (...args: never[]) => void);
+  };
+}
+
+/** A rung's menu label: `2160p · Original`, `720p`. */
+export function rungLabel(level: VideoQualityLevel): string {
+  return level.original ? `${level.height}p · Original` : `${level.height}p`;
+}
+
+/**
+ * A quality control held OUTSIDE React state, for a surface whose menu lives in a slot it must
+ * not rebuild: Vidstack's layout remounts whenever its `slots` object changes (`VideoPlayer`'s
+ * memo says why), and the control changes on every rung switch. The slot reads this store with
+ * `useSyncExternalStore`, so a switch re-renders the menu and nothing else.
+ */
+export interface VideoQualityStore {
+  get: () => VideoQualityControl | null;
+  set: (control: VideoQualityControl | null) => void;
+  subscribe: (listener: () => void) => () => void;
+}
+
+export function createVideoQualityStore(): VideoQualityStore {
+  let current: VideoQualityControl | null = null;
+  const listeners = new Set<() => void>();
+  return {
+    get: () => current,
+    set: (control) => {
+      current = control;
+      for (const listener of listeners) listener();
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}