@hajimism/dek 0.2.1 → 0.2.2

package/src/core/zip.ts

@@ -0,0 +1,77 @@
+/** One file of an archive: its path inside it, with `/` between folders, and its bytes. */
+export type ZipFile = { path: string; data: Uint8Array };
+
+/**
+ * A ZIP archive of `files`, in order, each stored as it is. What dek packs is pictures, already
+ * compressed, and a little XML, so deflating would buy little and cost a dependency or a
+ * compressor to keep. Paths are UTF-8, and the time is fixed, so the same files make the same
+ * bytes.
+ */
+export function zipStored(files: readonly ZipFile[]): Uint8Array {
+  const encoder = new TextEncoder();
+  const locals: Uint8Array[] = [];
+  const centrals: Uint8Array[] = [];
+  let offset = 0;
+  for (const file of files) {
+    const name = encoder.encode(file.path);
+    const crc = Bun.hash.crc32(file.data);
+    const size = file.data.length;
+
+    const local = new Uint8Array(30 + name.length);
+    const head = new DataView(local.buffer);
+    head.setUint32(0, 0x04034b50, true);
+    writeCommon(head, 4, { crc, size });
+    head.setUint16(26, name.length, true);
+    local.set(name, 30);
+    locals.push(local, file.data);
+
+    const central = new Uint8Array(46 + name.length);
+    const entry = new DataView(central.buffer);
+    entry.setUint32(0, 0x02014b50, true);
+    entry.setUint16(4, 20, true);
+    writeCommon(entry, 6, { crc, size });
+    entry.setUint16(28, name.length, true);
+    entry.setUint32(42, offset, true);
+    central.set(name, 46);
+    centrals.push(central);
+
+    offset += local.length + size;
+  }
+  const directorySize = centrals.reduce((sum, part) => sum + part.length, 0);
+  const end = new Uint8Array(22);
+  const tail = new DataView(end.buffer);
+  tail.setUint32(0, 0x06054b50, true);
+  tail.setUint16(8, files.length, true);
+  tail.setUint16(10, files.length, true);
+  tail.setUint32(12, directorySize, true);
+  tail.setUint32(16, offset, true);
+  return concat([...locals, ...centrals, end]);
+}
+
+/** 1980-01-01 00:00, the earliest time a ZIP can say. */
+const DOS_DATE = (0 << 9) | (1 << 5) | 1;
+
+/**
+ * What the local header and the central directory entry share, from the version needed on: no
+ * flags but UTF-8 names, stored, the fixed time, the CRC, and the size twice.
+ */
+function writeCommon(view: DataView, at: number, { crc, size }: { crc: number; size: number }) {
+  view.setUint16(at, 20, true);
+  view.setUint16(at + 2, 1 << 11, true);
+  view.setUint16(at + 4, 0, true);
+  view.setUint16(at + 6, 0, true);
+  view.setUint16(at + 8, DOS_DATE, true);
+  view.setUint32(at + 10, crc, true);
+  view.setUint32(at + 14, size, true);
+  view.setUint32(at + 18, size, true);
+}
+
+function concat(parts: readonly Uint8Array[]): Uint8Array {
+  const out = new Uint8Array(parts.reduce((sum, part) => sum + part.length, 0));
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.length;
+  }
+  return out;
+}

package/src/runtime/annotate-pick.ts

@@ -3,9 +3,9 @@
 // each is called, and where it is on the slide. Only elements the dev server stamped with where
 // they are written count, so every one can be named by its file and line.
 
+import { type Box, cutText } from "../core/annotation-rows.ts";
 import { deckStops, positionFromHash } from "../core/position.ts";
 import { type BeatRef, stepKey } from "../core/step.ts";
-import type { Box } from "./annotate-notes.ts";
 
 /** The attribute the dev server writes on each start tag of a slide: `<line>:<column>`. */
 export const SOURCE_ATTR = "data-dek-source";
