@oar-sh/oar 0.9.8 → 0.9.9

package/server/public/app/pinned-messages-view.mjs

@@ -0,0 +1,253 @@
+// Pinned messages: the per-conversation pin list, the 📍 header button with
+// its count, and the list modal (the shared summary modal, kind
+// 'pinned-messages'). Fed by the conversation payload's `pins` on load and by
+// the `conversation_pins_updated` socket event (REPLACE semantics per
+// conversation), so a pin set on another device shows here without a reload.
+// This list is also what a bubble's Pin / Unpin label is drawn from.
+
+import {
+  IS_SHARED_VIEW,
+  closeSummaryModal,
+  escHtml,
+  fmtDate,
+  openSummaryModal,
+  renderSummaryModalContent,
+  showTransientRelayNotice,
+  summaryModalState,
+} from './store.js';
+import { updateMessagePin } from './api-client.js';
+
+export const PINNED_MESSAGES_MODAL_KIND = 'pinned-messages';
+
+const pinsByConversation = new Map();
+// The relay numbers its pin lists. A conversation load that left before a pin
+// change can arrive after the change's own socket event: the older list must
+// not win, or the page would stay wrong until the next load.
+const pinRevisionByConversation = new Map();
+const pinTogglesInFlight = new Set();
+let currentConversationId = null;
+let modalBodyBound = false;
+// The transcript lives in conversation-view.js and journal-view.js, which
+// import this module; they hand their side in through initPinnedMessagesView.
+let handlers = {
+  openConversation: null,
+  focusMessage: null,
+  syncRenderedPinState: null,
+};
+
+function normalizePins(pins) {
+  return (Array.isArray(pins) ? pins : [])
+    .map((pin) => ({ ...pin, messageId: String(pin?.messageId || '').trim() }))
+    .filter((pin) => pin.messageId);
+}
+
+export function getConversationPins(conversationId) {
+  return pinsByConversation.get(String(conversationId || '').trim()) || [];
+}
+
+export function isMessagePinned(conversationId, messageId) {
+  const id = String(messageId || '').trim();
+  return !!id && getConversationPins(conversationId).some((pin) => pin.messageId === id);
+}
+
+export function pinnedCountLabel(count) {
+  const total = Number(count) || 0;
+  return total ? `${total} pinned` : '';
+}
+
+function pinRoleLabel(role) {
+  return String(role || '').trim().toLowerCase() === 'user' ? 'You' : 'Agent';
+}
+
+export function renderPinnedListHtml(pins) {
+  const list = normalizePins(pins);
+  if (!list.length) {
+    return '<div class="pinned-empty">No pinned messages. Use Pin on a message to add one.</div>';
+  }
+  return `<div class="pinned-list">${list.map((pin) => {
+    const id = escHtml(pin.messageId);
+    const when = fmtDate(pin.timestamp);
+    const attachmentCount = Number(pin.attachmentCount) || 0;
+    const meta = [
+      escHtml(pinRoleLabel(pin.role)),
+      when ? escHtml(when) : '',
+      attachmentCount ? `📎 ${attachmentCount}` : '',
+      pin.hiddenFromShares === true ? '<span class="pinned-row-chip">hidden from shared</span>' : '',
+    ].filter(Boolean).join(' · ');
+    const preview = String(pin.preview || '').trim();
+    const previewHtml = preview
+      ? escHtml(preview)
+      : '<span class="pinned-row-no-text">(no text)</span>';
+    return `
+      <div class="pinned-row">
+        <button type="button" class="pinned-row-jump" data-pin-jump="${id}">
+          <span class="pinned-row-meta">${meta}</span>
+          <span class="pinned-row-preview">${previewHtml}</span>
+        </button>
+        <button type="button" class="pinned-row-unpin" data-pin-unpin="${id}" title="Unpin" aria-label="Unpin">🗑</button>
+      </div>`;
+  }).join('')}</div>`;
+}
+
+function syncPinnedHeaderButton() {
+  const button = document.getElementById('pinned-messages-btn');
+  if (!button) return;
+  const count = getConversationPins(currentConversationId).length;
+  button.hidden = IS_SHARED_VIEW || !count;
+  const countEl = button.querySelector('.header-icon-count');
+  if (countEl) countEl.textContent = count ? String(count) : '';
+  const label = count ? `Pinned messages (${count})` : 'Pinned messages';
+  button.setAttribute('title', label);
+  button.setAttribute('aria-label', label);
+}
+
+function pinnedModalContent() {
+  const pins = getConversationPins(currentConversationId);
+  return {
+    title: '📍 Pinned messages',
+    subtitle: pinnedCountLabel(pins.length),
+    bodyHtml: renderPinnedListHtml(pins),
+    kind: PINNED_MESSAGES_MODAL_KIND,
+  };
+}
+
+function syncCurrentConversationPins() {
+  syncPinnedHeaderButton();
+  if (summaryModalState.kind === PINNED_MESSAGES_MODAL_KIND) {
+    renderSummaryModalContent(pinnedModalContent());
+  }
+  handlers.syncRenderedPinState?.(
+    new Set(getConversationPins(currentConversationId).map((pin) => pin.messageId)),
+  );
+}
+
+export function setConversationPins(conversationId, pins, revision = 0) {
+  const id = String(conversationId || '').trim();
+  if (!id) return;
+  const nextRevision = Number(revision) || 0;
+  if (nextRevision) {
+    if (nextRevision < (pinRevisionByConversation.get(id) || 0)) return;
+    pinRevisionByConversation.set(id, nextRevision);
+  }
+  const normalized = normalizePins(pins);
+  // The list arrives with every conversation load, the live poll included: an
+  // unchanged one must not redraw the open modal under the user's finger.
+  if (JSON.stringify(normalized) === JSON.stringify(getConversationPins(id))) return;
+  if (normalized.length) pinsByConversation.set(id, normalized);
+  else pinsByConversation.delete(id);
+  if (id === currentConversationId) syncCurrentConversationPins();
+}
+
+export function setPinsConversation(conversationId) {
+  const id = String(conversationId || '').trim() || null;
+  if (id === currentConversationId) return;
+  currentConversationId = id;
+  // The conversation was closed (deleted, new chat): its list goes with it.
+  if (!id && summaryModalState.kind === PINNED_MESSAGES_MODAL_KIND) closeSummaryModal();
+  syncCurrentConversationPins();
+}
+
+export function openPinnedMessagesModal() {
+  if (IS_SHARED_VIEW) return;
+  openSummaryModal(pinnedModalContent());
+}
+
+function setPinButtonBusy(messageId, busy, pinned) {
+  const button = document.querySelector(`.msg-pin-btn[data-message-id="${CSS.escape(messageId)}"]`);
+  if (!button) return;
+  button.disabled = busy;
+  button.textContent = busy
+    ? (pinned ? 'Unpinning…' : 'Pinning…')
+    : (pinned ? 'Unpin' : 'Pin');
+}
+
+// `pinned` is the state the control showed when it was pressed; the request
+// asks for the opposite. The answer carries the conversation's whole pin list,
+// stored under that conversation's id: if the user has switched conversations
+// meanwhile, the open one is not touched.
+export async function toggleMessagePin(conversationId, messageId, pinned) {
+  const conversationKey = String(conversationId || '').trim();
+  const targetMessageId = String(messageId || '').trim();
+  if (!conversationKey || !targetMessageId) return;
+  const flightKey = `${conversationKey}:${targetMessageId}`;
+  if (pinTogglesInFlight.has(flightKey)) return;
+
+  pinTogglesInFlight.add(flightKey);
+  setPinButtonBusy(targetMessageId, true, pinned);
+  const result = await updateMessagePin(conversationKey, targetMessageId, !pinned);
+  pinTogglesInFlight.delete(flightKey);
+  if (!result?.ok) {
+    if (conversationKey === currentConversationId) setPinButtonBusy(targetMessageId, false, pinned);
+    showTransientRelayNotice(String(result?.error || '').trim() || (pinned
+      ? 'Could not unpin the message.'
+      : 'Could not pin the message.'));
+    return;
+  }
+
+  showTransientRelayNotice(result.pinned ? 'Message pinned.' : 'Message unpinned.');
+  if (conversationKey === currentConversationId) setPinButtonBusy(targetMessageId, false, result.pinned === true);
+  setConversationPins(conversationKey, result.pins, result.pinsRevision);
+}
+
+function isMessageOnPage(messageId) {
+  return !!document.querySelector(`#messages .msg[data-message-id="${CSS.escape(messageId)}"]`);
+}
+
+// On the page already: scroll there. Otherwise the path message search takes:
+// the relay answers with the messages around the target and the history
+// loaders page on from that window in both directions.
+export async function jumpToPinnedMessage(messageId) {
+  const targetMessageId = String(messageId || '').trim();
+  const conversationId = currentConversationId;
+  if (!targetMessageId || !conversationId) return;
+  closeSummaryModal();
+  if (handlers.focusMessage?.(targetMessageId)) return;
+
+  await handlers.openConversation?.(conversationId, {
+    aroundMessageId: targetMessageId,
+    focusMessageId: targetMessageId,
+  });
+  if (currentConversationId !== conversationId || isMessageOnPage(targetMessageId)) return;
+  showTransientRelayNotice('That message is no longer in this conversation.');
+  // A message the relay no longer has answers with an empty window; put the
+  // end of the conversation back instead of leaving the page blank.
+  if (!document.querySelector('#messages .msg[data-message-id]')) {
+    await handlers.openConversation?.(conversationId);
+  }
+}
+
+function handlePinnedModalClick(event) {
+  if (summaryModalState.kind !== PINNED_MESSAGES_MODAL_KIND) return;
+  const target = event.target instanceof Element ? event.target : null;
+  const unpinBtn = target?.closest('[data-pin-unpin]');
+  if (unpinBtn) {
+    event.preventDefault();
+    void toggleMessagePin(currentConversationId, unpinBtn.getAttribute('data-pin-unpin'), true);
+    return;
+  }
+  const jumpBtn = target?.closest('[data-pin-jump]');
+  if (jumpBtn) {
+    event.preventDefault();
+    void jumpToPinnedMessage(jumpBtn.getAttribute('data-pin-jump'));
+  }
+}
+
+export function initPinnedMessagesView(nextHandlers = {}) {
+  handlers = { ...handlers, ...nextHandlers };
+  const button = document.getElementById('pinned-messages-btn');
+  if (button && button.dataset.bound !== '1') {
+    button.dataset.bound = '1';
+    button.addEventListener('click', (event) => {
+      event.preventDefault();
+      openPinnedMessagesModal();
+    });
+  }
+  // #summary-modal-body outlives every modal, so it is bound exactly once; the
+  // handler no-ops unless the pin list is the modal currently mounted.
+  const modalBody = document.getElementById('summary-modal-body');
+  if (modalBody && !modalBodyBound) {
+    modalBodyBound = true;
+    modalBody.addEventListener('click', handlePinnedModalClick);
+  }
+  syncPinnedHeaderButton();
+}

