v4: what the server and the client both state is declared once — several rules were written out in two or more files, some already drifting apart. A link's site name (its host without www.) was computed in five places, now shared/url.ts's siteHost; dumpFileVersion, which the frontend and the server had to keep equal by hand, is one function in shared/dump.ts; the Markdown flattening of the chat's reply previews and the digest's quotes is shared/markdown.ts's markdownToPlainText, so the digest also keeps an image's alt text; an attachment's URL and how to find one in a text are shared/attachment.ts, which the editor, Markdown and attachment-service read, its id pattern the new UUID_RE that the file and thumbnail routes check ids with. On the server, the Bandcamp, YouTube playlist and link preview caches use one TtlCache (api/lib/ttl-cache.ts) instead of three copies of the same expiry and eviction; the link previews' theme-color and the emails' theme tokens read colours with one parser (api/lib/css-color.ts), and a transparent theme-color now gives no tint; the WebSocket route sends through ws-service's send, the welcome included, so it is type-checked; fetch.ts strips an IPv6 literal's brackets with public-address's bareHostname; and a category's slug is checked by the same validateSlug as a dump's, with its own length. The migrations keep their frozen copies, as they document. 272 backend tests and 677 frontend tests pass, and deno check, tsc, eslint and doc:lint are clean.

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

shared/attachment.ts

@@ -0,0 +1,37 @@
+/**
+ * Says where an image pasted into a text lives, and how to find it again in
+ * the text. The editor uploads the image and writes a link to it into the
+ * Markdown; the server binds the attachments a saved text links to that text,
+ * and `Markdown` gives a private one the viewer's media token.
+ *
+ * @module
+ */
+
+import { UUID_RE } from "./validation.ts";
+
+/**
+ * Returned by `POST /api/attachments` to the text editor, which inserts the
+ * image into the body as a link to {@link attachmentPath}.
+ */
+export interface AttachmentResponse {
+  id: string;
+}
+
+/** Returns the API path of attachment `id`, to which the API's base is added. */
+export function attachmentPath(id: string): string {
+  return `/api/attachments/${id}`;
+}
+
+const ID = UUID_RE.source.slice(1, -1);
+const ATTACHMENT_LINK_RE = new RegExp(`/api/attachments/(${ID})`, "g");
+const ATTACHMENT_URL_RE = new RegExp(`/api/attachments/${ID}$`);
+
+/** Returns the ids of the attachments `text` links to, in order. */
+export function attachmentIdsIn(text: string): string[] {
+  return [...text.matchAll(ATTACHMENT_LINK_RE)].map((m) => m[1]);
+}
+
+/** Checks whether `url` is an attachment's, with no query yet. */
+export function isAttachmentUrl(url: string): boolean {
+  return ATTACHMENT_URL_RE.test(url);
+}

shared/dump.ts

@@ -142,9 +142,15 @@ export interface UpdateDumpRequest {
 }
 
 /**
- * Returned by `POST /api/attachments` to the text editor, which inserts the
- * image into the body as a link to `GET /api/attachments/:id`.
+ * Returns a file dump's version, which the file and thumbnail URLs carry as
+ * `?v=`: the frontend's `dumpFileUrl` and `dumpThumbnailUrl`, and the digest's
+ * thumbnails. It changes whenever the file may have, so the file and thumbnail
+ * routes cache a URL naming the current one for good and revalidate any other.
+ * Without its dates, a dump gets a version no route serves as current.
  */
