From 1a495f5ed3f8a55222d406152c833882264dc377 Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Tue, 8 Sep 2026 22:54:16 +0200
Subject: feat(hub): client-side transfer leases and the transfers panel
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Steps 5 and 6 of ~/next/improve-downloads.md. The node has handed out slots
since step 2 and nothing asked for one; now the client does, and the panel shows
what is happening.

`transport.openTransfer()` returns a Lease: `acquire()` resolves when the node
grants, `release()` gives it back exactly once, and nothing else in the client
speaks to the node about slots. Whether a node hands out slots is read from the
handshake ack rather than guessed from a timeout — "no answer yet" and "this
node will never answer" are indistinguishable in time, and guessing wrong either
stalls every download or defeats the cap.

Two things exist only because a queue can lie: a watchdog re-asks when a pushed
grant does not arrive (the node is idempotent on `tr`, so asking again is free),
and a grant for a transfer the page has forgotten is handed straight back rather
than held until the node's deadline.

The slot is asked for **after** there is somewhere to write, and that ordering
is load-bearing: opening a target takes thirty seconds of streamed-download
timeouts, or as long as somebody leaves a Save As dialog open, and a grant not
taken up in time is revoked. Moving it earlier looked better and broke three
downloads into one. Pinned by a test.

The panel groups by state — running, waiting, finished — rather than re-sorting a
flat list, so a row moves only when its own state does. The ETA is withheld until
the speed window holds real measurement: a figure from the first two chunks
swings between four seconds and an hour, and people plan around the first number
they see. One live region announces state changes and not progress.

Three silent paths closed on the way: a download refused for want of a user
gesture (a browser grants one file picker per gesture, and downloading three
files is one gesture) now falls back to the streamed path, which needs none; a
click with no connection says so instead of doing nothing at all; and a queued
transfer counts as busy, so a transport is never closed under one that is
waiting for a grant that could then never arrive.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HCGdheDLxGReuKHga3BtST
---
 .../meshbay-hub/src/meshbay_hub/static/style.css   | 64 ++++++++++++++++++++++
 1 file changed, 64 insertions(+)

(limited to 'packages/meshbay-hub/src/meshbay_hub/static/style.css')

diff --git a/packages/meshbay-hub/src/meshbay_hub/static/style.css b/packages/meshbay-hub/src/meshbay_hub/static/style.css
index dfed44b..22fcd3f 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/style.css
+++ b/packages/meshbay-hub/src/meshbay_hub/static/style.css
@@ -4243,3 +4243,67 @@ h2 .gn-owner, h3 .gn-owner { font-size: 0.55em; }
   color: var(--warn);
   margin-bottom: 2px;
 }
+
+/* A transfer waiting for a slot. Deliberately not a progress bar at 0%: it is
+   not stalled and nothing is wrong, and a bar that never moves is exactly how a
+   queue comes to look like a hang. The stripes say "not yet", not "broken". */
+.dl-progress.dl-waiting {
+  background-color: var(--bg-raised);
+  background-image: repeating-linear-gradient(
+    45deg,
+    var(--accent-bg) 0 8px,
+    transparent 8px 16px);
+  animation: dl-waiting-slide 1.1s linear infinite;
+}
+@keyframes dl-waiting-slide {
+  from { background-position: 0 0; }
+  to   { background-position: 22.6px 0; }
+}
+/* The state has to survive without the motion: someone who asked for less of it
+   still needs to see that this row is waiting rather than stopped. */
+@media (prefers-reduced-motion: reduce) {
+  .dl-progress.dl-waiting { animation: none; }
+}
+
+/* ── Transfers panel (grouped) ───────────────────────────────────────────── */
+
+.transfer-head-title { font-weight: 600; }
+.transfer-head-summary {
+  margin-left: auto;
+  margin-right: .5rem;
+  font-size: .85em;
+  color: var(--text-dim);
+  /* Never wraps to a second line: it is the one part of the header that grows
+     with what is happening, and a header that changes height as transfers come
+     and go pushes every row under it. */
+  white-space: nowrap;
+}
+.transfer-group + .transfer-group { border-top: 1px solid var(--border); }
+.transfer-group-head {
+  padding: .35rem .6rem .2rem;
+  font-size: .78em;
+  text-transform: uppercase;
+  letter-spacing: .04em;
+  color: var(--text-dim);
+}
+/* Finished rows recede rather than disappear: somebody who just downloaded
+   three files wants to see that all three are there. */
+.transfer-item.transfer-done .transfer-name,
+.transfer-item.transfer-cancelled .transfer-name { color: var(--text-dim); }
+
+/* Announced, not shown. The transfers panel needs a live region that says what
+   changed state without drawing anything — used with aria-live, so it must
+   stay in the accessibility tree: `display: none` would remove it from there
+   too and announce nothing at all, which is the usual way this is got wrong. */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
-- 
cgit v1.2.3


From 29e93e5e553c94818cd2b4e587b0e54cfe7d8424 Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Wed, 9 Sep 2026 10:48:49 +0200
Subject: feat(spa): pause and resume a download, in session
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Stage 7a of ~/next/improve-downloads.md: pausing within a session, on the
targets that can actually do it. Resuming across a reload is 7b.

A paused transfer holds **nothing**. Its slot goes back to the node the moment
it stops and resuming rejoins the queue at the tail, because anything else lets
one member close a node by pausing four downloads and going to lunch. So the
lease is taken inside the run loop rather than before it, and pause is refused
outright for a transfer that could not ask for another one.

Resuming is exact rather than approximate: the pipeline stops between two
chunks and never inside one, so what is on disk is always a whole number of
chunks and `fromChunk` is a verified position. The failure mode being avoided
is a file that looks complete and is quietly corrupt.

The target has to survive it, so a pause no longer reaches the `abort()` that a
failure does -- that would delete Electron's `.part` or the file just created in
the granted folder, leaving nothing to continue. And the in-memory fallback
keeps its accumulated chunks rather than starting a second array.

The button is drawn only where the target says it can. A service-worker stream
says no, in its own code and for its own reasons: the browser is already writing
an HTTP response into its own download folder, not feeding it stalls that
download where we cannot see or resume it, and an idle worker is terminated
within seconds. Firefox and Safari therefore keep cancel and get no pause, which
is the decision recorded in §6.5.

Cancelling a paused transfer ends it. A paused run is parked on a promise;
without waking it the row said "cancelled" over work that had not stopped and a
target that was still open.

