v3: api/ gets one layout rule and keeps to it, and whatever crosses the wire is defined once, in shared/ — api/model/interfaces.ts and src/model.ts declared the same 40 types by hand and had drifted: the error envelope, email required on one side and optional on the other, Invitee/InviteTreeEntry and LinkPreview/UrlPreviewResponse for one shape each. The validation limits, the role permissions, the chat length cap, the @mention pattern and the Bandcamp and YouTube player responses were copied too, behind "keep in sync" comments. shared/ now holds them once, one file per domain (api, category, chat, comment, dump, follow, mention, notification, permissions, player, playlist, search, user, validation, ws), and imports nothing from either half. The server sends Dates; the client reads Wire<T>, the same type with every Date an ISO string, and turns it back with src/utils/shared/deserialize.ts. APIErrorCode becomes a const object, since the frontend's erasableSyntaxOnly rejects an enum. The shared types showed two real gaps: the avatar upload and GET /api/users/me return the full self user and the frontend read them as public users, and a stored session may predate media tokens, so the client keeps it as its own Session type. The backend rule: each folder holds one kind of module, each file is named after its domain. routes/ parse and answer; services/ hold the logic and every SQL query (lib/auth.ts's token check moves to user-service); remote/ is the only place that fetches from other sites — the guarded fetch and the HTML scraping out of rich-content-service, public-address, the Bandcamp and YouTube resolvers, the link providers, the image proxy (fetch, checks and cache, out of routes/preview.ts) and the Twemoji glyphs (out of lib/site-icons.ts). model/ holds per table a row type, its guard and its mappers; validators/ the request guards; db/connection.ts the handle and transaction(), db/startup.ts the purges and default admin that db.ts ran on import, called at the same moment. Tests mirror the source one file per module, test/<layer>/<module>.test.ts, with shared/'s under shared/test/ (deno task test runs both); the test that covered the bandcamp and soundcloud providers together is two now, and the backend can() has its own, so 202 tests. deno lint src/ is clean too: window.* becomes globalThis.*, and test bodies and act() callbacks that never awaited lose their async. The README states the rule. No behaviour changes; the catalogues only move their source references.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

api/remote/bandcamp-streams.ts

@@ -0,0 +1,136 @@
+import { APIErrorCode } from "../../shared/api.ts";
+import { APIException } from "../lib/api-exception.ts";
+import { fetchWithTimeout, isValidHttpUrl, readTextCapped } from "./fetch.ts";
+import { BANDCAMP_HOST_RE, parseTralbum } from "./bandcamp-tralbum.ts";
+import type { Tralbum } from "../../shared/player.ts";
+
+/**
+ * Resolves a Bandcamp page to its streamable tracks, at play time.
+ *
+ * Bandcamp's signed stream URLs expire 24h after the page fetch, so they can
+ * never be baked into `rich_content` at dump-creation time the way `embedUrl`
+ * is. This service is the play-time counterpart: the frontend asks for a page,
+ * gets a whole tracklist back, and plays the mp3s directly from bcbits.
+ */
+
+/** Comfortably inside the 24h signature life, so a cache hit is never a URL
+ * that is about to expire mid-listen. */
+const TTL_MS = 12 * 60 * 60 * 1000;
+const MAX_ENTRIES = 200;
+
+const cache = new Map<string, Tralbum>();
+
+/** Cache key: a page is the same page regardless of query, fragment or case. */
+function cacheKey(url: string): string {
+  try {
+    const u = new URL(url);
+    return `${u.protocol}//${u.hostname.toLowerCase()}${
+      u.pathname.replace(/\/+$/, "")
+    }`;
+  } catch {
+    return url;
+  }
+}
+
+function readCache(key: string): Tralbum | null {
+  const hit = cache.get(key);
+  if (!hit) return null;
+  if (Date.now() - hit.resolvedAt > TTL_MS) {
+    cache.delete(key);
+    return null;
+  }
+  return hit;
+}
+
+function writeCache(key: string, value: Tralbum): void {
+  // Map preserves insertion order, so the first key is the oldest write.
+  if (cache.size >= MAX_ENTRIES) {
+    const oldest = cache.keys().next().value;
+    if (oldest !== undefined) cache.delete(oldest);
+  }
+  cache.set(key, value);
+}
+
+/**
+ * Fetch and parse a Bandcamp page.
+ *
+ * `force` bypasses the cache — used by the client's re-resolve path, so a
+ * cached entry whose URLs have started 403ing can't keep being handed back.
+ */
+export async function resolveBandcamp(
+  pageUrl: string,
+  { force = false }: { force?: boolean } = {},
+): Promise<Tralbum> {
+  if (!isValidHttpUrl(pageUrl)) {
+    throw new APIException(
+      APIErrorCode.VALIDATION_ERROR,
+      400,
+      "Invalid URL",
+    );
+  }
+
+  let hostname: string;
+  try {
+    hostname = new URL(pageUrl).hostname;
+  } catch {
+    throw new APIException(APIErrorCode.VALIDATION_ERROR, 400, "Invalid URL");
+  }
+  if (!BANDCAMP_HOST_RE.test(hostname)) {
+    throw new APIException(
+      APIErrorCode.VALIDATION_ERROR,
+      400,
+      "Not a Bandcamp URL",
+    );
+  }
+
+  const key = cacheKey(pageUrl);
+  if (!force) {
+    const hit = readCache(key);
+    if (hit) return hit;
+  }
+
+  let res: Response;
+  try {
+    res = await fetchWithTimeout(pageUrl, 8000);
+  } catch {
+    throw new APIException(
+      APIErrorCode.SERVER_ERROR,
+      502,
+      "Could not reach Bandcamp",
+    );
+  }
+  // Every path out of here that doesn't read the body has to release it, or the
+  // connection stays open until GC. This endpoint is unauthenticated: a caller
+  // hammering random /track/<slug> URLs would otherwise leak one body a request.
+  if (!res.ok) {
+    await res.body?.cancel();
+    throw new APIException(
+      APIErrorCode.SERVER_ERROR,
+      502,
+      `Bandcamp returned ${res.status}`,
+    );
+  }
+  if (!(res.headers.get("content-type") ?? "").startsWith("text/html")) {
+    await res.body?.cancel();
+    throw new APIException(
+      APIErrorCode.SERVER_ERROR,
+      502,
+      "Bandcamp did not return a page",
+    );
+  }
+
+  const parsed = parseTralbum(await readTextCapped(res), pageUrl);
+  if (!parsed) {
+    // Covers "no data-tralbum", "hasAudio: false" and preorder-only releases
+    // with nothing streamable — all cases where the client falls back to the
+    // iframe embed rather than showing an error.
+    throw new APIException(
+      APIErrorCode.NOT_FOUND,
+      404,
+      "No streamable tracks on this page",
+    );
+  }
+
+  writeCache(key, parsed);
+  return parsed;
+}

api/remote/bandcamp-tralbum.ts

