@jxsuite/site 2.5.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/site",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "What a Jx project's page at a route consists of — routing, layout, context, head and the document that boots it",
   "license": "MIT",
   "repository": {
@@ -22,7 +22,9 @@
     "./routes": "./src/routes.ts",
     "./serve": "./src/serve.ts",
     "./shell": "./src/shell.ts",
-    "./site-style": "./src/site-style.ts"
+    "./site-style": "./src/site-style.ts",
+    "./xmp-containers": "./src/xmp-containers.ts",
+    "./xmp-packet": "./src/xmp-packet.ts"
   },
   "publishConfig": {
     "provenance": true
@@ -32,7 +34,7 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/runtime": "^6.2.1",
-    "@jxsuite/schema": "^5.4.0"
+    "@jxsuite/runtime": "^6.3.0",
+    "@jxsuite/schema": "^5.6.0"
   }
 }

package/src/shell.ts

@@ -47,6 +47,13 @@ export interface ShellOptions {
    * host that omits this should expect a collection to render as an empty list.
    */
   resolveToken?: string | undefined;
+  /**
+   * URL of the body eraser (`@jxsuite/erase/browser`, built as its own file) on this origin. With
+   * it, the page fetches the eraser only when a function body is TypeScript (`spec.md` §23.1);
+   * without it, a typed body fails to compile and says so. This package never imports the eraser,
+   * so a host that cannot run it still loads this one.
+   */
+  eraserUrl?: string | undefined;
 }
 
 /** Escape a string for an HTML attribute value. */