@@ -13,9 +13,6 @@ export const SOURCE_ATTR = "data-dek-source";
 /** The classes the dev server saw written on each stamped tag, before any script added more. */
 const CLASS_ATTR = "data-dek-class";
 
-/** How long a text may be before it is cut short. */
-const TEXT_MAX = 40;
-
 type Point = { x: number; y: number };
 
 /**
@@ -92,11 +89,10 @@ export function describeElement(
   slide: Element,
 ): { source: string; name: string; text: string } {
   const classes = (el.getAttribute(CLASS_ATTR) ?? "").split(" ").filter(Boolean);
-  const text = el === slide ? "" : (el.textContent ?? "").replace(/\s+/g, " ").trim();
   return {
     source: el.getAttribute(SOURCE_ATTR) ?? "",
     name: [el.tagName.toLowerCase(), ...classes].join("."),
-    text: text.length > TEXT_MAX ? `${text.slice(0, TEXT_MAX)}…` : text,
+    text: el === slide ? "" : cutText(el.textContent ?? ""),
   };
 }
 

package/src/runtime/annotate-view.ts

@@ -1,15 +1,7 @@
 /// <reference lib="dom" />
-import { PAGE_ID } from "../core/page.ts";
+import { type AnnotationRow, type Box, formatNotes, type Point } from "../core/annotation-rows.ts";
+import { ANNOTATIONS_CHANGED, PAGE_ID } from "../core/page.ts";
 import type { PresenterSlide } from "../core/presenter-state.ts";
-import {
-  formatNotes,
-  type Note,
-  type NoteTarget,
-  readNotes,
-  reanchor,
-  sortNotes,
-  writeNotes,
-} from "./annotate-notes.ts";
 import {
   candidatesAt,
   currentStop,
@@ -23,8 +15,6 @@ import { placePopup } from "./annotate-place.ts";
 import { slideSelector } from "./live.ts";
 import { isLetterKey, isTextEntry } from "./step.ts";
 
-type Point = { x: number; y: number };
-
 /** One element picked for the note being written, and where the click that picked it was. */
 type Pick = { el: Element; at: Point };
 
@@ -45,6 +35,7 @@ const LABELS = {
   notes: (n: number) => `${n} ${n === 1 ? "note" : "notes"}`,
   copied: (n: number) => `Copied ${n} ${n === 1 ? "note" : "notes"}`,
   manual: "Press ⌘C or Ctrl+C to copy",
+  failed: (why: string) => `Not saved: ${why}`,
 };
 
 /** Line icons, drawn in the text's color. */
