@suzumiyaaoba/mdxr 0.5.0 → 0.6.0

package/README.md

@@ -37,6 +37,12 @@ mdxr render plan.mdx --format json   # machine-readable errors
 
 Preview a document in the browser with live reload (`-p, --port`, default `3737`; `--open` to launch the browser once serving).
 
+### Review the rendered document
+
+Select text and click **Add comment**, or open **Annotate → Select figure** to comment on an image, diagram, or chart. Edit or delete comments in the panel, then **Copy Markdown** to send the quoted targets, source locations, and feedback to a coding agent.
+
+Saved annotations remain in your browser for that document; they do not modify the source file or travel with the HTML. If the document changes, targets that cannot be identified keep their original quotes and are marked unavailable. [Review annotations](https://suzumiyaaoba.com/mdxr/annotations) describes keyboard shortcuts, storage, and clipboard fallbacks.
+
 ### `mdxr text [file]`
 
 Render an `.mdx` document to plain Markdown — every component becomes an ASCII/text stand-in (status checkbox lists, block-bar charts, GFM tables, `<details>` disclosures) so the document stays readable in any Markdown viewer or terminal. Interactive-only widgets (dialogs, menus, shadcn chrome) degrade to their text content; unknown components warn to stderr and keep their children.

package/dist/cli.mjs

@@ -27,6 +27,7 @@ import { Fragment, createElement } from "react";
 import { icons } from "@iconify-json/lucide";
 import { icons as icons$1 } from "@iconify-json/vscode-icons";
 import { differenceInCalendarDays, isValid, parseISO } from "date-fns";
+import { createHash } from "node:crypto";
 import { build } from "esbuild";
 import os from "node:os";
 import { spawn } from "node:child_process";
@@ -1298,6 +1299,10 @@ const remarkInclude = () => (tree, file) => {
 	const expand = (parent, origin, chain) => {
 		if (chain.length > 32) file.fail("Include: nesting exceeds 32 files");
 		for (const child of parent.children) {
+			child.data = {
+				...child.data,
+				mdxrSourceFile: origin
+			};
 			if (isInclude(child)) {
 				const included = includedDocument(child, origin, chain, file);
 				expand(included.tree, included.abs, [...chain, included.abs]);
@@ -4675,6 +4680,67 @@ const mergeUserComponents = (mod, into = {}) => {
 	else if (isComponent(val) && /^[A-Z]/u.test(key)) put(into, key, val);
 	return into;
 };
+//#endregion
+//#region src/annotation-html.ts
+/** The pinned CSS optimizer does not parse custom highlights yet. Append these
+* native rules after optimization; limiting them to screens keeps print clean. */
+const ANNOTATION_HIGHLIGHT_CSS = `@media screen {
+::highlight(mdxr-annotations) { background-color: #facc1559; }
+::highlight(mdxr-annotation-active) { background-color: #38bdf859; }
+}`;
+/** Document chrome lives outside the hydrated MDX tree. All user text is filled via textContent. */
+const annotationHtml = (icon) => `
+<div id="mdxr-annotations" class="mdxr-annotations">
+  <button type="button" class="mdxr-annotation-toggle" data-annotation-toggle aria-controls="mdxr-annotation-panel" aria-expanded="false">
+    ${icon("message-square-text")} Annotate <span data-annotation-count>0</span>
+  </button>
+  <button type="button" class="mdxr-annotation-selection" data-annotation-selection hidden>${icon("message-square-plus")} Add comment</button>
+  <aside id="mdxr-annotation-panel" aria-labelledby="mdxr-annotation-title" hidden>
+    <header class="mdxr-annotation-header">
+      <div class="mdxr-annotation-heading">
+        <div class="mdxr-annotation-title-row"><h2 id="mdxr-annotation-title">Annotations</h2><span data-annotation-panel-count>0</span></div>
+        <p class="mdxr-annotation-document" data-annotation-document></p>
+      </div>
+      <button type="button" class="mdxr-annotation-icon-button" data-annotation-pick aria-label="Select figure" title="Select figure" aria-pressed="false">${icon("scan")}</button>
+      <button type="button" class="mdxr-annotation-icon-button" data-annotation-close aria-label="Close annotations" title="Close annotations (Esc)">${icon("x")}</button>
+    </header>
+    <div class="mdxr-annotation-scroll">
+      <div class="mdxr-annotation-picker" data-annotation-figure-picker hidden>
+        <label class="mdxr-annotation-sr-only" for="mdxr-annotation-figure">Figure</label>
+        <select id="mdxr-annotation-figure" data-annotation-figure></select>
+        <button type="button" class="mdxr-annotation-icon-button" data-annotation-use-figure aria-label="Comment on figure" title="Comment on figure">${icon("arrow-up-right")}</button>
+      </div>
+      <form class="mdxr-annotation-composer" data-annotation-form aria-label="New comment" hidden>
+        <blockquote data-annotation-draft-quote></blockquote>
+        <label class="mdxr-annotation-sr-only" for="mdxr-annotation-comment">Comment</label>
+        <textarea id="mdxr-annotation-comment" data-annotation-comment rows="4" required placeholder="Comment…"></textarea>
+        <div class="mdxr-annotation-composer-footer">
+          <button type="button" class="mdxr-annotation-icon-button" data-annotation-cancel aria-label="Cancel" title="Cancel">${icon("x")}</button>
+          <button type="submit" class="mdxr-annotation-submit" data-annotation-save aria-label="Save comment" title="Save comment (Ctrl / ⌘ + Enter)">${icon("arrow-up")}</button>
+        </div>
+      </form>
+      <p class="mdxr-annotation-empty" data-annotation-empty>No comments</p>
+      <ol class="mdxr-annotation-list" data-annotation-list></ol>
+    </div>
+    <footer class="mdxr-annotation-footer">
+      <button type="button" data-annotation-copy aria-label="Copy Markdown" title="Copy Markdown" disabled><span class="mdxr-annotation-copy-idle">${icon("copy")}</span><span class="mdxr-annotation-copy-done">${icon("check")}</span><span data-annotation-copy-label>Markdown</span></button>
+      <div class="mdxr-annotation-save-status" data-annotation-status-row data-state="saved"><p role="status" aria-live="polite" data-annotation-status></p></div>
+      <div data-annotation-export hidden>
+        <label class="mdxr-annotation-sr-only" for="mdxr-annotation-markdown">Markdown feedback</label>
+        <textarea id="mdxr-annotation-markdown" data-annotation-markdown rows="5" readonly></textarea>
+      </div>
+    </footer>
+  </aside>
+  <div class="mdxr-annotation-overlays" data-annotation-overlays aria-hidden="true"></div>
+  <div data-annotation-icons hidden>
+    <template data-annotation-icon="text">${icon("quote")}</template>
+    <template data-annotation-icon="figure">${icon("image")}</template>
+    <template data-annotation-icon="go">${icon("arrow-up-right")}</template>
+    <template data-annotation-icon="edit">${icon("pencil-line")}</template>
+    <template data-annotation-icon="delete">${icon("trash")}</template>
+    <template data-annotation-icon="warning">${icon("triangle-alert")}</template>
+  </div>
+</div>`;
 /** Mermaid bootstrap (module). Only injected when the document uses it. */
 const MERMAID_JS = `
 import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
@@ -4779,11 +4845,12 @@ const htmlDocument = (o) => `<!doctype html>
 <title>${escapeHtml(o.title)}</title>
 <script>${inlineScript(THEME_JS)}<\/script>
 ${o.needsKatex === true ? `<link rel="stylesheet" href="${KATEX_CDN_URL}">` : ""}
-<style>${inlineStyle(o.css)}</style>
+<style>${inlineStyle(o.css)}${o.annotations === void 0 ? "" : ANNOTATION_HIGHLIGHT_CSS}</style>
 </head>
 <body class="bg-white text-neutral-900 antialiased dark:bg-neutral-950 dark:text-neutral-100">
 ${THEME_TOGGLE_HTML}
 <main id="mdxr-root" class="prose prose-neutral dark:prose-invert mx-auto max-w-3xl px-6 py-10">${o.body}</main>
+${o.annotations === void 0 ? "" : `${annotationHtml(iconSvg)}<script type="application/json" id="mdxr-annotation-document">${JSON.stringify(o.annotations).replaceAll("<", "\\u003c")}<\/script>`}
 <script>${inlineScript(o.clientJs)}<\/script>
 ${o.needsMermaid ? `<script type="module">${inlineScript(MERMAID_JS)}<\/script>` : ""}
 ${o.liveReload === true ? `<script>${inlineScript(LIVE_RELOAD_JS)}<\/script>` : ""}
@@ -5678,6 +5745,38 @@ const rehypeShiki = () => async (tree) => {
 	})]);
 };
 //#endregion
+//#region src/remark/annotation-sources.ts
+/** A sidecar source index: no wrappers or props that change component children. */
+const remarkAnnotationSources = () => (tree, file) => {
+	const sources = [];
+	let heading = "";
+	visit(tree, (node) => {
+		if (node.type === "heading") heading = textContent$1(node).trim();
+		if (node.position === void 0 || node.name === "Include" || ![
+			"paragraph",
+			"heading",
+			"code",
+			"image",
+			"mdxJsxFlowElement",
+			"mdxJsxTextElement"
+		].includes(node.type)) return;
+		const origin = isRecord(node.data) ? node.data.mdxrSourceFile : void 0;
+		const label = jsxAttr(node, "caption") ?? jsxAttr(node, "title") ?? jsxAttr(node, "aria-label") ?? jsxAttr(node, "alt") ?? "";
+		const image = "url" in node && typeof node.url === "string" ? node.url : jsxAttr(node, "src") ?? "";
+		const text = typeof node.value === "string" ? node.value : textContent$1(node);
+		sources.push({
+			end: node.position.end.line,
+			file: typeof origin === "string" ? origin : file.path,
+			heading,
+			image,
+			label,
+			start: node.position.start.line,
+			text
+		});
+	});
+	file.data.annotationSources = sources;
+};
+//#endregion
 //#region src/mdx.ts
 /**
 * Which catalog entries the document references is visible in the compiled
@@ -5735,7 +5834,8 @@ const mdxToHtml = async (source, components, filePath = "document.mdx", opts = {
 			remarkCodeFile,
 			remarkCodeMeta,
 			remarkFilePaths,
-			remarkReferences
+			remarkReferences,
+			remarkAnnotationSources
 		]
 	});
 	for (const m of compiled.messages) process.stderr.write(`mdxr: warning: ${formatError(m)}\n`);
@@ -5760,6 +5860,7 @@ const mdxToHtml = async (source, components, filePath = "document.mdx", opts = {
 		throw enhanceRenderError(error, Object.keys(components));
 	}
 	return {
+		annotationSources: compiled.data.annotationSources ?? [],
 		body,
 		code,
 		context,
@@ -6251,6 +6352,7 @@ const importLine = (absPath) => `@import ${JSON.stringify(absPath.replaceAll("\\
 const buildCss = async (sources, themePath) => {
 	const input = [
 		"@import \"./src/styles/globals.css\";",
+		"@import \"./src/assets/annotations.css\";",
 		"@plugin \"@tailwindcss/typography\";",
 		"@plugin \"@iconify/tailwind4\";",
 		BASE_CSS,
@@ -6374,7 +6476,7 @@ const render = async (source, opts = {}) => {
 		...builtinComponents,
 		...user.components
 	};
-	const { body, code, fileLinks, frontmatter, renderedAt, renderWithHeader, usedComponents, usedIcons } = await mdxToHtml(source, components, filePath, {
+	const { annotationSources, body, code, fileLinks, frontmatter, renderedAt, renderWithHeader, usedComponents, usedIcons } = await mdxToHtml(source, components, filePath, {
 		editor: config.editor,
 		hydrate: opts.hydrate
 	});
@@ -6434,6 +6536,12 @@ const render = async (source, opts = {}) => {
 		usedIcons: docIcons
 	})]);
 	return htmlDocument({
+		annotations: {
+			file: filePath,
+			revision: createHash("sha256").update(code).digest("hex"),
+			sources: annotationSources,
+			title
+		},
 		body: docBody,
 		clientJs: js,
 		css,

package/dist/components.d.mts

@@ -69,7 +69,7 @@ declare function AlertAction({ className, ...props }: React$2.ComponentProps<"di
 //#region src/components/ui/button.d.ts
 declare const buttonVariants: (props?: ({
   size?: "default" | "sm" | "xs" | "icon" | "icon-lg" | "icon-sm" | "icon-xs" | "lg" | null | undefined;
-  variant?: "default" | "destructive" | "link" | "ghost" | "outline" | "secondary" | null | undefined;
+  variant?: "default" | "destructive" | "ghost" | "link" | "outline" | "secondary" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 declare function Button({ className, variant, size, ...props }: Button$1.Props & VariantProps<typeof buttonVariants>): import("react").JSX.Element;
 //#endregion
@@ -126,7 +126,7 @@ declare function AvatarGroupCount({ className, ...props }: React$2.ComponentProp
 //#endregion
 //#region src/components/ui/badge.d.ts
 declare const badgeVariants: (props?: ({
-  variant?: "default" | "destructive" | "link" | "ghost" | "outline" | "secondary" | null | undefined;
+  variant?: "default" | "destructive" | "ghost" | "link" | "outline" | "secondary" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 declare function Badge({ className, variant, render, ...props }: useRender.ComponentProps<"span"> & VariantProps<typeof badgeVariants>): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suzumiyaaoba/mdxr",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Render agent-authored MDX documents (plans, reports) to standalone HTML with a semantic component catalog",
   "keywords": [
     "agents",

package/src/annotation-html.ts

@@ -0,0 +1,60 @@
+/** The pinned CSS optimizer does not parse custom highlights yet. Append these
+ * native rules after optimization; limiting them to screens keeps print clean. */
+export const ANNOTATION_HIGHLIGHT_CSS = `@media screen {
+::highlight(mdxr-annotations) { background-color: #facc1559; }
+::highlight(mdxr-annotation-active) { background-color: #38bdf859; }
+}`;
+
+/** Document chrome lives outside the hydrated MDX tree. All user text is filled via textContent. */
+export const annotationHtml = (icon: (name: string) => string): string => `
+<div id="mdxr-annotations" class="mdxr-annotations">
+  <button type="button" class="mdxr-annotation-toggle" data-annotation-toggle aria-controls="mdxr-annotation-panel" aria-expanded="false">
+    ${icon("message-square-text")} Annotate <span data-annotation-count>0</span>
+  </button>
+  <button type="button" class="mdxr-annotation-selection" data-annotation-selection hidden>${icon("message-square-plus")} Add comment</button>
+  <aside id="mdxr-annotation-panel" aria-labelledby="mdxr-annotation-title" hidden>
+    <header class="mdxr-annotation-header">
+      <div class="mdxr-annotation-heading">
+        <div class="mdxr-annotation-title-row"><h2 id="mdxr-annotation-title">Annotations</h2><span data-annotation-panel-count>0</span></div>
+        <p class="mdxr-annotation-document" data-annotation-document></p>
+      </div>
+      <button type="button" class="mdxr-annotation-icon-button" data-annotation-pick aria-label="Select figure" title="Select figure" aria-pressed="false">${icon("scan")}</button>
+      <button type="button" class="mdxr-annotation-icon-button" data-annotation-close aria-label="Close annotations" title="Close annotations (Esc)">${icon("x")}</button>
+    </header>
+    <div class="mdxr-annotation-scroll">
+      <div class="mdxr-annotation-picker" data-annotation-figure-picker hidden>
+        <label class="mdxr-annotation-sr-only" for="mdxr-annotation-figure">Figure</label>
+        <select id="mdxr-annotation-figure" data-annotation-figure></select>
+        <button type="button" class="mdxr-annotation-icon-button" data-annotation-use-figure aria-label="Comment on figure" title="Comment on figure">${icon("arrow-up-right")}</button>
+      </div>
+      <form class="mdxr-annotation-composer" data-annotation-form aria-label="New comment" hidden>
+        <blockquote data-annotation-draft-quote></blockquote>
+        <label class="mdxr-annotation-sr-only" for="mdxr-annotation-comment">Comment</label>
+        <textarea id="mdxr-annotation-comment" data-annotation-comment rows="4" required placeholder="Comment…"></textarea>
+        <div class="mdxr-annotation-composer-footer">
+          <button type="button" class="mdxr-annotation-icon-button" data-annotation-cancel aria-label="Cancel" title="Cancel">${icon("x")}</button>
+          <button type="submit" class="mdxr-annotation-submit" data-annotation-save aria-label="Save comment" title="Save comment (Ctrl / ⌘ + Enter)">${icon("arrow-up")}</button>
+        </div>
+      </form>
+      <p class="mdxr-annotation-empty" data-annotation-empty>No comments</p>
+      <ol class="mdxr-annotation-list" data-annotation-list></ol>
+    </div>
+    <footer class="mdxr-annotation-footer">
+      <button type="button" data-annotation-copy aria-label="Copy Markdown" title="Copy Markdown" disabled><span class="mdxr-annotation-copy-idle">${icon("copy")}</span><span class="mdxr-annotation-copy-done">${icon("check")}</span><span data-annotation-copy-label>Markdown</span></button>
+      <div class="mdxr-annotation-save-status" data-annotation-status-row data-state="saved"><p role="status" aria-live="polite" data-annotation-status></p></div>
+      <div data-annotation-export hidden>
+        <label class="mdxr-annotation-sr-only" for="mdxr-annotation-markdown">Markdown feedback</label>
+        <textarea id="mdxr-annotation-markdown" data-annotation-markdown rows="5" readonly></textarea>
+      </div>
+    </footer>
+  </aside>
+  <div class="mdxr-annotation-overlays" data-annotation-overlays aria-hidden="true"></div>
+  <div data-annotation-icons hidden>
+    <template data-annotation-icon="text">${icon("quote")}</template>
+    <template data-annotation-icon="figure">${icon("image")}</template>
+    <template data-annotation-icon="go">${icon("arrow-up-right")}</template>
+    <template data-annotation-icon="edit">${icon("pencil-line")}</template>
+    <template data-annotation-icon="delete">${icon("trash")}</template>
+    <template data-annotation-icon="warning">${icon("triangle-alert")}</template>
+  </div>
+</div>`;

package/src/annotations.ts

@@ -0,0 +1,224 @@
+import { isRecord } from "./guards.js";
+
+export interface AnnotationSource {
+  file: string;
+  start: number;
+  end: number;
+  text: string;
+  heading: string;
+  label: string;
+  image: string;
+}
+
+export interface AnnotationDocument {
+  file: string;
+  revision: string;
+  title: string;
+  sources: AnnotationSource[];
+}
+
+export interface AnnotationAnchor {
+  kind: "text" | "figure";
+  revision: string;
+  /** Child-element indexes from #mdxr-root; never an executable selector. */
+  path: number[];
+  quote: string;
+  heading: string;
+  prefix: string;
+  suffix: string;
+  start: number;
+  end: number;
+  image: string;
+  /** Original location, retained if the document later changes. */
+  source?: AnnotationSource;
+}
+
+export interface DocumentAnnotation {
+  id: string;
+  comment: string;
+  anchor: AnnotationAnchor;
+}
+
+export const normalizeAnnotationText = (text: string): string =>
+  text.replaceAll(/\s+/gu, " ").trim();
+
+/** Report a source range only when the rendered target identifies one block. */
+export const findAnnotationSource = (
+  anchor: AnnotationAnchor,
+  sources: readonly AnnotationSource[]
+): AnnotationSource | undefined => {
+  const quote = normalizeAnnotationText(anchor.quote);
+  let matches = sources.filter((source) =>
+    anchor.kind === "text"
+      ? quote !== "" && normalizeAnnotationText(source.text).includes(quote)
+      : (anchor.image !== "" && source.image === anchor.image) ||
+        (quote !== "" && normalizeAnnotationText(source.label) === quote)
+  );
+  if (matches.length > 1 && anchor.heading !== "") {
+    const contextual = matches.filter(
+      (source) => source.heading === anchor.heading
+    );
+    if (contextual.length > 0) {
+      matches = contextual;
+    }
+  }
+  // JSX containers and their paragraphs can describe the same source region.
+  matches = matches.filter(
+    (source) =>
+      !matches.some(
+        (other) =>
+          other !== source &&
+          other.file === source.file &&
+          other.start >= source.start &&
+          other.end <= source.end &&
+          other.end - other.start < source.end - source.start
+      )
+  );
+  const [first] = matches;
+  return first !== undefined &&
+    matches.every(
+      (source) =>
+        source.file === first.file &&
+        source.start === first.start &&
+        source.end === first.end
+    )
+    ? first
+    : undefined;
+};
+
+const markdownText = (value: string): string =>
+  value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll(/(?<symbol>[\\`*_{}[\]()#+.!|>~-])/gu, "\\$<symbol>");
+
+const codeSpan = (value: string): string => {
+  const runs = value.match(/`+/gu) ?? [];
+  const fence = "`".repeat(Math.max(0, ...runs.map((run) => run.length)) + 1);
+  return `${fence} ${value.replaceAll(/[\r\n]/gu, " ")} ${fence}`;
+};
+
+export const annotationLocation = (source: AnnotationSource): string =>
+  `${source.file}:${source.start}${source.end === source.start ? "" : `-${source.end}`}`;
+
+/** Plain Markdown handoff; quotes are data, while comments retain Markdown. */
+export const annotationsMarkdown = (
+  document: Pick<AnnotationDocument, "file" | "title">,
+  annotations: readonly DocumentAnnotation[],
+  detached: ReadonlySet<string> = new Set()
+): string => {
+  const lines = [
+    `# Feedback: ${markdownText(normalizeAnnotationText(document.title))}`,
+    "",
+    `Document: ${codeSpan(document.file)}`,
+    "",
+    "Please address the following review comments in the source document.",
+  ];
+  for (const [index, annotation] of annotations.entries()) {
+    const { anchor, comment } = annotation;
+    lines.push(
+      "",
+      `## ${index + 1}. ${anchor.kind === "text" ? "Text" : "Figure"} comment`,
+      ""
+    );
+    if (anchor.source !== undefined) {
+      lines.push(
+        `Source block: ${codeSpan(annotationLocation(anchor.source))}`
+      );
+    }
+    if (anchor.heading !== "") {
+      lines.push(`Section: ${markdownText(anchor.heading)}`);
+    }
+    if (anchor.image !== "") {
+      lines.push(`Image: ${codeSpan(anchor.image)}`);
+    }
+    if (detached.has(annotation.id)) {
+      lines.push(
+        "Target no longer found in the current rendering; the quote and source location below refer to the original selection."
+      );
+    }
+    lines.push(
+      "",
+      ...anchor.quote.split(/\r?\n/u).map((line) => `> ${markdownText(line)}`),
+      "",
+      "**Comment**",
+      "",
+      comment.trim()
+    );
+  }
+  return `${lines.join("\n")}\n`;
+};
+
+const isIndex = (value: unknown): value is number =>
+  typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+
+const isSource = (value: unknown): value is AnnotationSource =>
+  isRecord(value) &&
+  ["file", "text", "heading", "label", "image"].every(
+    (key) => typeof value[key] === "string"
+  ) &&
+  isIndex(value.start) &&
+  value.start > 0 &&
+  isIndex(value.end) &&
+  value.end >= value.start;
+
+const isAnchor = (value: unknown): value is AnnotationAnchor =>
+  isRecord(value) &&
+  (value.kind === "text" || value.kind === "figure") &&
+  Array.isArray(value.path) &&
+  value.path.every(isIndex) &&
+  ["quote", "heading", "prefix", "suffix", "image", "revision"].every(
+    (key) => typeof value[key] === "string"
+  ) &&
+  isIndex(value.start) &&
+  isIndex(value.end) &&
+  value.end >= value.start &&
+  (value.source === undefined || isSource(value.source));
+
+const isAnnotation = (value: unknown): value is DocumentAnnotation =>
+  isRecord(value) &&
+  typeof value.id === "string" &&
+  value.id !== "" &&
+  typeof value.comment === "string" &&
+  value.comment.trim() !== "" &&
+  isAnchor(value.anchor);
+
+export const parseAnnotations = (raw: string | null): DocumentAnnotation[] => {
+  if (raw === null) {
+    return [];
+  }
+  const value: unknown = JSON.parse(raw);
+  if (
+    !isRecord(value) ||
+    value.version !== 1 ||
+    !Array.isArray(value.annotations) ||
+    !value.annotations.every(isAnnotation)
+  ) {
+    throw new Error("Invalid saved annotations");
+  }
+  const annotations: DocumentAnnotation[] = value.annotations;
+  if (new Set(annotations.map(({ id }) => id)).size !== annotations.length) {
+    throw new Error("Duplicate annotation identifiers");
+  }
+  return annotations;
+};
+
+export const parseAnnotationDocument = (
+  raw: string
+): AnnotationDocument | undefined => {
+  const value: unknown = JSON.parse(raw);
+  return isRecord(value) &&
+    typeof value.file === "string" &&
+    typeof value.title === "string" &&
+    typeof value.revision === "string" &&
+    Array.isArray(value.sources) &&
+    value.sources.every(isSource)
+    ? {
+        file: value.file,
+        revision: value.revision,
+        sources: value.sources,
+        title: value.title,
+      }
+    : undefined;
+};