Six cases, each checked against the unfixed source. Hub suite 842 passed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HCGdheDLxGReuKHga3BtST
---
 packages/meshbay-hub/src/meshbay_hub/static/app.js |  32 ++++-
 .../src/meshbay_hub/static/downloads.js            |  11 ++
 .../src/meshbay_hub/static/file-utils.js           |  57 ++++++--
 .../src/meshbay_hub/static/locales/de.js           |   5 +
 .../src/meshbay_hub/static/locales/en.js           |   5 +
 .../src/meshbay_hub/static/locales/es.js           |   5 +
 .../src/meshbay_hub/static/locales/fr.js           |   5 +
 .../src/meshbay_hub/static/locales/it.js           |   5 +
 .../src/meshbay_hub/static/locales/ja.js           |   5 +
 .../src/meshbay_hub/static/locales/nl.js           |   5 +
 .../src/meshbay_hub/static/locales/pl.js           |   5 +
 .../src/meshbay_hub/static/locales/pt-BR.js        |   5 +
 .../src/meshbay_hub/static/locales/zh-CN.js        |   5 +
 .../meshbay-hub/src/meshbay_hub/static/style.css   |  14 ++
 .../src/meshbay_hub/static/transfers.js            | 118 +++++++++++++--
 packages/meshbay-hub/tests/test_downloads.py       |  68 +++++++++
 packages/meshbay-hub/tests/test_transfers.py       | 160 +++++++++++++++++++++
 17 files changed, 484 insertions(+), 26 deletions(-)

(limited to 'packages/meshbay-hub/src/meshbay_hub/static/style.css')

diff --git a/packages/meshbay-hub/src/meshbay_hub/static/app.js b/packages/meshbay-hub/src/meshbay_hub/static/app.js
index 6f4bb92..0394af6 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/app.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/app.js
@@ -242,8 +242,24 @@ function TransferRow({ it }) {
           ? html`<a class="transfer-name" href="#" title=${it.name}
               onClick=${(e) => { e.preventDefault(); transfers.open(it.id); }}>${it.name}</a>`
           : html`<span class="transfer-name" title=${it.name}>${it.name}</span>`}
