cursedbelt-server 1.0.0

package/src/server/storage/chunked.integration.spec.ts

@@ -0,0 +1,185 @@
+import { Database } from 'bun:sqlite';
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { subtle } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { pickFreePort, startTestServer, type TestServer } from 'cwip/testing';
+import { runMigrations } from '../migration/runner';
+import { createBinaryServerStore } from './binaryServerStore';
+import {
+  type ChunkedUploadService,
+  createChunkedUploadService,
+  createSqliteFileCatalogue,
+  createStorageOpsLedger,
+  FILE_CATALOGUE_MIGRATIONS,
+} from './files';
+import type { MediaCtx } from './types';
+
+// End-to-end PROOF of the large-file (chunked) upload against a REAL binary-server: spawn bs with
+// a boot-registered app (our RS256 public key), then run the exact client flow — init → PUT each
+// chunk DIRECT to bs → bs assembles on the last chunk → complete registers the catalogue row over
+// the assembled bytes — and read the bytes back through the store. Skips cleanly when the local
+// binary-server checkout isn't present (CI / other machines).
+const BS_DIR = process.env.BINARY_SERVER_DIR ?? '';
+const BS_PRESENT = BS_DIR !== '' && existsSync(path.join(BS_DIR, 'src', 'index.ts'));
+const ISSUER = 'https://demo.local';
+const APP_ID = 'demo';
+const CTX: MediaCtx = { userId: 'user-stub', tenantId: 'user-stub' };
+
+const b64url = (b: ArrayBuffer | Uint8Array) =>
+  Buffer.from(b instanceof Uint8Array ? b : new Uint8Array(b)).toString('base64url');
+const jsonSeg = (o: unknown) => b64url(new TextEncoder().encode(JSON.stringify(o)));
+const pem = (der: ArrayBuffer, label: string) =>
+  `-----BEGIN ${label}-----\n${(
+    Buffer.from(der)
+      .toString('base64')
+      .match(/.{1,64}/g) ?? []
+  ).join('\n')}\n-----END ${label}-----\n`;
+
+// SKIPPED until a real binary-server checkout is present: point BINARY_SERVER_DIR at one.
+// There is deliberately no default — a published package must not go looking in one machine's
+// directory layout — and `binary-server` has not been re-homed here, so this skips on every host today.
+describe.skipIf(!BS_PRESENT)('chunked upload → real binary-server (integration)', () => {
+  let server: TestServer | null = null;
+  let tmp = '';
+  let base = '';
+  let svc: ChunkedUploadService;
+  let store: ReturnType<typeof createBinaryServerStore>;
+  let signJwt: (claims: Record<string, unknown>) => Promise<string>;
+
+  beforeAll(async () => {
+    // RS256 keypair — bs verifies our tokens with the exported public key; we sign with the private.
+    const kp = await subtle.generateKey(
+      {
+        name: 'RSASSA-PKCS1-v1_5',
+        modulusLength: 2048,
+        publicExponent: new Uint8Array([1, 0, 1]),
+        hash: 'SHA-256',
+      },
+      true,
+      ['sign', 'verify'],
+    );
+    const spki = pem(await subtle.exportKey('spki', kp.publicKey), 'PUBLIC KEY');
+    signJwt = async (claims) => {
+      const now = Math.floor(Date.now() / 1000);
+      const input = `${jsonSeg({ alg: 'RS256', typ: 'JWT' })}.${jsonSeg({ iss: ISSUER, iat: now, exp: now + 3600, ...claims })}`;
+      const sig = await subtle.sign(
+        'RSASSA-PKCS1-v1_5',
+        kp.privateKey,
+        new TextEncoder().encode(input),
+      );
+      return `${input}.${b64url(new Uint8Array(sig))}`;
+    };
+
+    tmp = await mkdtemp(path.join(tmpdir(), 'bs-int-'));
+    const port = await pickFreePort();
+    server = await startTestServer({
+      cwd: BS_DIR,
+      cmd: ['bun', path.join(BS_DIR, 'src', 'index.ts')],
+      port,
+      env: {
+        PORT: String(port),
+        HOST: '127.0.0.1',
+        STORAGE_ROOT: path.join(tmp, 'binaries'),
+        DB_PATH: path.join(tmp, 'bs.sqlite'),
+        FILE_TOKEN_PUBLIC_KEY: spki,
+        FILE_TOKEN_ISSUER: ISSUER,
+        CA_APP_ID: APP_ID,
+        INTERNAL_SECRET: 'demo-internal',
+      },
+      healthPath: '/healthz',
+      timeoutMs: 90_000,
+    });
+    base = server.baseUrl;
+
+    const signFileToken = (c: {
+      k?: string;
+      p?: string;
+      fn?: string;
+      dl?: 'inline' | 'attachment';
+    }) => signJwt(c);
+    store = createBinaryServerStore({
+      baseUrl: base,
+      appId: APP_ID,
+      signFileToken,
+      internalSecret: 'demo-internal',
+    });
+    const db = new Database(':memory:');
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    const catalogue = createSqliteFileCatalogue({
+      db,
+      store,
+      workDir: path.join(tmp, 'work'),
+      owner: (c) => c.userId,
+    });
+    const ledger = createStorageOpsLedger(db);
+    svc = createChunkedUploadService({
+      catalogue,
+      ledger,
+      backend: 'binary',
+      chunkSize: 64 * 1024, // small so a modest test file splits into several chunks
+      owner: (c) => c.userId,
+      mintChunkUpload: async ({ key, sid, ci, tc, owner }) => {
+        const token = await signJwt({
+          k: `${APP_ID}/${key}`,
+          uid: owner,
+          sid,
+          ci,
+          tc,
+        });
+        return `${base}/upload-chunk/${APP_ID}/${key}?token=${encodeURIComponent(token)}`;
+      },
+    });
+  }, 90_000);
+
+  afterAll(async () => {
+    await server?.stop();
+    if (tmp) await rm(tmp, { recursive: true, force: true });
+  });
+
+  test('uploads a multi-chunk file direct to bs, registers it, and reads the bytes back intact', async () => {
+    // A ~200 KiB payload → 4 chunks at 64 KiB. Deterministic bytes so we can verify integrity.
+    const size = 200 * 1024;
+    const payload = new Uint8Array(size);
+    for (let i = 0; i < size; i++) payload[i] = (i * 31 + 7) & 0xff;
+
+    const init = await svc.init(CTX, {
+      name: 'big.bin',
+      mime: 'application/octet-stream',
+      size,
+      tags: ['large'],
+    });
+    expect(init.chunkCount).toBe(Math.ceil(size / (64 * 1024)));
+    expect(init.chunkUploadUrls).toHaveLength(init.chunkCount);
+
+    // PUT each chunk DIRECT to bs (as the browser would). The last returns 201 assembled.
+    let assembled = false;
+    for (let ci = 0; ci < init.chunkCount; ci++) {
+      const start = ci * init.chunkSize;
+      const slice = payload.slice(start, Math.min(start + init.chunkSize, size));
+      const res = await fetch(init.chunkUploadUrls[ci], {
+        method: 'PUT',
+        headers: { 'content-type': 'application/octet-stream' },
+        body: slice,
+      });
+      expect(res.ok).toBe(true);
+      if (res.status === 201)
+        assembled = ((await res.json()) as { assembled?: boolean }).assembled === true;
+    }
+    expect(assembled).toBe(true); // bs assembled on the final chunk
+
+    // Complete → the catalogue row exists over the already-assembled bytes (no re-upload).
+    const rec = await svc.complete(init.sid, { size });
+    expect(rec?.id).toBe(init.fileId);
+    expect(rec?.name).toBe('big.bin');
+    expect(rec?.tags).toEqual(['large']);
+
+    // Read the assembled bytes back THROUGH the store (bs Range GET) — byte-for-byte intact.
+    const back = await store.get(`fs/${CTX.userId}/${init.fileId}`);
+    expect(back).not.toBeNull();
+    expect(back?.length).toBe(size);
+    expect(Buffer.from(back as Uint8Array).equals(Buffer.from(payload))).toBe(true);
+  }, 30_000);
+});