@@ -111,20 +102,43 @@ textarea::placeholder { color: var(--faint); }
 [data-part=undo] { margin-left: auto; padding: 3px 10px; color: var(--ink); background: var(--raised); }
 `;
 
+/** A note as the page sends it: the elements by where each start tag is written. */
+type NewTarget = { source: string; box: Box; point?: Point };
+
+/**
+ * What the page asks of the dev server's notes; each answer is the deck's notes as they stand,
+ * and a clear also hands back what it took, to put back.
+ */
+type Ask = (
+  op?:
+    | { op: "add"; slug: string; step: string; text: string; targets: NewTarget[] }
+    | { op: "edit"; id: string; text: string }
+    | { op: "remove"; id: string }
+    | { op: "clear" }
+    | { op: "restore"; annotations: unknown[] },
+) => Promise<{ annotations: AnnotationRow[]; removed?: unknown[] }>;
+
 /**
  * Annotate mode: point at elements of the slide on screen, write what should change, and copy
  * the notes as one block for an agent, each element named by the file and line it is written
  * at. It runs only on the dev server's pages for the speaker, beside the player, and shows
  * nothing until `a` or the presenter bar's button turns it on: the page may be on the projector.
+ * The notes are the dev server's, kept in `.dek/annotations.json` for `dekc annotations` to
+ * read; every tab of the deck shows the same ones, and asks again whenever they or a slide change.
  */
-export function createAnnotateView(options: { deck: string; slides: PresenterSlide[] }): void {
+export function createAnnotateView(options: {
+  deck: string;
+  slides: PresenterSlide[];
+  /** The dev server's annotations endpoint for this deck, with the presenter's token. */
+  url: string;
+  fetch: (url: string, init?: RequestInit) => Promise<Response>;
+}): void {
   const { deck, slides } = options;
   const deckEl = document.getElementById(PAGE_ID.deck);
   const stageEl = document.getElementById(PAGE_ID.currentStage);
   if (!deckEl || !stageEl) {
     return;
   }
-  const storageKey = `dek-annotate:${deck}`;
   const toggleEl = document.getElementById(PAGE_ID.annotateToggle);
 
   const host = document.createElement("div");
@@ -182,7 +196,7 @@ export function createAnnotateView(options: { deck: string; slides: PresenterSli
    * and with Undo after Clear. Clear is undone rather than confirmed, and only until something
    * else is said here, a note is written, or the mode is left.
    */
-  function report(text: string, extra: { byHand?: string; undo?: Note[] } = {}): void {
+  function report(text: string, extra: { byHand?: string; undo?: unknown[] } = {}): void {
     status.textContent = text;
     manual.hidden = extra.byHand === undefined;
     manual.value = extra.byHand ?? "";
@@ -196,31 +210,58 @@ export function createAnnotateView(options: { deck: string; slides: PresenterSli
   hitStyle.textContent = `#${PAGE_ID.deck} [${SOURCE_ATTR}] { pointer-events: auto !important; }`;
 
   let on = false;
-  let notes = load();
+  let notes: AnnotationRow[] = [];
   /** What the last Clear took away, while Undo can still bring it back. */
-  let cleared: Note[] | undefined;
+  let cleared: unknown[] | undefined;
   let picks: Pick[] = [];
   let choiceButtons = new Map<Element, HTMLButtonElement>();
-  let editing: Note | undefined;
+  let editing: AnnotationRow | undefined;
   let hovered: Element | undefined;
   let frame: number | undefined;
   // Hit testing tries dozens of points; the pointer is followed at most once a frame.
   let hoverTested = false;
   let hoverPending: Point | undefined;
 
