@morphemecms/cms 0.14.0-next-20261107080444 → 0.14.0

package/CHANGELOG.md

@@ -1,18 +1,22 @@
 # @morphemecms/cms
 
-## 0.14.0-next-20261107080444
+## 0.14.0
 
 ### Minor Changes
 
 - a70c310: Apps can be turned off without uninstalling them; the app page shows the app's version.
+- 26e7adc: The editor footer has links to support, system status, security reports, the privacy policy and the licenses, and a copyright line. System status shows whether GitHub and Cloudflare work for your site.
+- 4c30155: The Morpheme page shows a friendly note for each change: why, how and what.
 
 ### Patch Changes
 
+- da37368: The Enabled switch on an app's page sits right below the app's description.
 - dd625db: Editor menu: Advanced is now Developer, with Parts and Caching and builds in it. Parts moved from Appearance; old links still work.
 - 5cd4149: Editor menu: "Lists" is now "Dynamic lists", one row that opens the page with all lists (no fold-out).
 - 1fe1daa: The text toolbar is no taller than its tools on a phone, and it stays as far from the top of the screen as from the sides while you scroll.
 - b47a580: Google preview looks more like Google: a flat result on a phone, no card on a computer, a ringed site icon, https:// in the address, the ⋮ menu, a larger phone title, and the primary keyword in bold in the description.
 - 006c78b: The connection to Morpheme moves from the store screens to the Morpheme page under Settings, with the Morpheme logo.
+- a4da24e: System status checks only the Cloudflare services your site uses, so a site without R2 or D1 is not marked down by them.
 
 ## 0.13.0
 

package/lib/changelog.d.mts

@@ -4,6 +4,13 @@
  * @returns {Promise<Uint8Array>}
  */
 export function gunzip(bytes: Uint8Array): Promise<Uint8Array>;
+/**
+ * The bytes of the entry named exactly `path` in a tar, or null when there is none.
+ * @param {Uint8Array} tar
+ * @param {string} path
+ * @returns {Uint8Array | null}
+ */
+export function bytesFromTar(tar: Uint8Array, path: string): Uint8Array | null;
 /**
  * The UTF-8 text of the entry named exactly `path` in a tar, or null when there is none.
  * @param {Uint8Array} tar

package/lib/changelog.mjs

@@ -1,5 +1,5 @@
 // A version's release notes, read from its npm tarball: unzips the tarball, finds CHANGELOG.md in the tar and cuts out the
-// sections between two versions. Exposes gunzip, fileFromTar and sectionsBetween. Depends on ./cms-version.mjs; no node: imports
+// sections between two versions. Exposes gunzip, bytesFromTar, fileFromTar and sectionsBetween. Depends on ./cms-version.mjs; no node: imports
 // (runs in a Cloudflare Worker and in Node 18+).
 import { compareVersions } from './cms-version.mjs';
 
@@ -21,12 +21,12 @@ function field(header, start, end) {
 }
 
 /**
- * The UTF-8 text of the entry named exactly `path` in a tar, or null when there is none.
+ * The bytes of the entry named exactly `path` in a tar, or null when there is none.
  * @param {Uint8Array} tar
  * @param {string} path
- * @returns {string | null}
+ * @returns {Uint8Array | null}
  */