-export interface AttachmentResponse {
-  id: string;
+export function dumpFileVersion(
+  dump: { fileSize?: number; createdAt?: Date; updatedAt?: Date },
+): string {
+  const at = dump.updatedAt ?? dump.createdAt;
+  return `${dump.fileSize ?? 0}-${at ? at.getTime() : 0}`;
 }

shared/markdown.ts

@@ -0,0 +1,28 @@
+/**
+ * Flattens the Markdown users write into one line of plain text, where a
+ * quote of it can't render markup: the chat's reply previews and the digest
+ * email's quotes of a comment or a note.
+ *
+ * @module
+ */
+
+/**
+ * Returns the Markdown `md` as one line of plain text. Images become their alt
+ * text, or `imageLabel` without one, and links their text. It also takes a
+ * body cut short, possibly inside a link, as the server cuts a chat message's
+ * `replyToBody`: the unfinished link then shows as its text, without half a
+ * URL.
+ */
+export function markdownToPlainText(md: string, imageLabel: string): string {
+  return md
+    // An image or link cut short at the end loses its unfinished target.
+    .replace(/!\[([^\]]*)\]\([^)]*$/, (_, alt: string) => alt || imageLabel)
+    .replace(/(^|[^!])\[([^\]]*)\]\([^)]*$/, "$1$2")
+    .replace(/!\[[^\]]*$/, "")
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, (_, alt: string) => alt || imageLabel)
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/^\s{0,3}(#{1,6}|>|[-*+]|\d+\.)\s+/gm, "")
+    .replace(/```\w*|\*\*|__|~~|[*`]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}

shared/test/markdown.test.ts

@@ -0,0 +1,35 @@
+import { assertEquals } from "@std/assert";
+import { markdownToPlainText } from "../markdown.ts";
+
+Deno.test("markdownToPlainText: links become their text, images their alt or a label", () => {
+  assertEquals(
+    markdownToPlainText("see [this](https://x.y) now", "img"),
+    "see this now",
+  );
+  assertEquals(markdownToPlainText("![cat](a.png)", "Image"), "cat");
+  assertEquals(markdownToPlainText("![](a.png)", "Image"), "Image");
+});
+Deno.test("markdownToPlainText: markup characters and block markers go", () => {
+  assertEquals(
+    markdownToPlainText("# Title\n> quote\n- **bold** `code`", ""),
+    "Title quote bold code",
+  );
+});
+Deno.test("markdownToPlainText: a body cut off mid-link doesn't show a half URL", () => {
+  assertEquals(
+    markdownToPlainText("look [here](https://exa", "img"),
+    "look here",
+  );
+  assertEquals(
+    markdownToPlainText("pic ![alt](https://exa", "Image"),
+    "pic alt",
+  );
+  assertEquals(
+    markdownToPlainText("pic ![](https://exa", "Image"),
+    "pic Image",
+  );
+  assertEquals(markdownToPlainText("pic ![unfinished", "Image"), "pic");
+});
+Deno.test("markdownToPlainText: whitespace collapses to one line", () => {
+  assertEquals(markdownToPlainText("a\n\n  b\tc", ""), "a b c");
+});

shared/url.ts

@@ -0,0 +1,28 @@
+/**
+ * Names the site a link points at, as the app shows it: a link dump's title
+ * when its page has none, a preview's site name, the digest's domain line and
+ * the tint of a card without artwork. The server's link checks key on it too
+ * (`canonical-url.ts`), so a link reads as the same site everywhere.
+ *
+ * @module
+ */
+
+/**
+ * Returns `url`'s host without a leading `www.`; `URL` has already lowered
+ * its case. `www.youtube.com` and `youtube.com` give `youtube.com`.
+ */
+export function siteHostOf(url: URL): string {
+  return url.hostname.replace(/^www\./, "");
+}
+
+/**
+ * Returns {@link siteHostOf} the URL `raw`, or undefined when `raw` isn't
+ * one.
+ */
+export function siteHost(raw: string): string | undefined {
+  try {
+    return siteHostOf(new URL(raw));
+  } catch {
+    return undefined;
+  }
+}

shared/validation.ts

@@ -46,6 +46,14 @@ export const RENAME_LIMITS = {
   SLUG: { count: 3, windowMs: 24 * 3_600_000 },
 } as const;
 
+/**
+ * Matches an id the server makes with `crypto.randomUUID()`. A route checks
+ * one before it names a file on disk, and shared/attachment.ts finds the
+ * attachments a text links by it.
+ */
+export const UUID_RE: RegExp =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
 /**
  * Matches an email address well enough to catch a typo; only the reset email
  * arriving proves it.