dsh-figmark 1.1.3 → 1.2.1

package/lib/index.js

@@ -22,12 +22,13 @@ const GUIDANCE = [
 	"用户可能在文档预览里直接标注（箭头/框选/椭圆/手绘/单点），发送给你的消息以【附图标注】开头，正文就是**逐条标注清单**，不需要再去读任何附加文件（标注文件是投递用的临时件，发出即删）。收到时按下列纪律处理：",
 	"",
 	"1. 逐条读消息正文的清单：每条形如 `① 箭头 (10,10) → (40,30)，批注：标号指错了`。括号里是图面像素坐标，原点在左上角；框选与圈选给的是**左上角-右下角**，手绘线给的是它画在哪个框里。`批注：` 之后是用户写的**详细说明**——那是这条标注唯一的内容，按它判断意图。有的条目在形状后面紧跟一个圆括号，写着该处落在哪个元素上（SVG 给元素标题/`id`/元素文字，HTML 给 `selector`/元素文字），定位时优先用它。",
+	"1a. 若某条写的是**元素**而不是形状（`① 元素 …`），那条标注指的不是\"在这里画个框\"，而是**那一个元素本身**：圆括号里给的是选中时抽到的名字（元素标题 / `id` / 元素文字 / 选择器），按它去源文件里找到那一个元素，改的就是它，不是它周围的一块区域。这类标注没有可挪动的形状，用户说的\"这里\"就是那个元素。",
 	"2. **PDF 是整份文档一份标注**：每条标注都带 `第 N 页`，坐标是那一页自己的（原点在该页左上角）。看每条标注前先确认它的页码。",
 	"3. 若标注超出原图边界，标注图会把越界的那圈纸也画出来，并用**灰色虚线**框住原图真正的边缘：虚线**里面**是原图，**外面**是你画的标注伸出去的部分——那块不属于图，不要把它当成新增的画布内容。有形状的标注（箭头/框选/椭圆/手绘）会附一张标注图（`<图名>.annotated.png`，PDF 则是一份**带批注的 PDF**，其批注是原生 PDF 注释对象：`/Ink` 手绘、`/Square` 框选、`/Circle` 圈选、`/Line` 箭头），可直接打开核对图面位置。**若消息说「本条标注只有位置点，没有标注图」，那就是全部内容：只有坐标加一句说明，直接按原图定位处理，不要去找不存在的附件。**",
 	"4. 逐条处理标注：每条标注都要落到具体的图面改动，并在答复里逐条回应（编号与标注一致）。无法实现的标注要说明原因，不要静默跳过。",
 	"5. 修改附图以**标注所指的生成源**为准（绘制脚本、SVG 源或 `generate_patent_figure` 的入参），不要直接涂改导出的位图；PDF 同理，改的是生成该 PDF 的源头，不是那份带批注的副本。未标注的部分保持不动。",
 	"6. 改完图后重新渲染并核对：图面尺寸/坐标若变化，旧标注的坐标会失准，此时以 `anchor` 与标注文字为准复核一遍，再回报结果。",
-	"7. 若消息以【HTML 标注】开头，那是**渲染出来的 HTML 文档**：标注画在固定 1024px 宽的渲染面上，`points` 是那个宽度下的渲染像素。这类标注**没有标注图**（浏览器无法把渲染好的文档栅格化成图片），所以定位只能靠 `marks[].anchor.selector`——那是一条**可直接粘贴使用**的精确路径：每段是 `tag:nth-of-type(n)`，遇到 `#id` 就在那里截断，因此它要么以 `body > …` 开头，要么直接是 `#id > …`；`anchor.text` 是该元素的文字，`points` 只作辅助（渲染宽度一变坐标就会漂）。",
+	"7. 若消息以【HTML 标注】开头，那是**渲染出来的 HTML 文档**：标注画在固定 1024px 宽的渲染面上，`points` 是那个宽度下的渲染像素。这类标注**没有标注图**（浏览器无法把渲染好的文档栅格化成图片），所以定位只能靠 `marks[].anchor.selector`——那是一条**可直接粘贴使用**的精确路径：每段是 `tag:nth-of-type(n)`，遇到 `#id` 就在那里截断，因此它要么以 `body > …` 开头，要么直接是 `#id > …`；`anchor.text` 是该元素的文字，`points` 只作辅助（渲染宽度一变坐标就会漂）。SVG 的元素标注同理，只是那条路径以 `<svg>` 元素本身为根（`svg > g:nth-of-type(2) > …`），遇到 `#id` 同样在那里截断——所以它要么以 `svg > …` 开头，要么直接是 `#id > …`。",
 	"8. 处理 HTML 标注时，改的是**生成这份 HTML 的源文件**（模板、生成脚本或 HTML 本体），不是预览里的渲染结果；渲染面按本插件内联的样式与脚本策略绘制，脚本不会执行、外部资源不会加载，所以别把\"预览里看起来不对\"当成文件本身的问题。"
 ].join("\n");
 /** Section order used for the Markdown edit-proposal guidance (after the annotation one). */
@@ -82,8 +83,36 @@ function parseFileAddress(address) {
 	}
 	if (rest.startsWith("absolute/")) return { path: decodeSegment(rest.slice(9)) };
 }
