@torrent-tv/proxy 2.84.0 → 2.85.1

package/services/hls-session-manager.js

@@ -23,7 +23,6 @@ import { speedFromReadings } from "./encoder-readings.js";
 import { availableShareFrom } from "./available-share.js";
 import { contentionPenalty } from "./encode/contention.js";
 import { minimumBufferFrom } from "./supply-margin.js";
-import { earliestUrgentSecond, runsOf } from "./priority/PriorityMap.js";
 import { PriorityOrchestrator } from "./priority/PriorityOrchestrator.js";
 import { baseDrawFrom, costPerMegabyteFrom } from "./torrent-cost.js";
 import { medianOf, movedBeyondScatter, scatterOf } from "./learned-median.js";
@@ -89,6 +88,7 @@ import {
 // — did not move when the code did.
 export { ffmpegSeconds, onKeyframeGridFor, seekLandingOffsetFor, segmentCutTimesFrom };
 import { viewersOf } from "./viewer/Viewer.js";
+import { activeOutputFor } from "./viewer/active-output.js";
 import { earliestViewerSecondsOn, viewerSecondsOn, viewerSegmentsOn } from "./viewer/positions.js";
 import { Viewers } from "./viewer/Viewers.js";
 import { LiveOutputs } from "./output/LiveOutputs.js";
@@ -524,7 +524,6 @@ const BUDGET_DOWNLOAD_OK_FACTOR = 1.0;
 // instead. Which of the two, and whether a viewer's own pick may be moved at
 // all, is decided where the viewer's choice lives: in the browser, which
 // honours the request only in automatic mode.
-const LINK_REPORT_FRESH_MS = 30_000;
 // Usable share of the reported link (protocol overhead + measurement noise).
 const LINK_SAFETY = 0.8;
 // Deficit must persist this long before acting (absorbs one slow segment).
@@ -3058,54 +3057,6 @@ export class HlsSessionManager {
    *
    * @returns {Promise<void>}
    */
-  /**
-   * Record the latest viewer link report for a session (adaptive bitrate).
-   * Returns false for an unknown/disposed session.
-   *
-   * Kept per viewer. A browser that does not say who it is lands under one
-   * shared key, which is exactly the old behaviour for that browser and no
-   * worse: with one viewer the two are the same thing.
-   *
-   * @param {string} sessionId
-   * @param {{ linkMbps: number, bufferedAheadSec: number, consumerId?: string, positionSeconds?: number }} report
-   * @returns {boolean}
-   */
-  recordNetReport(sessionId, { linkMbps, bufferedAheadSec, consumerId, positionSeconds, playing, onScreen, inPictureInPicture }) {
-    const named = this.sessionsById.get(sessionId);
-    if (!named || named.state === "disposed") {
-      return false;
-    }
-    // A throughput that is not a positive finite number is not a measurement,
-    // and it reaches an encoder's `-maxrate` from here.
-    if (!Number.isFinite(linkMbps) || !(linkMbps > 0) || !Number.isFinite(bufferedAheadSec)) {
-      return false;
-    }
-    // The link carries the stream on screen, so the report belongs to the
-    // variant producing it — that is the encoder whose bitrate it can bound.
-    // Whose screen, is the reporter's own: with two viewers on two rungs, the
-    // report of one of them says nothing about the other's encoder.
-    const session = this.#activeVariant(named, typeof consumerId === "string" ? consumerId : "");
-    const now = Date.now();
-    this.viewers
-      .of(session, typeof consumerId === "string" && consumerId.length > 0 ? consumerId : "")
-      .report({ linkMbps, bufferedAheadSec, positionSeconds, playing, onScreen, inPictureInPicture }, now);
-    // A stale reading must not go on deciding for the viewers still here: a
-    // report describes a link at a moment, and a viewer who seeked since then
-    // is somewhere else entirely.
-    //
-    // Only the READING expires. Whether the person is still watching is a
-    // different question with its own answer — their connection — and a viewer
-    // who has simply stopped reporting is not thereby gone. Answering both from
-    // this one place is what stopped a soundtrack's encoder on 2026-09-05.
-    for (const viewer of viewersOf(session).values()) {
-      const report = viewer.netReport;
-      if (report !== null && now - report.at > LINK_REPORT_FRESH_MS) {
-        viewer.netReport = null;
-      }
-    }
-    return true;
-  }
-
   /**
    * Record where one viewer of this session is, and answer with the furthest
    * any of them has reached.
@@ -3153,8 +3104,8 @@ export class HlsSessionManager {
   #worstNetReport(session, now) {
     let worst = null;
     for (const viewer of viewersOf(session).values()) {
-      const report = viewer.netReport;
-      if (report === null || now - report.at > LINK_REPORT_FRESH_MS) {
+      const report = viewer.linkReading(now);
+      if (report === null) {
         continue;
       }
       if (worst === null) {
@@ -3204,7 +3155,7 @@ export class HlsSessionManager {
     // run and its own position, and that is exactly the pair this report exists
     // to tell apart. Answering an audio report from the picture's records would
     // state, confidently, something about the wrong stream.
-    const onScreen = this.#activeVariant(named);
+    const onScreen = activeOutputFor({ base: named, sessions: this.sessionsById, viewers: this.viewers });
     const session = track === "audio"
       ? ([...this.liveOutputs.familyOf(onScreen)].find((member) => member.audioOnly === true) ?? onScreen)
       : onScreen;
@@ -3293,7 +3244,7 @@ export class HlsSessionManager {
    */
   async #checkLinkBudget(session, now) {
     const report = this.#worstNetReport(session, now);
-    if (!report || now - report.at > LINK_REPORT_FRESH_MS) {
+    if (!report) {
       session.linkSlowSince = 0; // no fresh data — old clients / stopped reporter
       return false;
     }
@@ -4684,7 +4635,7 @@ export class HlsSessionManager {
       }
       return false;
     }
-    const playing = this.liveOutputs.variantHeightOf(this.#activeVariant(base));
+    const playing = this.liveOutputs.variantHeightOf(activeOutputFor({ base, sessions: this.sessionsById, viewers: this.viewers }));
     if (height === playing) {
       return false;
     }
@@ -4783,7 +4734,7 @@ export class HlsSessionManager {
       return false;
     }
     const report = this.#worstNetReport(session, now);
-    if (!report || now - report.at > LINK_REPORT_FRESH_MS) {
+    if (!report) {
       // Nothing fresh measures the link, so it has no opinion either way — the
       // same silence that stops #checkLinkBudget from acting.
       return true;
@@ -4811,7 +4762,7 @@ export class HlsSessionManager {
     // The SLOWEST link among the viewers: a step up has to be carried by all of
     // them, not by whichever reported last.
     const report = this.#worstNetReport(session, now);
-    if (!report || now - report.at > LINK_REPORT_FRESH_MS) {
+    if (!report) {
       return true;
     }
     return report.linkMbps * LINK_SAFETY >= wantedMbps;
@@ -7185,7 +7136,7 @@ export class HlsSessionManager {
     if (!ask) {
       return 0;
     }
-    if (ask.height === this.liveOutputs.variantHeightOf(this.#activeVariant(base))) {
+    if (ask.height === this.liveOutputs.variantHeightOf(activeOutputFor({ base, sessions: this.sessionsById, viewers: this.viewers }))) {
       base.qualityAsk = null; // the viewer is there; nothing left to ask for
       return 0;
     }
@@ -7200,45 +7151,6 @@ export class HlsSessionManager {
     return ask.height;
   }
 
-  /**
-   * The variant of a session that the viewer is watching right now.
-   *
-   * Every request that names the base session — seek, progress, link report,
-   * release — means the stream the viewer has on screen, and after a quality
-   * change that is another session. The browser is not told about the swap: it
-   * holds one session id for the whole file, which is what keeps the switch out
-   * of the state machine on that side.
-   *
-   * Kept per viewer, because one picture is shared by everyone watching it and
-   * a quality step is a session of its own: with one answer for the session, a
-   * step taken by one viewer would move the other one's stream, and that
-   * viewer's next seek would be forwarded to a rung they never chose. The
-   * session's own field remains the answer for a viewer who cannot name
-   * themselves, and the last one anybody moved to.
-   *
-   * @param {HlsSession} base
-   * @param {string} [consumerId]
-   * @returns {HlsSession}
-   */
-  #activeVariant(base, consumerId = "") {
-    const named = consumerId ? base.viewers?.get(consumerId)?.activeVariantId ?? null : null;
-    const activeId = named ?? base.activeVariantId;
-    if (!activeId || activeId === base.id) {
-      return base;
-    }
-    const active = this.sessionsById.get(activeId);
-    if (!active || active.state === "disposed") {
-      if (named) {
-        this.viewers.of(base, consumerId).activeVariantId = null;
-      }
-      if (base.activeVariantId === activeId) {
-        base.activeVariantId = base.id;
-      }
-      return base;
-    }
-    return active;
-  }
-
   /**
    * Every session of this family that a live viewer has on screen.
    *
@@ -7263,7 +7175,7 @@ export class HlsSessionManager {
       onScreen.add(viewer.activeVariantId);
     }
     if (onScreen.size === 0) {
-      onScreen.add(this.#activeVariant(base).id);
+      onScreen.add(activeOutputFor({ base, sessions: this.sessionsById, viewers: this.viewers }).id);
     }
     return onScreen;
   }
@@ -7296,7 +7208,7 @@ export class HlsSessionManager {
     if (Number.isInteger(wantedIndex) && wantedIndex >= 0) {
       return this.#segmentStartTime(base, wantedIndex);
     }
-    return viewerSecondsOn(this.#activeVariant(base, consumerId));
+    return viewerSecondsOn(activeOutputFor({ base, consumerId, sessions: this.sessionsById, viewers: this.viewers }));
   }
 
   /**
@@ -7377,7 +7289,7 @@ export class HlsSessionManager {
    * earliest. Reading it off a viewer put a person inside the encoding layer,
    * and then every question about WHICH person had to be answered a second time
    * here: the earliest of two, the one on this rung, the one who has not
-   * reported yet. `earliestUrgentSecond` answers it once, for everything.
+   * reported yet.
    *
    * The apparatus this replaced is worth naming so it is not rebuilt: three
    * position sources ranked by priority, a function saying which had answered,
@@ -7901,7 +7813,7 @@ export class HlsSessionManager {
     // buys it an encoder, and both halves are said here: a warmed rung is one
     // this person is watching for as long as the warm-up lasts, which is why
     // two encoders run through it.
-    if (variant.id !== this.#activeVariant(base, consumerId).id) {
+    if (variant.id !== activeOutputFor({ base, consumerId, sessions: this.sessionsById, viewers: this.viewers }).id) {
       this.viewers.of(variant, consumerId).moveTo(this.#segmentStartTime(base, index));
       this.planEncodersSoon();
     }
@@ -7926,7 +7838,7 @@ export class HlsSessionManager {
    * @returns {void}
    */
   #noteVariantActive(base, variant, wantedIndex = -1, consumerId = "") {
-    const previous = this.#activeVariant(base, consumerId);
+    const previous = activeOutputFor({ base, consumerId, sessions: this.sessionsById, viewers: this.viewers });
     if (previous.id === variant.id) {
       // The rung on screen asking for more of itself, which it does every few
       // seconds. Nothing is being decided here — and deciding anything was the
@@ -9449,7 +9361,7 @@ export class HlsSessionManager {
     // change is another session. Touching the named one as well is what keeps
     // the family alive: only the ACTIVE variant gets segment requests, so
     // without this the base session would idle out from under its own variants.
-    const session = this.#activeVariant(named, consumerId);
+    const session = activeOutputFor({ base: named, consumerId, sessions: this.sessionsById, viewers: this.viewers });
     session.lastAccessedAt = Date.now();
     const warmupTotalSeconds = this.startupWaitMs / 1000;
     const warmupElapsedSeconds = Math.max(0, (Date.now() - session.startedAt) / 1000);

package/services/priority/PriorityOrchestrator.js

@@ -223,13 +223,17 @@ export class PriorityOrchestrator {
           }
           const stated = {
             atSeconds: viewer.positionSeconds(now) ?? 0,
-            // CONSUMING, not merely playing. A page that is not on screen has
-            // its timers throttled and asks for nothing, which is exactly what
-            // a viewer holding a full cushion looks like; the two are told
-            // apart on the page and folded into one question here.
-            playing: typeof viewer.consumesFilm === "function"
-              ? viewer.consumesFilm()
-              : viewer.playing !== false
+            // WATCHING OR WAITING, not merely playing. Three states reach this
+            // one question: a viewer whose picture is advancing, a viewer
+            // blocked on material we owe them, and a viewer who stopped it
+            // themselves. The first two want the film in front of them NOW and
+            // share the upper band; only the third can wait. A page that is not
+            // on screen has its timers throttled and asks for nothing, which is
+            // indistinguishable from a full cushion, so it is not consuming
+            // either — told apart on the page, folded into one question here.
+            playing: typeof viewer.wantsFilmNow === "function"
+              ? viewer.wantsFilmNow()
+              : viewer.playing === true || viewer.waiting === true
           };
           held.viewers.push(stated);
           if (this.#watchedBy(session, viewer)) {

package/services/viewer/Viewer.js

@@ -40,6 +40,15 @@
  * question, and it reads a union of viewers rather than any one of them.
  */
 
+/**
+ * How long a link measurement describes the link it was taken on.
+ *
+ * A reading older than this says nothing about now: the viewer may have seeked,
+ * changed network, or stopped. Thirty seconds is three of the page's own
+ * reporting intervals, so a live viewer always has a fresh one.
+ */
+export const LINK_READING_FRESH_MS = 30_000;
+
 export class Viewer {
   /**
    * @param {string} id - The consumer id the browser sends with every request
@@ -149,13 +158,35 @@ export class Viewer {
      * @type {Set<string>}
      */
     this.wantsCuesFor = new Set();
-    // Whether the picture is moving. A viewer who has stopped it consumes
-    // nothing, so nothing in front of them ever becomes due — they have no
-    // deadline at all, and the work goes to whoever is watching. The page knows
-    // this exactly and says it outright; inferring it from a position that has
-    // not moved takes two reports and lies whenever a browser holding a full
-    // cushion goes quiet between segments, which it does.
-    this.playing = true;
+    // WHETHER THE PICTURE IS MOVING, and separately WHETHER THIS VIEWER IS
+    // BLOCKED ON US. Two booleans, because there are three states and one
+    // boolean cannot hold them:
+    //
+    //   playing        the picture advances, a second of film per second;
+    //   waiting        it does not advance because we have not delivered;
+    //   neither        the viewer stopped it themselves.
+    //
+    // Collapsed into one, the middle state read as the third: a viewer frozen
+    // for want of a segment counted as somebody who had chosen to stop, so
+    // nothing in front of them fell due and the work went to whoever was
+    // playing. That is backwards — a viewer waiting on us is the most urgent
+    // there is. The page tells the two apart exactly (its element says whether
+    // the picture advances, and the component owns the viewer's own pause) and
+    // states both.
+    //
+    // `playing` STARTS FALSE, and that is the whole of the fault of
+    // 2026-09-14. It used to start true, and the position is carried forward by
+    // the clock at that rate, so a viewer who had never said anything walked
+    // 146 seconds into a film they had not begun: the tab was hidden, the page
+    // deliberately held start-up until it was shown, and this end assumed the
+    // film was running the entire time. A statement about somebody else's
+    // machine is theirs to make. Until they make it the rate is zero.
+    //
+    // `waiting` STARTS TRUE, which is what a viewer arriving is: they have
+    // asked for a film and hold none of it. So their work is made first from
+    // the instant they arrive, without the position ever being invented.
+    this.playing = false;
+    this.waiting = true;
     // Whether the page carrying this viewer is ON SCREEN, and whether the
     // picture has been pulled out of it.
     //
@@ -171,7 +202,9 @@ export class Viewer {
     // before it could say otherwise.
     this.onScreen = true;
     this.inPictureInPicture = false;
-    // Seconds of film held ahead of the picture, as the page last said.
+    // Seconds of film held ahead of the picture, as the page last said. It is
+    // measured at the moment the position beside it was, which is what makes it
+    // the bound on carrying that position forward — see `positionSeconds`.
     this.bufferedSeconds = null;
   }
 
@@ -192,6 +225,13 @@ export class Viewer {
       return;
     }
     this.position = { seconds, at: now };
+    // WHAT THEY HELD AT THE PLACE THEY LEFT SAYS NOTHING ABOUT THE PLACE THEY
+    // ARRIVED AT. A seek empties the buffer by construction — the player
+    // discards what it holds and fetches from the new position — so carrying
+    // the old cushion over would license the position to run forward again from
+    // material that no longer exists. Zero is the truthful floor until they say
+    // otherwise, and a viewer who has just seeked says so within a tick.
+    this.bufferedSeconds = 0;
     this.lastSeenAt = now;
   }
 
@@ -205,13 +245,18 @@ export class Viewer {
    * places, two of them on a session shared with other people.
    *
    * @param {object} report
-   * @param {number} report.linkMbps
+   * @param {number} [report.linkMbps] - What their link last measured. Absent
+   *   until something measurable has crossed it, and then the rest of the
+   *   report still stands: this is a statement about a viewer, not about a link.
    * @param {number} report.bufferedAheadSec
    * @param {number | null} [report.positionSeconds] - Null from a page that
    *   does not say; then the position stands as it was.
-   * @param {boolean} [report.playing] - Absent from a page that does not say;
-   *   then the viewer counts as playing, which is what every page meant before
-   *   it could say otherwise.
+   * @param {boolean} [report.playing] - Whether the picture is advancing.
+   *   Absent means it was not stated, and nothing may be assumed about somebody
+   *   else's machine: the rate is then zero.
+   * @param {boolean} [report.waiting] - Whether this viewer is blocked on
+   *   material we owe them. Absent from a page one release behind; then it is
+   *   derived from the two facts that page does state.
    * @param {boolean} [report.onScreen] - Whether the page is visible, or the
    *   picture is in picture-in-picture. Absent means on screen.
    * @param {boolean} [report.inPictureInPicture] - Whether the picture has been
@@ -224,47 +269,49 @@ export class Viewer {
       bufferedAheadSec,
       positionSeconds = null,
       playing,
+      waiting,
       onScreen,
       inPictureInPicture
     },
     now = Date.now()
   ) {
-    this.netReport = {
-      linkMbps,
-      bufferedAheadSec,
-      positionSeconds:
-        Number.isFinite(positionSeconds) && positionSeconds >= 0 ? positionSeconds : null,
-      at: now
-    };
-    this.bufferedSeconds = bufferedAheadSec;
-    this.playing = playing === undefined ? true : Boolean(playing);
-    this.inPictureInPicture = inPictureInPicture === undefined ? false : Boolean(inPictureInPicture);
-    this.onScreen = onScreen === undefined ? true : Boolean(onScreen);
+    const held = Number.isFinite(bufferedAheadSec) && bufferedAheadSec > 0 ? bufferedAheadSec : 0;
+    // A LINK FIGURE IS ONE FIELD OF THIS REPORT AND NOT ITS TICKET. A page that
+    // has transferred nothing measurable has nothing to say about its link and
+    // everything to say about its viewer, and that is the cold open exactly —
+    // the moment the position matters most. Held as a precondition, in three
+    // places at once, it silenced every statement of the session of 2026-09-14.
+    if (Number.isFinite(linkMbps) && linkMbps > 0) {
+      this.netReport = {
+        linkMbps,
+        bufferedAheadSec: held,
+        positionSeconds:
+          Number.isFinite(positionSeconds) && positionSeconds >= 0 ? positionSeconds : null,
+        at: now
+      };
+    }
+    // The position first, then the cushion: `moveTo` clears what was held at
+    // wherever they were before, and this report's own figure is measured at
+    // the position this report states.
     if (Number.isFinite(positionSeconds) && positionSeconds >= 0) {
       this.moveTo(/** @type {number} */ (positionSeconds), now);
     }
+    this.bufferedSeconds = held;
+    this.playing = playing === true;
+    // A page that states `playing` and not `waiting` is one release behind this
+    // proxy, which is the ordinary state of a rolling pool — the proxy ships
+    // first by rule. It says `false` for both a viewer who stopped the picture
+    // and a viewer starved of material, so the two are told apart by the one
+    // quantity it does state: a stopped viewer holding film chose to stop, a
+    // stopped viewer holding nothing is waiting on us. It errs toward making
+    // material, which is the direction that costs an encoder rather than a
+    // viewer.
+    this.waiting = waiting === undefined ? this.playing === false && held === 0 : waiting === true;
+    this.inPictureInPicture = inPictureInPicture === undefined ? false : Boolean(inPictureInPicture);
+    this.onScreen = onScreen === undefined ? true : Boolean(onScreen);
     this.seen(now);
   }
 
-  /**
-   * When this viewer runs out of what they hold, in milliseconds.
-   *
-   * Film is consumed at one second per second while the picture moves, so the
-   * moment they run dry is now plus what they hold. Stopped, they consume
-   * nothing and there is no such moment — which is why a pause needs no rule of
-   * its own anywhere: it falls out of this as an absent deadline.
-   *
-   * @param {number} [now]
-   * @returns {number | null}
-   */
-  deadlineAt(now = Date.now()) {
-    if (!this.playing) {
-      return null;
-    }
-    const held = Number.isFinite(this.bufferedSeconds) ? Math.max(0, this.bufferedSeconds) : 0;
-    return now + held * 1000;
-  }
-
   /**
    * Whether this viewer is here.
    *
@@ -284,20 +331,53 @@ export class Viewer {
    * @returns {boolean}
    */
   /**
-   * Whether this viewer is CONSUMING film.
+   * What this viewer's link was last measured to carry, or null when nothing
+   * recent measures it.
+   *
+   * HOW LONG A READING DESCRIBES A LINK is a fact about the reading, so it is
+   * answered here and nowhere else. It used to be a constant in the session
+   * manager, consulted in four places — once where a reading is chosen, and
+   * three more times over a figure that had already passed that very filter,
+   * which made those three conditions unreachable.
+   *
+   * A viewer who has stopped reporting is NOT thereby gone: only the reading
+   * expires. Answering both from one place is what stopped a soundtrack's
+   * encoder on 2026-09-05.
+   *
+   * @param {number} [now]
+   * @returns {{ linkMbps: number, bufferedAheadSec: number, positionSeconds: number | null, at: number } | null}
+   */
+  linkReading(now = Date.now()) {
+    const reading = this.netReport;
+    if (reading === null || now - reading.at > LINK_READING_FRESH_MS) {
+      return null;
+    }
+    return reading;
+  }
+
+  /**
+   * Whether this viewer wants film NOW — either watching it or waiting for it.
+   *
+   * The one predicate every reading about urgency asks, and it is a union of
+   * two states rather than the negation of a pause:
    *
-   * Two ways of not consuming, and neither is absence: the picture is stopped,
-   * or the page is not on screen. Both mean nothing in front of them ever falls
-   * due, so the work goes to whoever is watching — and both leave them a place
-   * in the priority map, because they are still there and will want it again.
+   *   playing        consuming, and will run dry when their cushion does;
+   *   waiting        consuming nothing only because we have delivered nothing;
+   *   neither        they stopped the picture themselves.
    *
+   * A viewer who has stopped it keeps their place in the priority map — they
+   * are still there and will want the film in front of them again — but nothing
+   * of theirs falls due, so the work goes to whoever is watching or waiting.
+   *
+   * A page that is not on screen is not consuming: its timers are throttled and
+   * it asks for nothing, which is indistinguishable from a full cushion.
    * Picture-in-picture is watching with the tab hidden, and the page folds that
-   * into `onScreen` before it says it, so it needs no case of its own here.
+   * into `onScreen` before saying it, so it needs no case of its own here.
    *
    * @returns {boolean}
    */
-  consumesFilm() {
-    return this.playing !== false && this.onScreen !== false;
+  wantsFilmNow() {
+    return (this.playing === true || this.waiting === true) && this.onScreen !== false;
   }
 
   isPresent() {
@@ -323,7 +403,29 @@ export class Viewer {
    * since. A viewer whose picture is stopped covers nothing and stays where
    * they are, which is the same formula with the rate at zero.
    *
-   *   position(now) = stated + rate * (now - statedAt),   rate = playing ? 1 : 0
+   *   position(now) = stated + rate * min(now - statedAt, held),
+   *                                              rate = playing ? 1 : 0
+   *
+   * **THE SECOND TERM IS BOUNDED BY WHAT THEY HELD**, and the bound is stated
+   * by the viewer rather than chosen here: nobody can play past the end of what
+   * they have. A viewer who said "I hold thirty seconds" and has said nothing
+   * for two minutes has played at most thirty of those seconds; the rest of the
+   * silence is a viewer who ran dry, or one we are no longer hearing from, and
+   * in both cases they are not where the clock alone would put them.
+   *
+   * Unbounded, it walks a viewer off the end of a film they never started. On
+   * 2026-09-14 the tab was hidden for 145 seconds while the page deliberately
+   * held start-up until it was shown, the rate was assumed to be one, and this
+   * end placed the viewer at 145.979 s — the exact `-ss` the soundtrack's
+   * encoder was given, while the browser was asking for segment #0 and getting
+   * 503 for sixty seconds. Their cushion was 0.0 s throughout, so this bound
+   * alone would have held them at zero whatever the rate said.
+   *
+   * The bound binds only where the clock has outrun the cushion — a report lost,
+   * or a viewer starving — and there it under-states the position. That is the
+   * safe direction and deliberately so: under-stating makes material a viewer
+   * has already passed, which costs an encoder; over-stating skips material
+   * they are about to need, which costs the viewer the picture.
    *
    * Held as a stored number instead, it was a staircase: flat for the ten
    * seconds between reports and then a jump, so everything derived from it —
@@ -342,9 +444,10 @@ export class Viewer {
     if (this.position === null) {
       return null;
     }
-    const rate = this.playing ? 1 : 0;
+    const rate = this.playing === true ? 1 : 0;
     const elapsedSec = Math.max(0, (now - this.position.at) / 1000);
-    return this.position.seconds + rate * elapsedSec;
+    const held = Number.isFinite(this.bufferedSeconds) ? Math.max(0, this.bufferedSeconds) : 0;
+    return this.position.seconds + rate * Math.min(elapsedSec, held);
   }
 }
 

package/services/viewer/active-output.js

@@ -0,0 +1,54 @@
+/**
+ * @file Which output a viewer has on screen.
+ *
+ * Every request that names the picture's session — a seek, a progress poll, a
+ * link report, a release — means the stream the viewer is actually watching,
+ * and after a quality change that is another session. The browser is never told
+ * about the swap: it holds one session id for the whole file, which is what
+ * keeps the switch out of the state machine on that side.
+ *
+ * KEPT PER VIEWER, because one picture is shared by everyone watching it and a
+ * quality step is a session of its own. With one answer for the session, a step
+ * taken by one viewer moved the other one's stream, and that viewer's next seek
+ * was forwarded to a rung they never chose. The session's own field remains the
+ * answer for a viewer who cannot name themselves, and is the last rung anybody
+ * moved to.
+ *
+ * It is handed the picture, a name, the live sessions and the registry of
+ * viewers, and it HOLDS none of them — but it is not read-only: finding a rung
+ * that has been disposed, it puts both remembers back on the picture, or the
+ * next question gets the same dead answer. It lives in the VIEWER layer because
+ * the question is about a person — which of several equally live outputs is
+ * theirs — and it knows nothing of encoders, files or heights.
+ */
+
+/**
+ * @param {object} params
+ * @param {object} params.base - The picture's own session.
+ * @param {string} [params.consumerId] - Whose screen. Empty asks about the
+ *   session's own last answer, which is what an unnamed browser gets.
+ * @param {{ get: (id: string) => object | undefined }} params.sessions - Every live session, by id.
+ * @param {{ of: (session: object, consumerId: string) => { activeVariantId: string | null } }} params.viewers
+ * @returns {object} A live session, never a disposed one.
+ */
+export function activeOutputFor({ base, consumerId = "", sessions, viewers }) {
+  const named = consumerId ? base.viewers?.get(consumerId)?.activeVariantId ?? null : null;
+  const activeId = named ?? base.activeVariantId;
+  if (!activeId || activeId === base.id) {
+    return base;
+  }
+  const active = sessions.get(activeId);
+  if (!active || active.state === "disposed") {
+    // The rung is gone, so the viewer is watching the picture again. Said in
+    // both places that remember it, or the next question gets the same dead
+    // answer.
+    if (named) {
+      viewers.of(base, consumerId).activeVariantId = null;
+    }
+    if (base.activeVariantId === activeId) {
+      base.activeVariantId = base.id;
+    }
+    return base;
+  }
+  return active;
+}

package/services/viewer/report-intake.js

@@ -0,0 +1,44 @@
+/**
+ * @file A viewer's statement about itself, taken in.
+ *
+ * The VIEWER layer's own entry point, and the whole of what happens when a page
+ * says where it is: the output the reporter has on screen is resolved, the
+ * statement reaches the person it is about, and readings that have gone stale
+ * stop deciding for the people still here.
+ *
+ * It lived in the session manager, which is a description of an OUTPUT, and the
+ * two questions were tangled there: whether this is a measurement of a LINK,
+ * and whether this is a statement by a VIEWER. Required to be both, a page that
+ * had measured nothing could say nothing — see `Viewer.report`.
+ *
+ * Given the sessions and the registry as plain values, so nothing here knows
+ * how a session is found, what a variant is, or that there is an encoder.
+ */
+
+import { activeOutputFor } from "./active-output.js";
+
+/**
+ * Take one report from one viewer.
+ *
+ * @param {object} params
+ * @param {{ get: (id: string) => object | undefined }} params.sessions - Every live session, by id.
+ * @param {{ of: (session: object, consumerId: string) => import("./Viewer.js").Viewer }} params.viewers
+ * @param {string} params.sessionId - The session the page addresses, which is
+ *   always the picture's: the browser is not told which rung it is on.
+ * @param {object} params.report - What they said about themselves.
+ * @param {number} [params.now]
+ * @returns {boolean} False when no such session is live, which is the page
+ *   reporting into one that has been disposed.
+ */
+export function recordViewerReport({ sessions, viewers, sessionId, report, now = Date.now() }) {
+  const named = sessions.get(sessionId);
+  if (!named || named.state === "disposed") {
+    return false;
+  }
+  const consumerId = typeof report?.consumerId === "string" ? report.consumerId : "";
+  // The stream on screen is the reporter's own: with two viewers on two rungs,
+  // one report says nothing about the other's encoder.
+  const session = activeOutputFor({ base: named, consumerId, sessions, viewers });
+  viewers.of(session, consumerId).report(report, now);
+  return true;
+}