-export function fileFromTar(tar, path) {
+export function bytesFromTar(tar, path) {
   let offset = 0;
   while (offset + 512 <= tar.length) {
     const header = tar.subarray(offset, offset + 512);
@@ -35,12 +35,23 @@ export function fileFromTar(tar, path) {
     const prefix = field(header, 345, 500);
     const size = parseInt(field(header, 124, 136).trim(), 8) || 0;
     const data = tar.subarray(offset + 512, offset + 512 + size);
-    if ((prefix ? prefix + '/' + name : name) === path) return new TextDecoder().decode(data);
+    if ((prefix ? prefix + '/' + name : name) === path) return data;
     offset += 512 + Math.ceil(size / 512) * 512;
   }
   return null;
 }
 
+/**
+ * The UTF-8 text of the entry named exactly `path` in a tar, or null when there is none.
+ * @param {Uint8Array} tar
+ * @param {string} path
+ * @returns {string | null}
+ */
+export function fileFromTar(tar, path) {
+  const bytes = bytesFromTar(tar, path);
+  return bytes === null ? null : new TextDecoder().decode(bytes);
+}
+
 /**
  * The changelog's sections for versions after `from` up to and including `to`, newest first, without empty ones.
  * @param {string} changelog

package/lib/footerClearance.d.mts

@@ -0,0 +1 @@
+export function needsClearance(pageHeight: number, windowHeight: number, hasFab: boolean): boolean;

package/lib/footerClearance.mjs

@@ -0,0 +1,9 @@
+// Whether a screen needs clearance under its footer for the floating action button: only when it has one and its content
+// pushes the footer below the window, so a short screen has its footer at the very bottom. Exposes needsClearance. No imports.
+
+/**
+ * @param {number} pageHeight The page's height with no clearance added.
+ * @param {number} windowHeight The window's height.
+ * @param {boolean} hasFab Whether the screen shows a FAB.
+ */
+export const needsClearance = (pageHeight, windowHeight, hasFab) => hasFab && pageHeight > windowHeight;

package/lib/footerClearance.test.mjs

@@ -0,0 +1,24 @@
+// Tests for lib/footerClearance.mjs: clearance under the footer only for a FAB, and only when the page is taller than the window.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { needsClearance } from './footerClearance.mjs';
+
+test('a page that fits the window needs no clearance', () => {
+  assert.equal(needsClearance(600, 800, true), false);
+});
+
+test('a page exactly as tall as the window needs none', () => {
+  assert.equal(needsClearance(800, 800, true), false);
+});
+
+test('a tall page with a FAB needs clearance', () => {
+  assert.equal(needsClearance(801, 800, true), true);
+});
+
+test('a tall page without a FAB needs none', () => {
+  assert.equal(needsClearance(2000, 800, false), false);
+});
+
+test('a short page without a FAB needs none', () => {
+  assert.equal(needsClearance(600, 800, false), false);
+});

package/lib/footerLinks.d.mts

@@ -0,0 +1,12 @@
+/** @typedef {{ id: 'support' | 'status' | 'terms' | 'security' | 'privacy' | 'licenses', href: string | null }} FooterLink */
+/** @type {FooterLink[]} A link with `href: null` is not shown yet. */
+export const FOOTER_LINKS: FooterLink[];
+export function copyright(year: number): string;
+export function visibleLinks(links: FooterLink[]): (FooterLink & {
+    href: string;
+})[];
+export function isExternal(href: string): boolean;
+export type FooterLink = {
+    id: "support" | "status" | "terms" | "security" | "privacy" | "licenses";
+    href: string | null;
+};

package/lib/footerLinks.mjs

@@ -0,0 +1,26 @@
+// The links in the editor's footer, in the order they are shown, and its copyright line (EditorFooter.tsx).
+// Exposes FOOTER_LINKS, copyright, visibleLinks and isExternal. No imports.
+
+/** @typedef {{ id: 'support' | 'status' | 'terms' | 'security' | 'privacy' | 'licenses', href: string | null }} FooterLink */
+
+/** @type {FooterLink[]} A link with `href: null` is not shown yet. */
+export const FOOTER_LINKS = [
+  { id: 'support', href: 'https://github.com/larsadolfsen/morpheme-cms/issues' },
+  { id: 'status', href: '#status' },
+  { id: 'terms', href: null },
+  { id: 'security', href: 'https://github.com/larsadolfsen/morpheme-cms/security' },
+  { id: 'privacy', href: 'https://getmorpheme.com/privacy-policy/' },
+  { id: 'licenses', href: '#licenses' },
+];
+
+/** The copyright line for a year (the caller passes the current one: this has no Date). @param {number} year */
+export const copyright = (year) => `© ${year} Lars Adolfsen`;
+
+/**
+ * @param {FooterLink[]} links
+ * @returns {(FooterLink & { href: string })[]}
+ */
+export const visibleLinks = (links) => /** @type {(FooterLink & { href: string })[]} */ (links.filter((link) => link.href !== null));
+
+/** Whether a link leaves the editor (opens in a new tab). @param {string} href */
+export const isExternal = (href) => href.startsWith('https://');

package/lib/footerLinks.test.mjs

@@ -0,0 +1,32 @@
+// Tests for lib/footerLinks.mjs: which links the footer shows, and which of them leave the editor.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { copyright, FOOTER_LINKS, isExternal, visibleLinks } from './footerLinks.mjs';
+
+test('while terms has no URL, the footer shows 5 links and no terms', () => {
+  const shown = visibleLinks(FOOTER_LINKS);
+  assert.equal(shown.length, 5);
+  assert.equal(
+    shown.some((l) => l.id === 'terms'),
+    false,
+  );
+});
+
+test('with a terms URL, the footer shows 6 links and terms is third', () => {
+  const links = FOOTER_LINKS.map((l) => (l.id === 'terms' ? { ...l, href: 'https://example.com/terms' } : l));
+  const shown = visibleLinks(links);
+  assert.equal(shown.length, 6);
+  assert.equal(shown[2].id, 'terms');
+});
+
+test('each external href starts with https://, and the others stay in the editor', () => {
+  for (const { href } of visibleLinks(FOOTER_LINKS)) {
+    assert.equal(isExternal(href), href.startsWith('https://'));
+    assert.equal(isExternal(href), !href.startsWith('#'));
+  }
+});
+
+test('the copyright line has the year it is given', () => {
+  assert.equal(copyright(2026), '© 2026 Lars Adolfsen');
+  assert.equal(copyright(2027), '© 2027 Lars Adolfsen');
+});

package/lib/menu.test.mjs

@@ -240,11 +240,11 @@ test('Find apps is the first item under Apps, then the apps installed, and Devel
   );
 });
 
