@torrent-tv/proxy 2.90.0 → 2.92.0

package/services/transport/tunnel-client.js

@@ -9,6 +9,13 @@
  *
  * The tunnel reconnects automatically with a fixed back-off after any
  * unexpected close.
+ *
+ * A server being replaced by a release asks its proxies to move
+ * (`server-moving`). The proxy then opens a second connection, which reaches the
+ * new server, and keeps the old one until the old server closes it. While both
+ * are open each reply goes over the connection its request arrived on: a
+ * browser that signalled through the old server is answered there, because the
+ * new one does not know that browser.
  */
 
 import { WebSocket } from "ws";
@@ -27,6 +34,11 @@ import { WebSocket } from "ws";
  *   Auth token sent as the `x-proxy-id` / `x-proxy-token` headers during the WS handshake.
  * @property {number}  proxyPort
  *   Local port the proxy's Fastify server is listening on.
+ * @property {string}  [name]
+ *   Display name, sent with every connection so that whichever server instance
+ *   the connection reaches knows it without a separate registration request.
+ * @property {string}  [baseUrl]
+ *   Advertised direct URL, sent with every connection for the same reason.
  * @property {(sessionId: string, signal: WebRtcSignal) => void} [onSignal]
  *   Called when the server forwards a WebRTC signal (SDP offer or ICE candidate)
  *   from a browser to this proxy.  `sessionId` scopes the signal to a P2P session.