package/src/server/storage/diskStore.ts

@@ -0,0 +1,83 @@
+import { mkdir, rm, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import type { MediaStore } from './types';
+
+// Local-disk MediaStore (the dev default). Bun-native: Bun.file/Bun.write handle web streams
+// and byte-range slices directly, so there is no node:stream on the hot path. Keys are
+// generated server-side (owner/id…) but we still guard against path traversal so a stored key
+// can never escape the media root.
+export function createDiskStore(root: string): MediaStore {
+  const resolveKey = (key: string): string => {
+    const full = path.join(root, key);
+    const rel = path.relative(root, full);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new Error(`Invalid media key: ${key}`);
+    }
+    return full;
+  };
+
+  return {
+    async put(key, bytes) {
+      // Bun.write creates intermediate directories automatically.
+      await Bun.write(resolveKey(key), bytes);
+    },
+    async putStream(key, body) {
+      const full = resolveKey(key);
+      // Grab the reader BEFORE any real await: in Bun 1.3.x a request-body stream's
+      // internals detach across an I/O tick, after which releaseLock() (and the
+      // async iterator) throw "undefined is not a function" — 500ing every upload.
+      const reader = body.getReader();
+      await mkdir(path.dirname(full), { recursive: true });
+      // Stream through a Bun FileSink — peak memory is one chunk. (NB: `Bun.write(full,
+      // new Response(body))` HANGS on a web ReadableStream in Bun 1.3.x, so we pump manually.)
+      const writer = Bun.file(full).writer();
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          writer.write(value);
+        }
+        await writer.end();
+      } finally {
+        try {
+          reader.releaseLock();
+        } catch {
+          // Same Bun 1.3.x detach bug via a caller-side await (e.g. an async auth
+          // guard): reads still complete, only this cleanup call explodes — and by
+          // here the stream is fully consumed, so there is nothing left to release.
+        }
+      }
+    },
+    async get(key) {
+      const file = Bun.file(resolveKey(key));
+      if (!(await file.exists())) return null;
+      return new Uint8Array(await file.arrayBuffer());
+    },
+    async remove(key) {
+      try {
+        await unlink(resolveKey(key));
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException)?.code !== 'ENOENT') throw err;
+      }
+    },
+    async removePrefix(prefix) {
+      await rm(resolveKey(prefix), { recursive: true, force: true });
+    },
+    async stat(key) {
+      const file = Bun.file(resolveKey(key));
+      if (!(await file.exists())) return null;
+      return { size: file.size };
+    },
+    async getRange(key, range) {
+      const file = Bun.file(resolveKey(key));
+      if (!(await file.exists())) return null;
+      // Bun.file.slice(start, end) is exclusive-end; our ranges are inclusive.
+      const blob = range ? file.slice(range.start, range.end + 1) : file;
+      return { stream: blob.stream() };
+    },
+    async localPath(key) {
+      const full = resolveKey(key);
+      return (await Bun.file(full).exists()) ? full : null;
+    },
+  };
+}