@@ -70,10 +77,17 @@ function jsonPayload(doc: JxDocument): string {
 
 /** The document for one composed page. */
 export function pageShell(page: ComposedPage, options: ShellOptions): string {
-  const imports = options.resolveToken ? "Jx, setResolveToken" : "Jx";
-  const setToken = options.resolveToken
-    ? `\nsetResolveToken(${JSON.stringify(options.resolveToken)});`
-    : "";
+  const names = ["Jx"];
+  let setup = "";
+  if (options.resolveToken) {
+    names.push("setResolveToken");
+    setup += `\nsetResolveToken(${JSON.stringify(options.resolveToken)});`;
+  }
+  if (options.eraserUrl) {
+    names.push("setBodyEraserLoader");
+    setup += `\nsetBodyEraserLoader(() => import(${JSON.stringify(options.eraserUrl)}));`;
+  }
+  const imports = names.join(", ");
   const style = options.styleUrl
     ? `\n  <link rel="stylesheet" href="${attr(options.styleUrl)}">`
     : "";
@@ -93,7 +107,7 @@ export function pageShell(page: ComposedPage, options: ShellOptions): string {
 <body>
 <script type="application/json" id="jx-page-document">${jsonPayload(page.doc)}</script>
 <script type="module">
-import { ${imports} } from "${attr(options.runtimeUrl)}";${setToken}
+import { ${imports} } from "${attr(options.runtimeUrl)}";${setup}
 const source = document.getElementById("jx-page-document").textContent;
 await Jx(JSON.parse(source), document.body, { base: ${JSON.stringify(options.base)} });
 </script>${client}

package/src/xmp-containers.ts

@@ -0,0 +1,542 @@
+/**
+ * Where each image format keeps its XMP packet, and how to put a new one there.
+ *
+ * Each format has exactly one place the XMP specification (Part 3, "Storage in files") or the
+ * format's own specification names, and that is the only place read or written:
+ *
+ * - **JPEG**: an `APP1` segment whose payload starts `http://ns.adobe.com/xap/1.0/\0`, placed after
+ *   the `APP0`/Exif `APP1` segments at the head of the file. Extended XMP segments are left alone.
+ * - **PNG**: an `iTXt` chunk with the keyword `XML:com.adobe.xmp`, uncompressed, before `IDAT`.
+ * - **WebP**: an `XMP ` chunk in the extended file format, flagged in `VP8X`; a simple (lossy or
+ *   lossless) file is converted to the extended form, its canvas taken from the bitstream header.
+ * - **SVG**: an `x:xmpmeta` inside the root's `<metadata>` element. The file is text, so the packet
+ *   is spliced into the source rather than re-serialized: the author's own formatting is kept.
+ *
+ * Any other format (GIF, AVIF, HEIC, TIFF, every video) has no writer here, and {@link xmpFormatOf}
+ * answers `null` for it: the Media workspace then says the file cannot hold alt text rather than
+ * pretending to save it.
+ *
+ * @docs studio/projects/media
+ */
+
+export type XmpFormat = "jpeg" | "png" | "webp" | "svg";
+
+/** Why bytes could not be read or rewritten. */
+export class XmpContainerError extends Error {
+  override name = "XmpContainerError";
+}
+
+const FORMAT_BY_EXTENSION = new Map<string, XmpFormat>([
+  [".jpeg", "jpeg"],
+  [".jpg", "jpeg"],
+  [".png", "png"],
+  [".svg", "svg"],
+  [".webp", "webp"],
+]);
+
+/** The container a path's extension names, when Studio can read and write its XMP. */
+export function xmpFormatOf(path: string): XmpFormat | null {
+  const dot = path.lastIndexOf(".");
+  return FORMAT_BY_EXTENSION.get(dot > 0 ? path.slice(dot).toLowerCase() : "") ?? null;
+}
+
+const utf8 = new TextEncoder();
+const fromUtf8 = new TextDecoder("utf-8", { fatal: true });
+
+function decode(bytes: Uint8Array): string {
+  try {
+    return fromUtf8.decode(bytes);
+  } catch {
+    throw new XmpContainerError("The metadata is not valid UTF-8.");
+  }
+}
+
+function concat(parts: readonly Uint8Array[]): Uint8Array<ArrayBuffer> {
+  const out = new Uint8Array(parts.reduce((n, part) => n + part.length, 0));
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.length;
+  }
+  return out;
+}
+
+function view(bytes: Uint8Array): DataView {
+  return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+
+/** Whether a flag bit is set in a byte: a bit test by arithmetic, as the lint asks. */
+function hasFlag(byte: number, flag: number): boolean {
+  return Math.floor(byte / flag) % 2 === 1;
+}
+
+function ascii(bytes: Uint8Array, at: number, length: number): string {
+  return String.fromCodePoint(...bytes.subarray(at, at + length));
+}
+
+/** The packet in `bytes`, or `null` when the file has none. */
+export function extractXmp(bytes: Uint8Array, format: XmpFormat): string | null {
+  switch (format) {
+    case "jpeg": {
+      return jpegXmp(bytes).packet;
+    }
+    case "png": {
+      return pngXmp(bytes).packet;
+    }
+    case "webp": {
+      return webpXmp(bytes).packet;
+    }
+    default: {
+      return svgXmp(decode(bytes)).packet;
+    }
+  }
+}
+
+/** `bytes` with its packet replaced by `packet` (or given one). */
+export function embedXmp(
+  bytes: Uint8Array,
+  format: XmpFormat,
+  packet: string,
+): Uint8Array<ArrayBuffer> {
+  switch (format) {
+    case "jpeg": {
+      return jpegEmbed(bytes, packet);
+    }
+    case "png": {
+      return pngEmbed(bytes, packet);
+    }
+    case "webp": {
+      return webpEmbed(bytes, packet);
+    }
+    default: {
+      return utf8.encode(svgEmbed(decode(bytes), packet));
+    }
+  }
+}
+
+// ─── JPEG ────────────────────────────────────────────────────────────────────
+
+const JPEG_XMP_HEADER = utf8.encode("http://ns.adobe.com/xap/1.0/\0");
+/** The largest payload one segment holds: a 16-bit length that counts its own two bytes. */
+const JPEG_SEGMENT_MAX = 0xff_ff - 2;
+
+interface JpegSegment {
+  marker: number;
+  start: number;
+  end: number;
+}
+
+/** The marker segments before the scan data. */
+function jpegSegments(bytes: Uint8Array): JpegSegment[] {
+  if (bytes[0] !== 0xff || bytes[1] !== 0xd8) {
+    throw new XmpContainerError("Not a JPEG file.");
+  }
+  const segments: JpegSegment[] = [];
+  let at = 2;
+  while (at + 4 <= bytes.length) {
+    if (bytes[at] !== 0xff) {
+      throw new XmpContainerError("The JPEG's markers are damaged.");
+    }
+    const marker = bytes[at + 1] ?? 0;
+    if (marker === 0xff) {
+      // Fill byte.
+      at += 1;
+      continue;
+    }
+    if (marker === 0xda || marker === 0xd9) {
+      break;
+    }
+    const length = view(bytes).getUint16(at + 2);
+    const end = at + 2 + length;
+    if (length < 2 || end > bytes.length) {
+      throw new XmpContainerError("The JPEG's markers are damaged.");
+    }
+    segments.push({ end, marker, start: at });
+    at = end;
+  }
+  return segments;
+}
+
+function isJpegXmp(bytes: Uint8Array, segment: JpegSegment): boolean {
+  const payload = segment.start + 4;
+  return (
+    segment.marker === 0xe1 &&
+    segment.end - payload >= JPEG_XMP_HEADER.length &&
+    JPEG_XMP_HEADER.every((byte, i) => bytes[payload + i] === byte)
+  );
+}
+
+interface Found<T> {
+  packet: string | null;
+  parts: T[];
+}
+
+function jpegXmp(bytes: Uint8Array): Found<JpegSegment> {
+  const segments = jpegSegments(bytes);
+  const found = segments.find((segment) => isJpegXmp(bytes, segment));
+  const packet =
+    found === undefined
+      ? null
+      : decode(bytes.subarray(found.start + 4 + JPEG_XMP_HEADER.length, found.end));
+  return { packet, parts: segments };
+}
+
+function jpegEmbed(bytes: Uint8Array, packet: string): Uint8Array<ArrayBuffer> {
+  const { parts: segments } = jpegXmp(bytes);
+  const body = utf8.encode(packet);
+  const length = JPEG_XMP_HEADER.length + body.length;
+  if (length > JPEG_SEGMENT_MAX) {
+    throw new XmpContainerError("The metadata is too large for one JPEG segment.");
+  }
+  const head = Uint8Array.of(0xff, 0xe1, 0, 0);
+  view(head).setUint16(2, length + 2);
+  const segment = concat([head, JPEG_XMP_HEADER, body]);
+  // After the leading APP0 (JFIF) and Exif APP1 segments, where readers look first.
+  let insertAt = 2;
+  for (const each of segments) {
+    if ((each.marker === 0xe0 || each.marker === 0xe1) && !isJpegXmp(bytes, each)) {
+      insertAt = each.end;
+    } else {
+      break;
+    }
+  }
+  const parts: Uint8Array[] = [bytes.subarray(0, insertAt), segment];
+  let at = insertAt;
+  for (const each of segments) {
+    if (each.start >= insertAt && isJpegXmp(bytes, each)) {
+      parts.push(bytes.subarray(at, each.start));
+      at = each.end;
+    }
+  }
+  parts.push(bytes.subarray(at));
+  return concat(parts);
+}
+
+// ─── PNG ─────────────────────────────────────────────────────────────────────
+
+const PNG_SIGNATURE = Uint8Array.of(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a);
+const PNG_XMP_KEYWORD = "XML:com.adobe.xmp";
+
+interface PngChunk {
+  type: string;
+  start: number;
+  dataStart: number;
+  end: number;
+}
+
+let crcTable: Uint32Array | null = null;
+
+/** CRC-32 as PNG computes it (ISO 3309), over the chunk type and data. */
+/* oxlint-disable no-bitwise -- CRC-32 IS bitwise arithmetic over 32-bit words; written any other
+   way it is the same operations, slower and harder to check against the specification. */
+export function crc32(bytes: Uint8Array): number {
+  if (crcTable === null) {
+    crcTable = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+      let c = n;
+      for (let k = 0; k < 8; k++) {
+        c = c & 1 ? 0xed_b8_83_20 ^ (c >>> 1) : c >>> 1;
+      }
+      crcTable[n] = c >>> 0;
+    }
+  }
+  let crc = 0xff_ff_ff_ff;
+  for (const byte of bytes) {
+    crc = (crcTable[(crc ^ byte) & 0xff] ?? 0) ^ (crc >>> 8);
+  }
+  return (crc ^ 0xff_ff_ff_ff) >>> 0;
+}
+/* oxlint-enable no-bitwise */
+
+function pngChunks(bytes: Uint8Array): PngChunk[] {
+  if (!PNG_SIGNATURE.every((byte, i) => bytes[i] === byte)) {
+    throw new XmpContainerError("Not a PNG file.");
+  }
+  const chunks: PngChunk[] = [];
+  let at = PNG_SIGNATURE.length;
+  while (at + 12 <= bytes.length) {
+    const length = view(bytes).getUint32(at);
+    const end = at + 12 + length;
+    if (end > bytes.length) {
+      throw new XmpContainerError("The PNG's chunks are damaged.");
+    }
+    const type = ascii(bytes, at + 4, 4);
+    chunks.push({ dataStart: at + 8, end, start: at, type });
+    at = end;
+    if (type === "IEND") {
+      break;
+    }
+  }
+  return chunks;
+}
+
+/** An `iTXt` chunk's text when its keyword is XMP's, else `null`. */
+function pngChunkXmp(bytes: Uint8Array, chunk: PngChunk): string | null {
+  if (chunk.type !== "iTXt") {
+    return null;
+  }
+  const data = bytes.subarray(chunk.dataStart, chunk.end - 4);
+  const keywordEnd = data.indexOf(0);
+  if (keywordEnd === -1 || ascii(data, 0, keywordEnd) !== PNG_XMP_KEYWORD) {
+    return null;
+  }
+  if (data[keywordEnd + 1] !== 0) {
+    throw new XmpContainerError("The PNG's metadata is compressed, which Studio does not rewrite.");
+  }
+  // Keyword \0, compression flag, method, language \0, translated keyword \0, then the text.
+  const languageEnd = data.indexOf(0, keywordEnd + 3);
+  const translatedEnd = languageEnd === -1 ? -1 : data.indexOf(0, languageEnd + 1);
+  if (translatedEnd === -1) {
+    throw new XmpContainerError("The PNG's metadata chunk is damaged.");
+  }
+  return decode(data.subarray(translatedEnd + 1));
+}
+
+function pngXmp(bytes: Uint8Array): Found<PngChunk> {
+  const chunks = pngChunks(bytes);
+  const packets = chunks.map((chunk) => pngChunkXmp(bytes, chunk));
+  return { packet: packets.find((packet) => packet !== null) ?? null, parts: chunks };
+}
+
+function pngEmbed(bytes: Uint8Array, packet: string): Uint8Array<ArrayBuffer> {
+  const { parts: chunks } = pngXmp(bytes);
+  const data = concat([
+    utf8.encode(PNG_XMP_KEYWORD),
+    Uint8Array.of(0, 0, 0, 0, 0),
+    utf8.encode(packet),
+  ]);
+  const typeAndData = concat([utf8.encode("iTXt"), data]);
+  const chunk = new Uint8Array(12 + data.length);
+  view(chunk).setUint32(0, data.length);
+  chunk.set(typeAndData, 4);
+  view(chunk).setUint32(8 + data.length, crc32(typeAndData));
+  const firstData = chunks.find((each) => each.type === "IDAT");
+  if (firstData === undefined) {
+    throw new XmpContainerError("The PNG has no image data.");
+  }
+  const parts: Uint8Array[] = [bytes.subarray(0, PNG_SIGNATURE.length)];
+  for (const each of chunks) {
+    if (each === firstData) {
+      parts.push(chunk);
+    }
+    if (pngChunkXmp(bytes, each) === null) {
+      parts.push(bytes.subarray(each.start, each.end));
+    }
+  }
+  const last = chunks.at(-1);
+  parts.push(bytes.subarray(last === undefined ? PNG_SIGNATURE.length : last.end));
+  return concat(parts);
+}
+
+// ─── WebP ────────────────────────────────────────────────────────────────────
+
+interface RiffChunk {
+  fourcc: string;
+  start: number;
+  dataStart: number;
+  size: number;
+  /** The end including the pad byte. */
+  end: number;
+}
+
+const VP8X_XMP = 0x04;
+const VP8X_ALPHA = 0x10;
+
+function webpChunks(bytes: Uint8Array): RiffChunk[] {
+  if (ascii(bytes, 0, 4) !== "RIFF" || ascii(bytes, 8, 4) !== "WEBP") {
+    throw new XmpContainerError("Not a WebP file.");
+  }
+  const riffEnd = Math.min(bytes.length, 8 + view(bytes).getUint32(4, true));
+  const chunks: RiffChunk[] = [];
+  let at = 12;
+  while (at + 8 <= riffEnd) {
+    const size = view(bytes).getUint32(at + 4, true);
+    const dataStart = at + 8;
+    const end = dataStart + size + (size % 2);
+    if (dataStart + size > riffEnd) {
+      throw new XmpContainerError("The WebP's chunks are damaged.");
+    }
+    chunks.push({
+      dataStart,
+      end: Math.min(end, riffEnd),
+      fourcc: ascii(bytes, at, 4),
+      size,
+      start: at,
+    });
+    at = end;
+  }
+  return chunks;
+}
+
+function webpXmp(bytes: Uint8Array): Found<RiffChunk> {
+  const chunks = webpChunks(bytes);
+  const found = chunks.find((chunk) => chunk.fourcc === "XMP ");
+  const packet =
+    found === undefined
+      ? null
+      : decode(bytes.subarray(found.dataStart, found.dataStart + found.size));
+  return { packet, parts: chunks };
+}
+
+function riffChunk(fourcc: string, data: Uint8Array): Uint8Array {
+  const chunk = new Uint8Array(8 + data.length + (data.length % 2));
+  chunk.set(utf8.encode(fourcc), 0);
+  view(chunk).setUint32(4, data.length, true);
+  chunk.set(data, 8);
+  return chunk;
+}
+
+/** A `VP8X` header for a simple file, its canvas and alpha read from the bitstream. */
+function vp8xFor(bytes: Uint8Array, image: RiffChunk): Uint8Array {
+  const data = bytes.subarray(image.dataStart, image.dataStart + image.size);
+  let width: number;
+  let height: number;
+  let alpha = false;
+  if (image.fourcc === "VP8 ") {
+    // Frame tag (3 bytes), start code 9d 01 2a, then 14-bit width and height.
+    if (data.length < 10 || data[3] !== 0x9d || data[4] !== 0x01 || data[5] !== 0x2a) {
+      throw new XmpContainerError("The WebP's image data is damaged.");
+    }
+    // The top two bits of each are a scale, not part of the size.
+    width = view(data).getUint16(6, true) % 0x40_00;
+    height = view(data).getUint16(8, true) % 0x40_00;
+  } else if (image.fourcc === "VP8L") {
+    if (data.length < 5 || data[0] !== 0x2f) {
+      throw new XmpContainerError("The WebP's image data is damaged.");
+    }
+    // 14 bits of width - 1, 14 of height - 1, then the alpha hint, little-endian.
+    const bits = view(data).getUint32(1, true);
+    width = (bits % 0x40_00) + 1;
+    height = (Math.floor(bits / 0x40_00) % 0x40_00) + 1;
+    alpha = hasFlag(bits, 2 ** 28);
+  } else {
+    throw new XmpContainerError("The WebP has no image data.");
+  }
+  const header = new Uint8Array(10);
+  header[0] = VP8X_XMP + (alpha ? VP8X_ALPHA : 0);
+  // Canvas width - 1 and height - 1, each 24 bits little-endian; a 14-bit size fits in the low 16.
+  view(header).setUint16(4, width - 1, true);
+  view(header).setUint16(7, height - 1, true);
+  return riffChunk("VP8X", header);
+}
+
+function webpEmbed(bytes: Uint8Array, packet: string): Uint8Array<ArrayBuffer> {
+  const { parts: chunks } = webpXmp(bytes);
+  const parts: Uint8Array[] = [];
+  const vp8x = chunks.find((chunk) => chunk.fourcc === "VP8X");
+  if (vp8x === undefined) {
+    const [image] = chunks;
+    if (image === undefined) {
+      throw new XmpContainerError("The WebP has no image data.");
+    }
+    parts.push(vp8xFor(bytes, image));
+  }
+  for (const chunk of chunks) {
+    if (chunk.fourcc === "XMP ") {
+      continue;
+    }
+    if (chunk === vp8x) {
+      const copy = bytes.slice(chunk.start, chunk.end);
+      const flags = copy[8] ?? 0;
+      copy[8] = hasFlag(flags, VP8X_XMP) ? flags : flags + VP8X_XMP;
+      parts.push(copy);
+    } else {
+      parts.push(bytes.subarray(chunk.start, chunk.end));
+    }
+  }
+  // XMP is the last chunk of an extended file.
+  parts.push(riffChunk("XMP ", utf8.encode(packet)));
+  const body = concat(parts);
+  const out = new Uint8Array(12 + body.length);
+  out.set(utf8.encode("RIFF"), 0);
+  view(out).setUint32(4, 4 + body.length, true);
+  out.set(utf8.encode("WEBP"), 8);
+  out.set(body, 12);
+  return out;
+}
+
+// ─── SVG ─────────────────────────────────────────────────────────────────────
+
+const XMPMETA = /<([\w.-]+:)?xmpmeta\b[\s\S]*?<\/\1?xmpmeta\s*>/;
+
+/** The end of the start tag that begins at `lt`, honouring quoted attribute values. */
+function tagEnd(text: string, lt: number): number {
+  let quote: string | null = null;
+  for (let at = lt + 1; at < text.length; at++) {
+    const ch = text[at];
+    if (quote !== null) {
+      if (ch === quote) {
+        quote = null;
+      }
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+    } else if (ch === ">") {
+      return at;
+    }
+  }
+  return -1;
+}
+
+/** The root `<svg …>` start tag: where it begins, where its `>` is, and whether it closes itself. */
+interface SvgRootTag {
+  start: number;
+  end: number;
+  selfClosing: boolean;
+}
+
+/** The `x:xmpmeta` element an SVG holds, with its range in the source; `null` and -1 when none. */
+interface SvgPacket {
+  packet: string | null;
+  start: number;
+  end: number;
+}
+
+/** The root `<svg …>` start tag's range. */
+function svgRoot(text: string): SvgRootTag {
+  const match = /<svg[\s>/]/.exec(text);
+  if (match === null) {
+    throw new XmpContainerError("Not an SVG file.");
+  }
+  const end = tagEnd(text, match.index);
+  if (end === -1) {
+    throw new XmpContainerError("The SVG's root element is damaged.");
+  }
+  return { end, selfClosing: text[end - 1] === "/", start: match.index };
+}
+
+/** The `x:xmpmeta` element's source and range, inside the root's metadata. */
+function svgXmp(text: string): SvgPacket {
+  svgRoot(text);
+  const match = XMPMETA.exec(text);
+  return match === null
+    ? { end: -1, packet: null, start: -1 }
+    : { end: match.index + match[0].length, packet: match[0], start: match.index };
+}
+
+/** The packet without its `xpacket` wrapper: SVG is already XML, and holds the element alone. */
+function bareXmpmeta(packet: string): string {
+  const match = XMPMETA.exec(packet);
+  if (match === null) {
+    throw new XmpContainerError("The metadata has no x:xmpmeta element.");
+  }
+  return match[0];
+}
+
+function svgEmbed(text: string, packet: string): string {
+  const meta = bareXmpmeta(packet);
+  const found = svgXmp(text);
+  if (found.packet !== null) {
+    return text.slice(0, found.start) + meta + text.slice(found.end);
+  }
+  const root = svgRoot(text);
+  if (root.selfClosing) {
+    const open = text.slice(root.start, root.end - 1).trimEnd();
+    return `${text.slice(0, root.start)}${open}><metadata>${meta}</metadata></svg>${text.slice(root.end + 1)}`;
+  }
+  const existing = /<metadata(\s[^>]*)?>/.exec(text.slice(root.end));
+  if (existing !== null) {
+    const at = root.end + existing.index + existing[0].length;
+    return text.slice(0, at) + meta + text.slice(at);
+  }
+  return `${text.slice(0, root.end + 1)}<metadata>${meta}</metadata>${text.slice(root.end + 1)}`;
+}

package/src/xmp-packet.ts

@@ -0,0 +1,727 @@
+/**
+ * The XMP packet a media file carries, read and rewritten for the two properties Studio edits.
+ *
+ * Studio keeps what a picture IS inside the picture (studio.md §22.6), in the fields every photo
+ * tool already reads and writes, so a file moved, renamed, copied or opened in another program
+ * takes its description with it and no index beside it can drift:
+ *
+ * - **Alt text** is the IPTC Photo Metadata Standard's `Iptc4xmpCore:AltTextAccessibility`, a
+ *   language alternative whose `x-default` entry is the text. Other languages are kept as found.
+ * - **Tags** are `dc:subject`, the unordered bag IPTC's Keywords maps to in XMP.
+ * - **The focal point** is one IPTC Image Region (`Iptc4xmpExt:ImageRegion`): a polygon of a single
+ *   vertex in relative units (the standard's own way to say "a point"), whose role is the IPTC
+ *   NewsCodes `areaOfInterest`. Every other region in the bag is kept.
+ *
+ * **Everything else in the packet is kept.** A rewrite parses the packet into a small tree,
+ * replaces those two properties on the first `rdf:Description` (removing them from any other, so a
+ * file never says two things), and serializes the tree back: a camera's EXIF mirror, a licence, a
+ * Lightroom develop setting all survive byte-for-byte in meaning. A packet that does not parse is
+ * never "repaired" into a fresh one, which would silently delete whatever it held; it is refused,
+ * and the caller says so.
+ *
+ * The parser is deliberately DOM-free: XMP is a constrained XML (no DTD, no external entities), the
+ * tree has to round-trip text it does not understand exactly, and a pure module tests and runs the
+ * same everywhere.
+ *
+ * @docs studio/projects/media
+ */
+
+/** What Studio reads from, and writes to, one media file. */
+export interface MediaRecord {
+  /** The file's alt text, `""` when it has none. */
+  alt: string;
+  /** Its tags, in the order the file lists them, without duplicates or blanks. */
+  tags: string[];
+  /** The point a crop of the picture keeps in view, or `null` when it has none. */
+  focus: FocalPoint | null;
+}
+
+/** A point on a picture, each coordinate a fraction of its width or height from the top left. */
+export interface FocalPoint {
+  readonly x: number;
+  readonly y: number;
+}
+
+export const RDF_NS = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
+export const DC_NS = "http://purl.org/dc/elements/1.1/";
+export const IPTC_CORE_NS = "http://iptc.org/std/Iptc4xmpCore/1.0/xmlns/";
+export const IPTC_EXT_NS = "http://iptc.org/std/Iptc4xmpExt/2008-02-29/";
+export const XMP_NS = "http://ns.adobe.com/xap/1.0/";
+/** The IPTC Image Region Role a focal point is written with. */
+export const AREA_OF_INTEREST = "http://cv.iptc.org/newscodes/imageregionrole/areaOfInterest";
+const XML_NS = "http://www.w3.org/XML/1998/namespace";
+const X_NS = "adobe:ns:meta/";
+
+/** The empty record: no alt text, no tags. */
+export function emptyMediaRecord(): MediaRecord {
+  return { alt: "", focus: null, tags: [] };
+}
+
+// ─── A small XML tree ────────────────────────────────────────────────────────
+
+interface XmlElement {
+  type: "element";
+  /** The qualified name as written (`dc:subject`). */
+  name: string;
+  /** Attributes in source order, values decoded. */
+  attrs: [string, string][];
+  children: XmlNode[];
+}
+
+interface XmlText {
+  type: "text";
+  /** Decoded text. */
+  value: string;
+}
+
+/** A node kept verbatim: a comment, a processing instruction, a CDATA section. */
+interface XmlRaw {
+  type: "raw";
+  source: string;
+}
+
+type XmlNode = XmlElement | XmlText | XmlRaw;
+
+/** Why a packet could not be read: the message a caller reports. */
+export class XmpParseError extends Error {
+  override name = "XmpParseError";
+}
+
+const ENTITIES = new Map([
+  ["amp", "&"],
+  ["apos", "'"],
+  ["gt", ">"],
+  ["lt", "<"],
+  ["quot", '"'],
+]);
+
+/** The code point a numeric character reference names, or `null` for a named one. */
+function codePointOf(ref: string): number | null {
+  if (ref.startsWith("#x") || ref.startsWith("#X")) {
+    return Number.parseInt(ref.slice(2), 16);
+  }
+  return ref.startsWith("#") ? Number(ref.slice(1)) : null;
+}
+
+function decodeEntities(text: string): string {
+  return text.replaceAll(/&(#x[\da-f]+|#\d+|\w+);/gi, (whole, ref: string) => {
+    const code = codePointOf(ref);
+    const decoded =
+      code === null
+        ? ENTITIES.get(ref)
+        : code <= 0x10_ff_ff
+          ? String.fromCodePoint(code)
+          : undefined;
+    if (decoded === undefined) {
+      throw new XmpParseError(`Unknown entity ${whole}`);
+    }
+    return decoded;
+  });
+}
+
+function escapeText(text: string): string {
+  return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+function escapeAttr(text: string): string {
+  return escapeText(text).replaceAll('"', "&quot;");
+}
+
+const NAME = /^[A-Za-z_][\w.:-]*/;
+
+/** Parse markup into nodes. Throws {@link XmpParseError} on anything that is not well formed. */
+function parseXml(source: string): XmlNode[] {
+  const root: XmlElement = { attrs: [], children: [], name: "#root", type: "element" };
+  const stack: XmlElement[] = [root];
+  let at = 0;
+  const top = (): XmlElement => stack.at(-1) ?? root;
+  while (at < source.length) {
+    const lt = source.indexOf("<", at);
+    if (lt === -1) {
+      top().children.push({ type: "text", value: decodeEntities(source.slice(at)) });
+      break;
+    }
+    if (lt > at) {
+      top().children.push({ type: "text", value: decodeEntities(source.slice(at, lt)) });
+    }
+    const rest = source.slice(lt, lt + 9);
+    let end: number;
+    if (rest.startsWith("<!--")) {
+      end = source.indexOf("-->", lt);
+      end = end === -1 ? -1 : end + 3;
+    } else if (rest.startsWith("<![CDATA[")) {
+      end = source.indexOf("]]>", lt);
+      end = end === -1 ? -1 : end + 3;
+    } else if (rest.startsWith("<?")) {
+      end = source.indexOf("?>", lt);
+      end = end === -1 ? -1 : end + 2;
+    } else if (rest.startsWith("<!")) {
+      throw new XmpParseError("A packet may not declare a document type.");
+    } else if (rest.startsWith("</")) {
+      const close = source.indexOf(">", lt);
+      if (close === -1) {
+        throw new XmpParseError("Unclosed end tag.");
+      }
+      const name = source.slice(lt + 2, close).trim();
+      const open = stack.pop();
+      if (open === undefined || open === root || open.name !== name) {
+        throw new XmpParseError(`Unexpected </${name}>.`);
+      }
+      at = close + 1;
+      continue;
+    } else {
+      at = parseStartTag(source, lt, stack);
+      continue;
+    }
+    if (end === -1) {
+      throw new XmpParseError("Unterminated markup.");
+    }
+    top().children.push({ source: source.slice(lt, end), type: "raw" });
+    at = end;
+  }
+  if (stack.length !== 1) {
+    throw new XmpParseError(`<${top().name}> is never closed.`);
+  }
+  return root.children;
+}
+
+/** Parse the start tag at `lt` onto `stack`, returning where parsing continues. */
+function parseStartTag(source: string, lt: number, stack: XmlElement[]): number {
+  let at = lt + 1;
+  const nameMatch = NAME.exec(source.slice(at));
+  if (nameMatch === null) {
+    throw new XmpParseError("A tag has no name.");
+  }
+  const element: XmlElement = { attrs: [], children: [], name: nameMatch[0], type: "element" };
+  at += nameMatch[0].length;
+  for (;;) {
+    while (/\s/.test(source[at] ?? "")) {
+      at += 1;
+    }
+    const ch = source[at];
+    if (ch === undefined) {
+      throw new XmpParseError(`<${element.name}> is never finished.`);
+    }
+    if (ch === ">" || source.startsWith("/>", at)) {
+      stack.at(-1)?.children.push(element);
+      if (ch === ">") {
+        stack.push(element);
+        return at + 1;
+      }
+      return at + 2;
+    }
+    const attrName = NAME.exec(source.slice(at));
+    if (attrName === null) {
+      throw new XmpParseError(`<${element.name}> has a malformed attribute.`);
+    }
+    at += attrName[0].length;
+    while (/\s/.test(source[at] ?? "")) {
+      at += 1;
+    }
+    if (source[at] !== "=") {
+      throw new XmpParseError(`${attrName[0]} has no value.`);
+    }
+    at += 1;
+    while (/\s/.test(source[at] ?? "")) {
+      at += 1;
+    }
+    const quote = source[at];
+    if (quote !== '"' && quote !== "'") {
+      throw new XmpParseError(`${attrName[0]} is not quoted.`);
+    }
+    const close = source.indexOf(quote, at + 1);
+    if (close === -1) {
+      throw new XmpParseError(`${attrName[0]} is never closed.`);
+    }
+    element.attrs.push([attrName[0], decodeEntities(source.slice(at + 1, close))]);
+    at = close + 1;
+  }
+}
+
+function serializeXml(nodes: readonly XmlNode[]): string {
+  return nodes
+    .map((node) => {
+      if (node.type === "text") {
+        return escapeText(node.value);
+      }
+      if (node.type === "raw") {
+        return node.source;
+      }
+      const attrs = node.attrs.map(([k, v]) => ` ${k}="${escapeAttr(v)}"`).join("");
+      return node.children.length === 0
+        ? `<${node.name}${attrs}/>`
+        : `<${node.name}${attrs}>${serializeXml(node.children)}</${node.name}>`;
+    })
+    .join("");
+}
+
+// ─── Namespaces ──────────────────────────────────────────────────────────────
+
+/** Prefix → URI bindings in scope. */
+type Scope = ReadonlyMap<string, string>;
+
+function scopeOf(element: XmlElement, parent: Scope): Scope {
+  const declared = element.attrs.filter(([k]) => k === "xmlns" || k.startsWith("xmlns:"));
+  if (declared.length === 0) {
+    return parent;
+  }
+  const scope = new Map(parent);
+  for (const [k, v] of declared) {
+    scope.set(k === "xmlns" ? "" : k.slice(6), v);
+  }
+  return scope;
+}
+
+/** A qualified name's namespace URI and local name, or `null` when its prefix is unbound. */
+function resolve(qname: string, scope: Scope, isAttr = false): [string, string] | null {
+  const colon = qname.indexOf(":");
+  if (colon === -1) {
+    // An unprefixed attribute is in no namespace; an unprefixed element takes the default.
+    return isAttr ? ["", qname] : [scope.get("") ?? "", qname];
+  }
+  const prefix = qname.slice(0, colon);
+  const uri = prefix === "xml" ? XML_NS : scope.get(prefix);
+  return uri === undefined ? null : [uri, qname.slice(colon + 1)];
+}
+
+function isNamed(qname: string, scope: Scope, ns: string, local: string, isAttr = false): boolean {
+  const resolved = resolve(qname, scope, isAttr);
+  return resolved !== null && resolved[0] === ns && resolved[1] === local;
+}
+
+function elements(nodes: readonly XmlNode[]): XmlElement[] {
+  return nodes.filter((node): node is XmlElement => node.type === "element");
+}
+
+function textOf(element: XmlElement): string {
+  return element.children
+    .map((node) =>
+      node.type === "text" ? node.value : node.type === "element" ? textOf(node) : "",
+    )
+    .join("");
+}
+
+/** Every `rdf:Description`, with the scope in force inside it, in document order. */
+function descriptions(nodes: readonly XmlNode[], scope: Scope = new Map()): [XmlElement, Scope][] {
+  const found: [XmlElement, Scope][] = [];
+  for (const element of elements(nodes)) {
+    const inner = scopeOf(element, scope);
+    if (isNamed(element.name, inner, RDF_NS, "Description")) {
+      found.push([element, inner]);
+    } else {
+      found.push(...descriptions(element.children, inner));
+    }
+  }
+  return found;
+}
+
+// ─── Reading ─────────────────────────────────────────────────────────────────
+
+/** The `rdf:li` items of a property's container (`rdf:Bag`, `rdf:Seq` or `rdf:Alt`). */
+function listItems(property: XmlElement, scope: Scope): [XmlElement, Scope][] {
+  const items: [XmlElement, Scope][] = [];
+  for (const container of elements(property.children)) {
+    const inner = scopeOf(container, scope);
+    for (const li of elements(container.children)) {
+      const liScope = scopeOf(li, inner);
+      if (isNamed(li.name, liScope, RDF_NS, "li")) {
+        items.push([li, liScope]);
+      }
+    }
+  }
+  return items;
+}
+
+function langOf(li: XmlElement, scope: Scope): string | null {
+  const attr = li.attrs.find(([k]) => isNamed(k, scope, XML_NS, "lang", true));
+  return attr === undefined ? null : attr[1];
+}
+
+/** The alt text in a lang-alt property: its `x-default` entry, else its first. */
+function altFrom(property: XmlElement, scope: Scope): string {
+  const items = listItems(property, scope);
+  const chosen = items.find(([li, s]) => langOf(li, s)?.toLowerCase() === "x-default") ?? items[0];
+  return chosen === undefined ? textOf(property).trim() : textOf(chosen[0]);
+}
+
+// ─── Image regions ───────────────────────────────────────────────────────────
+
+/**
+ * Where a structure's fields are: on the element itself when it is written
+ * `rdf:parseType="Resource"` (or as attributes, the shorthand form), else on the `rdf:Description`
+ * inside it.
+ */
+function structOf(element: XmlElement, scope: Scope): [XmlElement, Scope] {
+  const resource = element.attrs.some(
+    ([k, v]) => v === "Resource" && isNamed(k, scope, RDF_NS, "parseType", true),
+  );
+  if (!resource) {
+    for (const child of elements(element.children)) {
+      const inner = scopeOf(child, scope);
+      if (isNamed(child.name, inner, RDF_NS, "Description")) {
+        return [child, inner];
+      }
+    }
+  }
+  return [element, scope];
+}
+
+/** A structure's field written as an element, with the scope inside it. */
+function fieldElement(
+  holder: XmlElement,
+  scope: Scope,
+  ns: string,
+  local: string,
+): [XmlElement, Scope] | null {
+  for (const child of elements(holder.children)) {
+    const inner = scopeOf(child, scope);
+    if (isNamed(child.name, inner, ns, local)) {
+      return [child, inner];
+    }
+  }
+  return null;
+}
+
+/** A structure's simple field, as an attribute or an element, trimmed; `null` when absent. */
+function fieldText(holder: XmlElement, scope: Scope, ns: string, local: string): string | null {
+  const attr = holder.attrs.find(([k]) => isNamed(k, scope, ns, local, true));
+  if (attr !== undefined) {
+    return attr[1].trim();
+  }
+  const found = fieldElement(holder, scope, ns, local);
+  return found === null ? null : textOf(found[0]).trim();
+}
+
+/** A relative coordinate, or `null` when it is missing, not a number, or off the picture. */
+function coordinate(text: string | null): number | null {
+  if (text === null || text === "") {
+    return null;
+  }
+  const value = Number(text);
+  return Number.isFinite(value) && value >= 0 && value <= 1 ? value : null;
+}
+
+/** Whether a region's roles include the area of interest, by its NewsCodes URI (http or https). */
+function isAreaOfInterest(region: XmlElement, scope: Scope): boolean {
+  const roles = fieldElement(region, scope, IPTC_EXT_NS, "rRole");
+  if (roles === null) {
+    return false;
+  }
+  return listItems(...roles).some(([li, liScope]) => {
+    const [role, roleScope] = structOf(li, liScope);
+    const ids = fieldElement(role, roleScope, XMP_NS, "Identifier");
+    const values =
+      ids === null
+        ? [fieldText(role, roleScope, XMP_NS, "Identifier") ?? ""]
+        : listItems(...ids).map(([id]) => textOf(id).trim());
+    return values.some((value) => value.replace(/^https:/, "http:") === AREA_OF_INTEREST);
+  });
+}
+
+/**
+ * The focal point an image region states: a relative polygon of exactly one vertex whose role is
+ * the area of interest. Any other region (a face, a crop, a rectangle) is `null`, and kept.
+ */
+function focusOf(li: XmlElement, scope: Scope): FocalPoint | null {
+  const [region, regionScope] = structOf(li, scope);
+  const boundaryField = fieldElement(region, regionScope, IPTC_EXT_NS, "RegionBoundary");
+  if (boundaryField === null || !isAreaOfInterest(region, regionScope)) {
+    return null;
+  }
+  const [boundary, boundaryScope] = structOf(...boundaryField);
+  const vertices = fieldElement(boundary, boundaryScope, IPTC_EXT_NS, "rbVertices");
+  if (
+    fieldText(boundary, boundaryScope, IPTC_EXT_NS, "rbShape") !== "polygon" ||
+    fieldText(boundary, boundaryScope, IPTC_EXT_NS, "rbUnit") !== "relative" ||
+    vertices === null
+  ) {
+    return null;
+  }
+  const points = listItems(...vertices);
+  if (points.length !== 1) {
+    return null;
+  }
+  const [point, pointScope] = structOf(...points[0]!);
+  const x = coordinate(fieldText(point, pointScope, IPTC_EXT_NS, "rbX"));
+  const y = coordinate(fieldText(point, pointScope, IPTC_EXT_NS, "rbY"));
+  return x === null || y === null ? null : { x, y };
+}
+
+/** Tags without blanks or repeats, in order. */
+export function cleanTags(tags: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const raw of tags) {
+    const tag = raw.trim();
+    const key = tag.toLowerCase();
+    if (tag !== "" && !seen.has(key)) {
+      seen.add(key);
+      out.push(tag);
+    }
+  }
+  return out;
+}
+
+/**
+ * What a packet says about the file: its alt text and tags. `null` (no packet) is the empty record.
+ * Throws {@link XmpParseError} when the packet is not well formed.
+ */
+export function readMediaRecord(packet: string | null): MediaRecord {
+  if (packet === null) {
+    return emptyMediaRecord();
+  }
+  const record = emptyMediaRecord();
+  let altFound = false;
+  for (const [description, scope] of descriptions(parseXml(packet))) {
+    for (const [name, value] of description.attrs) {
+      // The attribute form a simple-valued property may take: never a list, but tolerated.
+      if (!altFound && isNamed(name, scope, IPTC_CORE_NS, "AltTextAccessibility", true)) {
+        record.alt = value;
+        altFound = true;
+      }
+    }
+    for (const property of elements(description.children)) {
+      const inner = scopeOf(property, scope);
+      if (!altFound && isNamed(property.name, inner, IPTC_CORE_NS, "AltTextAccessibility")) {
+        record.alt = altFrom(property, inner);
+        altFound = true;
+      } else if (isNamed(property.name, inner, DC_NS, "subject")) {
+        record.tags.push(...listItems(property, inner).map(([li]) => textOf(li)));
+      } else if (
+        record.focus === null &&
+        isNamed(property.name, inner, IPTC_EXT_NS, "ImageRegion")
+      ) {
+        for (const [li, liScope] of listItems(property, inner)) {
+          record.focus ??= focusOf(li, liScope);
+        }
+      }
+    }
+  }
+  record.tags = cleanTags(record.tags);
+  record.alt = record.alt.trim();
+  return record;
+}
+
+// ─── Writing ─────────────────────────────────────────────────────────────────
+
+const PACKET_BEGIN = `<?xpacket begin="" id="W5M0MpCehiHzreSzNTczkc9d"?>`;
+const PACKET_END = `<?xpacket end="w"?>`;
+
+/** A fresh packet holding one empty description: what a file with no XMP is given. */
+function freshPacket(): string {
+  return (
+    `${PACKET_BEGIN}<x:xmpmeta xmlns:x="${X_NS}"><rdf:RDF xmlns:rdf="${RDF_NS}">` +
+    `<rdf:Description rdf:about=""/></rdf:RDF></x:xmpmeta>${PACKET_END}`
+  );
+}
+
+/** A prefix bound to `ns` in scope, else bind `preferred` (or a numbered variant) on `element`. */
+function prefixFor(element: XmlElement, scope: Scope, ns: string, preferred: string): string {
+  for (const [prefix, uri] of scope) {
+    if (uri === ns && prefix !== "") {
+      return prefix;
+    }
+  }
+  let prefix = preferred;
+  for (let n = 1; scope.has(prefix) || element.attrs.some(([k]) => k === `xmlns:${prefix}`); n++) {
+    prefix = `${preferred}${n}`;
+  }
+  element.attrs.push([`xmlns:${prefix}`, ns]);
+  return prefix;
+}
+
+function el(name: string, attrs: [string, string][], children: XmlNode[]): XmlElement {
+  return { attrs, children, name, type: "element" };
+}
+
+/** Remove one property, in element and attribute form, from a description. */
+function dropProperty(description: XmlElement, scope: Scope, ns: string, local: string): void {
+  description.attrs = description.attrs.filter(([k]) => !isNamed(k, scope, ns, local, true));
+  description.children = description.children.filter(
+    (node) => node.type !== "element" || !isNamed(node.name, scopeOf(node, scope), ns, local),
+  );
+}
+
+/**
+ * The existing lang-alt entries other than `x-default`, so a rewrite of the alt text keeps the
+ * translations another tool wrote.
+ */
+function otherLanguages(description: XmlElement, scope: Scope): { lang: string; text: string }[] {
+  const property = elements(description.children).find((node) =>
+    isNamed(node.name, scopeOf(node, scope), IPTC_CORE_NS, "AltTextAccessibility"),
+  );
+  if (property === undefined) {
+    return [];
+  }
+  return listItems(property, scopeOf(property, scope))
+    .filter(([li, s]) => (langOf(li, s) ?? "x-default").toLowerCase() !== "x-default")
+    .map(([li, s]) => ({ lang: langOf(li, s) ?? "", text: textOf(li) }));
+}
+
+/**
+ * The packet with its alt text and tags set to `record`, everything else kept.
+ *
+ * `null` (the file has no packet) starts a fresh one. Throws {@link XmpParseError} when the existing
+ * packet does not parse: a rewrite never replaces what it could not read.
+ */
+export function writeMediaRecord(packet: string | null, record: MediaRecord): string {
+  const nodes = parseXml(packet ?? freshPacket());
+  const all = descriptions(nodes);
+  const [target, scope] = all[0] ?? addDescription(nodes);
+  const translations = otherLanguages(target, scope);
+  for (const [description, s] of all) {
+    dropProperty(description, s, IPTC_CORE_NS, "AltTextAccessibility");
+    dropProperty(description, s, DC_NS, "subject");
+    dropFocus(description, s);
+  }
+  const rdf = prefixFor(target, scope, RDF_NS, "rdf");
+  const alt = record.alt.trim();
+  if (alt !== "" || translations.length > 0) {
+    const iptc = prefixFor(target, scope, IPTC_CORE_NS, "Iptc4xmpCore");
+    // Re-homed under a new container, each language is written with `xml:`, which is always bound.
+    const entries = alt === "" ? translations : [{ lang: "x-default", text: alt }, ...translations];
+    const items = entries.map(({ lang, text }) =>
+      el(`${rdf}:li`, [["xml:lang", lang]], [{ type: "text", value: text }]),
+    );
+    target.children.push(el(`${iptc}:AltTextAccessibility`, [], [el(`${rdf}:Alt`, [], items)]));
+  }
+  const tags = cleanTags(record.tags);
+  if (tags.length > 0) {
+    const dc = prefixFor(target, scope, DC_NS, "dc");
+    const items = tags.map((tag) => el(`${rdf}:li`, [], [{ type: "text", value: tag }]));
+    target.children.push(el(`${dc}:subject`, [], [el(`${rdf}:Bag`, [], items)]));
+  }
+  if (record.focus !== null) {
+    writeFocus(all.length === 0 ? [[target, scope]] : all, record.focus);
+  }
+  return serializeXml(nodes);
+}
+
+/**
+ * Remove every focal-point region from a description's image regions, keeping the others, and the
+ * property itself when it no longer holds any.
+ */
+function dropFocus(description: XmlElement, scope: Scope): void {
+  description.children = description.children.filter((node) => {
+    if (node.type !== "element") {
+      return true;
+    }
+    const inner = scopeOf(node, scope);
+    if (!isNamed(node.name, inner, IPTC_EXT_NS, "ImageRegion")) {
+      return true;
+    }
+    for (const container of elements(node.children)) {
+      const containerScope = scopeOf(container, inner);
+      container.children = container.children.filter(
+        (li) => li.type !== "element" || focusOf(li, scopeOf(li, containerScope)) === null,
+      );
+    }
+    return listItems(node, inner).length > 0;
+  });
+}
+
+/** A decimal short enough to read, exact enough for any picture: four places. */
+function decimal(value: number): string {
+  return String(Math.round(value * 10_000) / 10_000);
+}
+
+/**
+ * Add the focal-point region: into the image regions a description already has (the first one with
+ * any), else as a new bag on the first description, so a file never carries the property twice.
+ */
+function writeFocus(all: readonly [XmlElement, Scope][], focus: FocalPoint): void {
+  let home: [XmlElement, Scope] = all[0]!;
+  let bag: XmlElement | null = null;
+  for (const [description, scope] of all) {
+    const found = fieldElement(description, scope, IPTC_EXT_NS, "ImageRegion");
+    const container = found === null ? undefined : elements(found[0].children)[0];
+    if (container !== undefined) {
+      home = [description, scope];
+      bag = container;
+      break;
+    }
+  }
+  const [description, scope] = home;
+  const rdf = prefixFor(description, scope, RDF_NS, "rdf");
+  const ext = prefixFor(description, scope, IPTC_EXT_NS, "Iptc4xmpExt");
+  const xmp = prefixFor(description, scope, XMP_NS, "xmp");
+  const resource = (): [string, string][] => [[`${rdf}:parseType`, "Resource"]];
+  const text = (name: string, value: string): XmlElement => el(name, [], [{ type: "text", value }]);
+  const point = el(`${rdf}:li`, resource(), [
+    text(`${ext}:rbX`, decimal(focus.x)),
+    text(`${ext}:rbY`, decimal(focus.y)),
+  ]);
+  const boundary = el(`${ext}:RegionBoundary`, resource(), [
+    text(`${ext}:rbShape`, "polygon"),
+    text(`${ext}:rbUnit`, "relative"),
+    el(`${ext}:rbVertices`, [], [el(`${rdf}:Seq`, [], [point])]),
+  ]);
+  const roleId = el(`${rdf}:Bag`, [], [text(`${rdf}:li`, AREA_OF_INTEREST)]);
+  const roleName = el(
+    `${rdf}:li`,
+    [["xml:lang", "x-default"]],
+    [{ type: "text", value: "Focal point" }],
+  );
+  const role = el(`${rdf}:li`, resource(), [
+    el(`${xmp}:Identifier`, [], [roleId]),
+    el(`${ext}:Name`, [], [el(`${rdf}:Alt`, [], [roleName])]),
+  ]);
+  const region = el(`${rdf}:li`, resource(), [
+    boundary,
+    el(`${ext}:rRole`, [], [el(`${rdf}:Bag`, [], [role])]),
+  ]);
+  if (bag === null) {
+    description.children.push(el(`${ext}:ImageRegion`, [], [el(`${rdf}:Bag`, [], [region])]));
+  } else {
+    bag.children.push(region);
+  }
+}
+
+/** Whether two focal points are the same point, as written (to four places). */
+export function sameFocus(a: FocalPoint | null, b: FocalPoint | null): boolean {
+  return a === null || b === null
+    ? a === b
+    : decimal(a.x) === decimal(b.x) && decimal(a.y) === decimal(b.y);
+}
+
+/** The `rdf:RDF` element and the scope inside it, or `null` when the packet has none. */
+function findRdf(nodes: readonly XmlNode[], scope: Scope = new Map()): [XmlElement, Scope] | null {
+  for (const element of elements(nodes)) {
+    const inner = scopeOf(element, scope);
+    if (isNamed(element.name, inner, RDF_NS, "RDF")) {
+      return [element, inner];
+    }
+    const found = findRdf(element.children, inner);
+    if (found !== null) {
+      return found;
+    }
+  }
+  return null;
+}
+
+/**
+ * Give a packet with no description one, under its `rdf:RDF` and in that element's own prefix.
+ * Refuses a packet with no RDF at all: there is nowhere a property could go.
+ */
+function addDescription(nodes: readonly XmlNode[]): [XmlElement, Scope] {
+  const found = findRdf(nodes);
+  if (found === null) {
+    throw new XmpParseError("The packet has no rdf:RDF element.");
+  }
+  const [rdf, scope] = found;
+  const colon = rdf.name.indexOf(":");
+  const prefix = colon === -1 ? "" : `${rdf.name.slice(0, colon)}:`;
+  const description = el(`${prefix}Description`, [[`${prefix}about`, ""]], []);
+  rdf.children.push(description);
+  return [description, scope];
+}
+
+/** Whether two records say the same thing. */
+export function sameMediaRecord(a: MediaRecord, b: MediaRecord): boolean {
+  return (
+    a.alt.trim() === b.alt.trim() &&
+    sameFocus(a.focus, b.focus) &&
+    a.tags.length === b.tags.length &&
+    a.tags.every((tag, index) => tag === b.tags[index])
+  );
+}