@hajimism/dek 0.2.1 → 0.3.0

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);
 }

package/src/video/worker.ts

@@ -21,8 +21,10 @@ async function capture(
   request: VideoCaptureRequest,
 ): Promise<VideoCaptureResponse> {
   mkdirSync(request.outDir, { recursive: true });
+  // A deck is self-contained (DEK020), so the page needs no network.
   const page = await browser.newPage({
     viewport: { width: request.viewport.width, height: request.viewport.height },
+    offline: true,
   });
   await loadVideoDoc(page, request.html);
 

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "allowJs": true,
+    "types": ["bun"],
+
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  },
+  "include": ["src", "tests"]
+}

package/src/runtime/annotate-notes.ts

@@ -1,207 +0,0 @@
-// What annotate mode keeps and hands over: notes on elements of a slide, each a snapshot of what
-// the page showed when it was written, and the Markdown an agent is given to act on them. No DOM
-// here, so all of it is decided by these functions alone.
-
-import { type BeatRef, resolveStop } from "../core/step.ts";
-
-/** A box on the slide, in logical pixels. */
-export type Box = { x: number; y: number; width: number; height: number };
-
-/** One element a note is about, as the page showed it when the note was written. */
-export type NoteTarget = {
-  /** `<line>:<column>` of its start tag in `slides/<slug>.html`. */
-  source: string;
-  /** Its tag and its own classes, as `div.chevron`. */
-  name: string;
-  /** Its text, whitespace collapsed and cut short; empty for a shape. */
-  text: string;
-  box: Box;
-  /** Where the slide itself was clicked, when the note is about a place rather than an element. */
-  point?: { x: number; y: number };
-};
-
-/** One note, on one slide at one beat. */
-export type Note = {
-  slug: string;
-  /** The stop as `dekc shot --step` takes it: `0` as the slide arrives, else the beat. */
-  step: string;
-  targets: NoteTarget[];
-  /** What the human wrote; it may be empty, when the words go in the chat. */
-  text: string;
-  /** Written before an edit that took its element away, so its line is as it was then. */
-  stale?: true;
-};
-
-/** A slide as the page lists it. */
-export type SlideInfo = { slug: string; title: string; beats: BeatRef[] };
-
-/**
- * The notes in the order they are handed over: by slide and beat in talk order, then as they
- * were written. Markers on the page are numbered in this order too.
- */
-export function sortNotes<T extends Note>(slides: readonly SlideInfo[], notes: readonly T[]): T[] {
-  const order = (slug: string): number => slides.findIndex((slide) => slide.slug === slug);
-  const stop = (note: Note): number =>
-    resolveStop(slides[order(note.slug)]?.beats ?? [], note.step) ?? Number.MAX_SAFE_INTEGER;
-  return notes
-    .map((note, index) => ({ note, index }))
-    .sort(
-      (a, b) =>
-        order(a.note.slug) - order(b.note.slug) || stop(a.note) - stop(b.note) || a.index - b.index,
-    )
-    .map(({ note }) => note);
-}
-
-/**
- * The notes as one Markdown block for an agent: grouped by slide and beat in talk order, each
- * element with the file and line it is written at, and how to see the slide at that beat.
- */
-export function formatNotes(
-  deck: string,
-  slides: readonly SlideInfo[],
-  notes: readonly Note[],
-): string {
-  if (notes.length === 0) {
-    return "";
-  }
-  const groups = new Map<string, Note[]>();
-  for (const note of sortNotes(slides, notes)) {
-    const key = `${note.slug}\n${note.step}`;
-    groups.set(key, [...(groups.get(key) ?? []), note]);
-  }
-
-  const lines = [
-    `## Notes on decks/${deck}`,
-    "",
-    "Boxes and points are in the slide's own pixels, from its top left.",
-  ];
-  let number = 0;
-  for (const group of groups.values()) {
-    const first = group[0];
-    if (!first) {
-      continue;
-    }
-    const index = slides.findIndex((slide) => slide.slug === first.slug);
-    const title = slides[index]?.title;
-    lines.push(
-      "",
-      `### Slide ${index + 1} of ${slides.length}, ${first.slug}${title ? ` (${JSON.stringify(title)})` : ""}, ${beatLabel(first.step)}`,
-    );
-    for (const note of group) {
-      number++;
-      const where = (target: NoteTarget): string =>
-        `${describe(target)} at decks/${deck}/slides/${note.slug}.html:${target.source} (${measure(target)})${note.stale ? ", as written before an edit; the line may have moved" : ""}`;
-      lines.push("");
-      if (note.targets.length === 1 && note.targets[0]) {
-        lines.push(`${number}. ${where(note.targets[0])}`);
-      } else {
-        lines.push(`${number}. ${note.targets.length} elements:`);
-        lines.push(...note.targets.map((target) => `   - ${where(target)}`));
-      }
-      if (note.text.trim() !== "") {
-        lines.push(
-          ...note.text
-            .trim()
-            .split(/\r?\n/)
-            .map((line) => `   > ${line}`.trimEnd()),
-        );
-      }
-    }
-    lines.push("", `To see it: \`dekc shot ${deck} ${first.slug} --step ${first.step}\``);
-  }
-  return `${lines.join("\n")}\n`;
-}
-
-function beatLabel(step: string): string {
-  if (step === "0") {
-    return "as it arrives";
-  }
-  return /^\d+$/.test(step) ? `at beat ${step}` : `at beat \`${step}\``;
-}
-
-function describe(target: NoteTarget): string {
-  return target.text === "" ? target.name : `${target.name} ${JSON.stringify(target.text)}`;
-}
-
-function measure(target: NoteTarget): string {
-  if (target.point) {
-    return `point ${target.point.x},${target.point.y}`;
-  }
-  const { x, y, width, height } = target.box;
-  return `box ${x},${y} ${width}×${height}`;
-}
-
-/** An element on the slide as it is now, to match a note's target against. */
-type Present = { source: string; name: string; text: string };
-
-/**
- * The element a note's target is now, after an edit replaced its slide: the one at the same
- * place with the same name and text; else the only one with that name and text, wherever it
- * moved; else the one at the same place with the same name, whose text was rewritten, as an
- * agent does when it acts on the note. None when it cannot be told.
- */
-export function reanchor<T extends Present>(
-  target: NoteTarget,
-  present: readonly T[],
-): T | undefined {
-  const same = present.find(
-    (el) => el.source === target.source && el.name === target.name && el.text === target.text,
-  );
-  if (same) {
-    return same;
-  }
-  const moved = present.filter((el) => el.name === target.name && el.text === target.text);
-  if (moved.length === 1) {
-    return moved[0];
-  }
-  return present.find((el) => el.source === target.source && el.name === target.name);
-}
-
-/** The notes kept in storage, or none when what is there is not notes. */
-export function readNotes(raw: string | null): Note[] {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw ?? "");
-  } catch {
-    return [];
-  }
-  if (!isRecord(parsed) || parsed.version !== 1 || !Array.isArray(parsed.notes)) {
-    return [];
-  }
-  return parsed.notes.filter(isNote);
-}
-
-/** The notes as storage keeps them. */
-export function writeNotes(notes: readonly Note[]): string {
-  return JSON.stringify({ version: 1, notes });
-}
-
-function isNote(value: unknown): value is Note {
-  return (
-    isRecord(value) &&
-    typeof value.slug === "string" &&
-    typeof value.step === "string" &&
-    typeof value.text === "string" &&
-    (value.stale === undefined || value.stale === true) &&
-    Array.isArray(value.targets) &&
-    value.targets.length > 0 &&
-    value.targets.every(isTarget)
-  );
-}
-
-function isTarget(value: unknown): value is NoteTarget {
-  return (
-    isRecord(value) &&
-    typeof value.source === "string" &&
-    typeof value.name === "string" &&
-    typeof value.text === "string" &&
-    isRecord(value.box) &&
-    [value.box.x, value.box.y, value.box.width, value.box.height].every(Number.isFinite) &&
-    (value.point === undefined ||
-      (isRecord(value.point) && Number.isFinite(value.point.x) && Number.isFinite(value.point.y)))
-  );
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}