-test('Analytics, SEO, the SEO rating and Licenses are not in the menu', () => {
-  for (const gone of ['analytics', 'seo', 'rating', 'licenses']) {
+test('Analytics, SEO, the SEO rating, Licenses and System status are not in the menu', () => {
+  for (const gone of ['analytics', 'seo', 'rating', 'licenses', 'status']) {
     assert.equal(allIds.includes(gone), false);
   }
-  for (const gone of ['#analytics', '#seo', '#seo/rating', '#licenses']) {
+  for (const gone of ['#analytics', '#seo', '#seo/rating', '#licenses', '#status']) {
     assert.equal(allHrefs.includes(gone), false);
   }
 });

package/lib/releaseNotes.d.mts

@@ -0,0 +1,136 @@
+/**
+ * The size in pixels of a WebP image, read from its header (a lossy VP8, a lossless VP8L or an extended VP8X chunk).
+ * @param {Uint8Array} bytes
+ * @returns {ImageSize | null} null when `bytes` is not a WebP of one of these kinds
+ */
+export function webpSize(bytes: Uint8Array): ImageSize | null;
+/**
+ * The problems in the pending notes: a note missing in a locale, a kind that differs between locales, and each problem of
+ * entryProblems. Names the file and the locale of each problem.
+ * @param {Pending} pending
+ * @returns {string[]} empty when all good
+ */
+export function problemsOf(pending: Pending): string[];
+/**
+ * The pending notes of each locale as one release of `version`: the notes as they are in their files, sorted by id, and the
+ * ids of the cards that have a screenshot. A locale without notes is left out.
+ * @param {Pending} pending
+ * @param {string} version
+ * @returns {Record<string, { file: ReleasedNotes, images: string[] }>}
+ */
+export function released(pending: Pending, version: string): Record<string, {
+    file: ReleasedNotes;
+    images: string[];
+}>;
+/**
+ * The repository path of a released screenshot.
+ * @param {string} version
+ * @param {string} locale
+ * @param {string} id
+ * @returns {string}
+ */
+export function imagePath(version: string, locale: string, id: string): string;
+/**
+ * The notes for a locale, else the en-US notes, else undefined.
+ * @param {Record<string, ReleaseNote[]> | undefined} notes
+ * @param {string} locale
+ * @returns {ReleaseNote[] | undefined}
+ */
+export function notesFor(notes: Record<string, ReleaseNote[]> | undefined, locale: string): ReleaseNote[] | undefined;
+/**
+ * The kept versions an update brought, newest first. After a finished update to the running version: the versions after
+ * `from` up to the running one. Else: the running version alone, when it is kept.
+ * @param {{ from?: string, to: string, state: string } | null} update
+ * @param {string} running
+ * @param {string[]} kept versions that have notes in KV
+ * @returns {string[]}
+ */
+export function installedVersions(update: {
+    from?: string;
+    to: string;
+    state: string;
+} | null, running: string, kept: string[]): string[];
+/**
+ * The release notes and screenshots of `version` from an unzipped npm tar. Notes: package/release-notes/i18n/<locale>/<version>.json
+ * per locale. Screenshots: one per card, at imagePath(). A missing or unreadable notes file leaves its locale out; a missing
+ * screenshot is left out. Returns undefined when no locale has notes.
+ * @param {Uint8Array} tar
+ * @param {string} version
+ * @returns {{ notes: Record<string, ReleaseNote[]>, images: { locale: string, id: string, bytes: Uint8Array }[] } | undefined}
+ */
+export function notesFromTar(tar: Uint8Array, version: string): {
+    notes: Record<string, ReleaseNote[]>;
+    images: {
+        locale: string;
+        id: string;
+        bytes: Uint8Array;
+    }[];
+} | undefined;
+/**
+ * The address the editor loads a card's screenshot from (served by the Worker).
+ * @param {string} version
+ * @param {string} locale
+ * @param {string} id
+ * @returns {string}
+ */
+export function imageUrl(version: string, locale: string, id: string): string;
+/**
+ * The parts of a screenshot address, or null when the path is not one or a part is not valid: version x.y.z, locale en-US or
+ * da-DK, id of a-z, 0-9 and "-". Keeps any other text out of the KV key.
+ * @param {string} pathname
+ * @returns {{ version: string, locale: string, id: string } | null}
+ */
+export function parseImagePath(pathname: string): {
+    version: string;
+    locale: string;
+    id: string;
+} | null;
+/**
+ * The notes of a version with the screenshot address set on each card. Does not change `notes`; lines stay as they are.
+ * @param {string} version
+ * @param {Record<string, ReleaseNote[]> | undefined} notes locale -> notes
+ * @returns {Record<string, ReleaseNote[]> | undefined}
+ */
+export function withImageUrls(version: string, notes: Record<string, ReleaseNote[]> | undefined): Record<string, ReleaseNote[]> | undefined;
+/** @typedef {{ id: string, kind: 'card', title: string, text: string, image?: string } | { id: string, kind: 'line', text: string }} ReleaseNote */
+/** @typedef {{ version: string, notes: ReleaseNote[] }} ReleasedNotes */
+/** @typedef {{ width: number, height: number }} ImageSize */
+/** @typedef {{ note: object, imageBytes: number | null, imageSize: ImageSize | null }} PendingEntry  imageBytes: size of <id>.webp in bytes, null when there is none; imageSize: its pixels, null when it is not a WebP */
+/** @typedef {Record<string, Record<string, PendingEntry>>} Pending  locale -> id -> entry */
+/** The largest screenshot a card may have, in bytes. */
+export const MAX_IMAGE_BYTES: number;
+/** The width of a card's screenshot in pixels (375 CSS pixels at scale 2) and its greatest height (400 CSS pixels at scale 2). */
+export const IMAGE_WIDTH: 750;
+export const MAX_IMAGE_HEIGHT: 800;
+export function imageKey(version: string, locale: string, id: string): string;
+export type ReleaseNote = {
+    id: string;
+    kind: "card";
+    title: string;
+    text: string;
+    image?: string;
+} | {
+    id: string;
+    kind: "line";
+    text: string;
+};
+export type ReleasedNotes = {
+    version: string;
+    notes: ReleaseNote[];
+};
+export type ImageSize = {
+    width: number;
+    height: number;
+};
+/**
+ * imageBytes: size of <id>.webp in bytes, null when there is none; imageSize: its pixels, null when it is not a WebP
+ */
+export type PendingEntry = {
+    note: object;
+    imageBytes: number | null;
+    imageSize: ImageSize | null;
+};
+/**
+ * locale -> id -> entry
+ */
+export type Pending = Record<string, Record<string, PendingEntry>>;

package/lib/releaseNotes.mjs

@@ -0,0 +1,249 @@
+// Pure helpers for release notes: checks pending notes (cards with a screenshot of the right type and size, lines), groups them per version and locale,
+// picks a locale's notes, lists the versions an update brought and reads a version's notes and screenshots from its tar.
+// Also builds the Worker's screenshot address and KV key, parses the address and adds the address to a version's cards.
+// Exposes MAX_IMAGE_BYTES, IMAGE_WIDTH, MAX_IMAGE_HEIGHT, webpSize, problemsOf, released, imagePath, notesFor, installedVersions, notesFromTar, imageUrl, imageKey,
+// parseImagePath and withImageUrls. Depends on ./cms-version.mjs and ./changelog.mjs; no node: imports.
+import { compareVersions } from './cms-version.mjs';
+import { bytesFromTar, fileFromTar } from './changelog.mjs';
+
+/** @typedef {{ id: string, kind: 'card', title: string, text: string, image?: string } | { id: string, kind: 'line', text: string }} ReleaseNote */
+/** @typedef {{ version: string, notes: ReleaseNote[] }} ReleasedNotes */
+/** @typedef {{ width: number, height: number }} ImageSize */
+/** @typedef {{ note: object, imageBytes: number | null, imageSize: ImageSize | null }} PendingEntry  imageBytes: size of <id>.webp in bytes, null when there is none; imageSize: its pixels, null when it is not a WebP */
+/** @typedef {Record<string, Record<string, PendingEntry>>} Pending  locale -> id -> entry */
+
+/** The largest screenshot a card may have, in bytes. */
+export const MAX_IMAGE_BYTES = 200 * 1024;
+
+/** The width of a card's screenshot in pixels (375 CSS pixels at scale 2) and its greatest height (400 CSS pixels at scale 2). */
+export const IMAGE_WIDTH = 750;
+export const MAX_IMAGE_HEIGHT = 800;
+
+/** The locales every pending note must exist in. */
+const LOCALES = ['en-US', 'da-DK'];
+
+/** The kinds of note. */
+const KINDS = ['card', 'line'];
+
+const pathOf = (locale, id) => `release-notes/i18n/${locale}/pending/${id}.json`;
+const isFilled = (value) => typeof value === 'string' && value.trim() !== '';
+
+/**
+ * The size in pixels of a WebP image, read from its header (a lossy VP8, a lossless VP8L or an extended VP8X chunk).
+ * @param {Uint8Array} bytes
+ * @returns {ImageSize | null} null when `bytes` is not a WebP of one of these kinds
+ */
+export function webpSize(bytes) {
+  const text = (from, to) => String.fromCharCode(...bytes.subarray(from, to));
+  if (bytes.length < 30 || text(0, 4) !== 'RIFF' || text(8, 12) !== 'WEBP') return null;
+  const u16 = (at) => bytes[at] | (bytes[at + 1] << 8);
+  const u24 = (at) => u16(at) | (bytes[at + 2] << 16);
+  switch (text(12, 16)) {
+    case 'VP8 ':
+      if (bytes[23] !== 0x9d || bytes[24] !== 0x01 || bytes[25] !== 0x2a) return null;
+      return { width: u16(26) & 0x3fff, height: u16(28) & 0x3fff };
+    case 'VP8L':
+      if (bytes[20] !== 0x2f) return null;
+      return {
+        width: 1 + (bytes[21] | ((bytes[22] & 0x3f) << 8)),
+        height: 1 + ((bytes[22] >> 6) | (bytes[23] << 2) | ((bytes[24] & 0x0f) << 10)),
+      };
+    case 'VP8X':
+      return { width: 1 + u24(24), height: 1 + u24(27) };
+    default:
+      return null;
+  }
+}
+
+/**
+ * The problems of one pending note: its id, its kind, its text and, for a card, its title and screenshot.
+ * @param {string} locale
+ * @param {string} id
+ * @param {PendingEntry} entry
+ * @returns {string[]}
+ */
+function entryProblems(locale, id, { note, imageBytes, imageSize }) {
+  const path = pathOf(locale, id);
+  const fields = note ?? {};
+  const problems = [];
+  if (fields.id !== id) problems.push(`${path}: id "${fields.id}" does not match the file name`);
+  if (!KINDS.includes(fields.kind)) return [...problems, `${path}: kind must be "card" or "line"`];
+  if (!isFilled(fields.text)) problems.push(`${path}: text is empty`);
+  if (fields.kind === 'card') {
+    if (!isFilled(fields.title)) problems.push(`${path}: title is empty`);
+    if (imageBytes === null) problems.push(`${path}: a card needs the screenshot ${id}.webp`);
+    else {
+      const image = pathOf(locale, id).replace(/\.json$/, '.webp');
+      if (imageBytes > MAX_IMAGE_BYTES) problems.push(`${image}: screenshot is ${Math.ceil(imageBytes / 1024)} KB, the limit is 200 KB`);
+      if (!imageSize) problems.push(`${image}: screenshot is not a WebP file`);
+      else if (imageSize.width !== IMAGE_WIDTH || imageSize.height > MAX_IMAGE_HEIGHT)
+        problems.push(
+          `${image}: screenshot is ${imageSize.width}×${imageSize.height} px, it must be ${IMAGE_WIDTH} px wide and at most ${MAX_IMAGE_HEIGHT} px high`,
+        );
+    }
+  } else if (imageBytes !== null) {
+    problems.push(`${path}: a line has no screenshot (${id}.webp)`);
+  }
+  return problems;
+}
+
+/**
+ * The problems in the pending notes: a note missing in a locale, a kind that differs between locales, and each problem of
+ * entryProblems. Names the file and the locale of each problem.
+ * @param {Pending} pending
+ * @returns {string[]} empty when all good
+ */
+export function problemsOf(pending) {
+  const problems = [];
+  const locales = [...new Set([...LOCALES, ...Object.keys(pending)])];
+  const ids = [...new Set(locales.flatMap((locale) => Object.keys(pending[locale] ?? {})))];
+  for (const id of ids) {
+    const kinds = new Set();
+    for (const locale of locales) {
+      const entry = pending[locale]?.[id];
+      if (!entry) {
+        problems.push(`${pathOf(locale, id)} is missing`);
+        continue;
+      }
+      problems.push(...entryProblems(locale, id, entry));
+      kinds.add(entry.note?.kind);
+    }
+    if (kinds.size > 1) problems.push(`${id}: kind differs between locales`);
+  }
+  return problems;
+}
+
+/**
+ * The pending notes of each locale as one release of `version`: the notes as they are in their files, sorted by id, and the
+ * ids of the cards that have a screenshot. A locale without notes is left out.
+ * @param {Pending} pending
+ * @param {string} version
+ * @returns {Record<string, { file: ReleasedNotes, images: string[] }>}
+ */
+export function released(pending, version) {
+  const result = {};
+  for (const [locale, entries] of Object.entries(pending)) {
+    const ids = Object.keys(entries).sort();
+    if (ids.length === 0) continue;
+    result[locale] = {
+      file: { version, notes: ids.map((id) => entries[id].note) },
+      images: ids.filter((id) => entries[id].note.kind === 'card'),
+    };
+  }
+  return result;
+}
+
+/**
+ * The repository path of a released screenshot.
+ * @param {string} version
+ * @param {string} locale
+ * @param {string} id
+ * @returns {string}
+ */
+export function imagePath(version, locale, id) {
+  return `release-notes/i18n/${locale}/${version}/${id}.webp`;
+}
+
+/**
+ * The notes for a locale, else the en-US notes, else undefined.
+ * @param {Record<string, ReleaseNote[]> | undefined} notes
+ * @param {string} locale
+ * @returns {ReleaseNote[] | undefined}
+ */
+export function notesFor(notes, locale) {
+  return notes?.[locale] ?? notes?.['en-US'];
+}
+
+/**
+ * The kept versions an update brought, newest first. After a finished update to the running version: the versions after
+ * `from` up to the running one. Else: the running version alone, when it is kept.
+ * @param {{ from?: string, to: string, state: string } | null} update
+ * @param {string} running
+ * @param {string[]} kept versions that have notes in KV
+ * @returns {string[]}
+ */
+export function installedVersions(update, running, kept) {
+  const finished = update?.state === 'done' && update.to === running && typeof update.from === 'string';
+  const versions = finished
+    ? kept.filter((version) => compareVersions(version, update.from) === 1 && compareVersions(version, running) <= 0)
+    : kept.filter((version) => version === running);
+  return versions.sort((a, b) => compareVersions(b, a));
+}
+
+/**
+ * The release notes and screenshots of `version` from an unzipped npm tar. Notes: package/release-notes/i18n/<locale>/<version>.json
+ * per locale. Screenshots: one per card, at imagePath(). A missing or unreadable notes file leaves its locale out; a missing
+ * screenshot is left out. Returns undefined when no locale has notes.
+ * @param {Uint8Array} tar
+ * @param {string} version
+ * @returns {{ notes: Record<string, ReleaseNote[]>, images: { locale: string, id: string, bytes: Uint8Array }[] } | undefined}
+ */
+export function notesFromTar(tar, version) {
+  const notes = {};
+  const images = [];
+  for (const locale of LOCALES) {
+    const text = fileFromTar(tar, `package/release-notes/i18n/${locale}/${version}.json`);
+    if (text === null) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      continue; // Bad JSON: this locale has no notes.
+    }
+    if (!Array.isArray(parsed?.notes)) continue;
+    notes[locale] = parsed.notes;
+    for (const note of parsed.notes) {
+      if (note?.kind !== 'card') continue;
+      const bytes = bytesFromTar(tar, `package/${imagePath(version, locale, note.id)}`);
+      if (bytes !== null) images.push({ locale, id: note.id, bytes });
+    }
+  }
+  return Object.keys(notes).length > 0 ? { notes, images } : undefined;
+}
+
+/**
+ * The address the editor loads a card's screenshot from (served by the Worker).
+ * @param {string} version
+ * @param {string} locale
+ * @param {string} id
+ * @returns {string}
+ */
+export function imageUrl(version, locale, id) {
+  return `/api/cms/note-image/${version}/${locale}/${id}`;
+}
+
+/**
+ * The KV key of a card's screenshot.
+ * @param {string} version
+ * @param {string} locale
+ * @param {string} id
+ * @returns {string}
+ */
+export const imageKey = (version, locale, id) => `cms:note-image:${version}:${locale}:${id}`;
+
+/**
+ * The parts of a screenshot address, or null when the path is not one or a part is not valid: version x.y.z, locale en-US or
+ * da-DK, id of a-z, 0-9 and "-". Keeps any other text out of the KV key.
+ * @param {string} pathname
+ * @returns {{ version: string, locale: string, id: string } | null}
+ */
+export function parseImagePath(pathname) {
+  const match = /^\/api\/cms\/note-image\/(\d+\.\d+\.\d+)\/(en-US|da-DK)\/([a-z0-9-]+)$/.exec(pathname);
+  return match ? { version: match[1], locale: match[2], id: match[3] } : null;
+}
+
+/**
+ * The notes of a version with the screenshot address set on each card. Does not change `notes`; lines stay as they are.
+ * @param {string} version
+ * @param {Record<string, ReleaseNote[]> | undefined} notes locale -> notes
+ * @returns {Record<string, ReleaseNote[]> | undefined}
+ */
+export function withImageUrls(version, notes) {
+  if (!notes) return notes;
+  return Object.fromEntries(
+    Object.entries(notes).map(([locale, list]) => [
+      locale,
+      list.map((note) => (note?.kind === 'card' ? { ...note, image: imageUrl(version, locale, note.id) } : note)),
+    ]),
+  );
+}