package/server/public/app/pwa-install.js

@@ -25,7 +25,7 @@ function matchesDisplayMode(query) {
   }
 }
 
-function isInstalledAppMode() {
+export function isInstalledAppMode() {
   const standalone = matchesDisplayMode('(display-mode: standalone)');
   const minimalUi = matchesDisplayMode('(display-mode: minimal-ui)');
   const launchedFromAndroidApp = String(document.referrer || '').startsWith('android-app://');

package/server/public/app/relay-dot-state.mjs

@@ -9,7 +9,9 @@
  * A managed-but-disconnected tunnel stays green rather than going grey: the
  * relay itself is still reachable, and grey would claim otherwise. The tooltip
  * carries the bad news instead. Note this state is only ever visible locally —
- * a remote browser whose tunnel is down cannot load the page at all.
+ * a remote browser whose tunnel is down cannot load the page at all. A tunnel
+ * that never started because cloudflared is not installed reads "off" there,
+ * followed by the relay's sentence on how to install it.
  *
  * `tone` is the same state as `className`, minus the dot's CSS baggage. The
  * mobile burger toggle dyes its bars from it, because the dot itself sits in
@@ -24,6 +26,7 @@ function normalizeTunnel(tunnel) {
   if (!managed) return null;
   return {
     connected: tunnel.connected === true,
+    binaryMissing: tunnel.binaryMissing === true,
     lastError: String(tunnel.lastError || '').trim(),
   };
 }
@@ -56,6 +59,10 @@ export function resolveRelayDotState({
   let reach = 'Web relay reachable';
   if (tunnelled) {
     reach = 'Web relay reachable via Cloudflare Tunnel';
+  } else if (tunnel?.binaryMissing) {
+    reach = tunnel.lastError
+      ? `Web relay reachable; Cloudflare tunnel off: ${tunnel.lastError}`
+      : 'Web relay reachable; Cloudflare tunnel off: cloudflared is not installed';
   } else if (tunnel) {
     reach = tunnel.lastError
       ? `Web relay reachable; Cloudflare tunnel disconnected (${tunnel.lastError})`

package/server/public/app/router.js

@@ -1,3 +1,4 @@
+import { versionedFileHref } from './file-version.mjs';
 import {
   BASE,
   escHtml,
@@ -116,10 +117,15 @@ export function normalizeDriveBrowserPath(rawPath) {
   return rest ? `${drive}/${rest}` : drive;
 }
 
-export function driveFileHrefFromPath(rawPath) {
+/**
+ * `version` is the file's version token when the caller knows it (a preview
+ * carries one): the address then changes with the file, so an older copy
+ * cannot be served for it. The server ignores the parameter.
+ */
+export function driveFileHrefFromPath(rawPath, version = '') {
   const normalized = normalizeDriveBrowserPath(rawPath);
   if (!normalized) return '';
-  return `${BASE}/api/drives/file?path=${encodeURIComponent(normalized)}`;
+  return versionedFileHref(`${BASE}/api/drives/file?path=${encodeURIComponent(normalized)}`, version);
 }
 
 /**

package/server/public/app/socket-handlers.js

@@ -44,6 +44,7 @@ import {
 } from './ask-user-view.js';
 import { upsertRelayBoard, loadRelayBoards, renderRelayBoards } from './relay-board-view.js';
 import { setConversationBackgroundTasks } from './background-tasks-view.mjs';
+import { setConversationPins } from './pinned-messages-view.mjs';
 import { setPreviews } from './preview-cards.mjs';
 import { setRemoteRelaysSnapshot } from './remote-relays-store.mjs';
 import { REMOTE_RELAY_SOCKET_EVENT } from './remote-relay-shared.mjs';
@@ -545,6 +546,11 @@ export async function connectSocket(overrideDeps) {
   socket.on('background_tasks', ({ conversationId, tasks }) => {
     setConversationBackgroundTasks(conversationId, tasks);
   });
+  // A message was pinned or unpinned (any client): the conversation's whole
+  // pin list, replacing what this page had.
+  socket.on('conversation_pins_updated', ({ conversationId, pins, revision }) => {
+    setConversationPins(conversationId, pins, revision);
+  });
   // REPLACE semantics for the whole set: the preview registry is relay-owned
   // and global, so every change ships the full list.
   socket.on('previews', ({ previews }) => {

package/server/public/app/store.js

@@ -133,6 +133,8 @@ export let filePreviewState = {
     preload: 'metadata',
     autoplay: false,
   },
+  // The files the viewer can step through (see viewer-gallery.mjs), or null.
+  gallery: null,
 };
 // Toolbar filters are sticky per browser (all default off); the toggles in
 // attachments-view.js are the only writers.
@@ -1418,6 +1420,9 @@ export function renderSummaryModalContent({ title, subtitle = '', bodyHtml = '',
   runSummaryModalLeave(String(kind || '').trim());
   summaryModalState.kind = String(kind || '').trim();
   summaryModalState.refresh = typeof refresh === 'function' ? refresh : null;
+  // Lets the stylesheet tell one kind of this shared modal from another.
+  const modalEl = document.getElementById('summary-modal');
+  if (modalEl?.dataset) modalEl.dataset.kind = summaryModalState.kind;
 
   const titleEl = document.getElementById('summary-modal-title');
   const subtitleEl = document.getElementById('summary-modal-subtitle');
@@ -1445,6 +1450,7 @@ export function closeSummaryModal() {
   const modal = document.getElementById('summary-modal');
   modal?.classList.remove('visible');
   modal?.setAttribute('aria-hidden', 'true');
+  if (modal?.dataset) delete modal.dataset.kind;
   const titleEl = document.getElementById('summary-modal-title');
   const subtitleEl = document.getElementById('summary-modal-subtitle');
   const bodyEl = document.getElementById('summary-modal-body');

package/server/public/app/viewer-chat-gallery.mjs

@@ -0,0 +1,59 @@
+// The media of a conversation as a gallery: every image, video and audio
+// attachment and every picture embedded in a bubble, in the order they
+// stand in the conversation, open at the one that was tapped.
+//
+// It is read from the rendered messages rather than from message records:
+// an embedded picture only becomes an address the viewer can open once the
+// bubble is rendered (local paths are rewritten then), and the rendered
+// order is the conversation's order.
+
+export const CHAT_MEDIA_SELECTOR = '.msg-attachment[data-media-url], .msg-bubble img';
+
+function baseName(filePath) {
+  return String(filePath || '').split(/[\\/]/).filter(Boolean).pop() || 'image';
+}
+
+/** The viewer item behind a media node, or null for a node that is none. */
+export function chatMediaItemFromNode(node, { parseAppFileHref } = {}) {
+  if (!node) return null;
+  const attachment = node.closest?.('.msg-attachment[data-media-url]');
+  if (attachment) {
+    return {
+      source: 'upload',
+      href: String(attachment.dataset.mediaUrl || ''),
+      name: String(attachment.dataset.mediaName || 'attachment'),
+      mime: String(attachment.dataset.mediaType || ''),
+    };
+  }
+  if (String(node.tagName || '').toUpperCase() !== 'IMG') return null;
+  const src = String(node.getAttribute('src') || '').trim();
+  if (!src) return null;
+  const target = parseAppFileHref?.(src) || null;
+  if (target?.kind === 'drive') return { source: 'drives', path: target.path, name: baseName(target.path) };
+  if (target?.kind === 'workspace') return { source: 'workspace', path: target.path, name: baseName(target.path) };
+  // A data: thumbnail or a picture from the web: shown as it is.
+  const dataMime = /^data:(image\/[a-z0-9.+-]+)/i.exec(src)?.[1] || '';
+  return { source: 'upload', href: src, name: String(node.getAttribute('alt') || 'image'), mime: dataMime || 'image/*' };
+}
+
+/**
+ * The gallery of `root`'s media open at `clickedNode`, or null when there
+ * is nothing else to move to (the viewer then shows the one file).
+ * Embedded pictures can be left out (the shared view cannot fetch them).
+ */
+export function chatMediaGallery(root, clickedNode, { includeEmbedded = true, parseAppFileHref } = {}) {
+  if (!root || !clickedNode) return null;
+  const clicked = clickedNode.closest?.('.msg-attachment[data-media-url]') || clickedNode;
+  const items = [];
+  let index = -1;
+  for (const node of root.querySelectorAll(CHAT_MEDIA_SELECTOR)) {
+    const isAttachment = node.matches('.msg-attachment');
+    if (!isAttachment && (node.closest('.msg-attachment') || !includeEmbedded)) continue;
+    const item = chatMediaItemFromNode(node, { parseAppFileHref });
+    if (!item) continue;
+    if (node === clicked) index = items.length;
+    items.push(item);
+  }
+  if (index === -1 || items.length < 2) return null;
+  return { source: 'chat', items, index };
+}

package/server/public/app/viewer-controls-state.mjs

@@ -0,0 +1,59 @@
+// When the fullscreen viewer's hovering controls are shown.
+//
+// A single tap on the content toggles them. While a video or audio file
+// plays they also fade out on their own after a moment, as players do; any
+// interaction brings them back and starts that clock again. Pausing shows
+// them and stops the clock, so a paused player is never left bare. Images
+// and text have no clock: their controls stay until the next tap.
+
+export const CONTROLS_AUTO_HIDE_MS = 3000;
+
+export function createControlsState({
+  autoHideMs = CONTROLS_AUTO_HIDE_MS,
+  onChange = () => {},
+  setTimeoutImpl = setTimeout,
+  clearTimeoutImpl = clearTimeout,
+} = {}) {
+  const state = { visible: true, playing: false, timer: null };
+
+  const stopClock = () => {
+    if (state.timer === null) return;
+    clearTimeoutImpl(state.timer);
+    state.timer = null;
+  };
+
+  const set = (visible) => {
+    if (state.visible === visible) return;
+    state.visible = visible;
+    onChange(visible);
+  };
+
+  // The clock runs only while the controls are up and media plays.
+  const armClock = () => {
+    stopClock();
+    if (!state.playing || !state.visible) return;
+    state.timer = setTimeoutImpl(() => {
+      state.timer = null;
+      set(false);
+    }, autoHideMs);
+  };
+
+  return {
+    get visible() { return state.visible; },
+    get playing() { return state.playing; },
+    show() { set(true); armClock(); },
+    hide() { stopClock(); set(false); },
+    toggle() { if (state.visible) this.hide(); else this.show(); },
+    /** The user touched a control or moved the mouse: keep the controls a while longer. */
+    interaction() { if (state.visible) armClock(); else this.show(); },
+    setPlaying(playing) {
+      const next = playing === true;
+      if (state.playing === next) return;
+      state.playing = next;
+      if (next) armClock();
+      else { stopClock(); set(true); }
+    },
+    reset() { stopClock(); state.playing = false; set(true); },
+    dispose() { stopClock(); },
+  };
+}

package/server/public/app/viewer-gallery.mjs

@@ -0,0 +1,46 @@
+// The files a viewer can move between without being closed: the files of
+// the folder a file was opened from, in the order the browser shows them.
+// An index into that list is the open file; neighbours are the files on
+// either side, and the list never wraps.
+
+/**
+ * A gallery over a folder listing (`children` as the repo browser holds
+ * them; directories are skipped). `null` when the opened file is not in the
+ * list or has no neighbours — a viewer without a gallery shows one file.
+ */
+export function galleryFromFolder(children, openedPath, { source = 'workspace' } = {}) {
+  const items = (Array.isArray(children) ? children : [])
+    .filter((child) => child && child.type !== 'dir' && String(child.path || ''))
+    .map((child) => ({ path: String(child.path), name: String(child.name || '') }));
+  const index = items.findIndex((item) => item.path === String(openedPath || ''));
+  if (index === -1 || items.length < 2) return null;
+  return { source: String(source || 'workspace'), items, index };
+}
+
+/** The index `delta` steps away, or -1 past either end. */
+export function galleryNeighborIndex(gallery, delta) {
+  if (!gallery || !Array.isArray(gallery.items)) return -1;
+  const next = Number(gallery.index) + Number(delta);
+  return Number.isInteger(next) && next >= 0 && next < gallery.items.length ? next : -1;
+}
+
+/** The same gallery, open at another index. */
+export function galleryAt(gallery, index) {
+  if (!gallery || index < 0 || index >= gallery.items.length) return null;
+  return { ...gallery, index };
+}
+
+export function galleryPositionLabel(gallery) {
+  if (!gallery || !Array.isArray(gallery.items) || !gallery.items.length) return '';
+  return `${gallery.index + 1} / ${gallery.items.length}`;
+}
+
+/** The items on either side of the open one, nearest first. */
+export function galleryNeighbors(gallery) {
+  const out = [];
+  for (const delta of [1, -1]) {
+    const index = galleryNeighborIndex(gallery, delta);
+    if (index !== -1) out.push(gallery.items[index]);
+  }
+  return out;
+}

package/server/public/app/viewer-gestures.mjs

@@ -0,0 +1,105 @@
+// A swipe across the viewer: one pointer, moving mostly along one axis.
+//
+// The axis is decided once the pointer has moved a little, and stays: a
+// drag that started sideways is a sideways drag even if it wanders. Each
+// axis can be switched off for the moment (sideways while an image is
+// zoomed in, since that is a pan; downwards while text is scrolled). The
+// content follows the finger through `onMove`; on release the drag is a
+// swipe when it went far enough or fast enough, else it springs back.
+
+export const SWIPE_LOCK_PX = 12;
+export const SWIPE_THRESHOLD_PX = 80;
+export const SWIPE_FLICK_PX_PER_MS = 0.45;
+export const SWIPE_MIN_FLICK_PX = 30;
+
+export function createSwipeRecognizer({
+  onStart = () => {},
+  onMove = () => {},
+  onEnd = () => {},
+  canStart = () => true,
+  horizontalEnabled = () => true,
+  verticalEnabled = () => false,
+  lockPx = SWIPE_LOCK_PX,
+  thresholdPx = SWIPE_THRESHOLD_PX,
+  flickPxPerMs = SWIPE_FLICK_PX_PER_MS,
+  minFlickPx = SWIPE_MIN_FLICK_PX,
+} = {}) {
+  const state = { pointer: null, pointers: 0 };
+
+  const finish = (event, { cancelled = false } = {}) => {
+    const p = state.pointer;
+    state.pointer = null;
+    if (!p || !p.axis) return;
+    const dx = event ? event.clientX - p.x : 0;
+    const dy = event ? event.clientY - p.y : 0;
+    const along = p.axis === 'x' ? dx : dy;
+    // Velocity from the last two samples; a finger that paused before
+    // lifting has none.
+    const dt = event ? event.timeStamp - p.lastAt : Infinity;
+    const velocity = dt > 0 && dt < 100 && Number.isFinite(dt)
+      ? ((p.axis === 'x' ? event.clientX - p.lastX : event.clientY - p.lastY) / dt)
+      : 0;
+    const farEnough = Math.abs(along) > thresholdPx;
+    const flicked = Math.abs(along) > minFlickPx && Math.abs(velocity) > flickPxPerMs
+      && Math.sign(velocity) === Math.sign(along);
+    let swipe = null;
+    if (!cancelled && (farEnough || flicked)) {
+      swipe = p.axis === 'x' ? (along < 0 ? 'left' : 'right') : (along < 0 ? 'up' : 'down');
+    }
+    onEnd({ axis: p.axis, dx, dy, swipe, cancelled });
+  };
+
+  return {
+    handle(event) {
+      const type = String(event?.type || '');
+      if (type === 'pointerdown') {
+        state.pointers += 1;
+        if (state.pointers > 1) {
+          // A second finger: a pinch, not a swipe.
+          finish(null, { cancelled: true });
+          return;
+        }
+        if (!canStart(event)) return;
+        state.pointer = {
+          id: event.pointerId,
+          x: event.clientX, y: event.clientY,
+          lastX: event.clientX, lastY: event.clientY, lastAt: event.timeStamp,
+          axis: null,
+        };
+        return;
+      }
+      const p = state.pointer;
+      if (type === 'pointermove') {
+        if (!p || event.pointerId !== p.id) return;
+        const dx = event.clientX - p.x;
+        const dy = event.clientY - p.y;
+        if (!p.axis) {
+          if (Math.max(Math.abs(dx), Math.abs(dy)) < lockPx) return;
+          const axis = Math.abs(dx) >= Math.abs(dy) ? 'x' : 'y';
+          if ((axis === 'x' && !horizontalEnabled()) || (axis === 'y' && !verticalEnabled())) {
+            state.pointer = null;
+            return;
+          }
+          p.axis = axis;
+          onStart({ axis });
+        }
+        p.lastX = event.clientX;
+        p.lastY = event.clientY;
+        p.lastAt = event.timeStamp;
+        onMove({ axis: p.axis, dx, dy });
+        return;
+      }
+      if (type === 'pointerup' || type === 'pointercancel') {
+        state.pointers = Math.max(0, state.pointers - 1);
+        if (!p || event.pointerId !== p.id) return;
+        finish(event, { cancelled: type === 'pointercancel' });
+      }
+    },
+    /** True while a swipe is being tracked along an axis. */
+    get active() { return Boolean(state.pointer?.axis); },
+    cancel() {
+      finish(null, { cancelled: true });
+      state.pointers = 0;
+    },
+  };
+}

package/server/public/app/viewer-history.mjs

@@ -0,0 +1,43 @@
+// The system back gesture closes the viewer instead of leaving the app.
+//
+// Opening the viewer pushes one history entry marked as ours; back pops it
+// and the pop closes the viewer. Closing by any other means (the × button,
+// Escape, a swipe down) pops that entry itself so history is left as it
+// was, and the pop that follows is recognised as our own and ignored. The
+// address never changes: the entry carries only its state.
+
+export const VIEWER_HISTORY_MARK = 'oarFileViewer';
+const OWN_POP_WINDOW_MS = 1500;
+
+export function createViewerHistory({ history, onBack, now = () => Date.now() } = {}) {
+  const state = { pushed: false, ownPopAt: 0 };
+  return {
+    get pushed() { return state.pushed; },
+    /** The viewer came up: one entry, however many files it then shows. */
+    opened() {
+      if (state.pushed) return;
+      history.pushState({ [VIEWER_HISTORY_MARK]: true }, '');
+      state.pushed = true;
+    },
+    /** The viewer went away by itself: take its entry back out of history. */
+    closed() {
+      if (!state.pushed) return;
+      state.pushed = false;
+      if (history.state?.[VIEWER_HISTORY_MARK]) {
+        state.ownPopAt = now();
+        history.back();
+      }
+    },
+    /** Feed every popstate here; the one answering our own back() is skipped. */
+    onPopState() {
+      if (state.ownPopAt && now() - state.ownPopAt < OWN_POP_WINDOW_MS) {
+        state.ownPopAt = 0;
+        return;
+      }
+      state.ownPopAt = 0;
+      if (!state.pushed) return;
+      state.pushed = false;
+      onBack?.();
+    },
+  };
+}