@hajimism/dek 0.2.1 → 0.2.2

package/src/core/annotation-rows.ts

@@ -0,0 +1,176 @@
+// What annotate mode hands over, shared by the dev server, `dekc annotations`, and the page: a
+// note on elements of a slide as the files have them now, how one is matched again after an
+// edit, and the Markdown Copy writes. No DOM and no file system here, so all of it is decided by
+// these functions alone.
+
+/** A box on the slide, in logical pixels, from its top left. */
+export type Box = { x: number; y: number; width: number; height: number };
+
+/** A point on the slide, in logical pixels, from its top left. */
+export type Point = { x: number; y: number };
+
+/**
+ * Whether a note still stands as written: `open` while the slide's own files are as they were
+ * when it was written, `edited` once one of them changed, and `gone` once none of its elements is
+ * on the slide, or the slide is gone from the script.
+ */
+export type AnnotationStatus = "open" | "edited" | "gone";
+
+/** One element a note is about, where the file has it now. */
+export type TargetRow = {
+  /** The slide's HTML file. */
+  path: string;
+  /** Where its start tag is now; where it was last found, when it is not found. */
+  line: number;
+  column: number;
+  found: boolean;
+  /** Its tag and its classes as written where it was last found, as `div.chevron`. */
+  name: string;
+  /** Its text as written when the note was written, cut short; empty for a shape. */
+  was: string;
+  /** Its text as written now; null when it is not found. */
+  text: string | null;
+  /** Its box on the slide when the note was written. */
+  box: Box;
+  /** Where the slide itself was clicked, when the note is about a place rather than an element. */
+  point?: Point;
+};
+
+/** One note as it stands now, numbered as the page's markers and Copy number it. */
+export type AnnotationRow = {
+  number: number;
+  id: string;
+  slug: string;
+  /** The stop as `dekc shot --step` takes it: `0` as the slide arrives, else the beat. */
+  step: string;
+  status: AnnotationStatus;
+  /** What the human wrote; it may be empty, when the words go in the chat. */
+  text: string;
+  targets: TargetRow[];
+  /** The slide's own files that changed since the note was written. */
+  changed: string[];
+  /** The command that shows the slide at the note's beat. */
+  shot: string;
+  createdAt: string;
+};
+
+/** How long an element's text may be before it is cut short. */
+const TEXT_MAX = 40;
+
+/** An element's text, whitespace collapsed, as a note quotes it. */
+export function cutText(text: string): string {
+  const squashed = text.replace(/\s+/g, " ").trim();
+  return squashed.length > TEXT_MAX ? `${squashed.slice(0, TEXT_MAX)}…` : squashed;
+}
+
+/** An element as a note names it, to match a note's target against. */
+type Named = { source: string; name: string; text: string };
+
+/**
+ * The element a note's target is now, after an edit: 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; else the one at the same place with the same tag, whose classes were changed, as an
+ * agent does to restyle it. None when it cannot be told.
+ */
+export function reanchor<T extends Named>(target: Named, 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];
+  }
+  const named = present.find((el) => el.source === target.source && el.name === target.name);
+  if (named) {
+    return named;
+  }
+  const tag = (name: string): string => name.split(".")[0] ?? "";
+  return present.find((el) => el.source === target.source && tag(el.name) === tag(target.name));
+}
+
+/** A slide as the page lists it. */
+export type SlideInfo = { slug: string; title: string };
+
+/**
+ * The notes as one Markdown block for an agent, in the order given, grouped by slide and beat:
+ * each element with the file and line it is written at now, and how to see the slide at that
+ * beat. Written for an agent that has no dev server to ask, so it says what `dekc annotations`
+ * would.
+ */
+export function formatNotes(
+  deck: string,
+  slides: readonly SlideInfo[],
+  rows: readonly AnnotationRow[],
+): string {
+  if (rows.length === 0) {
+    return "";
+  }
+  const groups = new Map<string, AnnotationRow[]>();
+  for (const row of rows) {
+    const key = `${row.slug}\n${row.step}`;
+    groups.set(key, [...(groups.get(key) ?? []), row]);
+  }
+
+  const lines = [
+    `## Notes on decks/${deck}`,
+    "",
+    "Boxes and points are in the slide's own pixels, from its top left.",
+  ];
+  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 row of group) {
+      const where = (target: TargetRow): string =>
+        `${describe(target)} at decks/${deck}/slides/${row.slug}.html:${target.line}:${target.column} (${measure(target)})${target.found ? "" : ", as written before an edit; the line may have moved"}`;
+      lines.push("");
+      if (row.targets.length === 1 && row.targets[0]) {
+        lines.push(`${row.number}. ${where(row.targets[0])}`);
+      } else {
+        lines.push(`${row.number}. ${row.targets.length} elements:`);
+        lines.push(...row.targets.map((target) => `   - ${where(target)}`));
+      }
+      if (row.text.trim() !== "") {
+        lines.push(
+          ...row.text
+            .trim()
+            .split(/\r?\n/)
+            .map((line) => `   > ${line}`.trimEnd()),
+        );
+      }
+    }
+    lines.push("", `To see it: \`${first.shot}\``);
+  }
+  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: TargetRow): string {
+  const text = target.text ?? target.was;
+  return text === "" ? target.name : `${target.name} ${JSON.stringify(text)}`;
+}
+
+function measure(target: TargetRow): 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}`;
+}

package/src/core/annotations.ts

@@ -0,0 +1,362 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { z } from "zod";
+import {
+  type AnnotationRow,
+  type AnnotationStatus,
+  reanchor,
+  type TargetRow,
+} from "./annotation-rows.ts";
+import { deckPaths } from "./deck-paths.ts";
+import { DekError } from "./error.ts";
+import { deckSlides, type WrittenElement, writtenElements } from "./html.ts";
+import { type ProjectDeck, readDeckFile } from "./resolve.ts";
+import { readSourceIfExists, writeInside } from "./safe-fs.ts";
+import { resolveStop } from "./step.ts";
+import { formatZodIssues } from "./zod.ts";
+
+const Box = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+  width: z.number().finite(),
+  height: z.number().finite(),
+});
+const Point = z.object({ x: z.number().finite(), y: z.number().finite() });
+
+/**
+ * One element a note is about. `was` is its text as the file wrote it when the note was written;
+ * `source`, `name`, and `text` are where and what it was last found as, so a note follows its
+ * element through one edit after another.
+ */
+const Target = z.object({
+  source: z.string(),
+  name: z.string(),
+  was: z.string(),
+  text: z.string(),
+  box: Box,
+  point: Point.optional(),
+});
+
+/** The slide's own files, each by a hash of what it held when the note was written. */
+const SLIDE_FILES = [".html", ".css", ".ts"] as const;
+
+/**
+ * A note as it is kept: what the human wrote on which elements of a slide at which beat, and the
+ * slide's own files as they were then, so a reader can tell an edited slide from one untouched.
+ */
+const Annotation = z.object({
+  id: z.string().min(1),
+  slug: z.string(),
+  step: z.string(),
+  text: z.string(),
+  createdAt: z.string(),
+  files: z.record(z.string(), z.string()),
+  targets: z.array(Target).min(1),
+});
+
+export type Annotation = z.infer<typeof Annotation>;
+
+/** Every deck's notes, by deck name, in one file of the project's. */
+const AnnotationsFile = z.object({
+  version: z.literal(1),
+  decks: z.record(z.string(), z.array(Annotation)),
+});
+
+type AnnotationsFile = z.infer<typeof AnnotationsFile>;
+
+/**
+ * What the page asks of the notes: add one on elements of the slide, given by where each start
+ * tag is written; change one's words; remove one; clear the deck's; or put back what a clear took.
+ */
+export const AnnotationOp = z.discriminatedUnion("op", [
+  z.object({
+    op: z.literal("add"),
+    slug: z.string(),
+    step: z.string(),
+    text: z.string(),
+    targets: z.array(z.object({ source: z.string(), box: Box, point: Point.optional() })).min(1),
+  }),
+  z.object({ op: z.literal("edit"), id: z.string(), text: z.string() }),
+  z.object({ op: z.literal("remove"), id: z.string() }),
+  z.object({ op: z.literal("clear") }),
+  z.object({ op: z.literal("restore"), annotations: z.array(Annotation) }),
+]);
+
+export type AnnotationOp = z.infer<typeof AnnotationOp>;
+
+/** Where the notes are kept: beside the marks, out of every deck. */
+export function annotationsPath(root: string): string {
+  return join(root, ".dek", "annotations.json");
+}
+
+/**
+ * Do what the page asks, and answer with the deck's notes as they stand now; a clear also hands
+ * back what it took, to put back. Input that names nothing on the slide as it is now, as a page
+ * opened before an edit can send, is refused and changes nothing.
+ */
+export function applyAnnotationOp(
+  root: string,
+  deck: ProjectDeck,
+  op: AnnotationOp,
+  now: Date = new Date(),
+): { annotations: AnnotationRow[]; removed?: Annotation[] } {
+  const file = readAnnotationsFile(root);
+  const notes = file.decks[deck.name] ?? [];
+  const known = (id: string): Annotation => {
+    const found = notes.find((note) => note.id === id);
+    if (!found) {
+      throw new DekError(`no note ${id} on deck "${deck.name}"`, {
+        hint: "reload the page: the notes changed since it read them",
+      });
+    }
+    return found;
+  };
+  let next: Annotation[];
+  let removed: Annotation[] | undefined;
+  switch (op.op) {
+    case "add":
+      next = [...notes, newAnnotation(deck, op, now)];
+      break;
+    case "edit": {
+      const target = known(op.id);
+      next = notes.map((note) => (note === target ? { ...note, text: op.text } : note));
+      break;
+    }
+    case "remove": {
+      const target = known(op.id);
+      next = notes.filter((note) => note !== target);
+      break;
+    }
+    case "clear":
+      next = [];
+      removed = notes;
+      break;
+    case "restore": {
+      const ids = new Set(notes.map((note) => note.id));
+      next = [...notes, ...op.annotations.filter((note) => !ids.has(note.id))];
+      break;
+    }
+  }
+  writeAnnotationsFile(root, deck.name, next, file);
+  return { annotations: listAnnotations(root, deck), ...(removed ? { removed } : {}) };
+}
+
+/**
+ * The deck's notes in talk order, each element where the file has it now. Where each was found
+ * is kept for the next reader, so a note follows its element through edit after edit.
+ */
+export function listAnnotations(root: string, deck: ProjectDeck): AnnotationRow[] {
+  const file = readAnnotationsFile(root);
+  const notes = file.decks[deck.name] ?? [];
+  const slides = deckSlides(deck);
+  const present = new Map<string, WrittenElement[] | undefined>();
+  const elementsOf = (slug: string): WrittenElement[] | undefined => {
+    if (!present.has(slug)) {
+      const inScript = deck.deck.sections.some((section) => section.slug === slug);
+      present.set(slug, inScript ? writtenElements(slides, slug) : undefined);
+    }
+    return present.get(slug);
+  };
+  const followed = notes.map((note) => follow(note, elementsOf(note.slug)));
+  const moved = followed.some(({ note }, index) => note !== notes[index]);
+  if (moved) {
+    writeAnnotationsFile(
+      root,
+      deck.name,
+      followed.map(({ note }) => note),
+      file,
+    );
+  }
+  return order(deck, followed).map(({ note, found }, index) => toRow(deck, note, found, index + 1));
+}
+
+/** Drop the deck's notes, the other decks' kept; how many there were. */
+export function clearAnnotations(root: string, deck: ProjectDeck): number {
+  const file = readAnnotationsFile(root);
+  const count = file.decks[deck.name]?.length ?? 0;
+  if (count > 0) {
+    writeAnnotationsFile(root, deck.name, [], file);
+  }
+  return count;
+}
+
+type AddOp = Extract<AnnotationOp, { op: "add" }>;
+
+/** A note as the slide's files have it now, refused when they do not have what it names. */
+function newAnnotation(deck: ProjectDeck, op: AddOp, now: Date): Annotation {
+  const section = deck.deck.sections.find((entry) => entry.slug === op.slug);
+  if (!section) {
+    throw new DekError(`no slide "${op.slug}" in deck "${deck.name}"`, {
+      hint: "reload the page: the script changed since it opened",
+    });
+  }
+  if (resolveStop(section.beats, op.step) === undefined) {
+    throw new DekError(`no beat "${op.step}" on slide "${op.slug}"`, {
+      hint: "reload the page: the script changed since it opened",
+    });
+  }
+  const elements = writtenElements(deckSlides(deck), op.slug) ?? [];
+  const targets = op.targets.map((target) => {
+    const element = elements.find((el) => el.source === target.source);
+    if (!element) {
+      throw new DekError(`slides/${op.slug}.html has no element at ${target.source}`, {
+        hint: "pick it again: the slide changed since the page drew it",
+      });
+    }
+    return {
+      source: element.source,
+      name: element.name,
+      was: element.text,
+      text: element.text,
+      box: target.box,
+      ...(target.point ? { point: target.point } : {}),
+    };
+  });
+  return {
+    id: crypto.randomUUID(),
+    slug: op.slug,
+    step: op.step,
+    text: op.text,
+    createdAt: now.toISOString(),
+    files: slideFileHashes(deck, op.slug),
+    targets,
+  };
+}
+
+/** A note matched again to the slide as it is now, and which of its elements were found. */
+type Followed = { note: Annotation; found: boolean[] };
+
+function follow(note: Annotation, present: WrittenElement[] | undefined): Followed {
+  const matches = note.targets.map((target) => (present ? reanchor(target, present) : undefined));
+  const changed = note.targets.some((target, index) => {
+    const match = matches[index];
+    return (
+      match !== undefined &&
+      (match.source !== target.source || match.name !== target.name || match.text !== target.text)
+    );
+  });
+  return {
+    note: changed
+      ? {
+          ...note,
+          targets: note.targets.map((target, index) => {
+            const match = matches[index];
+            return match
+              ? { ...target, source: match.source, name: match.name, text: match.text }
+              : target;
+          }),
+        }
+      : note,
+    found: matches.map((match) => match !== undefined),
+  };
+}
+
+/** By slide and beat in talk order, then as they were written; past the deck, at the end. */
+function order(deck: ProjectDeck, followed: Followed[]): Followed[] {
+  const { sections } = deck.deck;
+  const rank = ({ note }: Followed): [number, number] => {
+    const slide = sections.findIndex((section) => section.slug === note.slug);
+    const stop = slide < 0 ? undefined : resolveStop(sections[slide]?.beats ?? [], note.step);
+    return [slide < 0 ? sections.length : slide, stop ?? Number.MAX_SAFE_INTEGER];
+  };
+  return followed
+    .map((entry, index) => ({ entry, index, rank: rank(entry) }))
+    .sort((a, b) => a.rank[0] - b.rank[0] || a.rank[1] - b.rank[1] || a.index - b.index)
+    .map(({ entry }) => entry);
+}
+
+function toRow(
+  deck: ProjectDeck,
+  note: Annotation,
+  found: boolean[],
+  number: number,
+): AnnotationRow {
+  const paths = deckPaths(deck.dir);
+  const html = paths.slide(note.slug, ".html");
+  const targets: TargetRow[] = note.targets.map((target, index) => {
+    const [line = 0, column = 0] = target.source.split(":").map(Number);
+    const isFound = found[index] === true;
+    return {
+      path: html,
+      line,
+      column,
+      found: isFound,
+      name: target.name,
+      was: target.was,
+      text: isFound ? target.text : null,
+      box: target.box,
+      ...(target.point ? { point: target.point } : {}),
+    };
+  });
+  const now = slideFileHashes(deck, note.slug);
+  const changed = SLIDE_FILES.filter((ext) => now[ext] !== note.files[ext]).map((ext) =>
+    paths.slide(note.slug, ext),
+  );
+  const status: AnnotationStatus = !found.some(Boolean)
+    ? "gone"
+    : changed.length > 0
+      ? "edited"
+      : "open";
+  return {
+    number,
+    id: note.id,
+    slug: note.slug,
+    step: note.step,
+    status,
+    text: note.text,
+    targets,
+    changed,
+    shot: `dekc shot ${deck.name} ${note.slug} --step ${note.step}`,
+    createdAt: note.createdAt,
+  };
+}
+
+/** A hash of each of the slide's own files there is, by its extension. */
+function slideFileHashes(deck: ProjectDeck, slug: string): Record<string, string> {
+  const paths = deckPaths(deck.dir);
+  return Object.fromEntries(
+    SLIDE_FILES.flatMap((ext) => {
+      const text = readDeckFile(deck.dir, paths.slide(slug, ext));
+      return text === undefined
+        ? []
+        : [[ext, createHash("sha256").update(text).digest("hex").slice(0, 16)]];
+    }),
+  );
+}
+
+function readAnnotationsFile(root: string): AnnotationsFile {
+  const path = annotationsPath(root);
+  const text = readSourceIfExists(path, root);
+  if (text === undefined) {
+    return { version: 1, decks: {} };
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw unreadable(path, error instanceof Error ? error.message : String(error));
+  }
+  const parsed = AnnotationsFile.safeParse(value);
+  if (!parsed.success) {
+    throw unreadable(path, formatZodIssues(parsed.error));
+  }
+  return parsed.data;
+}
+
+function unreadable(path: string, why: string): DekError {
+  return new DekError(`.dek/annotations.json does not read: ${why}`, {
+    path,
+    hint: "delete .dek/annotations.json to start over; every deck's notes go with it",
+  });
+}
+
+function writeAnnotationsFile(
+  root: string,
+  deck: string,
+  notes: Annotation[],
+  file: AnnotationsFile,
+): void {
+  const { [deck]: _old, ...others } = file.decks;
+  const decks = notes.length > 0 ? { ...others, [deck]: notes } : others;
+  writeInside(annotationsPath(root), `${JSON.stringify({ version: 1, decks }, null, 2)}\n`, root);
+}

package/src/core/diagnostic.ts

@@ -53,6 +53,7 @@ export const RULES = {
   DEK031: { severity: "error", scopes: ["slide"] },
   DEK032: { severity: "error", scopes: ["slide"] },
   DEK033: { severity: "error", scopes: ["slide"] },
+  DEK034: { severity: "error", scopes: ["slide"] },
   DEK040: { severity: "warning", scopes: ["slide"] },
   DEK041: { severity: "warning", scopes: ["deck"] },
   DEK042: { severity: "warning", scopes: ["slide"] },

package/src/core/html-scan.ts

@@ -39,8 +39,17 @@ export type HtmlScan = {
    * collapsed. An SVG's `<title>` and `<desc>` describe it and are never drawn, so they hold none.
    */
   hiddenTexts: Array<{ element: HtmlElement; text: string }>;
+  /**
+   * Each outermost picture a screen reader is not told to skip: an `<img>`, an `<svg>`, or an
+   * element with `role="img"`, none of them under `aria-hidden="true"`. `text` says whether it
+   * holds any text to read, and `titled` whether a `<title>` inside it names it.
+   */
+  pictures: Picture[];
 };
 
+/** A picture in the markup, with what it holds that a screen reader could say. */
+export type Picture = { element: HtmlElement; text: boolean; titled: boolean };
+
 const HEADING_TAGS = new Set(["h1", "h2", "h3", "h4", "h5", "h6"]);
 /** Elements that give a heading something to show without any text. */
 const CONTENT_TAGS = new Set(["img", "svg", "picture", "video", "canvas", "object", "math"]);
@@ -62,6 +71,10 @@ export function scanSlideHtml(html: string): HtmlScan {
   // The outermost aria-hidden element still open, and how many undrawn elements are open in it.
   let hiding: { index: number; text: string } | undefined;
   let undrawn = 0;
+  // The outermost picture still open, and whether a <title> inside it is open.
+  const pictures: Array<{ index: number; text: boolean; titled: boolean }> = [];
+  let picture: { index: number; text: boolean; titled: boolean } | undefined;
+  let titles = 0;
 
   const transformed = new HTMLRewriter()
     .on("*", {
@@ -94,6 +107,27 @@ export function scanSlideHtml(html: string): HtmlScan {
             hiding = undefined;
           });
         }
+        if (picture) {
+          if (tag === "title" && el.canHaveContent) {
+            titles++;
+            el.onEndTag(() => {
+              titles--;
+            });
+          }
+        } else if (
+          !hiding &&
+          el.getAttribute("aria-hidden")?.trim() !== "true" &&
+          isPicture(tag, el.getAttribute("role"))
+        ) {
+          const entry = { index: parsed.length, text: false, titled: false };
+          pictures.push(entry);
+          if (el.canHaveContent) {
+            picture = entry;
+            el.onEndTag(() => {
+              picture = undefined;
+            });
+          }
+        }
         if (HEADING_TAGS.has(tag) && el.canHaveContent) {
           const heading = {
             index: parsed.length,
@@ -119,6 +153,10 @@ export function scanSlideHtml(html: string): HtmlScan {
         if (hiding && undrawn === 0) {
           hiding.text += chunk.text;
         }
+        if (picture && !hiding && chunk.text.trim() !== "") {
+          picture.text = true;
+          picture.titled ||= titles > 0;
+        }
         if (open.length > 0 && chunk.text.trim() !== "") {
           for (const heading of open) {
             heading.content = true;
@@ -187,9 +225,25 @@ export function scanSlideHtml(html: string): HtmlScan {
       const squashed = text.replace(/\s+/g, " ").trim();
       return element && squashed !== "" ? [{ element, text: squashed }] : [];
     }),
+    pictures: pictures.flatMap(({ index, text, titled }) => {
+      const element = elements[index];
+      return element ? [{ element, text, titled }] : [];
+    }),
   };
 }
 
+/**
+ * Whether an element draws a picture a screen reader must be told about. `role="presentation"`
+ * or `"none"` says it is decoration, as `aria-hidden` does.
+ */
+function isPicture(tag: string, role: string | null): boolean {
+  const roles = (role ?? "").trim().toLowerCase().split(/\s+/);
+  if (roles[0] === "presentation" || roles[0] === "none") {
+    return false;
+  }
+  return tag === "img" || tag === "svg" || roles[0] === "img";
+}
+
 /** The value of `name` on `element`, as the parser read it. */
 function attributeValue(element: HtmlElement, name: string): string | undefined {
   return element.attributes.find((attribute) => attribute.name === name)?.value;