the file browser draws pictures, in both views

images and videos get a thumbnail in grid and list. one <Thumbnail>, two sizes —
two implementations would have drifted the first time one learned something the
other did not, and the fallback is the part that would have drifted.

FFMPEG FOR BOTH, and no new dependency. a video needs a frame extracted, which
only ffmpeg does; an image only needs resizing, which sharp does faster and with
better format coverage. sharp is nevertheless not used: it sits in node_modules as
somebody else's transitive dependency and is absent from package.json, so importing
it is an undeclared dependency — the thing the frozen lockfile exists to prevent —
and declaring it is a deliberate --no-frozen-lockfile that belongs to whoever owns
the dependency list. ffmpeg is already a hard requirement of this router, so this
adds nothing to what the machine must have. the cost is HEIC and a few exotics,
which fall back to the icon.

THE CACHE KEY CONTAINS MTIME AND SIZE. a path alone would be wrong: replace a photo
under the same name and every screen keeps the old picture with nothing to clear it
but somebody who knows the cache exists. keyed on content, a changed file is a
different key — the old entry is orphaned rather than stale, and the response can be
`immutable` honestly rather than as a bet.

FAILURES ARE REMEMBERED. the browser retries a broken <img> every time it re-enters
the viewport, so without this one corrupt video runs ffmpeg on every scroll, forever.
in memory, so a restart gives it another chance after somebody installs a codec.

`ls` DECIDES what can be thumbnailed, not the client. the browser's own
NATIVE_VIDEO_EXTS is deliberately only what a <video> tag can play, which is a
different question from what ffmpeg can take a frame out of — every .mkv would have
gone without a picture for that reason alone. the entry has just been stat'd, so the
answer is a lookup on its name.

FOUND WHILE TESTING, and the reason there is a test folder: ffmpeg EXITS 0 HAVING
WRITTEN A ZERO-BYTE FILE when the seek lands past the end of the input. a 0.4s clip
gave exit 0 and 0 bytes with `-ss 1`, and exit 0 and a real JPEG without it. the
retry keyed on the exit code and so never fired, reporting every short video as
having no thumbnail. it keys on the output file now — there is one question worth
asking an image encoder and it is whether there is an image.

four ffmpeg at a time. the grid is virtualised so only what is on screen is asked
for, but scrolling fast through a folder of video queues far more than is visible,
and unbounded decoding turned a 1.9GB box into a swap storm once already.

size is snapped to 64px steps so a panel resizing by a pixel cannot mint a hundred
entries of one image. verified: 240 and 256 share a cache entry, 200 gets its own.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043

src/servers/api/file-browser/router.ts

@@ -9,6 +9,7 @@ import * as errors from '@@/custom-errors';
 import { readTtsConfig } from '@@/api/server-settings/tts';
 import { readOcrConfig } from '@@/api/server-settings/ocr';
 import { getUserSettings } from 'officerdb';
+import { buildThumbnail, clampSize, thumbnailKind } from './thumbnails';
 
 async function getUserTtsVoice(userId: number): Promise<string | null> {
   try {
@@ -210,11 +211,24 @@ router.get('/ls', async (ctx) => {
       if (!isInside(rootDir, fullPath)) return null;
       const s = await stat(fullPath).catch(() => null);
       if (!s) return null;
+      const isDirectory = s.isDirectory();
       return {
         name,
-        type: s.isDirectory() ? 'directory' : 'file',
+        type: isDirectory ? 'directory' : 'file',
         size: s.size,
         modifiedAt: s.mtimeMs,
+        /*
+          Whether `/thumb` will produce something, decided HERE so there is one list of extensions
+          rather than one on each side of the wire.
+
+          The client had no way to know without its own copy, and the copies would have drifted — the
+          browser's `NATIVE_VIDEO_EXTS` is deliberately only the formats a <video> tag can play, which
+          is a different question from what ffmpeg can take a frame out of, and every .mkv in the
+          folder would have gone without a picture for that reason alone.
+
+          Costs nothing: this entry has just been stat'd and the answer is a lookup on its name.
+        */
+        thumb: isDirectory ? null : thumbnailKind(name),
       };
     }),
   );
@@ -333,6 +347,52 @@ router.post('/rename', async (ctx) => {
 
 // Serve raw file (binary-safe, for audio/video/images/download)
 // Supports Range requests for audio/video seeking
+/**
+ * A small JPEG of an image or a video, for the browser's grid and list.
+ *
+ * ── Why not just point <img> at `/raw` ──
+ *
+ * Because a directory of photographs is then a directory of full-size downloads. Thirty 8MB images to
+ * draw thirty 80px squares is a quarter of a gigabyte over the wire to show something the size of a
+ * postage stamp, and it is worse on a phone, which is where it matters. Video cannot be done that way
+ * at all — there is no frame until something decodes one.
+ *
+ * ── Authenticated by `?token=`, like `/raw` ──
+ *
+ * An `<img>` cannot send an Authorization header. `user-middleware` already accepts the token in the
+ * query for exactly this reason, so this route needs no special handling — and it stays behind the same
+ * gate as everything else here rather than becoming a public URL that happens to be hard to guess.
+ *
+ * ── `immutable`, honestly ──
+ *
+ * The cache key contains the file's mtime and size, so this URL's answer genuinely cannot change: a
+ * different file is a different URL. That is what makes a year-long cache correct rather than a bet.
+ */
+router.get('/thumb', async (ctx) => {
+  const user = ctx.get('user');
+  const rootDir = getRootDir(user, ctx.req.query('root') ?? undefined);
+  const relPath = (ctx.req.query('path') || '').replace(/^\/+/, '');
+  if (!relPath) throw errors.BAD_REQUEST('path is required');
+
+  const absPath = resolveUserPath(rootDir, relPath);
+  const kind = thumbnailKind(relPath);
+  // 415 rather than 404: the file is there, it is simply not something a frame can be taken from. The
+  // client does not ask for these, so this is the answer to a stale tab rather than to normal use.
+  if (!kind) return ctx.text('no thumbnail for this file type', 415);
+
+  const result = await buildThumbnail(absPath, getUserDataDir(user.email), kind, clampSize(ctx.req.query('size')));
+  // 422, and the client falls back to the file icon. Not 500: a file ffmpeg cannot read is a fact about
+  // the file, and logging it as a server error would bury the ones that are.
+  if (!result.ok) return ctx.text(result.reason, 422);
+
+  return new Response(Bun.file(result.path), {
+    headers: {
+      'Content-Type': 'image/jpeg',
+      'Cache-Control': 'private, max-age=31536000, immutable',
+    },
+  });
+});
+
 router.get('/raw', async (ctx) => {
   const user = ctx.get('user');
   const rootDir = getRootDir(user, ctx.req.query('root') ?? undefined);