@@ -0,0 +1,124 @@
+/**
+ * Parser for Bandcamp's `data-tralbum` attribute.
+ *
+ * Every Bandcamp track and album page carries the whole release — titles,
+ * durations and signed mp3 stream URLs — as one HTML-escaped JSON blob on a
+ * `data-tralbum` attribute. One fetch of an album page therefore yields every
+ * track's stream URL; there is no per-track request.
+ *
+ * The stream URLs are signed and expire 24h after the page was fetched, which
+ * is why nothing here is ever persisted to `rich_content` — see
+ * `api/routes/bandcamp.ts` for the resolve-at-play-time endpoint.
+ *
+ * The shape is undocumented, so every field is treated as optional and the
+ * whole parse is best-effort: a `null` return means "not a Bandcamp page",
+ * which callers turn into a fallback to the iframe embed.
+ */
+
+import type { Tralbum, TralbumTrack } from "../../shared/player.ts";
+
+/** Hostnames Bandcamp serves its own sites from. Anchored at the end so that
+ * `bandcamp.com.example.org` cannot pass. Artists on custom domains do not
+ * match this and keep using the embed. */
+export const BANDCAMP_HOST_RE = /(?:^|\.)bandcamp\.com$/;
+
+/**
+ * Decode HTML entities in a single pass.
+ *
+ * The single pass is the point: `decodeHtmlEntities` in remote/html.ts
+ * replaces `&` before `"`, so an escaped-ampersand-then-quot sequence
+ * (`"`, i.e. the literal text `"` inside a title) decodes twice
+ * and yields a bare `"` — which lands inside the JSON string and breaks the
+ * parse. Matching every entity form in one regex means each is replaced once.
+ */
+function decodeEntitiesOnce(input: string): string {
+  const named: Record<string, string> = {
+    quot: '"',
+    apos: "'",
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    nbsp: " ",
+  };
+  return input.replace(
+    /&(?:#(\d+)|#[xX]([0-9a-fA-F]+)|([a-zA-Z]+));/g,
+    (match, dec: string, hex: string, name: string) => {
+      if (dec) return String.fromCodePoint(Number(dec));
+      if (hex) return String.fromCodePoint(parseInt(hex, 16));
+      return named[name.toLowerCase()] ?? match;
+    },
+  );
+}
+
+/** Resolve Bandcamp's protocol-relative and root-relative art URLs. */
+function artworkUrl(artId: unknown): string | undefined {
+  if (typeof artId !== "number" && typeof artId !== "string") return undefined;
+  const id = String(artId).trim();
+  if (!/^\d+$/.test(id)) return undefined;
+  // _16 is the large square art Bandcamp's own player uses.
+  return `https://f4.bcbits.com/img/a${id}_16.jpg`;
+}
+
+/**
+ * Pull the `data-tralbum` blob out of a Bandcamp page and normalise it.
+ * Returns null when the page has no blob, no audio, or nothing parseable.
+ */
+export function parseTralbum(html: string, sourceUrl: string): Tralbum | null {
+  const match = html.match(/\bdata-tralbum=(["'])([\s\S]*?)\1/);
+  if (!match) return null;
+
+  let raw: Record<string, unknown>;
+  try {
+    raw = JSON.parse(decodeEntitiesOnce(match[2]));
+  } catch {
+    return null;
+  }
+  if (!raw || typeof raw !== "object") return null;
+  if (raw.hasAudio === false) return null;
+
+  const rawTracks = Array.isArray(raw.trackinfo) ? raw.trackinfo : [];
+  const tracks: TralbumTrack[] = rawTracks.map((entry, index) => {
+    const t = (entry ?? {}) as Record<string, unknown>;
+    const file = (t.file ?? {}) as Record<string, unknown>;
+    const mp3 = typeof file["mp3-128"] === "string" ? file["mp3-128"] : null;
+    // Only ever hand out bcbits URLs. Without this the endpoint would relay
+    // whatever host a hostile page put in the blob straight to the browser.
+    const streamUrl = mp3 && isBcbitsUrl(mp3) ? mp3 : null;
+    return {
+      index,
+      trackNum: typeof t.track_num === "number" ? t.track_num : undefined,
+      title: typeof t.title === "string" && t.title.trim()
+        ? t.title
+        : `Track ${index + 1}`,
+      duration: typeof t.duration === "number" && t.duration > 0
+        ? t.duration
+        : undefined,
+      streamUrl,
+      streamable: streamUrl !== null && t.streaming === 1 &&
+        t.unreleased_track !== true && !t.encoding_pending,
+      capped: t.is_capped === true,
+    };
+  });
+
+  if (!tracks.some((t) => t.streamable)) return null;
+
+  const current = (raw.current ?? {}) as Record<string, unknown>;
+  return {
+    sourceUrl,
+    itemType: raw.item_type === "album" ? "album" : "track",
+    title: typeof current.title === "string" ? current.title : undefined,
+    artist: typeof raw.artist === "string" ? raw.artist : undefined,
+    artworkUrl: artworkUrl(raw.art_id),
+    tracks,
+    resolvedAt: Date.now(),
+  };
+}
+
+function isBcbitsUrl(url: string): boolean {
+  try {
+    const { protocol, hostname } = new URL(url);
+    return protocol === "https:" && /(?:^|\.)bcbits\.com$/.test(hostname);
+  } catch {
+    return false;
+  }
+}

api/remote/fetch.ts

@@ -0,0 +1,241 @@
+import { isPrivateHostname, resolvePublicAddress } from "./public-address.ts";
+import { isSelfUrl } from "../lib/self-url.ts";
+
+const FETCH_HEADERS = {
+  "User-Agent":
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36",
+  "Accept":
+    "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
+  "Accept-Language": "fr-FR,fr;q=0.9,en-US;q=0.8,en;q=0.7",
+};
+
+const MAX_REDIRECTS = 5;
+
+/**
+ * Fetch `url` via a `curl --insecure` subprocess and return a minimal Response.
+ * Used as a last resort when Deno's rustls rejects the server's TLS certificate
+ * due to an unsupported algorithm (e.g. UnsupportedSignatureAlgorithm).
+ * Returns null if curl is unavailable or exits non-zero.
+ *
+ * `address` pins the connection to the IP already checked by
+ * resolvePublicAddress, and curl doesn't follow redirects itself: a 3xx comes
+ * back with its Location so fetchWithTimeout can check the next hop too.
+ */
+async function fetchViaCurl(
+  url: URL,
+  address: string,
+  timeoutMs: number,
+): Promise<Response | null> {
+  const tmpPath = await Deno.makeTempFile();
+  const port = url.port || (url.protocol === "https:" ? "443" : "80");
+  const pinned = address.includes(":") ? `[${address}]` : address;
+  try {
+    const { code, stdout } = await new Deno.Command("curl", {
+      args: [
+        "--silent",
+        "--insecure",
+        "--proto",
+        "=http,https",
+        "--resolve",
+        `${url.hostname.replace(/^\[(.*)\]$/, "$1")}:${port}:${pinned}`,
+        "--max-time",
+        String(Math.ceil(timeoutMs / 1000)),
+        "--max-filesize",
+        String(2 * MAX_PAGE_BYTES),
+        "--user-agent",
+        FETCH_HEADERS["User-Agent"],
+        "--header",
+        `Accept: ${FETCH_HEADERS["Accept"]}`,
+        "--header",
+        `Accept-Language: ${FETCH_HEADERS["Accept-Language"]}`,
+        "--output",
+        tmpPath,
+        "--write-out",
+        "%{http_code}\n%{redirect_url}\n%{content_type}",
+        url.href,
+      ],
+      stdout: "piped",
+      stderr: "null",
+    }).output();
+
+    if (code !== 0) return null;
+
+    const [status, location, contentType = ""] = new TextDecoder()
+      .decode(stdout).split("\n").map((l) => l.trim());
+    const statusCode = Number(status);
+    if (!(statusCode >= 200 && statusCode <= 599)) return null;
+    const headers = new Headers();
+    if (location) headers.set("location", location);
+    if (contentType) headers.set("content-type", contentType);
+
+    const bytes = await Deno.readFile(tmpPath);
+    if (!contentType.startsWith("text/")) {
+      return new Response(bytes, { status: statusCode, headers });
+    }
+    // Decode using the charset declared in the Content-Type header so that
+    // pages served in ISO-8859-1, windows-1252, etc. are read correctly.
+    const charset = /charset=([\w-]+)/i.exec(contentType)?.[1] ?? "utf-8";
+    let bodyText: string;
+    try {
+      bodyText = new TextDecoder(charset, { fatal: false }).decode(bytes);
+    } catch {
+      bodyText = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+    }
+    headers.set("content-type", contentType.replace(/;.*$/, "; charset=utf-8"));
+    return new Response(bodyText, { status: statusCode, headers });
+  } catch {
+    return null;
+  } finally {
+    await Deno.remove(tmpPath).catch(() => {});
+  }
+}
+
+/**
+ * Most bytes of a fetched page that are read. Metadata lives in the <head>,
+ * and a "page" past this is a download, not something to scrape.
+ */
+export const MAX_PAGE_BYTES = 4 * 1024 * 1024;
+
+/**
+ * Hands `body` on, and clears the request's deadline once it has been read to
+ * the end or cancelled. Until then the deadline still applies: a server that
+ * answers at once and then drips its body can't hold the request open.
+ */
+function withDeadline(
+  body: ReadableStream<Uint8Array>,
+  timer: ReturnType<typeof setTimeout>,
+): ReadableStream<Uint8Array> {
+  const reader = body.getReader();
+  return new ReadableStream({
+    async pull(controller) {
+      try {
+        const { done, value } = await reader.read();
+        if (done) {
+          clearTimeout(timer);
+          controller.close();
+        } else {
+          controller.enqueue(value);
+        }
+      } catch (err) {
+        clearTimeout(timer);
+        controller.error(err);
+      }
+    },
+    cancel(reason) {
+      clearTimeout(timer);
+      return reader.cancel(reason);
+    },
+  });
+}
+
+/**
+ * Reads a response's body as text, stopping at `maxBytes` (the rest is
+ * cancelled, never downloaded).
+ */
+export async function readTextCapped(
+  res: Response,
+  maxBytes = MAX_PAGE_BYTES,
+): Promise<string> {
+  if (!res.body) return "";
+  const reader = res.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    while (size < maxBytes) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      size += value.byteLength;
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+  const bytes = new Uint8Array(Math.min(size, maxBytes));
+  let offset = 0;
+  for (const chunk of chunks) {
+    const part = chunk.subarray(0, bytes.byteLength - offset);
+    bytes.set(part, offset);
+    offset += part.byteLength;
+    if (offset >= bytes.byteLength) break;
+  }
+  return new TextDecoder().decode(bytes);
+}
+
+/** One request, no redirects followed. The timeout covers the body too. */
+async function fetchOnce(
+  url: URL,
+  address: string,
+  timeoutMs: number,
+): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      signal: controller.signal,
+      headers: FETCH_HEADERS,
+      redirect: "manual",
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    if (!(err instanceof TypeError && err.message.includes("certificate"))) {
+      throw err;
+    }
+
+    // Deno/rustls rejected the server's TLS certificate (expired, self-signed,
+    // or an unsupported signature algorithm) and offers no way to override
+    // verification programmatically. Fall back to a `curl --insecure`
+    // subprocess, which uses its own TLS stack.
+    const curlRes = await fetchViaCurl(url, address, timeoutMs);
+    if (curlRes) return curlRes;
+
+    throw err;
+  }
+  if (!res.body) {
+    clearTimeout(timer);
+    return res;
+  }
+  return new Response(withDeadline(res.body, timer), {
+    status: res.status,
+    statusText: res.statusText,
+    headers: res.headers,
+  });
+}
+
+/**
+ * Fetch a user-supplied URL. Every hop — the URL itself and each redirect —
+ * must resolve to a public address (see resolvePublicAddress), so a link or a
+ * redirect can't point the server at its own network.
+ */
+export async function fetchWithTimeout(
+  url: string,
+  timeoutMs = 5000,
+): Promise<Response> {
+  let current = new URL(url);
+  for (let hop = 0;; hop++) {
+    if (current.protocol !== "http:" && current.protocol !== "https:") {
+      throw new TypeError(`Unsupported protocol ${current.protocol}`);
+    }
+    const address = await resolvePublicAddress(current);
+    const res = await fetchOnce(current, address, timeoutMs);
+    const location = res.headers.get("location");
+    if (res.status < 300 || res.status >= 400 || !location) return res;
+
+    await res.body?.cancel();
+    if (hop >= MAX_REDIRECTS) throw new TypeError("Too many redirects");
+    current = new URL(location, current);
+  }
+}
+
+export function isValidHttpUrl(raw: string): boolean {
+  try {
+    const u = new URL(raw);
+    if (u.protocol !== "http:" && u.protocol !== "https:") return false;
+    // This site's own pages are fine even on a private host (e.g. localhost in
+    // development): selfProvider reads them from the DB, no HTTP involved.
+    // Every actual fetch is checked again, after DNS, in fetchWithTimeout.
+    return !isPrivateHostname(u) || isSelfUrl(u);
+  } catch {
+    return false;
+  }
+}

api/remote/html.ts

@@ -0,0 +1,403 @@
+function decodeHtmlEntities(str: string): string {
+  return str
+    .replace(/&/gi, "&")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&quot;/gi, '"')
+    .replace(/&apos;/gi, "'")
+    .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(Number(dec)))
+    .replace(
+      /&#x([0-9a-f]+);/gi,
+      (_, hex) => String.fromCodePoint(parseInt(hex, 16)),
+    );
+}
+
+/**
+ * Find the first `<meta>` tag whose `attr` equals `value` and return its
+ * `content` (either attribute ordering). Each tag is matched in isolation so
+ * the `content` capture can never span across tag boundaries.
+ */
+function extractMetaContent(
+  html: string,
+  attr: string,
+  value: string,
+): string | undefined {
+  const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const keyRe = new RegExp(`\\b${attr}=["']${escaped}["']`, "i");
+  const contentRe = /\bcontent=(["'])([\s\S]*?)\1/i;
+  const tagRe = /<meta\b[^>]*>/gi;
+  let m: RegExpExecArray | null;
+  while ((m = tagRe.exec(html)) !== null) {
+    const tag = m[0];
+    if (!keyRe.test(tag)) continue;
+    const content = contentRe.exec(tag);
+    if (content) return decodeHtmlEntities(content[2]);
+  }
+  return undefined;
+}
+
+export function extractOgTag(
+  html: string,
+  tag: string,
+): string | undefined {
+  return extractMetaContent(html, "property", `og:${tag}`);
+}
+
+/** Extract content from `<meta name="…" content="…">` (both attribute orderings). */
+export function extractMetaName(
+  html: string,
+  name: string,
+): string | undefined {
+  return extractMetaContent(html, "name", name);
+}
+
+/** Extract the text content of the `<title>` element. */
+export function extractPageTitle(html: string): string | undefined {
+  const match = html.match(/<title[^>]*>([^<]+)<\/title>/i);
+  return match ? decodeHtmlEntities(match[1].trim()) : undefined;
+}
+
+// ── Brand color helpers ───────────────────────────────────────────────────────
+
+/**
+ * Find the page's `theme-color`.
+ *
+ * Sites routinely ship the tag twice, scoped by `media`, and often list the
+ * dark-scheme one first — so unlike `extractMetaName` this can't just take the
+ * first match. Prefer the unscoped tag, then the light-scheme one, then any.
+ */
+export function extractThemeColor(html: string): string | undefined {
+  const tagRe = /<meta\b[^>]*>/gi;
+  const contentRe = /\bcontent=(["'])([\s\S]*?)\1/i;
+  const mediaRe = /\bmedia=(["'])([\s\S]*?)\1/i;
+  let unscoped: string | undefined;
+  let light: string | undefined;
+  let any: string | undefined;
+
+  let m: RegExpExecArray | null;
+  while ((m = tagRe.exec(html)) !== null) {
+    const tag = m[0];
+    if (!/\bname=["']theme-color["']/i.test(tag)) continue;
+    const content = contentRe.exec(tag)?.[2];
+    if (!content) continue;
+    const media = mediaRe.exec(tag)?.[2];
+    if (!media) unscoped ??= content;
+    else if (/light/i.test(media)) light ??= content;
+    any ??= content;
+  }
+  return unscoped ?? light ?? any;
+}
+
+/** Extract the `color` of `<link rel="mask-icon">` (Safari pinned tabs). */
+export function extractMaskIconColor(html: string): string | undefined {
+  const linkRe = /<link[^>]+>/gi;
+  let m: RegExpExecArray | null;
+  while ((m = linkRe.exec(html)) !== null) {
+    const tag = m[0];
+    if (!/\brel=["'][^"']*mask-icon[^"']*["']/i.test(tag)) continue;
+    const color = /\bcolor=(["'])([\s\S]*?)\1/i.exec(tag)?.[2];
+    if (color) return color;
+  }
+  return undefined;
+}
+
+// The handful of named colors that actually show up in `theme-color`. The full
+// 148-name table isn't worth carrying for the long tail.
+const NAMED_COLORS: Record<string, string> = {
+  black: "#000000",
+  white: "#ffffff",
+  red: "#ff0000",
+  green: "#008000",
+  blue: "#0000ff",
+  yellow: "#ffff00",
+  orange: "#ffa500",
+  purple: "#800080",
+  gray: "#808080",
+  grey: "#808080",
+  silver: "#c0c0c0",
+  maroon: "#800000",
+  navy: "#000080",
+  teal: "#008080",
+  olive: "#808000",
+  lime: "#00ff00",
+  aqua: "#00ffff",
+  cyan: "#00ffff",
+  fuchsia: "#ff00ff",
+  magenta: "#ff00ff",
+};
+
+function clampByte(n: number): number {
+  return Math.max(0, Math.min(255, Math.round(n)));
+}
+
+/**
+ * Normalize a CSS color to canonical lowercase `#rrggbb`, or `undefined` when
+ * it isn't one of the forms sites actually use. Alpha is dropped — the color is
+ * only ever used as a tint over the app's own surface.
+ */
+export function normalizeCssColor(raw: string | undefined): string | undefined {
+  if (!raw) return undefined;
+  const value = raw.trim().toLowerCase();
+
+  const named = NAMED_COLORS[value];
+  if (named) return named;
+
+  const hex = /^#([0-9a-f]{3,8})$/.exec(value)?.[1];
+  if (hex) {
+    if (hex.length === 3 || hex.length === 4) {
+      const [r, g, b] = [...hex.slice(0, 3)];
+      return `#${r}${r}${g}${g}${b}${b}`;
+    }
+    if (hex.length === 6 || hex.length === 8) return `#${hex.slice(0, 6)}`;
+    return undefined;
+  }
+
+  const rgb = /^rgba?\(([^)]+)\)$/.exec(value)?.[1];
+  if (rgb) {
+    const parts = rgb.split(/[\s,/]+/).filter(Boolean).slice(0, 3);
+    if (parts.length !== 3) return undefined;
+    const bytes = parts.map((p) => {
+      const n = parseFloat(p);
+      if (!Number.isFinite(n)) return NaN;
+      return clampByte(p.endsWith("%") ? (n / 100) * 255 : n);
+    });
+    if (bytes.some(Number.isNaN)) return undefined;
+    return `#${bytes.map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+  }
+
+  return undefined;
+}
+
+// ── JSON-LD helpers (file-private) ────────────────────────────────────────────
+
+type JsonLdResult = {
+  title?: string;
+  description?: string;
+  thumbnailUrl?: string;
+};
+
+function ldString(v: unknown): string | undefined {
+  if (typeof v === "string" && v.trim()) return v.trim();
+  if (Array.isArray(v) && typeof v[0] === "string" && v[0].trim()) {
+    return v[0].trim();
+  }
+  return undefined;
+}
+
+function ldImage(v: unknown): string | undefined {
+  if (
+    typeof v === "string" &&
+    (v.startsWith("http://") || v.startsWith("https://"))
+  ) return v;
+  if (Array.isArray(v)) return ldImage(v[0]);
+  if (v && typeof v === "object") {
+    const o = v as Record<string, unknown>;
+    return ldImage(o.url ?? o.contentUrl);
+  }
+  return undefined;
+}
+
+function ldExtractNode(data: unknown): JsonLdResult {
+  if (Array.isArray(data)) {
+    for (const item of data) {
+      const r = ldExtractNode(item);
+      if (r.title || r.thumbnailUrl) return r;
+    }
+    return {};
+  }
+  if (!data || typeof data !== "object") return {};
+  const o = data as Record<string, unknown>;
+  if (o["@graph"]) return ldExtractNode(o["@graph"]);
+  return {
+    title: ldString(o.name ?? o.headline),
+    description: ldString(o.description),
+    thumbnailUrl: ldImage(o.image ?? o.thumbnailUrl ?? o.thumbnail),
+  };
+}
+
+/**
+ * Parse every `<script type="application/ld+json">` block and return the first
+ * node that yields a title or image. Handles `@graph`, arrays, and the common
+ * `image` shapes (string, string[], ImageObject).
+ */
+export function extractJsonLd(html: string): JsonLdResult {
+  const pattern =
+    /<script[^>]+type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(html)) !== null) {
+    try {
+      const result = ldExtractNode(JSON.parse(match[1]));
+      if (result.title || result.thumbnailUrl) return result;
+    } catch { /* invalid JSON — skip */ }
+  }
+  return {};
+}
+
+/**
+ * Return the `src` of the first `<img>` whose declared width or height is at
+ * least `minSize` pixels (default 200). Skips data URIs. Resolves relative URLs.
+ */
+export function extractLargeImage(
+  html: string,
+  baseUrl: string,
+  minSize = 200,
+): string | undefined {
+  const imgPattern = /<img[^>]+>/gi;
+  let match: RegExpExecArray | null;
+  while ((match = imgPattern.exec(html)) !== null) {
+    const tag = match[0];
+    const src = /\bsrc=["']([^"']+)["']/i.exec(tag)?.[1];
+    if (!src || src.startsWith("data:")) continue;
+    const w = parseInt(/\bwidth=["']?(\d+)/i.exec(tag)?.[1] ?? "0");
+    const h = parseInt(/\bheight=["']?(\d+)/i.exec(tag)?.[1] ?? "0");
+    if (w >= minSize && h >= minSize) {
+      try {
+        return new URL(src, baseUrl).toString();
+      } catch {
+        continue;
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Collect all `<link rel="icon">` / `<link rel="apple-touch-icon">` tags, rank
+ * them by declared size (largest wins), and return the best resolved URL.
+ * Falls back to the first match when no `sizes` attribute is present.
+ *
+ * SVG icons are ranked above everything: they carry no `sizes` attribute, so
+ * they'd otherwise score 0 and lose to a 16×16 PNG, yet they scale cleanly to
+ * whatever size the placeholder renders them at.
+ */
+export function extractBestIcon(
+  html: string,
+  baseUrl: string,
+): string | undefined {
+  const linkRe = /<link[^>]+>/gi;
+  const relRe = /\brel=["']([^"']+)["']/i;
+  const hrefRe = /\bhref=["']([^"']+)["']/i;
+  const sizesRe = /\bsizes=["']([^"']+)["']/i;
+
+  const candidates: { href: string; area: number }[] = [];
+
+  let m: RegExpExecArray | null;
+  while ((m = linkRe.exec(html)) !== null) {
+    const tag = m[0];
+    const rel = relRe.exec(tag)?.[1] ?? "";
+    if (!/\bicon\b/i.test(rel) && !/apple-touch-icon/i.test(rel)) continue;
+    const href = hrefRe.exec(tag)?.[1];
+    if (!href) continue;
+    const sizesStr = sizesRe.exec(tag)?.[1] ?? "";
+    const sm = sizesStr.match(/(\d+)x(\d+)/i);
+    const isSvg = /\.svg(\?|$)/i.test(href) ||
+      /\btype=["']image\/svg\+xml["']/i.test(tag);
+    const area = isSvg
+      ? Number.MAX_SAFE_INTEGER
+      : sm
+      ? parseInt(sm[1]) * parseInt(sm[2])
+      : 0;
+    try {
+      candidates.push({ href: new URL(href, baseUrl).toString(), area });
+    } catch {
+      continue;
+    }
+  }
+
+  if (candidates.length === 0) return undefined;
+  candidates.sort((a, b) => b.area - a.area);
+  return candidates[0].href;
+}
+
+/**
+ * Return the `src` of the first `<img>` that looks like content rather than UI
+ * chrome. Skips SVGs, data URIs, and images whose filename matches common
+ * icon/logo/nav patterns (logo, icon, sprite, favicon, avatar, banner, etc.).
+ * Resolves relative and protocol-relative URLs.
+ */
+const UI_IMAGE_KEYWORDS = new Set([
+  "logo",
+  "icon",
+  "sprite",
+  "favicon",
+  "avatar",
+  "banner",
+  "header",
+  "nav",
+  "menu",
+  "cart",
+  "search",
+  "tracking",
+  "pixel",
+  "bg",
+  "background",
+]);
+
+function isUiImage(src: string): boolean {
+  if (/\.svg(\?|$)/i.test(src)) return true;
+  const filename = src.split("?")[0].split("/").pop() ?? "";
+  const baseName = filename.replace(/\.[^.]+$/, ""); // strip extension
+  // Split on common filename separators (-, _, .) and check each token
+  return baseName.toLowerCase().split(/[-_.]/).some((t) =>
+    UI_IMAGE_KEYWORDS.has(t)
+  );
+}
+
+/**
+ * Return the `src` of the first `<img>` that looks like content rather than UI
+ * chrome. Skips SVGs, data URIs, and images whose filename tokens match common
+ * icon/logo/nav patterns (logo, icon, sprite, etc.).
+ * Resolves relative and protocol-relative URLs.
+ */
+export function extractFirstContentImage(
+  html: string,
+  baseUrl: string,
+): string | undefined {
+  const imgPattern = /<img[^>]+>/gi;
+  let match: RegExpExecArray | null;
+  while ((match = imgPattern.exec(html)) !== null) {
+    const tag = match[0];
+    const src = /\bsrc=["']([^"']+)["']/i.exec(tag)?.[1];
+    if (!src || src.startsWith("data:")) continue;
+    if (isUiImage(src)) continue;
+    try {
+      return new URL(src, baseUrl).toString();
+    } catch {
+      continue;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Extract `href` from the first `<link rel="…">` whose rel contains `relFragment`,
+ * resolved to an absolute URL using `baseUrl`.
+ */
+export function extractLinkHref(
+  html: string,
+  relFragment: string,
+  baseUrl: string,
+): string | undefined {
+  const escaped = relFragment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const patterns = [
+    new RegExp(
+      `<link[^>]+rel=["'][^"']*${escaped}[^"']*["'][^>]+href=["']([^"']+)["']`,
+      "i",
+    ),
+    new RegExp(
+      `<link[^>]+href=["']([^"']+)["'][^>]+rel=["'][^"']*${escaped}[^"']*["']`,
+      "i",
+    ),
+  ];
+  for (const pattern of patterns) {
+    const match = html.match(pattern);
+    if (match) {
+      try {
+        return new URL(match[1], baseUrl).toString();
+      } catch {
+        return undefined;
+      }
+    }
+  }
+  return undefined;
+}

api/remote/image-proxy.ts

@@ -0,0 +1,106 @@
+import { fetchWithTimeout } from "./fetch.ts";
+
+export interface ProxiedImage {
+  bytes: Uint8Array;
+  contentType: string;
+}
+
+const PROXYABLE_IMAGE_TYPES = new Set([
+  "image/jpeg",
+  "image/png",
+  "image/gif",
+  "image/webp",
+  "image/avif",
+  "image/bmp",
+  "image/x-icon",
+  "image/vnd.microsoft.icon",
+]);
+
+// Proxied images, by URL: every viewer of a feed asks for the same
+// thumbnails, which were fetched from their hosts again for each one. Bounded
+// by total size; the least recently used go first.
+const IMAGE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const IMAGE_CACHE_MAX_BYTES = 32 * 1024 * 1024;
+const imageCache = new Map<
+  string,
+  { bytes: Uint8Array; contentType: string; at: number }
+>();
+let imageCacheBytes = 0;
+
+function readImageCache(
+  url: string,
+): { bytes: Uint8Array; contentType: string } | undefined {
+  const hit = imageCache.get(url);
+  if (!hit) return undefined;
+  imageCache.delete(url);
+  if (Date.now() - hit.at > IMAGE_CACHE_TTL_MS) {
+    imageCacheBytes -= hit.bytes.byteLength;
+    return undefined;
+  }
+  imageCache.set(url, hit); // most recently used
+  return hit;
+}
+
+function writeImageCache(
+  url: string,
+  bytes: Uint8Array,
+  contentType: string,
+): void {
+  const old = imageCache.get(url);
+  if (old) {
+    imageCache.delete(url);
+    imageCacheBytes -= old.bytes.byteLength;
+  }
+  while (
+    imageCacheBytes + bytes.byteLength > IMAGE_CACHE_MAX_BYTES &&
+    imageCache.size > 0
+  ) {
+    const [oldestUrl, oldest] = imageCache.entries().next().value!;
+    imageCache.delete(oldestUrl);
+    imageCacheBytes -= oldest.bytes.byteLength;
+  }
+  imageCache.set(url, { bytes, contentType, at: Date.now() });
+  imageCacheBytes += bytes.byteLength;
+}
+
+/** Forget every proxied image (tests). */
+export function clearImageCache(): void {
+  imageCache.clear();
+  imageCacheBytes = 0;
+}
+
+/**
+ * The image at `url`, from the cache or else from its host; null when the host
+ * answers with something that isn't a raster image of 5 MB at most. Throws when
+ * the host can't be reached.
+ */
+export async function fetchProxiedImage(
+  url: string,
+): Promise<ProxiedImage | null> {
+  const cached = readImageCache(url);
+  if (cached) return cached;
+
+  const res = await fetchWithTimeout(url, 8000);
+  // Raster formats only. The bytes go out under this site's origin, so an
+  // SVG (which can carry script) or anything else a browser might execute
+  // would run with the app's origin if opened directly.
+  const contentType = (res.headers.get("content-type") ?? "")
+    .split(";")[0].trim().toLowerCase();
+  if (!PROXYABLE_IMAGE_TYPES.has(contentType)) {
+    await res.body?.cancel();
+    return null;
+  }
+
+  const MAX_SIZE = 5 * 1024 * 1024; // 5 MB
+  const contentLength = Number(res.headers.get("content-length") ?? "0");
+  if (contentLength > MAX_SIZE) {
+    await res.body?.cancel();
+    return null;
+  }
+
+  const bytes = new Uint8Array(await res.arrayBuffer());
+  if (bytes.length > MAX_SIZE) return null;
+
+  writeImageCache(url, bytes, contentType);
+  return { bytes, contentType };
+}

api/remote/providers/bandcamp.ts

@@ -0,0 +1,40 @@
+import type { RichContent } from "../../../shared/dump.ts";
+import type { RichContentProvider } from "./provider.ts";
+import { extractOgTag } from "../html.ts";
+import { fetchWithTimeout, readTextCapped } from "../fetch.ts";
+
+const BANDCAMP_REGEX = /(?:^|\.)bandcamp\.com/;
+
+export const bandcampProvider: RichContentProvider = {
+  name: "bandcamp",
+
+  matches(url: string): boolean {
+    try {
+      return BANDCAMP_REGEX.test(new URL(url).hostname);
+    } catch {
+      return false;
+    }
+  },
+
+  async fetch(url: string): Promise<RichContent> {
+    const res = await fetchWithTimeout(url);
+    const contentType = res.headers.get("content-type") ?? "";
+
+    if (!contentType.startsWith("text/html")) {
+      await res.body?.cancel();
+      return { type: "bandcamp", siteName: "Bandcamp", url };
+    }
+
+    const html = await readTextCapped(res);
+
+    return {
+      type: "bandcamp",
+      siteName: "Bandcamp",
+      url,
+      title: extractOgTag(html, "title"),
+      description: extractOgTag(html, "description"),
+      thumbnailUrl: extractOgTag(html, "image"),
+      embedUrl: extractOgTag(html, "video") ?? undefined,
+    };
+  },
+};

api/remote/providers/generic.ts

@@ -0,0 +1,100 @@
+import type { RichContent } from "../../../shared/dump.ts";
+import type { RichContentProvider } from "./provider.ts";
+import {
+  extractBestIcon,
+  extractFirstContentImage,
+  extractJsonLd,
+  extractLargeImage,
+  extractMaskIconColor,
+  extractMetaName,
+  extractOgTag,
+  extractPageTitle,
+  extractThemeColor,
+  normalizeCssColor,
+} from "../html.ts";
+import { fetchWithTimeout, readTextCapped } from "../fetch.ts";
+
+export const genericProvider: RichContentProvider = {
+  name: "generic",
+
+  matches(_url: string): boolean {
+    return true; // fallback — always matches
+  },
+
+  async fetch(url: string): Promise<RichContent> {
+    const res = await fetchWithTimeout(url);
+    const contentType = res.headers.get("content-type") ?? "";
+
+    if (!contentType.startsWith("text/html")) {
+      await res.body?.cancel();
+      return { type: "generic", url };
+    }
+
+    const html = await readTextCapped(res);
+    const ld = extractJsonLd(html);
+
+    // If og:url is present but points to a different page (e.g. the homepage),
+    // the og: block is a site-level fallback, not page-specific metadata.
+    // In that case skip og:title and og:image so page-level signals win.
+    const ogUrl = extractOgTag(html, "url");
+    const useOg = !ogUrl || (() => {
+      try {
+        const ogPath = new URL(ogUrl).pathname.replace(/\/+$/, "") || "/";
+        const pagePath = new URL(url).pathname.replace(/\/+$/, "") || "/";
+        return ogPath === pagePath;
+      } catch {
+        return true;
+      }
+    })();
+
+    // Title: og:title (page-matched) → twitter:title → JSON-LD → <title>
+    const title = (useOg ? extractOgTag(html, "title") : undefined) ??
+      extractMetaName(html, "twitter:title") ??
+      ld.title ??
+      extractPageTitle(html);
+
+    // Site name: og:site_name → hostname
+    const siteName = extractOgTag(html, "site_name") ??
+      new URL(url).hostname.replace(/^www\./, "");
+
+    // Description: og:description → twitter:description → JSON-LD → <meta name="description">
+    const description = extractOgTag(html, "description") ??
+      extractMetaName(html, "twitter:description") ??
+      ld.description ??
+      extractMetaName(html, "description");
+
+    // Image: og:image (page-matched) → twitter:image → JSON-LD → large <img> →
+    // first content <img>. The chain deliberately stops there: a favicon is not
+    // artwork, and pretending otherwise means every art-less page gets a 16×16
+    // icon cover-cropped into a 128×72 box. No match here means "no artwork",
+    // and the frontend draws a generated placeholder instead.
+    const thumbnailUrl = (useOg ? extractOgTag(html, "image") : undefined) ??
+      extractMetaName(html, "twitter:image") ??
+      ld.thumbnailUrl ??
+      extractLargeImage(html, url) ??
+      extractFirstContentImage(html, url);
+
+    // Icon and brand color are independent facts about the page, so they're
+    // collected whether or not there's artwork. `/favicon.ico` is a guess; when
+    // it 404s the placeholder falls back to the site's initial.
+    const faviconUrl = extractBestIcon(html, url) ??
+      `${new URL(url).origin}/favicon.ico`;
+
+    const accentColor = normalizeCssColor(
+      extractThemeColor(html) ??
+        extractMetaName(html, "msapplication-TileColor") ??
+        extractMaskIconColor(html),
+    );
+
+    return {
+      type: "generic",
+      url,
+      title,
+      description,
+      thumbnailUrl,
+      faviconUrl,
+      accentColor,
+      siteName,
+    };
+  },
+};

api/remote/providers/provider.ts

@@ -0,0 +1,8 @@
+import type { RichContent } from "../../../shared/dump.ts";
+
+/** Metadata for the links one kind of site serves. */
+export interface RichContentProvider {
+  name: string;
+  matches(url: string): boolean;
+  fetch(url: string): Promise<RichContent>;
+}

api/remote/providers/self.ts

@@ -0,0 +1,89 @@
+import type { RichContent } from "../../../shared/dump.ts";
+import type { RichContentProvider } from "./provider.ts";
+import { getDump } from "../../services/dump-service.ts";
+import { getUserByUsername } from "../../services/user-service.ts";
+import { getPlaylistById } from "../../services/playlist-service.ts";
+import { PUBLIC_URL, THEME_COLOR } from "../../config.ts";
+import { isSelfUrl } from "../../lib/self-url.ts";
+
+const DUMP_RE = /^\/dumps\/([^/]+)$/;
+const USER_RE = /^\/users\/([^/]+)$/;
+const PLAYLIST_RE = /^\/playlists\/([^/]+)$/;
+
+// Internal links carry gerbeur's own branding, so an art-less one still gets a
+// recognizable placeholder instead of a generic tint.
+const SELF_BRANDING = {
+  siteName: "gerbeur",
+  faviconUrl: `${PUBLIC_URL}/apple-touch-icon.png`,
+  accentColor: THEME_COLOR,
+} as const;
+
+export const selfProvider: RichContentProvider = {
+  name: "self",
+
+  matches(url: string): boolean {
+    try {
+      return isSelfUrl(new URL(url));
+    } catch {
+      return false;
+    }
+  },
+
+  fetch(url: string): Promise<RichContent> {
+    const { pathname } = new URL(url);
+
+    const dumpMatch = pathname.match(DUMP_RE);
+    if (dumpMatch) {
+      const dump = getDump(dumpMatch[1]);
+      let thumbnailUrl: string | undefined;
+      if (dump.kind === "file" && dump.fileMime?.startsWith("image/")) {
+        thumbnailUrl = `${PUBLIC_URL}/api/files/${dump.id}`;
+      } else if (dump.richContent?.thumbnailUrl) {
+        thumbnailUrl = dump.richContent.thumbnailUrl;
+      }
+      return Promise.resolve({
+        type: "generic",
+        url,
+        ...SELF_BRANDING,
+        title: dump.title,
+        description: dump.comment,
+        thumbnailUrl,
+      });
+    }
+
+    const userMatch = pathname.match(USER_RE);
+    if (userMatch) {
+      const user = getUserByUsername(userMatch[1]);
+      const thumbnailUrl = user.avatarMime
+        ? `${PUBLIC_URL}/api/avatars/${user.id}`
+        : undefined;
+      return Promise.resolve({
+        type: "generic",
+        url,
+        ...SELF_BRANDING,
+        title: user.username,
+        description: user.description,
+        thumbnailUrl,
+      });
+    }
+
+    const playlistMatch = pathname.match(PLAYLIST_RE);
+    if (playlistMatch) {
+      const playlist = getPlaylistById(playlistMatch[1]);
+      const thumbnailUrl = playlist.imageMime
+        ? `${PUBLIC_URL}/api/playlists/${playlist.id}/image`
+        : undefined;
+      return Promise.resolve({
+        type: "generic",
+        url,
+        ...SELF_BRANDING,
+        title: playlist.title,
+        description: playlist.description,
+        thumbnailUrl,
+      });
+    }
+
+    // Should not reach here if matches() is correct
+    return Promise.resolve({ type: "generic", url });
+  },
+};

api/remote/providers/soundcloud.ts

@@ -0,0 +1,40 @@
+import type { RichContent } from "../../../shared/dump.ts";
+import type { RichContentProvider } from "./provider.ts";
+import { extractOgTag } from "../html.ts";
+import { fetchWithTimeout, readTextCapped } from "../fetch.ts";
+
+export const soundcloudProvider: RichContentProvider = {
+  name: "soundcloud",
+
+  matches(url: string): boolean {
+    try {
+      return new URL(url).hostname === "soundcloud.com";
+    } catch {
+      return false;
+    }
+  },
+
+  async fetch(url: string): Promise<RichContent> {
+    const res = await fetchWithTimeout(url);
+    const contentType = res.headers.get("content-type") ?? "";
+
+    if (!contentType.startsWith("text/html")) {
+      await res.body?.cancel();
+      return { type: "soundcloud", siteName: "SoundCloud", url };
+    }
+
+    const html = await readTextCapped(res);
+
+    return {
+      type: "soundcloud",
+      siteName: "SoundCloud",
+      url,
+      title: extractOgTag(html, "title"),
+      description: extractOgTag(html, "description"),
+      thumbnailUrl: extractOgTag(html, "image"),
+      embedUrl: `https://w.soundcloud.com/player/?url=${
+        encodeURIComponent(url)
+      }&visual=true&auto_play=false`,
+    };
+  },
+};

api/remote/providers/youtube.ts

@@ -0,0 +1,178 @@
+import type { RichContent } from "../../../shared/dump.ts";
+import type { RichContentProvider } from "./provider.ts";
+import { extractOgTag } from "../html.ts";
+import { fetchWithTimeout, readTextCapped } from "../fetch.ts";
+
+function extractVideoId(url: string): string | null {
+  try {
+    const u = new URL(url);
+    if (u.hostname === "youtu.be") {
+      return u.pathname.slice(1).split("/")[0] || null;
+    }
+    if (u.hostname === "youtube.com" || u.hostname === "www.youtube.com") {
+      if (u.pathname === "/watch" || u.pathname.startsWith("/watch?")) {
+        return u.searchParams.get("v");
+      }
+      if (
+        u.pathname.startsWith("/embed/") || u.pathname.startsWith("/shorts/")
+      ) {
+        return u.pathname.split("/")[2] || null;
+      }
+    }
+  } catch {
+    // invalid URL
+  }
+  return null;
+}
+
+function extractPlaylistId(url: string): string | null {
+  try {
+    return new URL(url).searchParams.get("list");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract the playback offset in seconds from a YouTube URL.
+ * Accepts `t` (plain seconds, `90s`, or `1h2m3s` / `20m5s` forms) and `start`
+ * (plain seconds). Returns null when absent or unparseable.
+ */
+function extractStartSeconds(url: string): number | null {
+  let raw: string | null;
+  try {
+    const u = new URL(url);
+    raw = u.searchParams.get("t") ?? u.searchParams.get("start");
+  } catch {
+    return null;
+  }
+  if (!raw) return null;
+
+  const plain = /^\d+$/.exec(raw);
+  if (plain) return Number(raw);
+
+  const hms = /^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/i.exec(raw);
+  if (!hms || (!hms[1] && !hms[2] && !hms[3])) return null;
+  return Number(hms[1] ?? 0) * 3600 + Number(hms[2] ?? 0) * 60 +
+    Number(hms[3] ?? 0);
+}
+
+/** Matches /channel/UC…, /@handle, /c/name, /user/name */
+function extractChannelPath(url: string): string | null {
+  try {
+    const u = new URL(url);
+    if (u.hostname === "youtube.com" || u.hostname === "www.youtube.com") {
+      if (
+        u.pathname.startsWith("/channel/") ||
+        u.pathname.startsWith("/@") ||
+        u.pathname.startsWith("/c/") ||
+        u.pathname.startsWith("/user/")
+      ) {
+        return u.pathname;
+      }
+    }
+  } catch {
+    // invalid URL
+  }
+  return null;
+}
+
+async function fetchOEmbed(
+  url: string,
+): Promise<{ title?: string; thumbnailUrl?: string }> {
+  try {
+    const oembedUrl = `https://www.youtube.com/oembed?url=${
+      encodeURIComponent(url)
+    }&format=json`;
+    const res = await fetchWithTimeout(oembedUrl);
+    if (res.ok) {
+      const data = await res.json() as {
+        title?: string;
+        thumbnail_url?: string;
+      };
+      return { title: data.title, thumbnailUrl: data.thumbnail_url };
+    }
+    await res.body?.cancel();
+  } catch {
+    // oembed failed — carry on
+  }
+  return {};
+}
+
+export const youtubeProvider: RichContentProvider = {
+  name: "youtube",
+
+  matches(url: string): boolean {
+    return (
+      extractVideoId(url) !== null ||
+      extractPlaylistId(url) !== null ||
+      extractChannelPath(url) !== null
+    );
+  },
+
+  async fetch(url: string): Promise<RichContent> {
+    const videoId = extractVideoId(url);
+    const listId = extractPlaylistId(url);
+    const channelPath = extractChannelPath(url);
+
+    // ── Channel ───────────────────────────────────────────────────────────────
+    if (channelPath && !videoId) {
+      // oEmbed doesn't support channel URLs — scrape og:image from the page instead
+      let title: string | undefined;
+      let thumbnailUrl: string | undefined;
+      try {
+        const res = await fetchWithTimeout(url);
+        if (res.ok) {
+          const html = await readTextCapped(res);
+          title = extractOgTag(html, "title");
+          thumbnailUrl = extractOgTag(html, "image");
+        } else {
+          await res.body?.cancel();
+        }
+      } catch {
+        // scrape failed — carry on with undefined values
+      }
+      return {
+        type: "youtube",
+        siteName: "YouTube",
+        url,
+        title,
+        thumbnailUrl,
+        // channels are not embeddable as a player
+      };
+    }
+
+    // ── Playlist (no specific video) ──────────────────────────────────────────
+    if (listId && !videoId) {
+      const { title, thumbnailUrl } = await fetchOEmbed(url);
+      return {
+        type: "youtube",
+        siteName: "YouTube",
+        url,
+        title,
+        thumbnailUrl,
+        embedUrl:
+          `https://www.youtube.com/embed/videoseries?list=${listId}&rel=0`,
+      };
+    }
+
+    // ── Video (with optional playlist context) ────────────────────────────────
+    const thumbnailUrl = `https://img.youtube.com/vi/${videoId}/hqdefault.jpg`;
+    const { title } = await fetchOEmbed(url);
+
+    const embedParams = new URLSearchParams({ rel: "0" });
+    if (listId) embedParams.set("list", listId);
+    const start = extractStartSeconds(url);
+    if (start) embedParams.set("start", String(start));
+
+    return {
+      type: "youtube",
+      siteName: "YouTube",
+      url,
+      videoId: videoId!,
+      title,
+      thumbnailUrl,
+      embedUrl: `https://www.youtube.com/embed/${videoId}?${embedParams}`,
+    };
+  },
+};

api/remote/public-address.ts

@@ -0,0 +1,142 @@
+/**
+ * Guards for server-side fetches of user-supplied URLs (link previews, the
+ * image proxy, Bandcamp resolution): the server must not become a way to reach
+ * addresses only it can see — loopback, the LAN, container networks, or the
+ * cloud metadata endpoint at 169.254.169.254.
+ */
+
+function parseIPv4(s: string): number[] | null {
+  const parts = s.split(".");
+  if (parts.length !== 4) return null;
+  const bytes = parts.map((p) => /^\d{1,3}$/.test(p) ? Number(p) : NaN);
+  return bytes.every((b) => b >= 0 && b <= 255) ? bytes : null;
+}
+
+function isPrivateIPv4([a, b]: number[]): boolean {
+  return a === 0 || // "this" network
+    a === 10 ||
+    a === 127 ||
+    (a === 100 && b >= 64 && b <= 127) || // carrier-grade NAT
+    (a === 169 && b === 254) || // link-local, cloud metadata
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 0) || // IETF protocol assignments (192.0.0.0/24 …)
+    (a === 192 && b === 168) ||
+    (a === 198 && (b === 18 || b === 19)) || // benchmarking
+    a >= 224; // multicast, reserved, broadcast
+}
+
+/** 16 bytes, or null when `s` isn't an IPv6 address. */
+function parseIPv6(s: string): number[] | null {
+  let addr = s.toLowerCase().replace(/%.*$/, ""); // drop a zone id
+  // An embedded dotted quad (::ffff:10.0.0.1) becomes the last two groups.
+  const lastColon = addr.lastIndexOf(":");
+  if (lastColon === -1) return null;
+  const tail = addr.slice(lastColon + 1);
+  if (tail.includes(".")) {
+    const v4 = parseIPv4(tail);
+    if (!v4) return null;
+    addr = `${addr.slice(0, lastColon + 1)}${
+      ((v4[0] << 8) | v4[1]).toString(16)
+    }:${((v4[2] << 8) | v4[3]).toString(16)}`;
+  }
+  const halves = addr.split("::");
+  if (halves.length > 2) return null;
+  const head = halves[0] ? halves[0].split(":") : [];
+  const rest = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+  const fill = 8 - head.length - rest.length;
+  if (halves.length === 1 ? fill !== 0 : fill < 1) return null;
+  const groups = [
+    ...head,
+    ...Array(halves.length === 2 ? fill : 0).fill("0"),
+    ...rest,
+  ];
+  if (!groups.every((g) => /^[0-9a-f]{1,4}$/.test(g))) return null;
+  return groups.flatMap((g) => {
+    const n = parseInt(g, 16);
+    return [n >> 8, n & 0xff];
+  });
+}
+
+function isPrivateIPv6(b: number[]): boolean {
+  const zeroPrefix = (n: number) => b.slice(0, n).every((x) => x === 0);
+  // IPv4 carried inside IPv6 is judged as the IPv4 address it carries.
+  if (zeroPrefix(10) && b[10] === 0xff && b[11] === 0xff) { // ::ffff:a.b.c.d
+    return isPrivateIPv4(b.slice(12));
+  }
+  if (zeroPrefix(12)) { // ::, ::1 and the deprecated ::a.b.c.d
+    return true;
+  }
+  if (
+    // 64:ff9b::/96 NAT64
+    b[0] === 0 && b[1] === 0x64 && b[2] === 0xff && b[3] === 0x9b &&
+    b.slice(4, 12).every((x) => x === 0)
+  ) return isPrivateIPv4(b.slice(12));
+  if (b[0] === 0x20 && b[1] === 0x02) { // 2002::/16 6to4
+    return isPrivateIPv4(b.slice(2, 6));
+  }
+  return (b[0] & 0xfe) === 0xfc || // fc00::/7 unique local
+    (b[0] === 0xfe && (b[1] & 0xc0) === 0x80) || // fe80::/10 link-local
+    (b[0] === 0xfe && (b[1] & 0xc0) === 0xc0) || // fec0::/10 site-local
+    b[0] === 0xff; // multicast
+}
+
+/** True for an IP literal outside the public internet. Non-IPs are false. */
+export function isPrivateAddress(ip: string): boolean {
+  const v4 = parseIPv4(ip);
+  if (v4) return isPrivateIPv4(v4);
+  const v6 = parseIPv6(ip);
+  return v6 ? isPrivateIPv6(v6) : false;
+}
+
+function isIpLiteral(host: string): boolean {
+  return parseIPv4(host) !== null || parseIPv6(host) !== null;
+}
+
+/** `URL.hostname` keeps the brackets around an IPv6 literal. */
+function bareHostname(url: URL): string {
+  return url.hostname.replace(/^\[(.*)\]$/, "$1");
+}
+
+/**
+ * The synchronous part of the check: a hostname that is a private IP literal,
+ * or a name that is local by definition. Names still need resolving (see
+ * resolvePublicAddress) — this only rejects what is obvious without DNS.
+ */
+export function isPrivateHostname(url: URL): boolean {
+  const host = bareHostname(url).toLowerCase();
+  if (host === "localhost" || host.endsWith(".localhost")) return true;
+  return isPrivateAddress(host);
+}
+
+/**
+ * Resolves `url`'s host and returns one of its addresses, or throws if the
+ * host is private or any address it resolves to is (a name with both a public
+ * and a private record is refused outright, since the fetch may pick either).
+ *
+ * The fetch itself resolves again, so a DNS server answering differently the
+ * second time (rebinding) isn't fully excluded; the curl fallback pins the
+ * address this returns.
+ */
+export async function resolvePublicAddress(url: URL): Promise<string> {
+  if (isPrivateHostname(url)) {
+    throw new Error(`Refusing to fetch private address ${url.hostname}`);
+  }
+  const host = bareHostname(url);
+  if (isIpLiteral(host)) return host;
+
+  const results = await Promise.allSettled([
+    Deno.resolveDns(host, "A"),
+    Deno.resolveDns(host, "AAAA"),
+  ]);
+  const addresses = results.flatMap((r) =>
+    r.status === "fulfilled" ? r.value : []
+  );
+  if (addresses.length === 0) {
+    throw new Error(`Could not resolve ${host}`);
+  }
+  const blocked = addresses.find(isPrivateAddress);
+  if (blocked) {
+    throw new Error(`Refusing to fetch ${host}: resolves to ${blocked}`);
+  }
+  return addresses[0];
+}

api/remote/twemoji.ts

@@ -0,0 +1,36 @@
+// Pinned Twemoji release.
+const TWEMOJI_VERSION = "16.0.1";
+
+// Cache the fetched glyph per emoji so repeated runs don't re-hit the network.
+const glyphCache = new Map<string, string>();
+
+/**
+ * Twemoji's plain vector-path SVG for `emoji`, whose file is named `cp` (see
+ * emojiToCodepoint in lib/site-icons.ts).
+ */
+export async function fetchTwemojiSvg(
+  emoji: string,
+  cp: string,
+): Promise<string> {
+  const cached = glyphCache.get(cp);
+  if (cached) return cached;
+  const url =
+    `https://cdn.jsdelivr.net/gh/jdecked/twemoji@${TWEMOJI_VERSION}/assets/svg/${cp}.svg`;
+  let res: Response;
+  try {
+    res = await fetch(url);
+  } catch (cause) {
+    throw new Error(
+      `Failed to fetch Twemoji glyph for "${emoji}" (${cp}) from ${url}`,
+      { cause },
+    );
+  }
+  if (!res.ok) {
+    throw new Error(
+      `Failed to fetch Twemoji glyph for "${emoji}" (${cp}) from ${url}: ${res.status} ${res.statusText}`,
+    );
+  }
+  const svg = await res.text();
+  glyphCache.set(cp, svg);
+  return svg;
+}

api/remote/youtube-playlist.ts

@@ -0,0 +1,208 @@
+import { APIErrorCode } from "../../shared/api.ts";
+import { APIException } from "../lib/api-exception.ts";
+import { readTextCapped } from "./fetch.ts";
+import type {
+  YouTubePlaylist,
+  YouTubePlaylistTrack,
+} from "../../shared/player.ts";
+
+/**
+ * Resolves a YouTube playlist to its tracklist, at play time.
+ *
+ * Playback itself stays in the iframe embed — YouTube plays the list and
+ * advances through it on its own. This only supplies what the embed doesn't
+ * expose: every entry's title and length, so the global player can draw a
+ * tracklist the way it does for a Bandcamp album. The client syncs the
+ * highlighted row and row clicks through the IFrame Player API.
+ *
+ * The data comes from the `ytInitialData` blob on the public playlist page. Its
+ * shape is undocumented and changes, so the parse is best-effort and accepts
+ * both the current `lockupViewModel` rows and the older `playlistVideoRenderer`
+ * ones. Only the first page (100 entries) is read; the client appends any
+ * further IDs the player reports, untitled.
+ */
+
+/** Titles and lengths rarely change; a stale entry only mislabels a row. */
+const TTL_MS = 6 * 60 * 60 * 1000;
+const MAX_ENTRIES = 200;
+
+const cache = new Map<string, { value: YouTubePlaylist; at: number }>();
+
+/** Playlist IDs are URL-safe base64-ish: PL…, OLAK5uy_…, RD… (mixes). */
+const LIST_ID_RE = /^[\w-]{2,64}$/;
+
+const HEADERS = {
+  "User-Agent":
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
+  "Accept": "text/html",
+  "Accept-Language": "en-US,en;q=0.8",
+  // Pre-answered consent: without it EU requests are redirected to
+  // consent.youtube.com and never see the playlist.
+  "Cookie": "SOCS=CAI",
+};
+
+/** "3:55", "1:02:03" → seconds. */
+function parseClock(text: string): number | undefined {
+  if (!/^\d+(?::\d{1,2}){1,2}$/.test(text)) return undefined;
+  return text.split(":").reduce((acc, part) => acc * 60 + Number(part), 0);
+}
+
+/** Depth-first walk collecting every value stored under `key`. */
+function collect(node: unknown, key: string, out: unknown[]): void {
+  if (Array.isArray(node)) {
+    for (const child of node) collect(child, key, out);
+  } else if (node && typeof node === "object") {
+    for (const [k, v] of Object.entries(node)) {
+      if (k === key) out.push(v);
+      else collect(v, key, out);
+    }
+  }
+}
+
+function firstString(node: unknown, key: string): string | undefined {
+  const found: unknown[] = [];
+  collect(node, key, found);
+  return found.find((v): v is string => typeof v === "string");
+}
+
+/** Follows `path` into parsed JSON; undefined wherever a step is missing. */
+function at(node: unknown, ...path: (string | number)[]): unknown {
+  let cur = node;
+  for (const key of path) {
+    if (cur === null || typeof cur !== "object") return undefined;
+    cur = (cur as Record<string | number, unknown>)[key];
+  }
+  return cur;
+}
+
+function fromLockup(lockup: unknown): YouTubePlaylistTrack | null {
+  if (at(lockup, "contentType") !== "LOCKUP_CONTENT_TYPE_VIDEO") return null;
+  const videoId = at(lockup, "contentId");
+  const title = at(
+    lockup,
+    "metadata",
+    "lockupMetadataViewModel",
+    "title",
+    "content",
+  );
+  if (typeof videoId !== "string" || typeof title !== "string") return null;
+  const badges: unknown[] = [];
+  collect(at(lockup, "contentImage"), "thumbnailBadgeViewModel", badges);
+  const duration = badges
+    .map((b) => at(b, "text"))
+    .filter((t): t is string => typeof t === "string")
+    .map(parseClock)
+    .find((d) => d !== undefined);
+  return { videoId, title, duration };
+}
+
+function fromLegacyRenderer(r: unknown): YouTubePlaylistTrack | null {
+  const videoId = at(r, "videoId");
+  const title = at(r, "title", "runs", 0, "text") ??
+    at(r, "title", "simpleText");
+  if (typeof videoId !== "string" || typeof title !== "string") return null;
+  const secs = Number(at(r, "lengthSeconds"));
+  return {
+    videoId,
+    title,
+    duration: Number.isFinite(secs) && secs > 0 ? secs : undefined,
+  };
+}
+
+export function parsePlaylistPage(
+  html: string,
+  listId: string,
+): YouTubePlaylist | null {
+  const start = html.indexOf("var ytInitialData = ");
+  if (start < 0) return null;
+  const end = html.indexOf(";</script>", start);
+  if (end < 0) return null;
+
+  let data: unknown;
+  try {
+    data = JSON.parse(html.slice(start + "var ytInitialData = ".length, end));
+  } catch {
+    return null;
+  }
+
+  const lockups: unknown[] = [];
+  collect(at(data, "contents"), "lockupViewModel", lockups);
+  const legacy: unknown[] = [];
+  collect(at(data, "contents"), "playlistVideoRenderer", legacy);
+
+  // A video can appear in a playlist twice; both rows are kept, so the list
+  // stays positional and matches what the embed plays.
+  const tracks = [
+    ...lockups.map(fromLockup),
+    ...legacy.map(fromLegacyRenderer),
+  ].filter((t): t is YouTubePlaylistTrack => t !== null);
+  if (tracks.length === 0) return null;
+
+  const metaTitle = at(data, "metadata", "playlistMetadataRenderer", "title");
+  const title = typeof metaTitle === "string"
+    ? metaTitle
+    : firstString(at(data, "header"), "content");
+  return { listId, title, tracks };
+}
+
+export async function resolveYouTubePlaylist(
+  listId: string,
+): Promise<YouTubePlaylist> {
+  if (!LIST_ID_RE.test(listId)) {
+    throw new APIException(
+      APIErrorCode.VALIDATION_ERROR,
+      400,
+      "Invalid playlist ID",
+    );
+  }
+
+  const hit = cache.get(listId);
+  if (hit && Date.now() - hit.at < TTL_MS) return hit.value;
+  if (hit) cache.delete(listId);
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 8000);
+  let html: string;
+  try {
+    const res = await fetch(
+      `https://www.youtube.com/playlist?list=${encodeURIComponent(listId)}`,
+      { headers: HEADERS, signal: controller.signal },
+    );
+    if (!res.ok) {
+      await res.body?.cancel();
+      throw new APIException(
+        APIErrorCode.SERVER_ERROR,
+        502,
+        `YouTube returned ${res.status}`,
+      );
+    }
+    html = await readTextCapped(res);
+  } catch (err) {
+    if (err instanceof APIException) throw err;
+    throw new APIException(
+      APIErrorCode.SERVER_ERROR,
+      502,
+      "Could not reach YouTube",
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+
+  const parsed = parsePlaylistPage(html, listId);
+  if (!parsed) {
+    // Private, deleted, or auto-generated mixes (RD…) that have no playlist
+    // page — the client just shows the embed without a tracklist.
+    throw new APIException(
+      APIErrorCode.NOT_FOUND,
+      404,
+      "No tracks on this playlist",
+    );
+  }
+
+  if (cache.size >= MAX_ENTRIES) {
+    const oldest = cache.keys().next().value;
+    if (oldest !== undefined) cache.delete(oldest);
+  }
+  cache.set(listId, { value: parsed, at: Date.now() });
+  return parsed;
+}