-/** Route prefix owned by this plugin. */
-const ROUTE_PREFIX = "/dsh-figmark";
+//#endregion
+//#region src/shared/path-name.ts
+/**
+* The two path-name readings both halves need, in one place.
+*
+* A path arrives here from the Host (which uses platform separators) or from a
+* browser document (which only ever writes `/`), so every splitter has to accept
+* both. They used to be written out at each call site — once for the address
+* grammar, once for the suffix table, once for a file name in a message — and the
+* copies had already drifted apart on backslashes. One home makes them agree.
+* @module dsh-figmark/shared/path-name
+*/
+/**
+* The last segment of a path, whatever separators it uses.
+* @param path - a POSIX- or Windows-separated path.
+* @returns the path's file name.
+*/
+function baseNameOf(path) {
+	return path.slice(Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1);
+}
+/**
+* Read a path's lower-case suffix without the dot.
+* @param path - file path or name.
+* @returns the suffix, or an empty string when the name has none.
+*/
+function suffixOf(path) {
+	const name = baseNameOf(path);
+	const dot = name.lastIndexOf(".");
+	return dot <= 0 ? "" : name.slice(dot + 1).toLowerCase();
+}
 //#endregion
 //#region src/shared/figure-kind.ts
 /**
@@ -115,24 +144,8 @@ const FIGURE_EXTENSIONS = [
 	"html",
 	"htm"
 ];
-/**
-* Read a path's lower-case suffix without the dot.
-* @param path - file path or name.
-* @returns the suffix, or an empty string when there is none.
-*/
-function suffixOf(path) {
-	const name = path.slice(Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1);
-	const dot = name.lastIndexOf(".");
-	return dot <= 0 ? "" : name.slice(dot + 1).toLowerCase();
-}
-/**
-* Whether a path names a document this plugin renders.
-* @param path - file path.
-* @returns true when the suffix is one this plugin annotates.
-*/
-function isFigurePath(path) {
-	return FIGURE_EXTENSIONS.includes(suffixOf(path));
-}
+/** Media type of a document that has pages rather than one surface. */
+const PAGED_MEDIA_TYPE = "application/pdf";
 /**
 * Media type of one document path.
 * @param path - file path.
@@ -140,7 +153,7 @@ function isFigurePath(path) {
 */
 function figureMediaType(path) {
 	switch (suffixOf(path)) {
-		case "pdf": return "application/pdf";
+		case "pdf": return PAGED_MEDIA_TYPE;
 		case "svg": return "image/svg+xml";
 		case "png": return "image/png";
 		case "jpg":
@@ -154,155 +167,265 @@ function figureMediaType(path) {
 		default: return;
 	}
 }
-//#endregion
-//#region src/host/sidecar.ts
 /**
-* Annotation files beside one figure.
+* Whether a path names a document this plugin renders.
+* @param path - file path.
+* @returns true when the suffix is one this plugin annotates.
+*/
+function isFigurePath(path) {
+	return FIGURE_EXTENSIONS.includes(suffixOf(path));
+}
+/**
+* Whether a figure's suffix calls for the paged-document treatment.
 *
-* An annotation never modifies the figure: it is written to sibling files
-* (`<name>.annot.json` for the marks and `<name>.annotated.png` — or
-* `<name>.annotated.pdf` for a document that has pages — for the flattened
-* review artifact). One figure is one document, however many pages it has, so a
-* paged document's marks share a single sidecar and name their page inside it.
+* One predicate for the whole plugin: the Host picks the review artifact's file
+* extension from it, the store refuses a review whose kind contradicts it, and the
+* browser half picks which JSON field carries the artifact from it. Reading the
+* media type instead would work today and break the day a second suffix maps to
+* `application/pdf`.
+* @param path - file path.
+* @returns true when the figure is a paged document.
+*/
+function isPagedFigurePath(path) {
+	return figureMediaType(path) === PAGED_MEDIA_TYPE;
+}
+//#endregion
+//#region src/host/figure-target.ts
+/**
+* Resolving one preview address to a figure that actually exists.
 *
-* The name keeps the figure's own extension (`fig1.svg` → `fig1.svg.annot.json`):
-* `fig1.svg` and `fig1.png` in one directory are two different documents, and marks
-* drawn on one of them mean nothing on the other, so they must never share a
-* sidecar. Every name is derived from the figure path, so the plugin can never be
-* asked to write an arbitrary location.
-* @module dsh-figmark/host/sidecar
+* This is the only place a request-supplied string becomes a filesystem path, so
+* it is where the plugin's write surface is defined: the address must parse as a
+* file address, must resolve to a suffix this plugin renders, and must name an
+* existing regular file. Anything else is refused with a message the browser can
+* put in front of the reader — and nothing downstream ever accepts a path from the
+* caller again, only the {@link FigureTarget} this module produced.
+* @module dsh-figmark/host/figure-target
 */
-/** Suffix appended to a figure's name for the marks file. */
-const ANNOTATION_SUFFIX = ".annot.json";
-/** Suffix appended to a figure's name for the flattened review artifact. */
-const ANNOTATED_SUFFIX = ".annotated";
 /**
-* Resolve one figure's sidecar paths.
-* @param figurePath - absolute path of the annotated figure.
-* @returns the sidecar paths; both live in the figure's own directory.
+* Resolve one request address to an existing figure file.
+* @param address - `dsh-resource://file/…` address from the preview tab.
+* @param sessionCwd - Session lookup used for a relative path.
+* @returns the target, or an error message describing why it cannot be annotated.
 */
-function sidecarPaths(figurePath) {
-	const name = basename(figurePath);
-	const directory = dirname(figurePath);
-	const reviewExtension = reviewFileExtension(figurePath);
+async function resolveTarget(address, sessionCwd) {
+	const parsed = parseFileAddress(address);
+	if (parsed === void 0) return {
+		ok: false,
+		message: `not a file address: ${address}`
+	};
+	const sessionId = parsed.sessionId;
+	const cwd = sessionId === void 0 ? void 0 : await sessionCwd(sessionId);
+	let absolute;
+	if (isAbsolute(parsed.path)) absolute = parsed.path;
+	else {
+		if (cwd === void 0) return {
+			ok: false,
+			message: `cannot resolve this Session's directory for a relative path: ${address}`
+		};
+		absolute = resolve(cwd, parsed.path);
+	}
+	if (!isFigurePath(absolute)) return {
+		ok: false,
+		message: `not an annotatable figure: ${absolute}`
+	};
+	const mediaType = figureMediaType(absolute);
+	/* v8 ignore next -- isFigurePath already restricted the suffixes figureMediaType covers. */
+	if (mediaType === void 0) return {
+		ok: false,
+		message: `no media type for ${absolute}`
+	};
+	try {
+		if ((await stat(absolute)).isFile()) return {
+			ok: true,
+			target: {
+				address,
+				path: absolute,
+				mediaType,
+				workspace: cwd ?? null
+			}
+		};
+	} catch {}
 	return {
-		annotation: join(directory, `${name}${ANNOTATION_SUFFIX}`),
-		review: join(directory, `${name}${ANNOTATED_SUFFIX}${reviewExtension}`)
+		ok: false,
+		message: `no such figure: ${absolute}`
 	};
 }
+/** Route prefix owned by this plugin. */
+const ROUTE_PREFIX = "/dsh-figmark";
+//#endregion
+//#region src/shared/annotation.ts
 /**
-* Suffix of the flattened review artifact for one figure.
+* Longest note one mark may carry, in characters.
 *
-* A paged document is reviewed as a document — the page marks travel as native
-* PDF annotations in a copy of the original — while a single-surface figure is
-* reviewed as the picture it is.
-* @param figurePath - absolute path of the annotated figure.
-* @returns the file extension, dot included.
+* Lives in `shared` because both halves need the same number for different
+* reasons: the browser stops the reader from typing past it, so the field cannot
+* grow into a sidecar the Host will refuse; the Host refuses one anyway, so a
+* client that forgot cannot write a file the next open cannot read. A single
+* number in one place is what keeps those two from drifting apart.
 */
-function reviewFileExtension(figurePath) {
-	return extname(figurePath).toLowerCase() === ".pdf" ? ".pdf" : ".png";
-}
+const MAX_DETAIL_CHARS = 4e3;
+/** Longest overall note a document may carry, in characters. */
+const MAX_SUMMARY_CHARS = 4e3;
+/** Thinnest stroke a mark can be drawn at, as a multiple of the default width. */
+const WEIGHT_MIN = .5;
 /**
-* The marks file this plugin derived before the figure's extension became part of
-* the name (`fig1.svg` → `fig1.annot.json`). Read-only: a file an earlier version
-* wrote stays readable, so an existing annotation never disappears on upgrade.
-* @param figurePath - absolute path of the annotated figure.
-* @returns the legacy marks file path beside the figure.
+* Hold a stroke weight inside the range the painter can draw.
+*
+* @param value - the weight to hold.
+* @returns the value, pulled to the nearest end of the range.
 */
-function legacyAnnotationPath(figurePath) {
-	return join(dirname(figurePath), `${basename(figurePath, extname(figurePath))}${ANNOTATION_SUFFIX}`);
+function clampWeight(value) {
+	return Math.min(8, Math.max(WEIGHT_MIN, value));
 }
+//#endregion
+//#region src/host/route-http.ts
 /**
-* Marks files to read for one figure, most authoritative first: the current name,
-* then the legacy one. A figure whose name carries no extension derives both from
-* the same name, so the list is deduplicated.
-* @param figurePath - absolute path of the annotated figure.
-* @returns the candidate marks file paths.
+* Largest accepted request body.
+*
+* Twice the review cap: the artifact travels base64-encoded inside a JSON
+* envelope, and base64 costs four characters for every three bytes. Anything past
+* this is refused before it is buffered, which is what keeps a hostile body from
+* being an allocation.
 */
-function annotationCandidates(figurePath) {
-	const current = sidecarPaths(figurePath).annotation;
-	const legacy = legacyAnnotationPath(figurePath);
-	return current === legacy ? [current] : [current, legacy];
-}
+const MAX_BODY_BYTES = 24 * 1024 * 1024 * 2;
 /**
-* Name pattern of the one-page-per-file sidecars this plugin wrote before a paged
-* document became a single annotation.
-*
-* Both spellings are matched — the extension-bearing name
-* (`fig1.pdf.p2.annot.json`) and the base-name one an even earlier version wrote
-* (`fig1.p2.annot.json`) — and the page number is the pattern's first group.
+* Whether a request carries the plugin guard and a same-origin posture.
 *
-* @param figurePath - absolute path of the annotated figure.
-* @returns an anchored, case-insensitive pattern over one directory entry's name.
+* A browser that does not send `Sec-Fetch-Site` at all cannot be origin-checked,
+* and the header alone is still a preflight requirement for any cross-origin
+* attempt — so an absent value passes and a present one must be same-origin.
+* @param req - incoming request.
+* @returns true when the request may proceed.
 */
-function legacyPagePattern(figurePath) {
-	const extension = extname(figurePath);
-	const alternatives = [.../* @__PURE__ */ new Set([basename(figurePath), basename(figurePath, extension)])].map(escapeForRegExp).join("|");
-	return new RegExp(`^(?:${alternatives})\\.p(\\d+)${escapeForRegExp(ANNOTATION_SUFFIX)}$`, "iu");
+function guarded(req) {
+	if (req.headers["x-dsh-figmark"] === void 0) return false;
+	const site = req.headers["sec-fetch-site"];
+	if (typeof site !== "string") return true;
+	return site === "same-origin" || site === "none";
 }
-/** Escape one literal so it matches itself inside a regular expression. */
-function escapeForRegExp(value) {
-	return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+/**
+* Write one JSON response.
+* @param res - response to own.
+* @param status - HTTP status code.
+* @param body - JSON-serializable payload.
+*/
+function sendJson(res, status, body) {
+	const text = JSON.stringify(body);
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"cache-control": "no-store"
+	});
+	res.end(text);
 }
 /**
-* Whether a stored document is the annotation of this very figure.
-*
-* A sidecar sits beside its figure and both names derive from the figure path, so
-* the file name — extension included, and case-insensitive because one file may be
-* spelled `FIG1.SVG` — is the whole identity. The check matters most for the legacy
-* name, which two figures sharing a base name also share.
-*
-* @param document - stored document to test.
-* @param figurePath - absolute path of the figure being opened.
-* @returns true when the document names this figure.
+* Write one refusal.
+* @param res - response to own.
+* @param status - HTTP status code.
+* @param error - what went wrong, in the Host's own words.
 */
-function annotationTargetsFigure(document, figurePath) {
-	return basename(document.figure.path).toLowerCase() === basename(figurePath).toLowerCase();
+function sendFailure(res, status, error) {
+	sendJson(res, status, {
+		ok: false,
+		error
+	});
+}
+/**
+* Read a request body with a byte cap.
+* @param req - incoming request.
+* @returns the body text.
+* @throws {Error} when the body exceeds the cap.
+*/
+async function readBody(req) {
+	const chunks = [];
+	let total = 0;
+	for await (const chunk of req) {
+		const buffer = chunk;
+		total += buffer.length;
+		if (total > MAX_BODY_BYTES) throw new Error(`request body exceeds ${MAX_BODY_BYTES} bytes`);
+		chunks.push(buffer);
+	}
+	return Buffer.concat(chunks).toString("utf8");
 }
 //#endregion
-//#region src/shared/annotation.ts
-/** Thinnest stroke a mark can be drawn at, as a multiple of the default width. */
-const WEIGHT_MIN = .5;
+//#region src/host/review-payload.ts
+/** First bytes of every PDF file, used to tell one payload from another. */
+const PDF_HEADER = "%PDF-";
 /**
-* Hold a stroke weight inside the range the painter can draw.
+* Read the one flattened review artifact a save may carry.
 *
-* @param value - the weight to hold.
-* @returns the value, pulled to the nearest end of the range.
+* The kind is taken from the payload, and the store refuses a pair that
+* contradicts the figure's own suffix — so a caller cannot name PNG bytes as the
+* review of a PDF.
+*
+* @param body - parsed request body.
+* @returns the artifact, or undefined when the save carried none.
+* @throws {Error} when both payloads are present, or the PDF bytes are not a PDF.
 */
-function clampWeight(value) {
-	return Math.min(8, Math.max(WEIGHT_MIN, value));
+function readReview(body) {
+	const image = typeof body["reviewImage"] === "string" ? body["reviewImage"] : "";
+	const pdf = typeof body["annotatedPdf"] === "string" ? body["annotatedPdf"] : "";
+	if (image !== "" && pdf !== "") throw new Error("a save carries one review artifact, not both");
+	if (pdf !== "") {
+		const bytes = new Uint8Array(Buffer.from(pdf, "base64"));
+		if (!Buffer.from(bytes.subarray(0, 5)).toString("latin1").startsWith(PDF_HEADER)) throw new Error("the annotated document is not a PDF");
+		return {
+			kind: "pdf",
+			bytes
+		};
+	}
+	if (image !== "") return {
+		kind: "image",
+		bytes: new Uint8Array(Buffer.from(image, "base64"))
+	};
 }
 //#endregion
-//#region src/host/store.ts
+//#region src/host/store-schema.ts
 /**
-* Reading and writing one figure's annotation sidecar.
+* The wire schema of one annotation document.
 *
-* The marks file is JSON owned by this plugin; the review artifact is the same
-* marks applied to the figure (a PNG for a single-surface figure, a copy of the
-* document carrying native PDF annotations for one that has pages). Both are
-* written through a temporary file and a rename, so a reader never observes a
-* half-written document.
-* @module dsh-figmark/host/store
+* Everything that crosses the HTTP boundary is JSON somebody else wrote, so it is
+* validated field by field before any of it reaches disk. This module owns that
+* one job: turning unknown JSON into {@link AnnotationDocument} or refusing it
+* with a message that names the field. It deliberately knows nothing about files
+* — the read and write modules call it, never the other way round.
+*
+* The two figure shapes are held apart here rather than tolerated downstream: a
+* document is either one surface (width and height) or a paged one (pageCount),
+* and a mark may name a page only when its figure has pages. A reader that got
+* both would have to guess which coordinate space the marks live in.
+* @module dsh-figmark/host/store-schema
 */
-/** Maximum accepted sidecar size; a document larger than this is not one we wrote. */
-const MAX_ANNOTATION_BYTES = 4 * 1024 * 1024;
-/** Maximum accepted flattened review artifact. */
-const MAX_REVIEW_BYTES = 24 * 1024 * 1024;
 /** Longest element selector one anchor may carry. */
 const MAX_SELECTOR_CHARS = 400;
+/**
+* A note as it is stored: trimmed, and refused when it is longer than a paragraph.
+*
+* The cap is enforced rather than truncated. A writer that silently cut a pasted
+* paragraph would hand the reader back a different sentence than the one they
+* wrote, with no way to tell which half survived; refusing says so and keeps the
+* screen's copy intact. Absent and empty are the same thing — an empty note is no
+* note, and writing one would make the file say something the reader did not.
+* @param value - the field as it arrived.
+* @param what - which field, for the refusal message.
+* @returns the note, or undefined when there is none.
+* @throws {Error} when the note is longer than a paragraph.
+*/
+function readNote(value, what, max) {
+	if (typeof value !== "string") return void 0;
+	if (value.length > max) throw new Error(`the annotation ${what} is longer than ${String(max)} characters`);
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
 /** Kinds a mark may declare. */
 const MARK_KINDS = [
 	"arrow",
 	"rect",
 	"ellipse",
 	"pen",
-	"point"
+	"point",
+	"element"
 ];
-/** Content hash of one file. */
-async function fileDigest(path) {
-	const bytes = await readFile(path);
-	return createHash("sha256").update(bytes).digest("hex");
-}
 /**
 * Whether a value is a finite figure coordinate pair.
 * @param value - candidate value from the wire.
@@ -340,16 +463,22 @@ function readAnchor(value) {
 	};
 }
 /**
-* Read one optional rotation from the wire.
+* Read one optional stroke weight from the wire.
 * @param value - the field as it arrived.
-* @returns the angle in degrees, or undefined when absent.
-* @throws {Error} when the field is present but is not a usable angle.
+* @returns the weight, or undefined when absent.
+* @throws {Error} when the field is present but is not a usable multiple.
 */
 function readWeight(value) {
 	if (value === void 0) return void 0;
 	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error("annotation mark weight must be a finite multiple of the default width");
 	return clampWeight(value);
 }
+/**
+* Read one optional rotation from the wire.
+* @param value - the field as it arrived.
+* @returns the angle in degrees, or undefined when absent.
+* @throws {Error} when the field is present but is not a finite number.
+*/
 function readRotation(value) {
 	if (value === void 0) return void 0;
 	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error("annotation mark rotation must be a finite number of degrees");
@@ -369,6 +498,19 @@ function readPositiveInteger(raw, field) {
 	return value;
 }
 /**
+* Read one optional positive size from the wire.
+* @param raw - the figure object as it arrived.
+* @param field - field name, used in the failure message.
+* @returns the size, or undefined when the field is absent.
+* @throws {Error} when the field is present but is not a positive number.
+*/
+function readSize(raw, field) {
+	const value = raw[field];
+	if (value === void 0) return void 0;
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) throw new Error(`annotation figure ${field} must be a positive number`);
+	return value;
+}
+/**
 * Validate one mark from the wire.
 *
 * A mark names the page it was drawn on exactly when its figure is a paged
@@ -396,12 +538,13 @@ function readMark(value, index, figure) {
 	const anchor = readAnchor(raw["anchor"]);
 	const rotation = readRotation(raw["rotation"]);
 	const weight = readWeight(raw["weight"]);
+	const detail = readNote(raw["detail"], "mark note", MAX_DETAIL_CHARS);
 	return {
 		id: raw["id"],
 		kind,
 		color: raw["color"],
 		points,
-		...typeof raw["detail"] === "string" ? { detail: raw["detail"] } : {},
+		...detail === void 0 ? {} : { detail },
 		...page === void 0 ? {} : { page },
 		...rotation === void 0 ? {} : { rotation },
 		...weight === void 0 ? {} : { weight },
@@ -409,66 +552,187 @@ function readMark(value, index, figure) {
 	};
 }
 /**
-* Validate a whole annotation document from the wire.
-* @param value - parsed request body.
-* @returns the validated document.
-* @throws {Error} when the body is not a document this plugin wrote.
+* Validate a whole annotation document from the wire.
+* @param value - parsed request body.
+* @returns the validated document.
+* @throws {Error} when the body is not a document this plugin wrote.
+*/
+function readAnnotationDocument(value) {
+	if (typeof value !== "object" || value === null) throw new Error("annotation document must be an object");
+	const raw = value;
+	if (raw["version"] !== 1) throw new Error(`annotation document version ${JSON.stringify(raw["version"])} is not 1`);
+	const figure = raw["figure"];
+	if (typeof figure !== "object" || figure === null) throw new Error("annotation document needs a figure");
+	const figureRaw = figure;
+	for (const field of [
+		"address",
+		"path",
+		"mediaType",
+		"sha256"
+	]) if (typeof figureRaw[field] !== "string" || figureRaw[field] === "") throw new Error(`annotation figure needs ${field}`);
+	const width = readSize(figureRaw, "width");
+	const height = readSize(figureRaw, "height");
+	if (width === void 0 !== (height === void 0)) throw new Error("annotation figure needs both its width and its height, or neither");
+	const pageCount = readPositiveInteger(figureRaw, "pageCount");
+	if (pageCount !== void 0 && width !== void 0) throw new Error("annotation figure is a paged document, so it cannot carry width and height");
+	const marks = raw["marks"];
+	if (!Array.isArray(marks)) throw new Error("annotation document needs a marks array");
+	const updatedAt = typeof raw["updatedAt"] === "string" ? raw["updatedAt"] : (/* @__PURE__ */ new Date()).toISOString();
+	const summary = readNote(raw["summary"], "document note", MAX_SUMMARY_CHARS);
+	return {
+		version: 1,
+		figure: {
+			address: figureRaw["address"],
+			path: figureRaw["path"],
+			mediaType: figureRaw["mediaType"],
+			sha256: figureRaw["sha256"],
+			...width !== void 0 && height !== void 0 ? {
+				width,
+				height
+			} : {},
+			...pageCount === void 0 ? {} : { pageCount }
+		},
+		createdAt: typeof raw["createdAt"] === "string" ? raw["createdAt"] : updatedAt,
+		updatedAt,
+		marks: marks.map((mark, index) => readMark(mark, index, {
+			...width === void 0 ? {} : { width },
+			...pageCount === void 0 ? {} : { pageCount }
+		})),
+		...summary === void 0 ? {} : { summary }
+	};
+}
+//#endregion
+//#region src/host/sidecar.ts
+/**
+* Annotation files beside one figure.
+*
+* An annotation never modifies the figure: it is written to sibling files
+* (`<name>.annot.json` for the marks and `<name>.annotated.png` — or
+* `<name>.annotated.pdf` for a document that has pages — for the flattened
+* review artifact). One figure is one document, however many pages it has, so a
+* paged document's marks share a single sidecar and name their page inside it.
+*
+* The name keeps the figure's own extension (`fig1.svg` → `fig1.svg.annot.json`):
+* `fig1.svg` and `fig1.png` in one directory are two different documents, and marks
+* drawn on one of them mean nothing on the other, so they must never share a
+* sidecar. Every name is derived from the figure path, so the plugin can never be
+* asked to write an arbitrary location.
+* @module dsh-figmark/host/sidecar
+*/
+/** Suffix appended to a figure's name for the marks file. */
+const ANNOTATION_SUFFIX = ".annot.json";
+/** Suffix appended to a figure's name for the flattened review artifact. */
+const ANNOTATED_SUFFIX = ".annotated";
+/**
+* Resolve one figure's sidecar paths.
+* @param figurePath - absolute path of the annotated figure.
+* @returns the sidecar paths; both live in the figure's own directory.
+*/
+function sidecarPaths(figurePath) {
+	const name = basename(figurePath);
+	const directory = dirname(figurePath);
+	const reviewExtension = reviewFileExtension(figurePath);
+	return {
+		annotation: join(directory, `${name}${ANNOTATION_SUFFIX}`),
+		review: join(directory, `${name}${ANNOTATED_SUFFIX}${reviewExtension}`)
+	};
+}
+/**
+* Suffix of the flattened review artifact for one figure.
+*
+* A paged document is reviewed as a document — the page marks travel as native
+* PDF annotations in a copy of the original — while a single-surface figure is
+* reviewed as the picture it is.
+* @param figurePath - absolute path of the annotated figure.
+* @returns the file extension, dot included.
+*/
+function reviewFileExtension(figurePath) {
+	return isPagedFigurePath(figurePath) ? ".pdf" : ".png";
+}
+/**
+* The marks file this plugin derived before the figure's extension became part of
+* the name (`fig1.svg` → `fig1.annot.json`). Read-only: a file an earlier version
+* wrote stays readable, so an existing annotation never disappears on upgrade.
+* @param figurePath - absolute path of the annotated figure.
+* @returns the legacy marks file path beside the figure.
+*/
+function legacyAnnotationPath(figurePath) {
+	return join(dirname(figurePath), `${basename(figurePath, extname(figurePath))}${ANNOTATION_SUFFIX}`);
+}
+/**
+* Marks files to read for one figure, most authoritative first: the current name,
+* then the legacy one. A figure whose name carries no extension derives both from
+* the same name, so the list is deduplicated.
+* @param figurePath - absolute path of the annotated figure.
+* @returns the candidate marks file paths.
+*/
+function annotationCandidates(figurePath) {
+	const current = sidecarPaths(figurePath).annotation;
+	const legacy = legacyAnnotationPath(figurePath);
+	return current === legacy ? [current] : [current, legacy];
+}
+/**
+* Name pattern of the one-page-per-file sidecars this plugin wrote before a paged
+* document became a single annotation.
+*
+* Both spellings are matched — the extension-bearing name
+* (`fig1.pdf.p2.annot.json`) and the base-name one an even earlier version wrote
+* (`fig1.p2.annot.json`) — and the page number is the pattern's first group.
+*
+* @param figurePath - absolute path of the annotated figure.
+* @returns an anchored, case-insensitive pattern over one directory entry's name.
+*/
+function legacyPagePattern(figurePath) {
+	const extension = extname(figurePath);
+	const alternatives = [.../* @__PURE__ */ new Set([basename(figurePath), basename(figurePath, extension)])].map(escapeForRegExp).join("|");
+	return new RegExp(`^(?:${alternatives})\\.p(\\d+)${escapeForRegExp(ANNOTATION_SUFFIX)}$`, "iu");
+}
+/** Escape one literal so it matches itself inside a regular expression. */
+function escapeForRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+/**
+* Whether a stored document is the annotation of this very figure.
+*
+* A sidecar sits beside its figure and both names derive from the figure path, so
+* the file name — extension included, and case-insensitive because one file may be
+* spelled `FIG1.SVG` — is the whole identity. The check matters most for the legacy
+* name, which two figures sharing a base name also share.
+*
+* @param document - stored document to test.
+* @param figurePath - absolute path of the figure being opened.
+* @returns true when the document names this figure.
 */
-function readAnnotationDocument(value) {
-	if (typeof value !== "object" || value === null) throw new Error("annotation document must be an object");
-	const raw = value;
-	if (raw["version"] !== 1) throw new Error(`annotation document version ${JSON.stringify(raw["version"])} is not 1`);
-	const figure = raw["figure"];
-	if (typeof figure !== "object" || figure === null) throw new Error("annotation document needs a figure");
-	const figureRaw = figure;
-	for (const field of [
-		"address",
-		"path",
-		"mediaType",
-		"sha256"
-	]) if (typeof figureRaw[field] !== "string" || figureRaw[field] === "") throw new Error(`annotation figure needs ${field}`);
-	const width = readSize(figureRaw, "width");
-	const height = readSize(figureRaw, "height");
-	if (width === void 0 !== (height === void 0)) throw new Error("annotation figure needs both its width and its height, or neither");
-	const pageCount = readPositiveInteger(figureRaw, "pageCount");
-	if (pageCount !== void 0 && width !== void 0) throw new Error("annotation figure is a paged document, so it cannot carry width and height");
-	const marks = raw["marks"];
-	if (!Array.isArray(marks)) throw new Error("annotation document needs a marks array");
-	const updatedAt = typeof raw["updatedAt"] === "string" ? raw["updatedAt"] : (/* @__PURE__ */ new Date()).toISOString();
-	return {
-		version: 1,
-		figure: {
-			address: figureRaw["address"],
-			path: figureRaw["path"],
-			mediaType: figureRaw["mediaType"],
-			sha256: figureRaw["sha256"],
-			...width !== void 0 && height !== void 0 ? {
-				width,
-				height
-			} : {},
-			...pageCount === void 0 ? {} : { pageCount }
-		},
-		createdAt: typeof raw["createdAt"] === "string" ? raw["createdAt"] : updatedAt,
-		updatedAt,
-		marks: marks.map((mark, index) => readMark(mark, index, {
-			...width === void 0 ? {} : { width },
-			...pageCount === void 0 ? {} : { pageCount }
-		})),
-		...typeof raw["summary"] === "string" && raw["summary"] !== "" ? { summary: raw["summary"] } : {}
-	};
+function annotationTargetsFigure(document, figurePath) {
+	return basename(document.figure.path).toLowerCase() === basename(figurePath).toLowerCase();
 }
+//#endregion
+//#region src/host/store-read.ts
 /**
-* Read one optional positive size from the wire.
-* @param raw - the figure object as it arrived.
-* @param field - field name, used in the failure message.
-* @returns the size, or undefined when the field is absent.
-* @throws {Error} when the field is present but is not a positive number.
+* Reading one figure's annotation sidecar, including the shapes older versions wrote.
+*
+* Three stored shapes have to read back as one document, because a figure
+* annotated by an earlier version must not lose its marks on upgrade: the current
+* sidecar name, the legacy base-name sidecar, and the per-page files a paged
+* document was once split into. All of them are read-only here — a save always
+* writes the current name — so the upgrade is invisible to the reader.
+*
+* Nothing in this module decides where a sidecar lives: the candidate names come
+* from the sidecar module, which derives every one of them from the figure path.
+* @module dsh-figmark/host/store-read
 */
-function readSize(raw, field) {
-	const value = raw[field];
-	if (value === void 0) return void 0;
-	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) throw new Error(`annotation figure ${field} must be a positive number`);
-	return value;
+/**
+* Content hash of one file.
+*
+* Read whole rather than streamed: the caller compares it against the hash the
+* browser recorded when the marks were drawn, and a figure large enough for the
+* difference to matter is not one this plugin renders in a sidebar.
+* @param path - absolute path of the file.
+* @returns the SHA-256 digest as lower-case hex.
+*/
+async function fileDigest(path) {
+	const bytes = await readFile(path);
+	return createHash("sha256").update(bytes).digest("hex");
 }
 /**
 * Read one figure's saved annotation.
@@ -478,15 +742,27 @@ function readSize(raw, field) {
 * that share a base name would otherwise read each other's marks.
 *
 * @param figurePath - absolute path of the figure.
-* @returns the document, or null when none was stored or it is unreadable.
+* @returns the document and any sidecar that was present but unusable.
 */
 async function readAnnotation(figurePath) {
+	const unreadable = [];
 	for (const candidate of annotationCandidates(figurePath)) {
-		const document = await readSidecar(candidate);
-		if (document !== null && annotationTargetsFigure(document, figurePath)) return document;
+		const read = await readSidecar(candidate);
+		if (read === "unreadable") unreadable.push(candidate);
+		else if (read !== null && annotationTargetsFigure(read, figurePath)) return {
+			annotation: read,
+			unreadable
+		};
 	}
-	if (figureMediaType(figurePath) !== "application/pdf") return null;
-	return await readLegacyPages(figurePath);
+	if (!isPagedFigurePath(figurePath)) return {
+		annotation: null,
+		unreadable
+	};
+	const merged = await readLegacyPages(figurePath);
+	return {
+		annotation: merged.annotation,
+		unreadable: [...unreadable, ...merged.unreadable]
+	};
 }
 /**
 * Restate the per-page sidecars an earlier version wrote as one document.
@@ -501,7 +777,7 @@ async function readAnnotation(figurePath) {
 * time it saves.
 *
 * @param figurePath - absolute path of the figure.
-* @returns the merged document, or null when no readable page file exists.
+* @returns the merged document, when any page file was readable.
 */
 async function readLegacyPages(figurePath) {
 	const directory = dirname(figurePath);
@@ -510,51 +786,64 @@ async function readLegacyPages(figurePath) {
 	try {
 		entries = await readdir(directory);
 	} catch {
-		return null;
+		return {
+			annotation: null,
+			unreadable: []
+		};
 	}
 	const pages = entries.map((name) => ({
 		name,
 		page: Number(pattern.exec(name)?.[1])
 	})).filter((entry) => Number.isInteger(entry.page) && entry.page > 0).sort((left, right) => left.page - right.page);
 	const read = [];
+	const unreadable = [];
 	for (const entry of pages) {
-		const document = await readSidecar(join(directory, entry.name));
-		if (document !== null && annotationTargetsFigure(document, figurePath)) read.push({
+		const path = join(directory, entry.name);
+		const document = await readSidecar(path);
+		if (document === "unreadable") unreadable.push(path);
+		else if (document !== null && annotationTargetsFigure(document, figurePath)) read.push({
 			page: entry.page,
 			document
 		});
 	}
 	const first = read[0];
-	if (first === void 0) return null;
+	if (first === void 0) return {
+		annotation: null,
+		unreadable
+	};
 	let summary;
 	for (const entry of read) if (entry.document.summary !== void 0) summary = entry.document.summary;
 	return {
-		version: 1,
-		figure: {
-			address: first.document.figure.address,
-			path: first.document.figure.path,
-			mediaType: first.document.figure.mediaType,
-			sha256: first.document.figure.sha256,
-			pageCount: read.reduce((highest, entry) => Math.max(highest, entry.page), first.page)
+		annotation: {
+			version: 1,
+			figure: {
+				address: first.document.figure.address,
+				path: first.document.figure.path,
+				mediaType: first.document.figure.mediaType,
+				sha256: first.document.figure.sha256,
+				pageCount: read.reduce((highest, entry) => Math.max(highest, entry.page), first.page)
+			},
+			createdAt: read.reduce((earliest, entry) => entry.document.createdAt < earliest ? entry.document.createdAt : earliest, first.document.createdAt),
+			updatedAt: read.reduce((latest, entry) => entry.document.updatedAt > latest ? entry.document.updatedAt : latest, first.document.updatedAt),
+			marks: read.flatMap((entry) => entry.document.marks.map((mark) => ({
+				...mark,
+				page: entry.page
+			}))),
+			...summary === void 0 ? {} : { summary }
 		},
-		createdAt: read.reduce((earliest, entry) => entry.document.createdAt < earliest ? entry.document.createdAt : earliest, first.document.createdAt),
-		updatedAt: read.reduce((latest, entry) => entry.document.updatedAt > latest ? entry.document.updatedAt : latest, first.document.updatedAt),
-		marks: read.flatMap((entry) => entry.document.marks.map((mark) => ({
-			...mark,
-			page: entry.page
-		}))),
-		...summary === void 0 ? {} : { summary }
+		unreadable
 	};
 }
 /**
 * Parse one marks file into this plugin's document shape.
 * @param sidecarPath - absolute path of the marks file.
-* @returns the document, or null when the file is missing, oversized, or unreadable.
+* @returns the document, null when there is no readable file, or `'unreadable'`
+*   when the file is there and is not something this plugin will read.
 */
 async function readSidecar(sidecarPath) {
 	let text;
 	try {
-		if ((await stat(sidecarPath)).size > MAX_ANNOTATION_BYTES) return null;
+		if ((await stat(sidecarPath)).size > 4194304) return "unreadable";
 		text = await readFile(sidecarPath, "utf8");
 	} catch {
 		return null;
@@ -611,6 +900,45 @@ function bridgeV2Document(raw) {
 		summary: raw["summary"]
 	};
 }
+//#endregion
+//#region src/host/store-write.ts
+/**
+* Writing one figure's annotation sidecar, and removing it again.
+*
+* The two files are written through a temporary name and a rename so a reader
+* never observes a half-written document: a preview opening while an autosave
+* runs reads either the previous document or the new one, never a truncated one.
+*
+* Both file names are derived here from the figure path, never passed in, and the
+* review artifact's kind is checked against the figure's own kind before anything
+* is touched — a PNG review of a PDF would be a file no reader could open.
+* @module dsh-figmark/host/store-write
+*/
+/**
+* How many scratch files this process has named.
+*
+* The clock is not enough on its own: two saves started in the same millisecond
+* share a pid and a millisecond, took the same scratch name, and one of them renamed
+* the other's half-written bytes into place — or found nothing to rename and failed a
+* save that had every right to succeed. A counter inside the process cannot repeat,
+* and the pid and clock still keep two *processes* apart.
+*/
+let scratchCount = 0;
+/**
+* Replace one file atomically.
+*
+* The temporary name carries the pid, a counter and the clock so two saves that
+* overlap cannot pick the same scratch file; the rename is the moment the new
+* content becomes observable.
+* @param path - absolute path of the file to replace.
+* @param content - text or bytes to write.
+*/
+async function writeAtomically(path, content) {
+	scratchCount += 1;
+	const temporary = `${path}.tmp-${process.pid}-${scratchCount}-${Date.now()}`;
+	await writeFile(temporary, content, typeof content === "string" ? "utf8" : void 0);
+	await rename(temporary, path);
+}
 /**
 * Write one figure's annotation, and optionally its flattened review artifact.
 * @param figurePath - absolute path of the annotated figure.
@@ -621,18 +949,14 @@ function bridgeV2Document(raw) {
 */
 async function writeAnnotation(figurePath, document, review) {
 	const paths = sidecarPaths(figurePath);
-	if (review !== void 0 && review.kind !== (reviewFileExtension(figurePath) === ".pdf" ? "pdf" : "image")) throw new Error(`a ${reviewFileExtension(figurePath)} review artifact cannot be written from ${review.kind} bytes`);
+	if (review !== void 0 && review.kind !== (isPagedFigurePath(figurePath) ? "pdf" : "image")) throw new Error(`a ${reviewFileExtension(figurePath)} review artifact cannot be written from ${review.kind} bytes`);
 	await mkdir(dirname(paths.annotation), { recursive: true });
-	const temporary = `${paths.annotation}.tmp-${process.pid}-${Date.now()}`;
-	await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, "utf8");
-	await rename(temporary, paths.annotation);
+	await writeAtomically(paths.annotation, `${JSON.stringify(document, null, 2)}\n`);
 	if (review === void 0) return {
 		paths,
 		wroteReview: false
 	};
-	const reviewTemporary = `${paths.review}.tmp-${process.pid}-${Date.now()}`;
-	await writeFile(reviewTemporary, review.bytes);
-	await rename(reviewTemporary, paths.review);
+	await writeAtomically(paths.review, review.bytes);
 	return {
 		paths,
 		wroteReview: true
@@ -654,7 +978,7 @@ async function writeAnnotation(figurePath, document, review) {
 async function removeAnnotation(figurePath) {
 	const paths = sidecarPaths(figurePath);
 	let removed = false;
-	for (const path of [paths.annotation, paths.review]) try {
+	for (const path of await allSidecarNames(figurePath)) try {
 		await rm(path, { force: false });
 		removed = true;
 	} catch (error) {
@@ -665,146 +989,113 @@ async function removeAnnotation(figurePath) {
 		removed
 	};
 }
-//#endregion
-//#region src/host/routes.ts
 /**
-* HTTP routes of the annotator.
+* Every file this plugin may have written beside one figure, oldest spelling first.
 *
-* The routes live outside the `/api` channel, so they carry their own guard: a
-* required request header (which a cross-origin form or image request cannot
-* set without a preflight this plugin never answers) plus an origin check on
-* browsers that send `Sec-Fetch-Site`. Writes are limited to the two sidecar
-* files derived from a figure that already exists.
-* @module dsh-figmark/host/routes
+* The read path accepts more names than the write path produces: the legacy
+* base-name sidecar (`fig1.annot.json` beside `fig1.svg`), and for a paged document
+* the one-file-per-page sidecars an earlier version wrote. Removing only the two
+* current names left those behind — and because the reader merges them back in, a
+* cleared figure reopened with its marks on it, which is the bug in finding 1.
+* Whatever the reader will read has to be what a clear removes.
+* @param figurePath - absolute path of the figure whose sidecars are removed.
+* @returns the paths to unlink.
 */
-/** Largest accepted request body. */
-const MAX_BODY_BYTES = MAX_REVIEW_BYTES * 2;
-/** First bytes of every PDF file, used to tell one payload from another. */
-const PDF_HEADER = "%PDF-";
+async function allSidecarNames(figurePath) {
+	const paths = sidecarPaths(figurePath);
+	const names = [
+		paths.annotation,
+		paths.review,
+		legacyAnnotationPath(figurePath)
+	];
+	if (isPagedFigurePath(figurePath)) {
+		const pattern = legacyPagePattern(figurePath);
+		let entries;
+		try {
+			entries = await readdir(dirname(figurePath));
+		} catch {
+			entries = [];
+		}
+		for (const entry of entries) if (pattern.test(entry)) names.push(join(dirname(figurePath), entry));
+	}
+	return [...new Set(names)];
+}
+//#endregion
+//#region src/host/routes.ts
 /**
-* Resolve one request address to an existing figure file.
-* @param address - `dsh-resource://file/…` address from the preview tab.
-* @param deps - Session lookup used for a relative path.
-* @returns the target, or an error message describing why it cannot be annotated.
+* Resolve the figure one request names, as an answer rather than an exception.
+* @param address - the address the request carried, empty when it carried none.
+* @param deps - Session lookup.
+* @returns the target, or the 404 refusal to send.
 */
-async function resolveTarget(address, deps) {
-	const parsed = parseFileAddress(address);
-	if (parsed === void 0) return {
+async function targetOf(address, deps) {
+	const resolved = await resolveTarget(address, deps.sessionCwd);
+	return resolved.ok ? {
+		ok: true,
+		body: resolved.target
+	} : {
 		ok: false,
-		message: `not a file address: ${address}`
+		status: 404,
+		error: resolved.message
 	};
-	let absolute;
-	if (isAbsolute(parsed.path)) absolute = parsed.path;
-	else {
-		const sessionId = parsed.sessionId;
-		const cwd = sessionId === void 0 ? void 0 : await deps.sessionCwd(sessionId);
-		if (cwd === void 0) return {
-			ok: false,
-			message: `cannot resolve this Session's directory for a relative path: ${address}`
-		};
-		absolute = resolve(cwd, parsed.path);
-	}
-	if (!isFigurePath(absolute)) return {
-		ok: false,
-		message: `not an annotatable figure: ${absolute}`
+}
+/**
+* Read the figure's current hash and its saved annotation.
+* @param target - the resolved figure.
+* @returns the read body.
+*/
+async function readAnswer(target) {
+	const saved = await readAnnotation(target.path);
+	const sha256 = await fileDigest(target.path);
+	return {
+		ok: true,
+		figure: {
+			...target,
+			sha256
+		},
+		annotation: saved.annotation,
+		...saved.unreadable.length === 0 ? {} : { unreadable: saved.unreadable }
 	};
-	const mediaType = figureMediaType(absolute);
-	/* v8 ignore next -- isFigurePath already restricted the suffixes figureMediaType covers. */
-	if (mediaType === void 0) return {
+}
+/**
+* Write the annotation one request carried.
+* @param target - the resolved figure.
+* @param raw - the parsed request body.
+* @returns the save body, or the refusal to send.
+*/
+async function saveAnswer(target, raw) {
+	const document = readAnnotationDocument(raw["annotation"]);
+	const review = readReview(raw);
+	if (review !== void 0 && review.bytes.byteLength > 25165824) return {
 		ok: false,
-		message: `no media type for ${absolute}`
+		status: 413,
+		error: "the review artifact is too large"
 	};
-	try {
-		if (!(await stat(absolute)).isFile()) return {
-			ok: false,
-			message: `not a regular file: ${absolute}`
-		};
-	} catch {
-		return {
-			ok: false,
-			message: `no such figure: ${absolute}`
-		};
-	}
+	const saved = await writeAnnotation(target.path, document, review);
 	return {
 		ok: true,
-		target: {
-			address,
-			path: absolute,
-			mediaType
+		body: {
+			ok: true,
+			annotationPath: saved.paths.annotation,
+			reviewPath: saved.wroteReview ? saved.paths.review : null
 		}
 	};
 }
 /**
-* Read the one flattened review artifact a save may carry.
-*
-* The kind is taken from the payload, and the store refuses a pair that
-* contradicts the figure's own suffix — so a caller cannot name PNG bytes as the
-* review of a PDF.
-*
-* @param body - parsed request body.
-* @returns the artifact, or undefined when the save carried none.
-* @throws {Error} when both payloads are present, or the PDF bytes are not a PDF.
+* Remove the sidecars of one figure.
+* @param target - the resolved figure.
+* @returns the removal body.
 */
-function readReview(body) {
-	const image = typeof body["reviewImage"] === "string" ? body["reviewImage"] : "";
-	const pdf = typeof body["annotatedPdf"] === "string" ? body["annotatedPdf"] : "";
-	if (image !== "" && pdf !== "") throw new Error("a save carries one review artifact, not both");
-	if (pdf !== "") {
-		const bytes = new Uint8Array(Buffer.from(pdf, "base64"));
-		if (!Buffer.from(bytes.subarray(0, 5)).toString("latin1").startsWith(PDF_HEADER)) throw new Error("the annotated document is not a PDF");
-		return {
-			kind: "pdf",
-			bytes
-		};
-	}
-	if (image !== "") return {
-		kind: "image",
-		bytes: new Uint8Array(Buffer.from(image, "base64"))
+async function removeAnswer(target) {
+	const removed = await removeAnnotation(target.path);
+	return {
+		ok: true,
+		annotationPath: removed.paths.annotation,
+		reviewPath: removed.paths.review,
+		removed: removed.removed
 	};
 }
 /**
-* Whether a request carries the plugin guard and a same-origin posture.
-* @param req - incoming request.
-* @returns true when the request may proceed.
-*/
-function guarded(req) {
-	if (req.headers["x-dsh-figmark"] === void 0) return false;
-	const site = req.headers["sec-fetch-site"];
-	if (typeof site !== "string") return true;
-	return site === "same-origin" || site === "none";
-}
-/**
-* Write one JSON response.
-* @param res - response to own.
-* @param status - HTTP status code.
-* @param body - JSON-serializable payload.
-*/
-function sendJson(res, status, body) {
-	const text = JSON.stringify(body);
-	res.writeHead(status, {
-		"content-type": "application/json; charset=utf-8",
-		"cache-control": "no-store"
-	});
-	res.end(text);
-}
-/**
-* Read a request body with a byte cap.
-* @param req - incoming request.
-* @returns the body text.
-* @throws {Error} when the body exceeds the cap.
-*/
-async function readBody(req) {
-	const chunks = [];
-	let total = 0;
-	for await (const chunk of req) {
-		const buffer = chunk;
-		total += buffer.length;
-		if (total > MAX_BODY_BYTES) throw new Error(`request body exceeds ${MAX_BODY_BYTES} bytes`);
-		chunks.push(buffer);
-	}
-	return Buffer.concat(chunks).toString("utf8");
-}
-/**
 * Build the route handlers this plugin registers.
 * @param deps - Session lookup.
 * @returns one handler per route path.
@@ -812,92 +1103,59 @@ async function readBody(req) {
 function createHandlers(deps) {
 	const annotation = async (req, res) => {
 		if (!guarded(req)) {
-			sendJson(res, 403, {
-				ok: false,
-				error: "missing plugin guard header"
-			});
+			sendFailure(res, 403, "missing plugin guard header");
 			return;
 		}
-		const url = new URL(req.url ?? "/", "http://localhost");
 		try {
-			if (req.method === "GET") {
-				const resolved = await resolveTarget(url.searchParams.get("address") ?? "", deps);
-				if (!resolved.ok) {
-					sendJson(res, 404, {
-						ok: false,
-						error: resolved.message
-					});
-					return;
-				}
-				const [sha256, saved] = await Promise.all([fileDigest(resolved.target.path), readAnnotation(resolved.target.path)]);
-				sendJson(res, 200, {
-					ok: true,
-					figure: {
-						...resolved.target,
-						sha256
-					},
-					annotation: saved
-				});
-				return;
-			}
-			if (req.method === "POST") {
-				const body = JSON.parse(await readBody(req));
-				const resolved = await resolveTarget(typeof body["address"] === "string" ? body["address"] : "", deps);
-				if (!resolved.ok) {
-					sendJson(res, 404, {
-						ok: false,
-						error: resolved.message
-					});
-					return;
-				}
-				const document = readAnnotationDocument(body["annotation"]);
-				const review = readReview(body);
-				if (review !== void 0 && review.bytes.byteLength > 25165824) {
-					sendJson(res, 413, {
-						ok: false,
-						error: "the review artifact is too large"
-					});
-					return;
-				}
-				const saved = await writeAnnotation(resolved.target.path, document, review);
-				sendJson(res, 200, {
-					ok: true,
-					annotationPath: saved.paths.annotation,
-					reviewPath: saved.wroteReview ? saved.paths.review : null
-				});
-				return;
-			}
-			if (req.method === "DELETE") {
-				const resolved = await resolveTarget(url.searchParams.get("address") ?? "", deps);
-				if (!resolved.ok) {
-					sendJson(res, 404, {
-						ok: false,
-						error: resolved.message
-					});
-					return;
-				}
-				const removed = await removeAnnotation(resolved.target.path);
-				sendJson(res, 200, {
-					ok: true,
-					annotationPath: removed.paths.annotation,
-					reviewPath: removed.paths.review,
-					removed: removed.removed
-				});
+			const answer = await route(req, new URL(req.url ?? "/", "http://localhost"), deps);
+			if (answer.ok) {
+				sendJson(res, 200, answer.body);
 				return;
 			}
-			sendJson(res, 405, {
-				ok: false,
-				error: `method ${req.method ?? ""} is not allowed`
-			});
+			sendFailure(res, answer.status, answer.error);
 		} catch (error) {
-			sendJson(res, 400, {
-				ok: false,
-				error: error instanceof Error ? error.message : String(error)
-			});
+			sendFailure(res, 400, error instanceof Error ? error.message : String(error));
 		}
 	};
 	return { annotation };
 }
+/**
+* Dispatch one guarded request to the operation its method names.
+* @param req - incoming request.
+* @param url - the request's URL.
+* @param deps - Session lookup.
+* @returns the answer to send.
+*/
+async function route(req, url, deps) {
+	const address = url.searchParams.get("address") ?? "";
+	if (req.method === "GET") {
+		const target = await targetOf(address, deps);
+		if (!target.ok) return target;
+		return {
+			ok: true,
+			body: await readAnswer(target.body)
+		};
+	}
+	if (req.method === "POST") {
+		const body = JSON.parse(await readBody(req));
+		const target = await targetOf(typeof body["address"] === "string" ? body["address"] : "", deps);
+		if (!target.ok) return target;
+		return await saveAnswer(target.body, body);
+	}
+	if (req.method === "DELETE") {
+		const target = await targetOf(address, deps);
+		if (!target.ok) return target;
+		return {
+			ok: true,
+			body: await removeAnswer(target.body)
+		};
+	}
+	return {
+		ok: false,
+		status: 405,
+		error: `method ${req.method ?? ""} is not allowed`
+	};
+}
 //#endregion
 //#region src/host/session-cwd.ts
 /**