@@ -120,6 +132,8 @@ export function createTunnelClient({
   proxyId,
   token,
   proxyPort,
+  name = "",
+  baseUrl = "",
   onSignal,
   onConnect,
   onHealthRequest,
@@ -141,6 +155,21 @@ export function createTunnelClient({
    */
   let renewalTimer = null;
   let stopped = false;
+  /**
+   * Every connection that is open now. Usually one; two while a renewal or a
+   * move to a new server is under way.
+   *
+   * @type {Set<WebSocket>}
+   */
+  const openConnections = new Set();
+  /**
+   * The connection each browser session signalled through. The proxy's answer
+   * and its ICE candidates go back the same way, because only the server
+   * instance that holds that browser's signalling socket can deliver them.
+   *
+   * @type {Map<string, WebSocket>}
+   */
+  const signalRoutes = new Map();
 
   /**
    * Write a message to the log sink if one was provided.
@@ -174,6 +203,14 @@ export function createTunnelClient({
       headers: {
         "x-proxy-id": proxyId,
         "x-proxy-token": token,
+        // Who this proxy is, on the connection itself: a separate registration
+        // request may reach a different server instance during a release.
+        "x-proxy-name": encodeURIComponent(name),
+        "x-proxy-base-url": baseUrl,
+        // This proxy answers on the connection a request arrived on and opens a
+        // new connection when the server says `server-moving`, so the server
+        // may wait for it to arrive at the new instance.
+        "x-proxy-follows-moves": "1",
         "user-agent": "torrent-tv-proxy/1.0"
       }
     });
@@ -182,6 +219,7 @@ export function createTunnelClient({
     socket = connection;
 
     connection.addEventListener("open", () => {
+      openConnections.add(connection);
       log("Tunnel connected.");
       // Start keepalive pings to prevent Cloudflare's idle WebSocket timeout.
       keepaliveTimer = setInterval(() => {
@@ -213,8 +251,19 @@ export function createTunnelClient({
         return;
       }
 
+      // The server is being replaced. A new connection reaches its successor;
+      // this one stays open until the old server has finished with the
+      // browsers it is still signalling for, and then it closes it.
+      if (message.type === "server-moving") {
+        if (connection === socket && !stopped) {
+          log("Tunnel: the server is being replaced; connecting to its successor before this connection closes.");
+          connect();
+        }
+        return;
+      }
+
       if (message.type === "request") {
-        void handleRelayRequest(message).catch((error) => {
+        void handleRelayRequest(message, connection).catch((error) => {
           log(`Tunnel relay error: ${error?.message ?? error}`);
         });
         return;
@@ -223,6 +272,7 @@ export function createTunnelClient({
       // WebRTC signalling: server forwards a signal from a browser session.
       if (message.type === "signal") {
         if (typeof message.sessionId === "string" && message.signal && typeof onSignal === "function") {
+          signalRoutes.set(message.sessionId, connection);
           onSignal(message.sessionId, message.signal);
         }
         return;
@@ -244,7 +294,7 @@ export function createTunnelClient({
           // silent-ok: an unanswerable question is answered "no", which is what
           // a null offer means to the caller.
         }
-        send({ type: "can-serve-response", requestId: message.requestId, offer });
+        send({ type: "can-serve-response", requestId: message.requestId, offer }, connection);
         return;
       }
 
@@ -266,7 +316,7 @@ export function createTunnelClient({
             requestId: message.requestId,
             metrics: answer?.metrics ?? answer ?? {},
             holds: Array.isArray(answer?.holds) ? answer.holds : []
-          });
+          }, connection);
         })();
         return;
       }
@@ -277,6 +327,12 @@ export function createTunnelClient({
         clearInterval(keepaliveTimer);
         keepaliveTimer = null;
       }
+      openConnections.delete(connection);
+      for (const [sessionId, route] of signalRoutes) {
+        if (route === connection) {
+          signalRoutes.delete(sessionId);
+        }
+      }
       // A connection this one replaced. The server closes it as soon as the
       // replacement registers, which is the whole point of renewing early —
       // there is nothing to report and nothing to reconnect, because the tunnel
@@ -285,15 +341,24 @@ export function createTunnelClient({
         log(`Tunnel handed over (code=${event.code}); the replacement is already carrying it.`);
         return;
       }
+      // The newest connection ended while an older one is still open: a move
+      // whose new connection did not get through. The older one goes on
+      // carrying the tunnel until its server closes it, and the move is tried
+      // again meanwhile.
+      const survivor = [...openConnections].at(-1);
+      if (survivor) {
+        socket = survivor;
+        log(`Tunnel connection ended (code=${event.code}) while the previous one is still open; it carries the tunnel, and a new connection is tried in ${RECONNECT_DELAY_MS}ms.`);
+        scheduleReconnect();
+        return;
+      }
       log(`Tunnel disconnected (code=${event.code}). Reconnecting in ${RECONNECT_DELAY_MS}ms...`);
       socket = null;
       if (renewalTimer !== null) {
         clearTimeout(renewalTimer);
         renewalTimer = null;
       }
-      if (!stopped) {
-        reconnectTimer = setTimeout(connect, RECONNECT_DELAY_MS);
-      }
+      scheduleReconnect();
     });
 
     connection.addEventListener("error", (event) => {
@@ -301,14 +366,31 @@ export function createTunnelClient({
     });
   }
 
+  /**
+   * Connect again after a fixed back-off, unless a reconnect is already due.
+   *
+   * @returns {void}
+   */
+  function scheduleReconnect() {
+    if (stopped || reconnectTimer !== null) {
+      return;
+    }
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      connect();
+    }, RECONNECT_DELAY_MS);
+  }
+
   /**
    * Fetch a resource from the local Fastify server and stream the response
    * back to the registry server chunk-by-chunk over the WebSocket.
    *
    * @param {TunnelRelayRequest} relayRequest
+   * @param {WebSocket} over - The connection the request arrived on, which
+   *   the response goes back over.
    * @returns {Promise<void>}
    */
-  async function handleRelayRequest(relayRequest) {
+  async function handleRelayRequest(relayRequest, over) {
     const { requestId, method, path, query, headers: forwardedHeaders, body } = relayRequest;
     const targetUrl = `http://127.0.0.1:${proxyPort}${path}` + (query ? `?${query}` : "");
     const requestHeaders = { ...(forwardedHeaders ?? {}), host: `127.0.0.1:${proxyPort}` };
@@ -322,7 +404,7 @@ export function createTunnelClient({
         redirect: "manual"
       });
     } catch (fetchError) {
-      sendError(requestId, fetchError?.message ?? String(fetchError));
+      sendError(requestId, fetchError?.message ?? String(fetchError), over);
       return;
     }
 
@@ -332,10 +414,10 @@ export function createTunnelClient({
       responseHeaders[headerName] = headerValue;
     }
 
-    send({ type: "response-start", requestId, status: response.status, headers: responseHeaders });
+    send({ type: "response-start", requestId, status: response.status, headers: responseHeaders }, over);
 
     if (!response.body) {
-      send({ type: "response-chunk", requestId, data: "", done: true });
+      send({ type: "response-chunk", requestId, data: "", done: true }, over);
       return;
     }
 
@@ -344,7 +426,7 @@ export function createTunnelClient({
       while (true) {
         const { done, value } = await reader.read();
         if (done) {
-          send({ type: "response-chunk", requestId, data: "", done: true });
+          send({ type: "response-chunk", requestId, data: "", done: true }, over);
           break;
         }
         send({
@@ -352,10 +434,10 @@ export function createTunnelClient({
           requestId,
           data: Buffer.from(value).toString("base64"),
           done: false
-        });
+        }, over);
       }
     } catch {
-      send({ type: "response-chunk", requestId, data: "", done: true });
+      send({ type: "response-chunk", requestId, data: "", done: true }, over);
     }
   }
 
@@ -363,13 +445,15 @@ export function createTunnelClient({
    * Serialise a message to JSON and send it through the WebSocket if open.
    *
    * @param {object} message
+   * @param {WebSocket | null} [over]
    * @returns {void}
    */
   function send(message, over = null) {
-    // Everything the proxy has to say goes over the LIVE connection. `over` is
-    // for the one thing that belongs to a particular socket rather than to the
-    // tunnel — its own keepalive — which must not be sent over a replacement
-    // that has already taken over.
+    // What the proxy says on its own goes over the LIVE connection. `over` is
+    // for what belongs to a particular socket rather than to the tunnel: its
+    // own keepalive, and every reply, which goes back over the connection its
+    // request arrived on — during a move that is the old server, the only one
+    // still waiting for it.
     const target = over ?? socket;
     if (target && target.readyState === WebSocket.OPEN) {
       target.send(JSON.stringify(message));
@@ -381,10 +465,11 @@ export function createTunnelClient({
    *
    * @param {string} requestId
    * @param {string} errorMessage
+   * @param {WebSocket} over - The connection the request arrived on.
    * @returns {void}
    */
-  function sendError(requestId, errorMessage) {
-    send({ type: "response-error", requestId, error: errorMessage });
+  function sendError(requestId, errorMessage, over) {
+    send({ type: "response-error", requestId, error: errorMessage }, over);
   }
 
   return {
@@ -414,6 +499,9 @@ export function createTunnelClient({
         clearTimeout(reconnectTimer);
         reconnectTimer = null;
       }
+      for (const connection of openConnections) {
+        connection.close(1000, "shutdown");
+      }
       if (socket) {
         socket.close(1000, "shutdown");
         socket = null;
@@ -429,7 +517,10 @@ export function createTunnelClient({
      * @returns {void}
      */
     sendSignal(sessionId, signal) {
-      send({ type: "signal", sessionId, signal });
+      // Back over the connection this session signalled through, while it is
+      // open; the server instance at the other end holds that browser.
+      const route = signalRoutes.get(sessionId);
+      send({ type: "signal", sessionId, signal }, route?.readyState === WebSocket.OPEN ? route : null);
     },
 
     /**

package/services/viewer/DownloadMaps.js

@@ -0,0 +1,168 @@
+/** One published download map per file, including download-only metadata reads. */
+export class DownloadMaps {
+  #files = new Map();
+  #publish;
+  #resolvePlayback;
+  #nextEpoch = 0;
+
+  constructor({ publish, resolvePlayback = async map => map.zones }) {
+    if (typeof publish !== "function") throw new TypeError("Download map publication is required.");
+    this.#publish = publish;
+    this.#resolvePlayback = resolvePlayback;
+  }
+
+  async playback({ sourceKey, fileIndex, durationSeconds, zones }) {
+    const file = this.#file(sourceKey, fileIndex);
+    file.durationSeconds = durationSeconds;
+    const revision = ++file.revision;
+    const now = Date.now();
+    file.sourceZones = zones.map(zone => Number.isFinite(zone.deadlineAt) || !Number.isFinite(zone.withinSeconds)
+      ? zone : { ...zone, deadlineAt: now + Math.max(0, zone.withinSeconds) * 1000 });
+    let changed = false;
+    const retained = file.zones.flatMap(zone => {
+      const interval = zone.downloadInterval ?? zone;
+      const current = file.sourceZones.find(candidate => candidate.from === interval.from && candidate.to === interval.to);
+      const deadlineAt = current && Number.isFinite(current.deadlineAt)
+        ? current.deadlineAt - (zone.leadSeconds ?? 0) * 1000 : current?.deadlineAt;
+      if (!current || Object.keys(current).some(key => key !== "from" && key !== "to" && !Object.is(zone[key], key === "deadlineAt" ? deadlineAt : current[key]))) changed = true;
+      return current ? [{ ...zone, ...current, from: zone.from, to: zone.to, deadlineAt }] : [];
+    });
+    file.zones = retained;
+    for (const [statement, metadata] of file.metadata) {
+      if (metadata.interval && !this.wantsInterval(sourceKey, fileIndex, metadata.interval)) {
+        file.metadata.delete(statement);
+        changed = true;
+      }
+      else if (metadata.interval) {
+        const current = file.sourceZones.find(zone => zone.from === metadata.interval.from && zone.to === metadata.interval.to);
+        const deadlineAt = Number.isFinite(current.deadlineAt) ? current.deadlineAt - metadata.leadSeconds * 1000 : current.deadlineAt;
+        if (metadata.priority !== current.priority || metadata.urgent !== current.urgent || metadata.deadlineAt !== deadlineAt) changed = true;
+        metadata.priority = current.priority;
+        metadata.urgent = current.urgent;
+        metadata.deadlineAt = deadlineAt;
+      }
+    }
+    if (changed) await this.#emit(file);
+    if (revision !== file.revision) return;
+    const resolved = await this.#resolvePlayback({ sourceKey, fileIndex, durationSeconds, zones: file.sourceZones });
+    if (revision !== file.revision) return;
+    file.zones = resolved;
+    return this.#emit(file);
+  }
+
+  refresh(sourceKey, fileIndex) {
+    const file = this.#files.get(`${sourceKey}:${fileIndex}`);
+    if (!file) return Promise.resolve();
+    return this.playback({ sourceKey, fileIndex, durationSeconds: file.durationSeconds, zones: file.sourceZones });
+  }
+
+  epoch(sourceKey, fileIndex) {
+    return this.#files.get(`${sourceKey}:${fileIndex}`)?.epoch ?? 0;
+  }
+
+  native({ sourceKey, fileIndex, zones }) {
+    const file = this.#file(sourceKey, fileIndex);
+    file.nativeZones = zones;
+    return this.#emit(file);
+  }
+
+  wantsInterval(sourceKey, fileIndex, { from, to }) {
+    return this.#files.get(`${sourceKey}:${fileIndex}`)?.sourceZones.some(zone => zone.from === from && zone.to === to) ?? false;
+  }
+
+  /** Exact source ranges already resolved by the download map, without new reads. */
+  inputsForOutput(sourceKey, outputKey, index) {
+    const sources = [];
+    for (const file of this.#files.values()) {
+      if (file.sourceKey !== sourceKey) continue;
+      const zones = file.zones.filter(zone => zone.outputKey === outputKey && zone.index === index);
+      if (!zones.length) continue;
+      sources.push({ sourceId: `${sourceKey}:${file.fileIndex}`,
+        ranges: zones.map(zone => ({ start: zone.byteStart, end: zone.byteEnd + 1 })) });
+    }
+    return sources.length ? sources : null;
+  }
+
+  metadata({ sourceKey, fileIndex, statement, result, priority = 100, urgent = true, deadlineAt = 0, interval, leadSeconds = 0, scope = "playback", order = 0 }) {
+    if (!Number.isFinite(leadSeconds) || leadSeconds < 0) throw new TypeError("Metadata preparation time must be finite and nonnegative.");
+    const file = this.#file(sourceKey, fileIndex);
+    if (result.kind === "needs-ranges") {
+      if (interval && !this.wantsInterval(sourceKey, fileIndex, interval)) return Promise.resolve();
+      const current = interval && file.sourceZones.find(zone => zone.from === interval.from && zone.to === interval.to);
+      if (current) {
+        priority = current.priority;
+        urgent = current.urgent;
+        deadlineAt = Number.isFinite(current.deadlineAt) ? current.deadlineAt - leadSeconds * 1000 : current.deadlineAt;
+      }
+      file.metadata.set(statement, { ranges: result.ranges, requestId: result.requestId, priority, urgent, deadlineAt, interval, leadSeconds, scope, order });
+    } else {
+      file.metadata.delete(statement);
+    }
+    return this.#emit(file);
+  }
+
+  withdrawMetadata(sourceKey, fileIndex, statement) {
+    const file = this.#files.get(`${sourceKey}:${fileIndex}`);
+    return file?.metadata.delete(statement) ? this.#emit(file) : Promise.resolve();
+  }
+
+  repriceMetadata(sourceKey, fileIndex, statement, demand) {
+    const file = this.#files.get(`${sourceKey}:${fileIndex}`);
+    const metadata = file?.metadata.get(statement);
+    if (!metadata || Object.keys(demand).every(key => Object.is(metadata[key], demand[key]))) return Promise.resolve();
+    Object.assign(metadata, demand);
+    return this.#emit(file);
+  }
+
+  forget(sourceKey, fileIndex, { keepPreparation = false } = {}) {
+    const file = this.#file(sourceKey, fileIndex);
+    file.zones = [];
+    file.sourceZones = [];
+    if (!keepPreparation) file.nativeZones = [];
+    file.revision++;
+    file.epoch = ++this.#nextEpoch;
+    for (const [statement, metadata] of file.metadata) {
+      if (!keepPreparation || metadata.scope !== "preparation") file.metadata.delete(statement);
+    }
+    // Keep the publication sequence when the same file is requested again.
+    return this.#emit(file);
+  }
+
+  /** Closing a source discards its maps and cancels queued publications. */
+  retire(sourceKey) {
+    for (const [key, file] of this.#files) {
+      if (file.sourceKey !== sourceKey) continue;
+      file.revision++;
+      this.#files.delete(key);
+    }
+  }
+
+  #file(sourceKey, fileIndex) {
+    if (typeof sourceKey !== "string" || !sourceKey || !Number.isSafeInteger(fileIndex) || fileIndex < 0) {
+      throw new TypeError("A download map requires a source file address.");
+    }
+    const key = `${sourceKey}:${fileIndex}`;
+    let file = this.#files.get(key);
+    if (!file) {
+      file = { sourceKey, fileIndex, durationSeconds: 0, zones: [], nativeZones: [], sourceZones: [], revision: 0, epoch: ++this.#nextEpoch, metadata: new Map(), pending: Promise.resolve() };
+      this.#files.set(key, file);
+    }
+    return file;
+  }
+
+  #emit(file) {
+    const zones = [...file.zones, ...file.nativeZones];
+    for (const { ranges, requestId, priority, urgent, deadlineAt, order } of file.metadata.values()) {
+      for (const [byteStart, byteEnd] of ranges) {
+        zones.push({ byteStart, byteEnd, priority, urgent, downloadOnly: true, requestId, deadlineAt, ...(order ? { order } : {}) });
+      }
+    }
+    const publication = { sourceKey: file.sourceKey, fileIndex: file.fileIndex, durationSeconds: file.durationSeconds, zones };
+    const pending = file.pending.then(() => {
+      if (this.#files.get(`${file.sourceKey}:${file.fileIndex}`) === file) return this.#publish(publication);
+    });
+    // A failed publication must not prevent the next state change from being sent.
+    file.pending = pending.catch(() => undefined);
+    return pending;
+  }
+}

package/services/viewer/NativeSourceMap.js

@@ -0,0 +1,33 @@
+import { mapForViewer, mergeMaps, runsOf } from "./PriorityMap.js";
+
+/** Price native source packets with the same viewer map as encoded outputs. */
+export function nativeSourceMap({ index, tracks, viewers, durationSeconds, startTimeSeconds = 0,
+  allowanceSeconds, urgentReadyFor, now = Date.now() }) {
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) return [];
+  const maps = viewers.map(viewer => mapForViewer({
+    atSeconds: viewer.positionSeconds(now) ?? 0, durationSeconds, allowanceSeconds,
+    playing: viewer.playing || viewer.waiting, viewerCount: viewers.length,
+    pauseSeconds: viewer.pausedAt === null ? 0 : (now - viewer.pausedAt) / 1000,
+    urgentReady: urgentReadyFor(viewer)
+  }));
+  const zones = [];
+  for (const zone of runsOf(mergeMaps(maps))) {
+    for (const track of tracks.filter(track => ["video", "audio"].includes(track.type))) {
+      const bounds = index.boundsOf(track.trackNumber);
+      if (!bounds) continue;
+      const from = Math.max(bounds.start, zone.from + startTimeSeconds);
+      const to = Math.min(bounds.end, durationSeconds + startTimeSeconds, zone.to + startTimeSeconds);
+      if (!(to > from)) continue;
+      const input = index.inputFor({ trackId: track.trackNumber, from, to });
+      if (input.kind === "needs-index") continue;
+      if (input.kind !== "result") throw new Error(`Native source input refused: ${input.reason}`);
+      const links = viewers.filter((_viewer, viewerIndex) => maps[viewerIndex].priority[zone.from] === zone.priority)
+        .map(viewer => viewer.linkReading()?.linkMbps).filter(rate => Number.isFinite(rate) && rate > 0);
+      const bytes = input.ranges.reduce((sum, [start, end]) => sum + end - start + 1, 0);
+      const deliverySeconds = links.length ? bytes * 8 / (Math.min(...links) * 1_000_000) : 0;
+      for (const [byteStart, byteEnd] of input.ranges) zones.push({ ...zone, byteStart, byteEnd,
+        deadlineAt: Number.isFinite(zone.withinSeconds) ? now + (zone.withinSeconds - deliverySeconds) * 1000 : Infinity });
+    }
+  }
+  return zones;
+}

package/services/viewer/PriorityMap.js

@@ -87,31 +87,14 @@
  */
 
 /**
- * THE SCALE. Three bands, and the order between them is the whole of what the
- * numbers claim.
- *
- * 1. IN FRONT OF SOMEBODY WHO IS WATCHING — the top value at the second they
- *    are about to see, falling as the film gets further from them;
- * 2. IN FRONT OF SOMEBODY WHO HAS STOPPED — the same shape, and every value of
- *    it below every value of band 1. A stopped viewer will watch this film when
- *    they press play, so it is still in front of them; nobody is waiting for it
- *    now, so it yields to anybody who is;
- * 3. BEHIND EVERYBODY — reachable only by a seek back, and nothing measures how
- *    likely that is, so it is one value rather than a shape.
- *
- * IN FRONT ALWAYS OUTRANKS BEHIND, at any distance and whoever is stopped. The
- * bands make that true by construction rather than by a comparison somebody has
- * to remember to write.
- *
- * The values inside a band are AN ENCODING OF AN ORDER, not a measurement:
- * every consumer asks only which of two seconds comes first, so any strictly
- * decreasing shape does the same work, and none of these numbers claims
- * anything about the world.
+ * Wanted seconds use priorities 1..100. Distance lowers priority relative to
+ * the measured urgent allowance. Pause preserves the same priorities until
+ * urgent outputs are ready. With competing viewers, elapsed pause time then
+ * attenuates the excess above 1 before maps merge. Zero means no demand.
+ * Direction, urgent preparation and attenuation are separate map fields;
+ * priority alone cannot distinguish an attenuated second from a passed one.
  */
 export const AT_A_WATCHING_VIEWER = 100;
-const WATCHING_FLOOR = 70;
-const AT_A_STOPPED_VIEWER = 69;
-const STOPPED_FLOOR = 39;
 
 /** Behind everybody. */
 export const NOBODY_IS_COMING = 1;
@@ -159,7 +142,7 @@ export function isAtAWatchingViewer(priority) {
  * @returns {boolean}
  */
 export function isNobodyComingNow(priority) {
-  return priority > NOBODY_IS_COMING && priority <= AT_A_STOPPED_VIEWER;
+  return priority === NOBODY_IS_COMING;
 }
 
 /**
@@ -197,7 +180,9 @@ export function emptyMap(durationSeconds) {
     durationSeconds: seconds,
     priority: new Uint8Array(seconds),
     secondsUntilPlayed: new Float64Array(seconds).fill(Number.POSITIVE_INFINITY),
-    behind: new Uint8Array(seconds).fill(1)
+    behind: new Uint8Array(seconds).fill(1),
+    urgent: new Uint8Array(seconds),
+    deferred: new Uint8Array(seconds)
   };
 }
 
@@ -209,11 +194,9 @@ export function emptyMap(durationSeconds) {
  * a clock time — is what the value is derived from, and it is why two viewers
  * can be compared at all: the nearer one wins the second they both want.
  *
- * **A pause removes the time, not the direction.** A stopped viewer is still
- * standing somewhere, and the film in front of them is still the film they will
- * watch, so their map keeps its shape and moves into the band below. Collapsed
- * to one flat value over the whole film, as it was, their position disappeared
- * entirely — and with it the rule that what is in front is made first.
+ * Pause retains urgent preparation first. Once that work is ready, the
+ * allowance / (allowance + pauseSeconds) coefficient gradually reduces this
+ * viewer's priorities if others consume the file. Resume restores them.
  *
  * **What must NOT be here**, and the boundary is the point: how fast this
  * machine encodes, how many encoders that takes, what a second weighs in bytes,
@@ -229,7 +212,15 @@ export function emptyMap(durationSeconds) {
  * @param {boolean} [params.playing] - Whether the picture is moving.
  * @returns {PriorityMap}
  */
-export function mapForViewer({ atSeconds, durationSeconds, allowanceSeconds, playing = true }) {
+export function pauseCoefficient({ playing, urgentReady, viewerCount, pauseSeconds, allowanceSeconds }) {
+  if (playing !== false || !urgentReady || viewerCount <= 1) return 1;
+  const allowance = Number.isFinite(allowanceSeconds) && allowanceSeconds > 0 ? allowanceSeconds : 1;
+  const elapsed = Number.isFinite(pauseSeconds) ? Math.max(0, pauseSeconds) : 0;
+  return allowance / (allowance + elapsed);
+}
+
+export function mapForViewer({ atSeconds, durationSeconds, allowanceSeconds, playing = true,
+  pauseSeconds = 0, urgentReady = false, viewerCount = 1 }) {
   const map = emptyMap(durationSeconds);
   if (map.durationSeconds === 0) {
     return map;
@@ -237,10 +228,13 @@ export function mapForViewer({ atSeconds, durationSeconds, allowanceSeconds, pla
   const at = Number.isFinite(atSeconds) && atSeconds > 0 ? Math.floor(atSeconds) : 0;
   const allowance = Number.isFinite(allowanceSeconds) && allowanceSeconds > 0
     ? allowanceSeconds
-    : 1;
+    : map.durationSeconds;
   const watching = playing !== false;
-  const top = watching ? AT_A_WATCHING_VIEWER : AT_A_STOPPED_VIEWER;
-  const floor = watching ? WATCHING_FLOOR : STOPPED_FLOOR;
+  // The measured urgent span is the time scale. There is no chosen decay
+  // period: one span on pause halves the excess above minimum priority.
+  const attenuate = !watching && urgentReady && viewerCount > 1;
+  const elapsed = Number.isFinite(pauseSeconds) ? Math.max(0, pauseSeconds) : 0;
+  const coefficient = pauseCoefficient({ playing, urgentReady, viewerCount, pauseSeconds: elapsed, allowanceSeconds: allowance });
   for (let second = 0; second < map.durationSeconds; second += 1) {
     if (second < at) {
       map.priority[second] = NOBODY_IS_COMING;
@@ -248,11 +242,13 @@ export function mapForViewer({ atSeconds, durationSeconds, allowanceSeconds, pla
     }
     map.behind[second] = 0;
     const distance = second - at;
-    map.priority[second] = Math.max(floor, top - stepsAway(distance, allowance));
-    // A viewer who has stopped is on their way nowhere, so there is no second by
-    // which any of this must exist. The direction survives the pause, in the
-    // priority above; the time does not, because there is none to state.
-    map.secondsUntilPlayed[second] = watching ? distance : Number.POSITIVE_INFINITY;
+    const priority = Math.max(NOBODY_IS_COMING, AT_A_WATCHING_VIEWER - stepsAway(distance, allowance));
+    map.priority[second] = Math.max(NOBODY_IS_COMING, 1 + Math.floor((priority - 1) * coefficient));
+    map.urgent[second] = distance < allowance && !attenuate ? 1 : 0;
+    map.deferred[second] = attenuate ? 1 : 0;
+    // Urgent preparation keeps its deadline during pause. After completion,
+    // pause duration defers this viewer's work without altering other viewers.
+    map.secondsUntilPlayed[second] = distance + (attenuate ? elapsed : 0);
   }
   return map;
 }
@@ -308,6 +304,7 @@ export function mergeMaps(maps) {
     return emptyMap(0);
   }
   const merged = emptyMap(Math.max(...all.map((map) => map.durationSeconds)));
+  merged.deferred.fill(1);
   for (const map of all) {
     for (let second = 0; second < map.durationSeconds; second += 1) {
       if (map.priority[second] > merged.priority[second]) {
@@ -321,8 +318,14 @@ export function mergeMaps(maps) {
       if (map.behind[second] === 0) {
         merged.behind[second] = 0;
       }
+      if (map.urgent?.[second]) merged.urgent[second] = 1;
+      // Deferred only if every viewer needing this second has yielded it.
+      if (map.behind[second] === 0 && !map.deferred?.[second]) merged.deferred[second] = 0;
     }
   }
+  for (let second = 0; second < merged.durationSeconds; second += 1) {
+    if (merged.behind[second]) merged.deferred[second] = 0;
+  }
   return merged;
 }
 
@@ -349,12 +352,16 @@ export function runsOf(map) {
       continue;
     }
     const behind = map.behind[second] === 1;
+    const urgent = map.urgent?.[second] === 1;
+    const deferred = map.deferred?.[second] === 1;
     const previous = runs[runs.length - 1];
     if (
       previous
       && previous.to === second
       && previous.priority === priority
       && previous.behind === behind
+      && previous.urgent === urgent
+      && previous.deferred === deferred
     ) {
       previous.to = second + 1;
       continue;
@@ -373,7 +380,9 @@ export function runsOf(map) {
       to: second + 1,
       priority,
       withinSeconds,
-      behind
+      behind,
+      urgent,
+      deferred
     });
   }
   return runs;