+        ${it.pausable && (it.status === 'running' || it.status === 'paused')
+          && html`
+          ${/* Offered only where the target can actually do it: a
+                service-worker stream is a download the browser already owns,
+                and a pause there would restart from zero. */''}
+          <button class="transfer-pause"
+            aria-label=${t(it.status === 'paused'
+                           ? 'transfers.resume_one' : 'transfers.pause_one',
+                           { name: it.name })}
+            title=${t(it.status === 'paused'
+                      ? 'transfers.resume' : 'transfers.pause')}
+            onClick=${() => (it.status === 'paused'
+                             ? transfers.resume(it.id) : transfers.pause(it.id))}>
+            <${Icon} name=${it.status === 'paused' ? 'play' : 'pause'} />
+          </button>
+        `}
         ${(it.status === 'running' || it.status === 'queued'
-           || it.status === 'preparing') && html`
+           || it.status === 'preparing' || it.status === 'paused') && html`
           <button class="transfer-cancel"
             aria-label=${t('transfers.cancel_one', { name: it.name })}
             title=${t('transfers.cancel')}
@@ -274,6 +290,20 @@ function TransferRow({ it }) {
             <span>${formatSize(it.total)}</span>
           </div>
         `
+        : it.status === 'paused'
+        ? html`
+          ${/* The bar keeps its fill: what has been written is still there,
+                and resuming continues from it rather than starting again. */''}
+          <div class="dl-progress" role="progressbar"
+            aria-valuenow=${it.percent} aria-valuemin="0" aria-valuemax="100">
+            <div class="dl-fill dl-paused" style="width:${it.percent}%"></div>
+          </div>
+          <div class="transfer-meta">
+            <span>${t('transfers.paused')}</span>
+            <span>${formatSize(it.done)}${it.total
+              ? ' / ' + formatSize(it.total) : ''}</span>
+          </div>
+        `
         : it.status === 'running'
         ? html`
           <div class="dl-progress" role="progressbar"
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/downloads.js b/packages/meshbay-hub/src/meshbay_hub/static/downloads.js
index 87d18b7..6ee7cf0 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/downloads.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/downloads.js
@@ -178,6 +178,9 @@ export async function openTarget(filename) {
       },
     },
     name,
+    // A held-open `FileSystemWritableFileStream`: pausing is simply not
+    // writing to it, and nothing is lost while nothing is written.
+    pausable: true,
     // Reading it back is the only way a page can "open" a file it wrote: hand
     // the bytes to a tab and let the browser decide what to do with them. No
     // web page can start a desktop application, or show a file manager.
@@ -612,6 +615,14 @@ async function _attemptStreamedDownload(filename, size, attempt,
   const writer = writable.getWriter();
   return {
     name: filename,
+    // **Not pausable, and this is not a limitation of our code.** The browser
+    // is already writing an HTTP response into its own download folder: not
+    // writing to the stream stalls that download where we cannot see it or
+    // resume it, and an idle worker is terminated within seconds, taking the
+    // stream with it. A pause button here would restart from zero, which is
+    // worse than not offering one. §6.5 of ~/next/improve-downloads.md records
+    // what giving Firefox and Safari a resumable target would cost.
+    pausable: false,
     writable: {
       write: (bytes) => { lastWrite = Date.now(); return writer.write(bytes); },
       close: async () => {
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/file-utils.js b/packages/meshbay-hub/src/meshbay_hub/static/file-utils.js
index ef074dd..99d9f9a 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/file-utils.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/file-utils.js
@@ -118,7 +118,10 @@ async function _openDownloadTarget(filename, size = 0, pickerOpts = {},
         filename, { auto: downloads.getMode() === 'auto' });
       // Null means the person dismissed the dialog, which is not an error and
       // must not start a transfer.
-      return native || false;
+      //
+      // The desktop sink is an open file stream in the main process: not
+      // writing to it for a while costs nothing and loses nothing.
+      return native ? { ...native, pausable: true } : false;
     } catch (err) {
       console.warn('[MeshBay] native save failed:', platform.bridgeMessage(err));
       return false;
@@ -179,7 +182,8 @@ async function _openDownloadTarget(filename, size = 0, pickerOpts = {},
     const handle = await window.showSaveFilePicker({
       suggestedName: filename, ...pickerOpts,
     });
-    return { writable: await handle.createWritable(), name: handle.name || filename };
+    return { writable: await handle.createWritable(),
+             name: handle.name || filename, pausable: true };
   } catch (err) {
     if (err.name === 'AbortError') return false;
     // "Must be handling a user gesture to show a file picker."
@@ -350,9 +354,10 @@ async function _fetchChunkResilient(transport, fileId, index, tr = '') {
 }
 
 async function pipelinedDownload(transport, gekKey, fileId, totalChunks, onChunk,
-                                 writable, signal, tr = '') {
-  const results = writable ? null : new Array(totalChunks);
-  let nextSend = 0, nextRecv = 0;
+                                 writable, signal, tr = '', fromChunk = 0,
+                                 results = null) {
+  if (!writable && !results) results = new Array(totalChunks);
+  let nextSend = fromChunk, nextRecv = fromChunk;
   const inflight = new Array(totalChunks);
 
   const fire = () => {
@@ -369,6 +374,21 @@ async function pipelinedDownload(transport, gekKey, fileId, totalChunks, onChunk
       err.name = 'AbortError';
       throw err;
     }
+    // Between two chunks, never inside one. Everything written so far is a
+    // whole number of chunks, which is what makes resuming exact rather than
+    // approximate — `fromChunk` is a position, not an estimate, and a resumed
+    // file is never appended to at an offset nobody checked.
+    //
+    // The chunks already in flight past this point are abandoned and asked for
+    // again on resume: at most one pipeline window of duplicated traffic, in
+    // exchange for not having to hold a half-received window across a pause of
+    // unknown length.
+    if (signal && signal.paused) {
+      signal.resumeFrom = nextRecv;
+      const err = new Error('Paused');
+      err.name = 'PausedError';
+      throw err;
+    }
     const chunkMsg = await inflight[nextRecv];
     // One shape, and a refusal for anything else. There used to be two fallbacks
     // below this: a base64 `ct_b64` chunk, which was the real wire format until
@@ -409,6 +429,9 @@ async function downloadEntry(transfers, transport, gek, entry) {
   const totalChunks = Math.ceil(entry.size / CHUNK_SIZE);
   const openRef = { url: null };
   let target = null;
+  // The in-memory fallback's accumulator, held out here so a pause does not
+  // discard what has already been decrypted.
+  const memoryChunks = new Array(totalChunks);
 
   transfers.start({
     kind: 'download', name: entry.name, total: entry.size, transport,
@@ -421,7 +444,10 @@ async function downloadEntry(transfers, transport, gek, entry) {
       target = await _openTargetInTurn(entry.name, entry.size);
       // Dismissed: nothing was started, so nothing is left on screen.
       if (target === false) return false;
-      return target ? { name: target.name } : true;
+      // `pausable` travels with the target, because only the target knows. The
+      // in-memory fallback (a null target) is just an array and pauses fine.
+      return target ? { name: target.name, pausable: !!target.pausable }
+                    : { pausable: true };
     },
 
     // After the target, never before: a granted slot has to be taken up within
@@ -434,24 +460,33 @@ async function downloadEntry(transfers, transport, gek, entry) {
     open: () => (target && target.open) ? target.open()
       : (openRef.url ? window.open(openRef.url, '_blank') : undefined),
 
-    run: async ({ signal, onProgress, lease }) => {
-      let done = 0;
+    // Kept across a pause: the chunks collected so far on the in-memory path.
+    // A resumed run fills in from where it stopped rather than starting a
+    // second array and throwing the first away.
+    run: async ({ signal, onProgress, lease, from = 0 }) => {
+      let done = from * CHUNK_SIZE;
       const onChunk = (bytes) => { done += bytes; onProgress(done, entry.size); };
 
       if (target) {
         try {
           await pipelinedDownload(transport, gek, entry.id, totalChunks,
                                   onChunk, target.writable, signal,
-                                  lease && lease.tr);
+                                  lease && lease.tr, from);
           await target.writable.close();
         } catch (err) {
-          await target.writable.abort().catch(() => {});
+          // A pause is not a failure, and the target must survive it: aborting
+          // here would delete the `.part` (Electron) or the file just created
+          // in the granted folder, and resuming would then have nothing to
+          // continue. Only a real end tears the target down.
+          if (err.name !== 'PausedError') {
+            await target.writable.abort().catch(() => {});
+          }
           throw err;
         }
       } else {
         const chunks = await pipelinedDownload(
           transport, gek, entry.id, totalChunks, onChunk, null, signal,
-          lease && lease.tr);
+          lease && lease.tr, from, memoryChunks);
         const blob = new Blob(chunks);
         _saveBlob(blob, entry.name);
         openRef.url = URL.createObjectURL(blob);
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
index f0ec776..ae20687 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
@@ -586,6 +586,11 @@ export default {
   'transfers.group_waiting': 'Wartend',
   'transfers.group_finished': 'Abgeschlossen',
   'transfers.cancel_one': '{name} abbrechen',
+  'transfers.pause': 'Anhalten',
+  'transfers.resume': 'Fortsetzen',
+  'transfers.paused': 'Angehalten',
+  'transfers.pause_one': '{name} anhalten',
+  'transfers.resume_one': '{name} fortsetzen',
   'transfers.eta_seconds': 'noch {n} s',
   'transfers.eta_minutes': 'noch {n} Min.',
   'transfers.eta_hours': 'noch {n} Std.',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
index c065b8a..7033778 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
@@ -702,6 +702,11 @@ export default {
   'transfers.group_waiting': 'Waiting',
   'transfers.group_finished': 'Finished',
   'transfers.cancel_one': 'Cancel {name}',
+  'transfers.pause': 'Pause',
+  'transfers.resume': 'Resume',
+  'transfers.paused': 'Paused',
+  'transfers.pause_one': 'Pause {name}',
+  'transfers.resume_one': 'Resume {name}',
   'transfers.eta_seconds': '{n}s left',
   'transfers.eta_minutes': '{n} min left',
   'transfers.eta_hours': '{n} h left',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
index f655bc0..311ba1f 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
@@ -582,6 +582,11 @@ export default {
   'transfers.group_waiting': 'En espera',
   'transfers.group_finished': 'Finalizados',
   'transfers.cancel_one': 'Cancelar {name}',
+  'transfers.pause': 'Pausar',
+  'transfers.resume': 'Reanudar',
+  'transfers.paused': 'En pausa',
+  'transfers.pause_one': 'Pausar {name}',
+  'transfers.resume_one': 'Reanudar {name}',
   'transfers.eta_seconds': 'quedan {n} s',
   'transfers.eta_minutes': 'quedan {n} min',
   'transfers.eta_hours': 'quedan {n} h',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
index e011873..106e3cd 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
@@ -585,6 +585,11 @@ export default {
   'transfers.group_waiting': 'En attente',
   'transfers.group_finished': 'Terminés',
   'transfers.cancel_one': 'Annuler {name}',
+  'transfers.pause': 'Suspendre',
+  'transfers.resume': 'Reprendre',
+  'transfers.paused': 'En pause',
+  'transfers.pause_one': 'Suspendre {name}',
+  'transfers.resume_one': 'Reprendre {name}',
   'transfers.eta_seconds': '{n} s restantes',
   'transfers.eta_minutes': '{n} min restantes',
   'transfers.eta_hours': '{n} h restantes',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
index 80e3c17..a610683 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
@@ -585,6 +585,11 @@ export default {
   'transfers.group_waiting': 'In attesa',
   'transfers.group_finished': 'Completati',
   'transfers.cancel_one': 'Annulla {name}',
+  'transfers.pause': 'Sospendi',
+  'transfers.resume': 'Riprendi',
+  'transfers.paused': 'In pausa',
+  'transfers.pause_one': 'Sospendi {name}',
+  'transfers.resume_one': 'Riprendi {name}',
   'transfers.eta_seconds': '{n} s rimanenti',
   'transfers.eta_minutes': '{n} min rimanenti',
   'transfers.eta_hours': '{n} h rimanenti',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
index 5dbb4fa..aed4ba0 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
@@ -577,6 +577,11 @@ export default {
   'transfers.group_waiting': '待機中',
   'transfers.group_finished': '完了',
   'transfers.cancel_one': '{name} をキャンセル',
+  'transfers.pause': '一時停止',
+  'transfers.resume': '再開',
+  'transfers.paused': '一時停止中',
+  'transfers.pause_one': '{name} を一時停止',
+  'transfers.resume_one': '{name} を再開',
   'transfers.eta_seconds': '残り {n} 秒',
   'transfers.eta_minutes': '残り {n} 分',
   'transfers.eta_hours': '残り {n} 時間',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
index f9c7cf3..fe10e12 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
@@ -586,6 +586,11 @@ export default {
   'transfers.group_waiting': 'Wachtend',
   'transfers.group_finished': 'Voltooid',
   'transfers.cancel_one': '{name} annuleren',
+  'transfers.pause': 'Pauzeren',
+  'transfers.resume': 'Hervatten',
+  'transfers.paused': 'Gepauzeerd',
+  'transfers.pause_one': '{name} pauzeren',
+  'transfers.resume_one': '{name} hervatten',
   'transfers.eta_seconds': 'nog {n} s',
   'transfers.eta_minutes': 'nog {n} min',
   'transfers.eta_hours': 'nog {n} u',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
index b26f3cb..c2ba35c 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
@@ -598,6 +598,11 @@ export default {
   'transfers.group_waiting': 'Oczekuje',
   'transfers.group_finished': 'Zakończone',
   'transfers.cancel_one': 'Anuluj {name}',
+  'transfers.pause': 'Wstrzymaj',
+  'transfers.resume': 'Wznów',
+  'transfers.paused': 'Wstrzymano',
+  'transfers.pause_one': 'Wstrzymaj {name}',
+  'transfers.resume_one': 'Wznów {name}',
   'transfers.eta_seconds': 'pozostało {n} s',
   'transfers.eta_minutes': 'pozostało {n} min',
   'transfers.eta_hours': 'pozostało {n} godz.',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
index db5a408..83d179b 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
@@ -584,6 +584,11 @@ export default {
   'transfers.group_waiting': 'Aguardando',
   'transfers.group_finished': 'Concluídos',
   'transfers.cancel_one': 'Cancelar {name}',
+  'transfers.pause': 'Pausar',
+  'transfers.resume': 'Retomar',
+  'transfers.paused': 'Pausado',
+  'transfers.pause_one': 'Pausar {name}',
+  'transfers.resume_one': 'Retomar {name}',
   'transfers.eta_seconds': 'faltam {n} s',
   'transfers.eta_minutes': 'faltam {n} min',
   'transfers.eta_hours': 'faltam {n} h',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
index ba88f4e..9acfb17 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
@@ -565,6 +565,11 @@ export default {
   'transfers.group_waiting': '等待中',
   'transfers.group_finished': '已完成',
   'transfers.cancel_one': '取消 {name}',
+  'transfers.pause': '暂停',
+  'transfers.resume': '继续',
+  'transfers.paused': '已暂停',
+  'transfers.pause_one': '暂停 {name}',
+  'transfers.resume_one': '继续 {name}',
   'transfers.eta_seconds': '剩余 {n} 秒',
   'transfers.eta_minutes': '剩余 {n} 分钟',
   'transfers.eta_hours': '剩余 {n} 小时',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/style.css b/packages/meshbay-hub/src/meshbay_hub/static/style.css
index 22fcd3f..a37e541 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/style.css
+++ b/packages/meshbay-hub/src/meshbay_hub/static/style.css
@@ -1975,6 +1975,20 @@ a.transfer-name {
   display: flex;
 }
 .transfer-cancel:hover { color: var(--error); }
+/* Same shape as cancel, and beside it: pausing and cancelling are the two
+   things a person does to a transfer, and one of them is not destructive. */
+.transfer-pause {
+  background: none;
+  border: none;
+  color: var(--text-dim);
+  cursor: pointer;
+  padding: 0 2px;
+  display: flex;
+}
+.transfer-pause:hover { color: var(--accent); }
+/* A paused bar keeps its fill -- what was written is still on disk -- but stops
+   looking like something in progress. */
+.dl-fill.dl-paused { background: var(--text-dim); }
 .transfer-meta {
   display: flex;
   justify-content: space-between;
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/transfers.js b/packages/meshbay-hub/src/meshbay_hub/static/transfers.js
index d3b164d..797321c 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/transfers.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/transfers.js
@@ -25,7 +25,15 @@ const SPEED_WINDOW_MS = 5000;
 /** Not finished: still preparing, waiting for a slot, or transferring. One
  *  definition, because six places ask and they were drifting apart. */
 function _live(status) {
-  return status === 'preparing' || status === 'queued' || status === 'running';
+  return status === 'preparing' || status === 'queued' || status === 'running'
+    || status === 'paused';
+}
+
+/** Raised by `run` when it stopped because the transfer was paused. */
+function _pausedError() {
+  const err = new Error('Paused');
+  err.name = 'PausedError';
+  return err;
 }
 
 function _abortError() {
@@ -81,6 +89,9 @@ export class TransferStore {
       // Only for a file written into a folder the browser granted us: that is
       // the one case where the page can read its own download back.
       canOpen: it.status === 'done' && typeof it.open === 'function',
+      // Whether the target can be stopped and continued. False is the honest
+      // answer for a service-worker stream, and the button is not drawn.
+      pausable: Boolean(it.pausable),
     }));
   }
 
@@ -144,7 +155,18 @@ export class TransferStore {
       ahead: (lease && lease.ahead) || 0,
       error: '',
       samples: [{ t: this._now(), done: 0 }],
-      signal: { aborted: false },
+      signal: { aborted: false, paused: false },
+      // Set from `prepare`: whether this target can be stopped and continued.
+      pausable: false,
+      // Where a resumed run picks up, in chunks. Zero until something pauses.
+      resumeFrom: 0,
+      // Resolved by resume(); awaited by the run loop while paused.
+      resumed: null,
+      _wake: null,
+      // Pausing gives the slot back, so resuming has to be able to ask for
+      // another one. A transfer handed a lease directly cannot, and must not
+      // be offered a button that would drop its slot for good.
+      _canRelease: Boolean(makeLease),
     };
     this._items.push(item);
     this._emit();
@@ -195,25 +217,58 @@ export class TransferStore {
             return undefined;
           }
           if (ready && ready.name) item.name = ready.name;
+          // Only the target knows. A service-worker stream is already an HTTP
+          // response the browser is writing to its own download folder: not
+          // writing to it stalls that download outside our control, and an idle
+          // worker is terminated within seconds, taking the stream with it. So
+          // the button is offered where it works and nowhere else — a pause
+          // that silently restarts from zero is worse than no pause.
+          if (ready && ready.pausable) item.pausable = true;
           item.status = 'running';
           this._emit();
         }
-        if (makeLease && !item.lease) {
-          item.lease = makeLease();
-          this._watchLease(item);
-          if (item.lease.state !== 'granted') {
-            item.status = 'queued';
-            item.ahead = item.lease.ahead || 0;
+        // Run, and be prepared to be stopped and started again.
+        //
+        // A paused transfer holds **nothing**: its slot goes back to the node
+        // and resuming rejoins the queue at the tail. Anything else lets one
+        // member close a node by pausing four downloads and going to lunch.
+        // So the lease is taken inside this loop, not before it.
+        for (;;) {
+          if (makeLease && !item.lease) {
+            item.lease = makeLease();
+            this._watchLease(item);
+            if (item.lease.state !== 'granted') {
+              item.status = 'queued';
+              item.ahead = item.lease.ahead || 0;
+              this._emit();
+            }
+          }
+          if (item.lease) {
+            await item.lease.acquire();
+            if (item.signal.aborted) throw _abortError();
+            item.status = 'running';
             this._emit();
           }
-        }
-        if (item.lease) {
-          await item.lease.acquire();
-          if (item.signal.aborted) throw _abortError();
-          item.status = 'running';
+          try {
+            return await run({ signal: item.signal, onProgress,
+                               lease: item.lease, from: item.resumeFrom || 0 });
+          } catch (err) {
+            if (err.name !== 'PausedError') throw err;
+          }
+          // Where to pick up. `run` records it on the signal rather than
+          // returning it, because it has to survive being thrown past.
+          item.resumeFrom = item.signal.resumeFrom || 0;
+          if (item.lease) {
+            item.lease.release('paused');
+            item.lease = null;
+          }
+          item.status = 'paused';
+          item.ahead = 0;
           this._emit();
+          this._maybeRelease(item.transport);
+          await item.resumed;
+          if (item.signal.aborted) throw _abortError();
         }
-        return run({ signal: item.signal, onProgress, lease: item.lease });
       })
       .then(() => {
         if (item.signal.aborted) finish('cancelled');
@@ -260,6 +315,37 @@ export class TransferStore {
     if (item && typeof item.open === 'function') return item.open();
   }
 
+  /**
+   * Stop a running transfer, keeping what it has already written.
+   *
+   * Only while running: a queued transfer is already stopped and holds no slot,
+   * and pausing it would only cost it its place. Only where the target can do
+   * it — see the note in `start`.
+   *
+   * The slot goes back to the node at once (§6.2 of the plan): a paused
+   * transfer holds nothing, and resuming rejoins the queue at the tail.
+   */
+  pause(id) {
+    const item = this._items.find(it => it.id === id);
+    if (!item || !item.pausable || !item._canRelease
+        || item.status !== 'running') return;
+    item.signal.paused = true;
+    // Created here rather than in resume(): the run loop awaits it the moment
+    // `run` throws, which can be sooner than the next call into this store.
+    item.resumed = new Promise((resolve) => { item._wake = resolve; });
+    this._emit();
+  }
+
+  /** Start it again, from where it stopped, behind whatever is waiting now. */
+  resume(id) {
+    const item = this._items.find(it => it.id === id);
+    if (!item || item.status !== 'paused') return;
+    item.signal.paused = false;
+    item.status = 'queued';
+    this._emit();
+    if (item._wake) { item._wake(); item._wake = null; }
+  }
+
   cancel(id) {
     const item = this._items.find(it => it.id === id);
     // 'queued' too: a transfer waiting for a slot is exactly the one somebody
@@ -268,6 +354,10 @@ export class TransferStore {
     if (!item || !_live(item.status)) return;
     item.signal.aborted = true;
     if (item.lease) item.lease.release('cancelled');
+    // A paused run is parked on `item.resumed`. Without this it stays parked
+    // for the life of the page, holding its target open, and the row says
+    // "cancelled" over a download that never stopped.
+    if (item._wake) { item._wake(); item._wake = null; }
     // Marked at once. The work stops when it next looks, but a cancelled
     // transfer should not keep reporting progress in the meantime.
     item.status = 'cancelled';
diff --git a/packages/meshbay-hub/tests/test_downloads.py b/packages/meshbay-hub/tests/test_downloads.py
index dfb1433..41ae5d3 100644
--- a/packages/meshbay-hub/tests/test_downloads.py
+++ b/packages/meshbay-hub/tests/test_downloads.py
@@ -489,3 +489,71 @@ out.push(asked);
     assert batched == [False, True, True], (
         "the stuck one is still the only holder of the gesture, so the released "
         "openings must not try for a dialog of their own")
+
+
+def test_a_pause_falls_between_chunks_and_resumes_at_one(tmp_path):
+    """What makes resuming exact rather than approximate.
+
+    Everything written is a whole number of chunks, because the loop checks for
+    a pause between two of them and never inside one. So `fromChunk` is a
+    position, not an estimate, and a resumed download is never appended to at an
+    offset nobody verified — the failure mode being avoided is a file that looks
+    complete and is quietly corrupt.
+
+    The real `pipelinedDownload` is lifted out and run against stubs, on the
+    rule this repo follows for the video player: model the environment, never
+    the code under test.
+    """
+    src = (STATIC / "file-utils.js").read_text()
+    fn = src[src.index("async function pipelinedDownload"):]
+    fn = fn[:fn.index("\n}\n") + 2]
+
+    script = tmp_path / "pipeline.mjs"
+    script.write_text("""
+const CHUNK_SIZE = 8;
+const PIPELINE_WINDOW = 4;
+const written = [];
+// `ct` has to be truthy: chunk 0 with a falsy body is refused as undecryptable,
+// which is the guard working, not the harness.
+const _fetchChunkResilient = async (transport, fileId, i) =>
+  ({ ct: new Uint8Array([i & 0xff]), nonce: new Uint8Array(12) });
+const _writeOrStall = async (w, bytes, index) => { written.push(index); };
+globalThis.window = { MeshBayCrypto: {
+  // The plaintext carries its own index, so what lands where can be checked.
+  decryptChunkBin: async (k, id, index) => ({ byteLength: CHUNK_SIZE, index }),
+} };
+""" + fn + """
+const out = {};
+const signal = { aborted: false, paused: false };
+// Stop it part way, the way the store does.
+let seen = 0;
+const onChunk = () => { if (++seen === 3) signal.paused = true; };
+try {
+  await pipelinedDownload({}, 'k', 'file', 10, onChunk, {}, signal, '', 0);
+  out.threw = 'no';
+} catch (err) {
+  out.threw = err.name;
+}
+out.resumeFrom = signal.resumeFrom;
+out.writtenBeforePause = written.slice();
+
+// And again, from where it said.
+signal.paused = false;
+written.length = 0;
+await pipelinedDownload({}, 'k', 'file', 10, () => {}, {}, signal, '',
+                        out.resumeFrom);
+out.writtenAfterResume = written.slice();
+console.log(JSON.stringify(out));
+""")
+    proc = subprocess.run(["node", str(script)], capture_output=True, text=True)
+    assert proc.returncode == 0, proc.stderr
+    out = json.loads(proc.stdout)
+
+    assert out["threw"] == "PausedError", out
+    # Whole chunks only, in order, with nothing skipped.
+    assert out["writtenBeforePause"] == list(range(len(out["writtenBeforePause"])))
+    assert out["resumeFrom"] == len(out["writtenBeforePause"]), (
+        f"stopped after {len(out['writtenBeforePause'])} chunks but asked to "
+        f"resume at {out['resumeFrom']} — that gap is a hole in the file")
+    # The resumed run covers exactly the rest, and repeats nothing.
+    assert out["writtenAfterResume"] == list(range(out["resumeFrom"], 10)), out
diff --git a/packages/meshbay-hub/tests/test_transfers.py b/packages/meshbay-hub/tests/test_transfers.py
index c48e38c..035f569 100644
--- a/packages/meshbay-hub/tests/test_transfers.py
+++ b/packages/meshbay-hub/tests/test_transfers.py
@@ -553,3 +553,163 @@ def test_a_transport_is_not_closed_under_a_preparing_transfer(tmp_path):
     """, tmp_path)
     assert out[1] is False
     assert out[3] is True
+
+
+# ── Pause and resume ────────────────────────────────────────────────────────
+#
+# The rule the whole design turns on: **a paused transfer holds nothing.** Its
+# slot goes back to the node the moment it stops, and resuming rejoins the queue
+# at the tail. Anything else lets one member close a node by pausing four
+# downloads and going to lunch (§6.2 of ~/next/improve-downloads.md).
+
+
+def _pausable_run():
+    """A `run` that stops where it is told and reports where it resumed."""
+    return """
+const mkStore = () => {
+  const t = new TransferStore();
+  const leases = [];
+  const state = { starts: [], paused: null, aborted: false };
+  t.start({
+    kind: 'download', name: 'f', total: 1000,
+    prepare: async () => ({ name: 'f', pausable: true }),
+    makeLease: () => { const l = new L(); leases.push(l); return l; },
+    run: async ({ signal, from }) => {
+      state.starts.push(from);
+      state.running = true;
+      try {
+      // Runs until told to stop, one "chunk" at a time.
+      for (let i = from; i < 10; i++) {
+        await new Promise(r => setTimeout(r, 5));
+        if (signal.aborted) { const e = new Error('c'); e.name = 'AbortError'; throw e; }
+        if (signal.paused) {
+          signal.resumeFrom = i;
+          const e = new Error('p'); e.name = 'PausedError'; throw e;
+        }
+      }
+      } finally { state.running = false; }
+    },
+  });
+  return { t, leases, state };
+};
+"""
+
+
+def test_pausing_gives_the_slot_back(tmp_path):
+    """The node has to get it back at once, not when the person resumes: the
+    whole point of a queue is that a slot nobody is using is a slot somebody
+    else can have."""
+    out = _run(_lease_stub() + _pausable_run() + """
+      const { t, leases } = mkStore();
+      await new Promise(r => setTimeout(r, 5));
+      leases[0].grant();
+      await new Promise(r => setTimeout(r, 20));
+      say('before:' + t.list()[0].status);
+      t.pause(t.list()[0].id);
+      await new Promise(r => setTimeout(r, 30));
+      say('after:' + t.list()[0].status);
+      say('released:' + leases[0].released.join(','));
+      say('leases:' + leases.length);
+    """, tmp_path)
+    assert out[0] == "before:running"
+    assert out[1] == "after:paused"
+    assert out[2] == "released:paused", "a paused transfer kept its slot"
+    assert out[3] == "leases:1"
+
+
+def test_resuming_asks_for_a_new_slot_and_continues_where_it_stopped(tmp_path):
+    """Rejoining at the tail is the design, not an accident: a paused transfer
+    that could reclaim its old place would be a way to hold one."""
+    out = _run(_lease_stub() + _pausable_run() + """
+      const { t, leases, state } = mkStore();
+      await new Promise(r => setTimeout(r, 5));
+      leases[0].grant();
+      await new Promise(r => setTimeout(r, 20));
+      const id = t.list()[0].id;
+      t.pause(id);
+      await new Promise(r => setTimeout(r, 30));
+      t.resume(id);
+      await new Promise(r => setTimeout(r, 10));
+      say('queued:' + t.list()[0].status, 'leases:' + leases.length);
+      leases[1].grant();
+      await new Promise(r => setTimeout(r, 120));
+      say('end:' + t.list()[0].status);
+      say('starts:' + state.starts.join(','));
+    """, tmp_path)
+    assert out[0] == "queued:queued", "a resumed transfer skipped the queue"
+    assert out[1] == "leases:2", "resuming did not ask for a slot again"
+    assert out[2] == "end:done"
+    starts = out[3].split(":")[1].split(",")
+    assert starts[0] == "0" and int(starts[1]) > 0, (
+        f"resumed from {starts} — it started again from the beginning")
+
+
+def test_a_transfer_whose_target_cannot_pause_is_not_paused(tmp_path):
+    """A service-worker stream is a download the browser already owns: not
+    writing to it stalls it outside our control and an idle worker is killed
+    within seconds. A button that silently restarts from zero is worse than no
+    button, so `pause` refuses rather than pretending."""
+    out = _run(_lease_stub() + """
+      const t = new TransferStore();
+      const lease = new L();
+      t.start({ kind: 'download', name: 'f', total: 10, lease,
+                prepare: async () => ({ name: 'f' }),
+                run: async ({ signal }) => {
+                  while (!signal.aborted) await new Promise(r => setTimeout(r, 5));
+                } });
+      lease.grant();
+      await new Promise(r => setTimeout(r, 20));
+      const id = t.list()[0].id;
+      say('pausable:' + t.list()[0].pausable);
+      t.pause(id);
+      await new Promise(r => setTimeout(r, 20));
+      say('status:' + t.list()[0].status);
+      t.cancel(id);
+    """, tmp_path)
+    assert out == ["pausable:false", "status:running"]
+
+
+def test_cancelling_a_paused_transfer_actually_ends_it(tmp_path):
+    """A paused run is parked on a promise. Without waking it, cancel marks the
+    row and leaves the work parked for the life of the page, holding its target
+    open — a button that lies, in the same way the first test in this file
+    describes."""
+    out = _run(_lease_stub() + _pausable_run() + """
+      const { t, leases, state } = mkStore();
+      await new Promise(r => setTimeout(r, 5));
+      leases[0].grant();
+      await new Promise(r => setTimeout(r, 20));
+      const id = t.list()[0].id;
+      t.pause(id);
+      await new Promise(r => setTimeout(r, 30));
+      t.cancel(id);
+      // What matters is whether the store's own loop ends, not whether the row
+      // says so: the row is marked at once either way.
+      const settled = await Promise.race([
+        t._items[0].promise.then(() => 'settled', () => 'settled'),
+        new Promise(r => setTimeout(() => r('parked'), 60)),
+      ]);
+      say('status:' + t.list()[0].status);
+      say('loop:' + settled);
+      say('resumed:' + state.starts.length);
+    """, tmp_path)
+    assert out[0] == "status:cancelled"
+    assert out[1] == "loop:settled", (
+        "the run was still parked on the resume promise after a cancel — the "
+        "row said cancelled over work that had not stopped")
+    assert out[2] == "resumed:1", "cancelling started the work again"
+
+
+def test_a_paused_transfer_still_counts_as_live(tmp_path):
+    """It is not finished, and its transport must not be closed under it — the
+    person is coming back to it."""
+    out = _run(_lease_stub() + _pausable_run() + """
+      const { t, leases } = mkStore();
+      await new Promise(r => setTimeout(r, 5));
+      leases[0].grant();
+      await new Promise(r => setTimeout(r, 20));
+      t.pause(t.list()[0].id);
+      await new Promise(r => setTimeout(r, 30));
+      say('pending:' + t.pending);
+    """, tmp_path)
+    assert out == ["pending:1"]
-- 
cgit v1.2.3


From e6f895c473a0b19e7b186889c1836d3945bc880b Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Wed, 9 Sep 2026 14:24:59 +0200
Subject: fix(spa): say why a download cannot be paused
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reported from Chrome, with a screenshot: four downloads with no pause button
and an upload beside them with one, and nothing anywhere saying why.

The reason is real. Without a granted download folder the browser writes
through the service worker — a download it already owns, which cannot be paused
without stalling it somewhere we can neither see nor resume. An upload writes to
the node, which keeps the position, so it is always pausable. But that was
stated only in a Settings line nobody reads on the way to a download, and a gap
where the row above has a button is not an explanation.

So a download that cannot be paused now shows a dimmed pause icon where the
button would be, carrying the reason and the remedy in its tooltip. Not a
button: there is nothing to click, and a disabled one invites the click anyway.

And only where the advice can be taken. Firefox and Safari have no folder to
choose — the streamed path is the only target they have, which is what §6.5 of
~/next/improve-downloads.md costs out — so telling someone there to choose one
would be advice they cannot follow. Nothing is drawn.

Hub suite 866 passed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HCGdheDLxGReuKHga3BtST
---
 packages/meshbay-hub/src/meshbay_hub/static/app.js | 14 +++++++++
 .../src/meshbay_hub/static/locales/de.js           |  1 +
 .../src/meshbay_hub/static/locales/en.js           |  1 +
 .../src/meshbay_hub/static/locales/es.js           |  1 +
 .../src/meshbay_hub/static/locales/fr.js           |  1 +
 .../src/meshbay_hub/static/locales/it.js           |  1 +
 .../src/meshbay_hub/static/locales/ja.js           |  1 +
 .../src/meshbay_hub/static/locales/nl.js           |  1 +
 .../src/meshbay_hub/static/locales/pl.js           |  1 +
 .../src/meshbay_hub/static/locales/pt-BR.js        |  1 +
 .../src/meshbay_hub/static/locales/zh-CN.js        |  1 +
 .../meshbay-hub/src/meshbay_hub/static/style.css   | 10 +++++++
 packages/meshbay-hub/tests/test_transfers.py       | 35 ++++++++++++++++++++++
 13 files changed, 69 insertions(+)

(limited to 'packages/meshbay-hub/src/meshbay_hub/static/style.css')

diff --git a/packages/meshbay-hub/src/meshbay_hub/static/app.js b/packages/meshbay-hub/src/meshbay_hub/static/app.js
index de47982..dfd0aeb 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/app.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/app.js
@@ -269,6 +269,20 @@ function TransferRow({ it }) {
             <${Icon} name=${it.status === 'paused' ? 'play' : 'pause'} />
           </button>
         `}
+        ${!it.pausable && downloads.SUPPORTED && it.kind === 'download'
+          && (it.status === 'running' || it.status === 'queued') && html`
+          ${/* Say why, rather than leaving a gap where a button is on the row
+                above. Without a granted folder this browser writes through the
+                service worker — a download it already owns, which cannot be
+                paused — so the button is absent for a reason nobody can see,
+                and an upload beside it has one. Shown only where choosing a
+                folder is actually possible: on Firefox and Safari there is no
+                folder to choose and this hint would be a lie. */''}
+          <span class="transfer-nopause" title=${t('transfers.not_pausable')}
+            aria-label=${t('transfers.not_pausable')}>
+            <${Icon} name="pause" />
+          </span>
+        `}
         ${(it.status === 'running' || it.status === 'queued'
            || it.status === 'preparing' || it.status === 'paused') && html`
           <button class="transfer-cancel"
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
index 738b131..0f632e3 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
@@ -590,6 +590,7 @@ export default {
   'transfers.pause': 'Anhalten',
   'transfers.resume': 'Fortsetzen',
   'transfers.paused': 'Angehalten',
+  'transfers.not_pausable': 'Kann nicht angehalten werden — wählen Sie in den Einstellungen einen Download-Ordner',
   'transfers.pause_one': '{name} anhalten',
   'transfers.resume_one': '{name} fortsetzen',
   'transfers.eta_seconds': 'noch {n} s',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
index 0b9de8a..cb7f4a0 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
@@ -706,6 +706,7 @@ export default {
   'transfers.pause': 'Pause',
   'transfers.resume': 'Resume',
   'transfers.paused': 'Paused',
+  'transfers.not_pausable': 'Cannot be paused — choose a download folder in Settings to enable it',
   'transfers.pause_one': 'Pause {name}',
   'transfers.resume_one': 'Resume {name}',
   'transfers.eta_seconds': '{n}s left',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
index 8da8f9f..fe1c13b 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
@@ -586,6 +586,7 @@ export default {
   'transfers.pause': 'Pausar',
   'transfers.resume': 'Reanudar',
   'transfers.paused': 'En pausa',
+  'transfers.not_pausable': 'No se puede pausar — elija una carpeta de descargas en Ajustes para activarlo',
   'transfers.pause_one': 'Pausar {name}',
   'transfers.resume_one': 'Reanudar {name}',
   'transfers.eta_seconds': 'quedan {n} s',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
index 3135c03..ea3f60e 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
@@ -589,6 +589,7 @@ export default {
   'transfers.pause': 'Suspendre',
   'transfers.resume': 'Reprendre',
   'transfers.paused': 'En pause',
+  'transfers.not_pausable': 'Non suspendable — choisissez un dossier de téléchargement dans les Réglages pour l\'activer',
   'transfers.pause_one': 'Suspendre {name}',
   'transfers.resume_one': 'Reprendre {name}',
   'transfers.eta_seconds': '{n} s restantes',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
index 91f0e9b..0687b25 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
@@ -589,6 +589,7 @@ export default {
   'transfers.pause': 'Sospendi',
   'transfers.resume': 'Riprendi',
   'transfers.paused': 'In pausa',
+  'transfers.not_pausable': 'Non si può sospendere — scelga una cartella di download nelle Impostazioni',
   'transfers.pause_one': 'Sospendi {name}',
   'transfers.resume_one': 'Riprendi {name}',
   'transfers.eta_seconds': '{n} s rimanenti',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
index b352188..a02e058 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
@@ -581,6 +581,7 @@ export default {
   'transfers.pause': '一時停止',
   'transfers.resume': '再開',
   'transfers.paused': '一時停止中',
+  'transfers.not_pausable': '一時停止できません。設定でダウンロードフォルダーを選ぶと使えます',
   'transfers.pause_one': '{name} を一時停止',
   'transfers.resume_one': '{name} を再開',
   'transfers.eta_seconds': '残り {n} 秒',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
index e0a799d..0235d8a 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
@@ -590,6 +590,7 @@ export default {
   'transfers.pause': 'Pauzeren',
   'transfers.resume': 'Hervatten',
   'transfers.paused': 'Gepauzeerd',
+  'transfers.not_pausable': 'Kan niet worden gepauzeerd — kies een downloadmap in Instellingen',
   'transfers.pause_one': '{name} pauzeren',
   'transfers.resume_one': '{name} hervatten',
   'transfers.eta_seconds': 'nog {n} s',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
index e6319b0..af4a5bb 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
@@ -602,6 +602,7 @@ export default {
   'transfers.pause': 'Wstrzymaj',
   'transfers.resume': 'Wznów',
   'transfers.paused': 'Wstrzymano',
+  'transfers.not_pausable': 'Nie można wstrzymać — proszę wybrać folder pobierania w Ustawieniach',
   'transfers.pause_one': 'Wstrzymaj {name}',
   'transfers.resume_one': 'Wznów {name}',
   'transfers.eta_seconds': 'pozostało {n} s',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
index 02c8356..f179c6f 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
@@ -588,6 +588,7 @@ export default {
   'transfers.pause': 'Pausar',
   'transfers.resume': 'Retomar',
   'transfers.paused': 'Pausado',
+  'transfers.not_pausable': 'Não pode ser pausado — escolha uma pasta de downloads em Configurações',
   'transfers.pause_one': 'Pausar {name}',
   'transfers.resume_one': 'Retomar {name}',
   'transfers.eta_seconds': 'faltam {n} s',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
index 6c4c73f..c89bbdc 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
@@ -569,6 +569,7 @@ export default {
   'transfers.pause': '暂停',
   'transfers.resume': '继续',
   'transfers.paused': '已暂停',
+  'transfers.not_pausable': '无法暂停——请在设置中选择下载文件夹以启用',
   'transfers.pause_one': '暂停 {name}',
   'transfers.resume_one': '继续 {name}',
   'transfers.eta_seconds': '剩余 {n} 秒',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/style.css b/packages/meshbay-hub/src/meshbay_hub/static/style.css
index a37e541..5e08a6a 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/style.css
+++ b/packages/meshbay-hub/src/meshbay_hub/static/style.css
@@ -1986,6 +1986,16 @@ a.transfer-name {
   display: flex;
 }
 .transfer-pause:hover { color: var(--accent); }
+/* Not a button: there is nothing to click. Dimmer than the cancel beside it,
+   and it carries its explanation in a tooltip rather than in the row, which
+   would be four lines of prose in a panel that has none. */
+.transfer-nopause {
+  color: var(--text-dim);
+  opacity: .45;
+  padding: 0 2px;
+  display: flex;
+  cursor: help;
+}
 /* A paused bar keeps its fill -- what was written is still on disk -- but stops
    looking like something in progress. */
 .dl-fill.dl-paused { background: var(--text-dim); }
diff --git a/packages/meshbay-hub/tests/test_transfers.py b/packages/meshbay-hub/tests/test_transfers.py
index d19a458..d93cf80 100644
--- a/packages/meshbay-hub/tests/test_transfers.py
+++ b/packages/meshbay-hub/tests/test_transfers.py
@@ -879,3 +879,38 @@ console.log(JSON.stringify({ active }));
     proc = subprocess.run(["node", str(script)], capture_output=True, text=True)
     assert proc.returncode == 0, proc.stderr
     assert json.loads(proc.stdout)["active"] == 1
+
+
+def test_a_row_that_cannot_pause_says_so_where_the_button_would_be():
+    """Reported from Chrome: four downloads with no pause button and an upload
+    with one, and no way to tell why.
+
+    The reason is real — without a granted folder the browser writes through the
+    service worker, a download it already owns and cannot pause — but it was
+    stated only in a Settings line nobody reads on the way to a download. A gap
+    where the row above has a button is not an explanation.
+
+    Shown only where a folder can actually be chosen: Firefox and Safari have
+    none to choose, and "choose a folder" would be advice that cannot be taken.
+    """
+    src = (STATIC / "app.js").read_text()
+    row = src[src.index("function TransferRow"):]
+    row = row[:row.index("\n}\n")]
+
+    hint = row[row.index("!it.pausable"):]
+    hint = hint[:hint.index("`}")]
+    assert "downloads.SUPPORTED" in hint, (
+        "the hint would tell a Firefox user to choose a folder it cannot offer")
+    assert "it.kind === 'download'" in hint, (
+        "an upload is always pausable; this is about download targets")
+    assert "transfers.not_pausable" in hint, "the reason is not stated"
+    # Not a button. There is nothing to click, and a disabled one invites the
+    # click anyway.
+    assert "<button" not in hint
+
+
+def test_the_reason_is_translated_everywhere():
+    """`t()` falls back to the key, so a missing catalogue entry shows
+    `transfers.not_pausable` in a tooltip rather than a sentence."""
+    for path in sorted((STATIC / "locales").glob("*.js")):
+        assert "'transfers.not_pausable'" in path.read_text(), path.name
-- 
cgit v1.2.3