-  function load(): Note[] {
-    try {
-      return readNotes(sessionStorage.getItem(storageKey));
-    } catch {
-      return [];
+  const ask: Ask = async (op) => {
+    const response = await options.fetch(
+      options.url,
+      op === undefined
+        ? undefined
+        : {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(op),
+          },
+    );
+    const body = (await response.json()) as {
+      ok?: boolean;
+      annotations?: AnnotationRow[];
+      removed?: unknown[];
+      error?: { message?: string };
+    };
+    if (!response.ok || body.ok !== true || !body.annotations) {
+      throw new Error(body.error?.message ?? `the dev server answered ${response.status}`);
     }
-  }
+    return { annotations: body.annotations, ...(body.removed ? { removed: body.removed } : {}) };
+  };
 
-  function save(): void {
+  /**
+   * Send `op`, or ask for the notes when there is none, and show what the server says they are
+   * now. A refusal is said above the bar, and the notes are asked for again, since a refused
+   * note names a slide the page no longer shows as it is.
+   */
+  async function sync(op?: Parameters<Ask>[0]): Promise<{ removed?: unknown[] } | undefined> {
     try {
-      sessionStorage.setItem(storageKey, writeNotes(notes));
-    } catch {
-      // Storage blocked: the notes last as long as the page.
+      const answer = await ask(op);
+      notes = answer.annotations;
+      rebuild();
+      return answer;
+    } catch (error) {
+      report(LABELS.failed(error instanceof Error ? error.message : String(error)));
+      if (op !== undefined) {
+        await sync();
+      }
+      return undefined;
     }
   }
 
@@ -324,7 +365,7 @@ export function createAnnotateView(options: { deck: string; slides: PresenterSli
       }
     });
     for (const marker of part("markers").querySelectorAll<HTMLElement>("[data-part=marker]")) {
-      const tip = pinAt(notes[Number(marker.dataset.note)]);
+      const tip = pinAt(notes.find((note) => note.id === marker.dataset.note));
       marker.hidden = !tip;
       if (tip) {
         marker.style.left = `${tip.x}px`;
@@ -337,7 +378,7 @@ export function createAnnotateView(options: { deck: string; slides: PresenterSli
    * Where a note's pin points: the top right corner of its first element, or the place clicked
    * when the note is about a place on the slide rather than an element.
    */
-  function pinAt(note: Note | undefined): Point | undefined {
+  function pinAt(note: AnnotationRow | undefined): Point | undefined {
     const anchor = anchorOf(note);
     const point = note?.targets[0]?.point;
     if (!anchor) {
@@ -350,16 +391,20 @@ export function createAnnotateView(options: { deck: string; slides: PresenterSli
     return { x: rect.right, y: rect.top };
   }
 
-  /** The element a note's marker sits on: its first element, on the slide on screen. */
-  function anchorOf(note: Note | undefined): Element | null {
+  /**
+   * The element a note's marker sits on: its first element, on the slide on screen, where the
+   * server found it as the file is now.
+   */
+  function anchorOf(note: AnnotationRow | undefined): Element | null {
     const { slug, slide } = onScreen();
     const first = note?.targets[0];
-    if (!note || note.stale || note.slug !== slug || !first || !slide) {
+    if (!note || note.slug !== slug || !first?.found || !slide) {
       return null;
     }
-    return slide.getAttribute(SOURCE_ATTR) === first.source
+    const source = `${first.line}:${first.column}`;
+    return slide.getAttribute(SOURCE_ATTR) === source
       ? slide
-      : slide.querySelector(`[${SOURCE_ATTR}="${first.source}"]`);
+      : slide.querySelector(`[${SOURCE_ATTR}="${source}"]`);
   }
 
   /** Redraw what the state is made of: the count, the picks, the choices, and the markers. */
@@ -378,7 +423,13 @@ export function createAnnotateView(options: { deck: string; slides: PresenterSli
     for (const [el, button] of choiceButtons) {
       button.setAttribute("aria-pressed", String(el === last));
     }
-    const picked = editing ? editing.targets : picks.map((pick) => describe(pick.el));
+    const picked = editing
+      ? editing.targets.map((target) => ({
+          name: target.name,
+          text: target.text ?? target.was,
+          source: `${target.line}:${target.column}`,
+        }))
+      : picks.map((pick) => describe(pick.el));
     part("picked").replaceChildren(
       ...picked.map((target) => {
         const item = document.createElement("li");
@@ -388,15 +439,15 @@ export function createAnnotateView(options: { deck: string; slides: PresenterSli
     );
     // Numbered as Copy numbers them, so a marker and its note in the chat say the same number.
     const markers = on
-      ? sortNotes(slides, notes).flatMap((note, index) => {
+      ? notes.flatMap((note) => {
           if (!anchorOf(note)) {
             return [];
           }
           const marker = document.createElement("button");
           marker.type = "button";
           marker.dataset.part = "marker";
-          marker.dataset.note = String(notes.indexOf(note));
-          marker.textContent = String(index + 1);
+          marker.dataset.note = note.id;
+          marker.textContent = String(note.number);
           marker.addEventListener("click", () => edit(note));
           return [marker];
         })
@@ -528,16 +579,17 @@ export function createAnnotateView(options: { deck: string; slides: PresenterSli
     openPopup();
   }
 
-  function edit(note: Note): void {
+  function edit(note: AnnotationRow): void {
     closePopup();
     editing = note;
     field.value = note.text;
     openPopup();
   }
 
-  function snapshot(pick: Pick, slide: Element): NoteTarget {
+  /** A picked element as the page sends it; the server reads its name and text from the file. */
+  function snapshot(pick: Pick, slide: Element): NewTarget {
     const box = slideBox(pick.el, deckEl as HTMLElement);
-    const target: NoteTarget = { ...describeElement(pick.el, slide), box };
+    const target: NewTarget = { source: describeElement(pick.el, slide).source, box };
     return pick.el === slide
       ? { ...target, point: slidePoint(pick.at, deckEl as HTMLElement) }
       : target;
@@ -546,26 +598,25 @@ export function createAnnotateView(options: { deck: string; slides: PresenterSli
   function submit(): void {
     const text = field.value;
     if (editing) {
-      const target = editing;
-      notes = notes.map((note) => (note === target ? { ...note, text } : note));
+      void sync({ op: "edit", id: editing.id, text });
     } else {
       const { slug, step, slide } = onScreen();
       if (!slide || picks.length === 0) {
         return;
       }
-      notes = [...notes, { slug, step, targets: picks.map((pick) => snapshot(pick, slide)), text }];
+      const targets = picks.map((pick) => snapshot(pick, slide));
+      void sync({ op: "add", slug, step, text, targets });
     }
     if (cleared) {
       report("");
     }
-    save();
     closePopup();
   }
 
   function remove(): void {
-    const target = editing;
-    notes = notes.filter((note) => note !== target);
-    save();
+    if (editing) {
+      void sync({ op: "remove", id: editing.id });
+    }
     closePopup();
   }
 
@@ -585,36 +636,6 @@ export function createAnnotateView(options: { deck: string; slides: PresenterSli
     }
   }
 
-  /**
-   * Match the notes on a slide an edit replaced to its elements as they are now; a note that
-   * cannot be matched keeps what it said, marked as written before the edit.
-   */
-  function follow(slug: string): void {
-    const slide = document.querySelector(slideSelector(slug));
-    if (!slide) {
-      return;
-    }
-    const present = [slide, ...slide.querySelectorAll(`[${SOURCE_ATTR}]`)].map((el) =>
-      describeElement(el, slide),
-    );
-    notes = notes.map((note) => {
-      if (note.slug !== slug) {
-        return note;
-      }
-      const found = note.targets.map((target) => reanchor(target, present));
-      if (found.some((el) => el === undefined)) {
-        return { ...note, stale: true };
-      }
-      const { stale: _, ...rest } = note;
-      return {
-        ...rest,
-        targets: note.targets.map((target, index) => ({ ...target, ...found[index] })),
-      };
-    });
-    save();
-    rebuild();
-  }
-
   // Holding Cmd or Ctrl to add an element lets clicks through the popup, which may lie over it.
   // Heard on the way down, before a field of the view keeps its keys to itself.
   const through = (event: KeyboardEvent): void => {
@@ -692,17 +713,15 @@ export function createAnnotateView(options: { deck: string; slides: PresenterSli
   act("delete", remove);
   act("copy", () => void copy());
   act("clear", () => {
-    const gone = notes;
-    notes = [];
-    save();
-    rebuild();
-    report(LABELS.cleared(gone.length), { undo: gone });
+    void sync({ op: "clear" }).then((answer) => {
+      const gone = answer?.removed ?? [];
+      report(LABELS.cleared(gone.length), { undo: gone });
+    });
   });
   act("undo", () => {
-    notes = cleared ?? notes;
-    save();
-    rebuild();
+    const back = cleared ?? [];
     report("");
+    void sync({ op: "restore", annotations: back });
   });
   act("close", () => setOn(false));
   toggleEl?.addEventListener("click", () => setOn(!on));
@@ -712,27 +731,22 @@ export function createAnnotateView(options: { deck: string; slides: PresenterSli
     }
     rebuild();
   });
-  // A live update replaces a slide's section whole; its notes are matched to the new one.
+  // A live update replaces a slide's section whole; the server matches its notes to the file
+  // as it is now, so the page asks for them again.
   new MutationObserver((records) => {
-    const slugs = new Set(
-      records.flatMap((record) =>
-        [...record.addedNodes].flatMap((node) =>
-          node instanceof Element && node.matches(".slide")
-            ? [node.getAttribute("data-slug") ?? ""]
-            : [],
-        ),
-      ),
+    const replaced = records.some((record) =>
+      [...record.addedNodes].some((node) => node instanceof Element && node.matches(".slide")),
     );
     // What was picked for the note being written went with the old section.
     if (picks.some((pick) => !pick.el.isConnected)) {
       closePopup();
     }
-    for (const slug of slugs) {
-      follow(slug);
+    if (replaced) {
+      void sync();
     }
   }).observe(deckEl, { childList: true });
-  for (const slug of new Set(notes.map((note) => note.slug))) {
-    follow(slug);
-  }
+  // Another tab, or another device, changed the notes.
+  document.addEventListener(ANNOTATIONS_CHANGED, () => void sync());
   rebuild();
+  void sync();
 }

package/src/runtime/annotate.ts

@@ -5,11 +5,15 @@
 import { PAGE_ID, readPageConfig } from "../core/page.ts";
 import type { PresenterSlide } from "../core/presenter-state.ts";
 import { createAnnotateView } from "./annotate-view.ts";
+import { deckUrl, liveTokenQuery } from "./routes.ts";
 
 const dataEl = document.getElementById(PAGE_ID.data);
 if (dataEl?.textContent) {
+  const page = readPageConfig(document.body);
   createAnnotateView({
-    deck: readPageConfig(document.body).deck,
+    deck: page.deck,
     slides: JSON.parse(dataEl.textContent) as PresenterSlide[],
+    url: `${deckUrl(location.pathname, { kind: "annotations" })}${liveTokenQuery(page.liveToken)}`,
+    fetch: (input, init) => fetch(input, init),
   });
 }

package/src/runtime/browser.ts

@@ -1,7 +1,7 @@
 /// <reference lib="dom" />
 
 import { isLiveEvent } from "../core/live-protocol.ts";
-import { PAGE_ID, readPageConfig } from "../core/page.ts";
+import { ANNOTATIONS_CHANGED, PAGE_ID, readPageConfig } from "../core/page.ts";
 import { deckStops, moveTarget, positionsEqual } from "../core/position.ts";
 import type { PresenterSlide } from "../core/presenter-state.ts";
 import type { Position } from "../core/step.ts";
@@ -185,6 +185,10 @@ if (dataEl?.textContent) {
       }
       return;
     }
+    if (raw.type === "annotations") {
+      document.dispatchEvent(new Event(ANNOTATIONS_CHANGED));
+      return;
+    }
     const event = await hydrateLiveEvent(raw, location.pathname);
     if (!event) {
       location.reload();

package/src/runtime/live.ts

@@ -62,6 +62,7 @@ export function applyLiveEvent(event: HydratedLiveEvent, host: LiveHost): { relo
       host.setDiagnostics(formatLiveDiagnostics(event.diagnostics));
       return { reload: false };
     case "timeline":
+    case "annotations":
       return { reload: false };
   }
 }

package/src/runtime/routes.ts

@@ -20,6 +20,8 @@ export type DeckRoute =
   | { kind: "goto" }
   /** The beats the presenter marked to rewrite: listed, and one marked or unmarked. */
   | { kind: "marks" }
+  /** The notes annotate mode keeps on elements of the slides: listed, and one added or changed. */
+  | { kind: "annotations" }
   /** A file under the deck's `assets/`, decoded. */
   | { kind: "asset"; path: string };
 
@@ -34,6 +36,7 @@ const FIXED: Record<Fixed, string> = {
   current: "/current",
   goto: "/goto",
   marks: "/marks",
+  annotations: "/annotations",
 };
 
 /** The path of `route` below its deck's prefix. */

package/src/server/auth.ts

@@ -86,7 +86,7 @@ export type Exposure = "audience" | "presenter";
 
 /**
  * What each dev server route reveals. The script, its notes, the voice read from it, moving the
- * deck, and the marks left on its beats belong to the presenter. The server routes only by these names, so a new route does
+ * deck, the marks left on its beats, and the annotations on its slides belong to the presenter. The server routes only by these names, so a new route does
  * not compile until it is placed here.
  */
 export const ROUTE_EXPOSURE = {
@@ -101,6 +101,7 @@ export const ROUTE_EXPOSURE = {
   voice: "presenter",
   control: "presenter",
   marks: "presenter",
+  annotations: "presenter",
   missing: "audience",
 } as const satisfies Record<string, Exposure>;
 
@@ -117,6 +118,7 @@ export const EVENT_EXPOSURE: Record<LiveEventType, Exposure> = {
   "reload-script": "audience",
   diagnostics: "presenter",
   timeline: "presenter",
+  annotations: "presenter",
 };
 
 /** True when a request cleared for `seen` may read what `exposure` names. */

package/src/server/routes.ts

@@ -1,5 +1,7 @@
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { join, relative } from "node:path";
+import type { AnnotationRow } from "../core/annotation-rows.ts";
+import { AnnotationOp, applyAnnotationOp, listAnnotations } from "../core/annotations.ts";
 import { fileInside, readTheme } from "../core/assets.ts";
 import { DekError, errorFields } from "../core/error.ts";
 import { escapeAttr, escapeHtml } from "../core/escape.ts";
@@ -116,6 +118,16 @@ export function routeRequest(req: Request, ctx: RouteContext): Routed {
         respond: () =>
           deck ? marksResponse(req, ctx.project().root, deck) : jsonNotFound(deckName),
       };
+    case "annotations":
+      return {
+        route: "annotations",
+        respond: () =>
+          deck
+            ? annotationsResponse(req, ctx.project().root, deck, () =>
+                ctx.hub.emit({ type: "annotations", deck: deckName }),
+              )
+            : jsonNotFound(deckName),
+      };
     case "asset": {
       const asset = dir && safeDeckAsset(dir, route.path);
       return asset
@@ -217,6 +229,61 @@ async function marksResponse(req: Request, root: string, deck: ProjectDeck): Pro
   }
 }
 
+/**
+ * The deck's annotations: GET lists them as the files have them now, and a POST of an operation
+ * adds, edits, removes, clears, or puts back. Every change is told to the deck's other pages,
+ * so tabs and devices annotating one deck show the same notes. One that names nothing on the
+ * slide as it is now, sent from a page an edit left behind, is refused.
+ */
+async function annotationsResponse(
+  req: Request,
+  root: string,
+  deck: ProjectDeck,
+  changed: () => void,
+): Promise<Response> {
+  const rows = (annotations: AnnotationRow[]) =>
+    annotations.map((row) => ({
+      ...row,
+      targets: row.targets.map((target) => ({ ...target, path: relative(root, target.path) })),
+      changed: row.changed.map((path) => relative(root, path)),
+    }));
+  try {
+    if (req.method === "GET") {
+      return jsonResponse({ ok: true, annotations: rows(listAnnotations(root, deck)) });
+    }
+    if (req.method !== "POST") {
+      return new Response("Method not allowed", { status: 405 });
+    }
+    let body: unknown;
+    try {
+      body = await req.json();
+    } catch {
+      body = undefined;
+    }
+    const op = AnnotationOp.safeParse(body);
+    if (!op.success) {
+      return jsonResponse(
+        {
+          ok: false,
+          error: {
+            message:
+              'the request names no operation: send {"op": "add" | "edit" | "remove" | "clear" | "restore", …}',
+          },
+        },
+        400,
+      );
+    }
+    const done = applyAnnotationOp(root, deck, op.data);
+    changed();
+    return jsonResponse({ ok: true, ...done, annotations: rows(done.annotations) });
+  } catch (error) {
+    if (!(error instanceof DekError)) {
+      throw error;
+    }
+    return jsonResponse({ ok: false, error: errorFields(error) }, 409);
+  }
+}
+
 function jsonNotFound(deckName: string): Response {
   return jsonResponse({ ok: false, error: { message: `deck "${deckName}" not found` } }, 404);
 }