package/src/server/storage/files/adapter.photo.display.spec.ts

@@ -0,0 +1,169 @@
+import { Database } from 'bun:sqlite';
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { isFfmpegAvailable } from '../../media-bun';
+import { runMigrations } from '../../migration/runner';
+import { createDiskStore } from '../diskStore';
+import type { MediaUrls } from '../sources';
+import { fsDisplayKey, type MediaCtx } from '../types';
+import { createCataloguePhotoSource } from './adapter';
+import { createSqliteFileCatalogue } from './catalogue';
+import type { FileUrls } from './fileRoutes';
+import { FILE_CATALOGUE_MIGRATIONS } from './migrations';
+import type { FileCatalogue, PrivateFileCatalogue } from './types';
+import { bytesStream } from 'cursedbelt-core/testing';
+
+// End-to-end: an HEIC photo must gain a browser-safe full-size display derivative + advertise it as
+// displayUrl; a normal JPEG must NOT (its raw url is already renderable).
+
+const haveFfmpeg = await isFfmpegAvailable();
+const CTX: MediaCtx = { userId: 'u1', tenantId: 't1' };
+
+const fakeFileUrls: FileUrls = {
+  async build(_ctx, fileId, mime) {
+    return { url: `/_files/s/tok/${fileId}?ct=${encodeURIComponent(mime)}` };
+  },
+};
+const fakeMediaUrls: MediaUrls = {
+  async build(_ctx, sourceId, videoId) {
+    const p = `/_media/s/tok/${sourceId}/${videoId}`;
+    return {
+      streamUrl: `${p}/media`,
+      hlsUrl: `${p}/hls`,
+      posterUrl: `${p}/poster`,
+      displayUrl: `${p}/display`,
+      vttUrl: `${p}/vtt`,
+      spriteUrl: `${p}/sprite`,
+    };
+  },
+};
+
+/** A real HEVC-in-HEIF still, the format sharp can't decode but ffmpeg can. */
+async function heicBytes(): Promise<Uint8Array | null> {
+  const dir = await mkdtemp(path.join(tmpdir(), 'fc-heic-src-'));
+  const dest = path.join(dir, 'src.heic');
+  const proc = Bun.spawn(
+    [
+      'ffmpeg',
+      '-hide_banner',
+      '-y',
+      '-f',
+      'lavfi',
+      '-i',
+      'testsrc=duration=1:size=800x600:rate=1',
+      '-frames:v',
+      '1',
+      '-c:v',
+      'libx265',
+      '-tag:v',
+      'hvc1',
+      '-f',
+      'hevc',
+      dest,
+    ],
+    { stdout: 'ignore', stderr: 'ignore' },
+  );
+  await proc.exited;
+  if (proc.exitCode !== 0) {
+    await rm(dir, { recursive: true, force: true });
+    return null; // libx265 not built in — caller skips
+  }
+  const bytes = new Uint8Array(await Bun.file(dest).arrayBuffer());
+  await rm(dir, { recursive: true, force: true });
+  return bytes;
+}
+
+// SKIPPED on a host without ffmpeg/ffprobe — it synthesizes and decodes real media. Runs by default wherever ffmpeg is installed.
+describe.skipIf(!haveFfmpeg)('photo display derivative (HEIC)', () => {
+  let db: Database;
+  let root: string;
+  let cat: FileCatalogue & PrivateFileCatalogue;
+
+  beforeAll(async () => {
+    db = new Database(':memory:');
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    root = await mkdtemp(path.join(tmpdir(), 'fc-photo-display-'));
+    cat = createSqliteFileCatalogue({
+      db,
+      store: createDiskStore(root),
+      workDir: path.join(root, 'w'),
+      owner: (c) => c.userId,
+    });
+  });
+  afterAll(async () => {
+    db.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const source = () =>
+    createCataloguePhotoSource({
+      id: 'photos',
+      title: 'Photos',
+      catalogue: cat,
+      fileUrls: fakeFileUrls,
+      mediaUrls: fakeMediaUrls,
+    });
+
+  const settle = async (id: string) => {
+    for (let i = 0; i < 60; i++) {
+      if ((await cat.get(CTX, id))?.hasThumbnail) break;
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  };
+
+  test('HEIC → display derivative stored + displayUrl advertised', async () => {
+    const bytes = await heicBytes();
+    if (!bytes) return; // no libx265 in this ffmpeg
+    const rec = await cat.ingest(CTX, {
+      name: 'photo.heic',
+      mime: 'image/heic',
+      body: bytesStream(bytes),
+    });
+    await settle(rec.id);
+
+    const store = createDiskStore(root);
+    expect(await store.stat(fsDisplayKey(CTX.userId, rec.id))).not.toBeNull();
+
+    const photo = await source().resolve(CTX, rec.id);
+    expect(photo?.thumbnailUrl).toBeDefined();
+    expect(photo?.displayUrl).toBe(`/_media/s/tok/photos/${rec.id}/display`);
+  });
+
+  test('JPEG → no display derivative, no displayUrl (raw is renderable)', async () => {
+    // A real JPEG sharp can resize.
+    const dir = await mkdtemp(path.join(tmpdir(), 'fc-jpg-'));
+    const jpgPath = path.join(dir, 'x.jpg');
+    const proc = Bun.spawn(
+      [
+        'ffmpeg',
+        '-hide_banner',
+        '-y',
+        '-f',
+        'lavfi',
+        '-i',
+        'testsrc=size=320x240:rate=1',
+        '-frames:v',
+        '1',
+        jpgPath,
+      ],
+      { stdout: 'ignore', stderr: 'ignore' },
+    );
+    await proc.exited;
+    const bytes = new Uint8Array(await Bun.file(jpgPath).arrayBuffer());
+    await rm(dir, { recursive: true, force: true });
+
+    const rec = await cat.ingest(CTX, {
+      name: 'photo.jpg',
+      mime: 'image/jpeg',
+      body: new Response(bytes).body as ReadableStream<Uint8Array>,
+    });
+    await settle(rec.id);
+
+    const store = createDiskStore(root);
+    expect(await store.stat(fsDisplayKey(CTX.userId, rec.id))).toBeNull();
+    const photo = await source().resolve(CTX, rec.id);
+    expect(photo?.displayUrl).toBeUndefined();
+  });
+});

package/src/server/storage/files/adapter.photo.spec.ts

@@ -0,0 +1,128 @@
+import { Database } from 'bun:sqlite';
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { runMigrations } from '../../migration/runner';
+import { createDiskStore } from '../diskStore';
+import type { MediaUrls } from '../sources';
+import type { MediaCtx } from '../types';
+import { createCataloguePhotoSource } from './adapter';
+import { createSqliteFileCatalogue } from './catalogue';
+import type { FileUrls } from './fileRoutes';
+import { FILE_CATALOGUE_MIGRATIONS } from './migrations';
+import type { FileCatalogue, PrivateFileCatalogue } from './types';
+
+// The photo source is an image-filtered VIEW over the catalogue: primary bytes via the file
+// route URL, grid thumb via the type-agnostic poster URL (only when the thumbnailer produced one).
+
+const CTX: MediaCtx = { userId: 'u1', tenantId: 't1' };
+const stream = (s: string) =>
+  new Response(new TextEncoder().encode(s)).body as ReadableStream<Uint8Array>;
+
+const fakeFileUrls: FileUrls = {
+  async build(_ctx, fileId, mime) {
+    return { url: `/_files/s/tok/${fileId}?ct=${encodeURIComponent(mime)}` };
+  },
+};
+const fakeMediaUrls: MediaUrls = {
+  async build(_ctx, sourceId, videoId) {
+    const p = `/_media/s/tok/${sourceId}/${videoId}`;
+    return {
+      streamUrl: `${p}/media`,
+      hlsUrl: `${p}/hls`,
+      posterUrl: `${p}/poster`,
+      displayUrl: `${p}/display`,
+      vttUrl: `${p}/vtt`,
+      spriteUrl: `${p}/sprite`,
+    };
+  },
+};
+
+describe('createCataloguePhotoSource', () => {
+  let db: Database;
+  let root: string;
+  let cat: FileCatalogue & PrivateFileCatalogue;
+  let photoId: string;
+  let videoId: string;
+
+  beforeAll(async () => {
+    db = new Database(':memory:');
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    root = await mkdtemp(path.join(tmpdir(), 'fc-photo-'));
+    let clock = 1;
+    cat = createSqliteFileCatalogue({
+      db,
+      store: createDiskStore(root),
+      workDir: path.join(root, 'w'),
+      owner: (c) => c.userId,
+      now: () => ++clock,
+    });
+  });
+  afterAll(async () => {
+    // The fake video's fire-and-forget transcode fails asynchronously — let it settle before
+    // closing the db, or its progress write hits a finalized statement between test files.
+    for (let i = 0; i < 40; i++) {
+      const status = (await cat.get(CTX, videoId))?.processingStatus;
+      if (status && status !== 'processing' && status !== 'pending') break;
+      await new Promise((r) => setTimeout(r, 50));
+    }
+    db.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const source = () =>
+    createCataloguePhotoSource({
+      id: 'photos',
+      title: 'Photos',
+      catalogue: cat,
+      fileUrls: fakeFileUrls,
+      mediaUrls: fakeMediaUrls,
+    });
+
+  test('lists ONLY images — video/doc rows are invisible to the photo view', async () => {
+    const img = await cat.ingest(CTX, {
+      name: 'a.jpg',
+      // a fake-jpeg text body: fine — the thumbnailer fails quietly and has_thumbnail stays 0
+      mime: 'image/jpeg',
+      body: stream('img-bytes'),
+      tags: ['trip'],
+    });
+    photoId = img.id;
+    videoId = (await cat.ingest(CTX, { name: 'b.mp4', mime: 'video/mp4', body: stream('vid') })).id;
+    await cat.ingest(CTX, { name: 'c.txt', mime: 'text/plain', body: stream('txt') });
+
+    const page = await source().list(CTX, {});
+    expect(page.items.map((p) => p.name)).toEqual(['a.jpg']);
+    const photo = page.items[0];
+    expect(photo.type).toBe('image');
+    expect(photo.url).toBe(`/_files/s/tok/${photoId}?ct=image%2Fjpeg`);
+    expect(photo.thumbnailUrl).toBeUndefined(); // no thumbnail produced for fake bytes
+    expect(photo.tags).toEqual(['trip']);
+  });
+
+  test('resolve: image → GalleryPhoto; non-image id → null', async () => {
+    expect((await source().resolve(CTX, photoId))?.name).toBe('a.jpg');
+    const all = await cat.list(CTX, {});
+    const video = all.items.find((f) => f.fileType === 'video');
+    expect(await source().resolve(CTX, video?.id ?? '')).toBeNull();
+  });
+
+  test('ingest rejects non-image uploads', async () => {
+    expect(
+      source().ingest?.(CTX, { name: 'x.mp4', mime: 'video/mp4', body: stream('v') }),
+    ).rejects.toThrow(/image/);
+  });
+
+  test('remove trashes (soft-deletes) through to the catalogue, not a hard delete', async () => {
+    const rec = await cat.ingest(CTX, {
+      name: 'gone.png',
+      mime: 'image/png',
+      body: stream('bye'),
+    });
+    await source().remove?.(CTX, rec.id);
+    // Trashed, not gone — the row + bytes survive until an explicit hard-delete (catalogue.remove).
+    expect((await cat.get(CTX, rec.id))?.trashedAt).toBeDefined();
+    expect((await source().list(CTX, {})).items.some((p) => p.id === rec.id)).toBe(false);
+  });
+});

package/src/server/storage/files/adapter.spec.ts

@@ -0,0 +1,121 @@
+import { Database } from 'bun:sqlite';
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { runMigrations } from '../../migration/runner';
+import { createDiskStore } from '../diskStore';
+import type { MediaUrls } from '../sources';
+import type { MediaCtx } from '../types';
+import { createCatalogueVideoSource, createFileToPlayable } from './adapter';
+import { createSqliteFileCatalogue } from './catalogue';
+import { FILE_CATALOGUE_MIGRATIONS } from './migrations';
+import type { FileCatalogue, FileRecord } from './types';
+
+const CTX: MediaCtx = { userId: 'u1', tenantId: 't1' };
+const stream = (s: string) =>
+  new Response(new TextEncoder().encode(s)).body as ReadableStream<Uint8Array>;
+
+// A fake URL builder — the real one signs a token; here we just echo the ids so the adapter's
+// URL wiring is testable without a signing service.
+const fakeUrls: MediaUrls = {
+  async build(_ctx, sourceId, videoId) {
+    const p = `/_media/s/tok/${sourceId}/${videoId}`;
+    return {
+      streamUrl: `${p}/media`,
+      hlsUrl: `${p}/hls`,
+      posterUrl: `${p}/poster`,
+      displayUrl: `${p}/display`,
+      vttUrl: `${p}/vtt`,
+      spriteUrl: `${p}/sprite`,
+    };
+  },
+};
+
+const videoRecord = (over: Partial<FileRecord> = {}): FileRecord => ({
+  id: 'v1',
+  name: 'clip.mp4',
+  mime: 'video/mp4',
+  size: 10,
+  fileType: 'video',
+  tags: ['fun'],
+  isPrivate: false,
+  favorite: false,
+  collectionIds: [],
+  hasThumbnail: true,
+  hasHls: true,
+  hasSprites: false,
+  durationSeconds: 12,
+  processingStatus: 'ready',
+  processingProgress: 100,
+  createdAt: 1,
+  updatedAt: 1,
+  ...over,
+});
+
+describe('createFileToPlayable', () => {
+  const toPlayable = createFileToPlayable(fakeUrls, 'files');
+
+  test('maps a ready video, gating optional URLs on capability flags', async () => {
+    const p = await toPlayable(CTX, videoRecord());
+    expect(p).not.toBeNull();
+    expect(p?.streamUrl).toBe('/_media/s/tok/files/v1/media');
+    expect(p?.hlsUrl).toBe('/_media/s/tok/files/v1/hls'); // hasHls
+    expect(p?.posterUrl).toBe('/_media/s/tok/files/v1/poster'); // hasThumbnail
+    expect(p?.vttUrl).toBeUndefined(); // hasSprites false
+    expect(p?.spriteUrl).toBeUndefined();
+    expect(p?.tags).toEqual(['fun']);
+    expect(p?.processingStatus).toBe('ready');
+  });
+
+  test('returns null for a non-video file', async () => {
+    expect(await toPlayable(CTX, videoRecord({ fileType: 'image', mime: 'image/png' }))).toBeNull();
+  });
+});
+
+describe('createCatalogueVideoSource (gallery = view over catalogue)', () => {
+  let db: Database;
+  let root: string;
+  let cat: FileCatalogue;
+
+  beforeAll(async () => {
+    db = new Database(':memory:');
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    root = await mkdtemp(path.join(tmpdir(), 'fc-adapter-'));
+    let clock = 1;
+    cat = createSqliteFileCatalogue({
+      db,
+      store: createDiskStore(root),
+      workDir: path.join(root, 'w'),
+      now: () => ++clock,
+    });
+    // Mix media types; only videos should surface through the gallery source.
+    await cat.ingest(CTX, { name: 'a.png', mime: 'image/png', body: stream('a'), tags: ['pic'] });
+    await cat.ingest(CTX, { name: 'doc.pdf', mime: 'application/pdf', body: stream('d') });
+  });
+  afterAll(async () => {
+    db.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test('lists only videos (none here) — images/docs are filtered out', async () => {
+    const src = createCatalogueVideoSource({
+      id: 'files',
+      title: 'Files',
+      catalogue: cat,
+      urls: fakeUrls,
+    });
+    const page = await src.list(CTX, {});
+    expect(page.items).toEqual([]); // catalogue has an image + a doc, zero videos
+  });
+
+  test('tags() reflects the catalogue facets', async () => {
+    const src = createCatalogueVideoSource({
+      id: 'files',
+      title: 'Files',
+      catalogue: cat,
+      urls: fakeUrls,
+    });
+    expect(await src.tags?.(CTX)).toContain('pic');
+  });
+});