@hajimism/dek 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 Release notes for `@hajimism/dek`. From 0.1.0 on, release-please writes this file from the Conventional Commits on `main`.
 
+## [0.2.1](https://github.com/hajimism/dek/compare/v0.2.0...v0.2.1) (2026-10-06)
+
+
+### Features
+
+* **dev:** annotate slide elements and copy the notes for an agent ([8565bd5](https://github.com/hajimism/dek/commit/8565bd5a8d385a84c10d4fa78cab1b7460a86389))
+
+
+### Documentation
+
+* **sample:** show annotate mode on a roadmap in with-agents ([c1d9c4c](https://github.com/hajimism/dek/commit/c1d9c4c6ddd6306748bdd5544b868fbf3d170a6c))
+
 ## [0.2.0](https://github.com/hajimism/dek/compare/v0.1.0...v0.2.0) (2026-10-01)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hajimism/dek",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A build system for talks.",
   "license": "MIT",
   "author": "Hajime Nakagawa (https://github.com/hajimism)",

package/src/cli/serve.ts

@@ -121,5 +121,5 @@ export function devBanner(
   remoteUrls: string[],
   options: Parameters<typeof remoteBanner>[2],
 ): string {
-  return `${remoteBanner(url, remoteUrls, options)}\n\np presenter view · s slide rail · Ctrl-C stops the server`;
+  return `${remoteBanner(url, remoteUrls, options)}\n\np presenter view · s slide rail · a annotate · Ctrl-C stops the server`;
 }

package/src/core/chrome.ts

@@ -60,10 +60,12 @@ ${indent(printPageCss({ width, height }))}
 @media print { #dek-presenter, #dek-progress { display: none !important; } }
 body[data-mode="video"] #dek-presenter, body[data-mode="video"] #dek-progress { display: none !important; }
 #dek-presenter[hidden], #dek-progress[hidden], #dek-next-end[hidden] { display: none; }
-#dek-mark-toggle { flex: none; width: 2.25rem; height: 2.25rem; padding: 0; border: 1px solid rgba(255,255,255,0.2); border-radius: 50%; background: transparent; color: rgba(255,255,255,0.45); cursor: pointer; font: 600 1rem/1 system-ui, sans-serif; }
+#dek-mark-toggle, #dek-annotate-toggle { flex: none; width: 2.25rem; height: 2.25rem; padding: 0; border: 1px solid rgba(255,255,255,0.2); border-radius: 50%; background: transparent; color: rgba(255,255,255,0.45); cursor: pointer; font: 600 1rem/1 system-ui, sans-serif; }
 #dek-mark-toggle::before { content: "✎"; }
 #dek-mark-toggle[aria-pressed="true"] { border-color: #eab308; color: #eab308; }
 #dek-mark-toggle[data-error] { border-color: #ef4444; }
+#dek-annotate-toggle::before { content: "⌖"; }
+#dek-annotate-toggle[aria-pressed="true"] { border-color: #3b82f6; color: #3b82f6; }
 #dek-beats li.is-marked::after { content: " ✎"; color: #eab308; }
 #dek-laser-toggle { flex: none; width: 2.25rem; height: 2.25rem; padding: 0; border: 1px solid rgba(255,255,255,0.2); border-radius: 50%; background: transparent; cursor: pointer; }
 #dek-laser-toggle::before { content: ""; display: block; width: 10px; height: 10px; margin: auto; border-radius: 50%; background: rgba(255,255,255,0.45); }

package/src/core/document.ts

@@ -24,6 +24,8 @@ export type PageTarget =
       mode: "player" | "presenter";
       includeNotes: boolean;
       liveReloadScript: string;
+      /** Annotate mode, run after the player on a page that is the speaker's: one with the notes. */
+      annotateScript: string;
       /**
        * What a presenter page sends as `?token=` on its live channels at `/decks/<name>/events`
        * and `/decks/<name>/ws`: neither an EventSource nor a WebSocket can set a header of its
@@ -70,7 +72,7 @@ export function renderDeckDocument(
   const data = presenterSlides(deck, scriptReader(target)).map((slide) =>
     includeNotes ? slide : { ...slide, script: "" },
   );
-  const slidesHtml = collectSlidesHtml(deck, { inline: standalone });
+  const slidesHtml = collectSlidesHtml(deck, { inline: standalone, sources: live });
   const themeCss = readTheme(deck.dir, standalone);
   const slideScripts = readSlideScripts(deck.dir, { strict: strictScripts });
   const state = data[0] ? presenterState(data, { slideIndex: 0, beatIndex: 0 }) : undefined;
@@ -105,6 +107,7 @@ export function renderDeckDocument(
       <p id="${PAGE_ID.elapsed}">0:00</p>
       <p id="${PAGE_ID.budget}">${budget}</p>
       ${target.kind === "dev" ? markButton(deck.deck.lang) : ""}
+      ${target.kind === "dev" ? annotateButton(deck.deck.lang) : ""}
       <button id="${PAGE_ID.laserToggle}" type="button" aria-pressed="false" aria-label="${escapeAttr(laserLabel(deck.deck.lang))}" title="${escapeAttr(laserLabel(deck.deck.lang))}"></button>
     </footer>
   </aside>`
@@ -157,7 +160,8 @@ export function renderDeckDocument(
   <script type="application/json" id="${PAGE_ID.data}">${jsonForScript(data)}</script>
   ${slideScriptTags(slideScripts)}
   <script>${options.playerScript}</script>
-  ${target.kind === "dev" ? `<script>${target.liveReloadScript}</script>` : ""}`,
+  ${target.kind === "dev" ? `<script>${target.liveReloadScript}</script>` : ""}
+  ${target.kind === "dev" && includeNotes ? `<script>${target.annotateScript}</script>` : ""}`,
   });
 }
 
@@ -197,6 +201,17 @@ function markButton(lang: string): string {
   return `<button id="${PAGE_ID.markToggle}" type="button" aria-pressed="false" aria-label="${escapeAttr(label)}" title="${escapeAttr(label)}"></button>`;
 }
 
+/**
+ * The button that turns annotate mode on and off. Only the dev server's page has it: the notes
+ * name files and lines of a project on this machine, and a built file is someone else's to read.
+ */
+function annotateButton(lang: string): string {
+  const label = lang.toLowerCase().startsWith("ja")
+    ? "スライドの要素に注釈を付ける (a)"
+    : "Annotate slide elements (a)";
+  return `<button id="${PAGE_ID.annotateToggle}" type="button" aria-pressed="false" aria-label="${escapeAttr(label)}" title="${escapeAttr(label)}"></button>`;
+}
+
 /** The laser button's name, with the key that does the same. */
 function laserLabel(lang: string): string {
   return lang.toLowerCase().startsWith("ja") ? "レーザーポインター (l)" : "Laser pointer (l)";

package/src/core/html.ts

@@ -1,6 +1,7 @@
 import { assetInliner } from "./assets.ts";
 import { deckPaths } from "./deck-paths.ts";
 import { escapeAttr, escapeHtml } from "./escape.ts";
+import { type LineColumn, lineLocator } from "./lines.ts";
 import { isInside } from "./path.ts";
 import { type ProjectDeck, readDeckFile } from "./resolve.ts";
 import { FALLBACK_LANG, type Section } from "./schema.ts";
@@ -41,6 +42,11 @@ export function hasSlideClass(className: string | null | undefined): boolean {
  * written. A slide that never closes runs to `</body>`, or to the end.
  */
 export function extractSlideSection(html: string): string | undefined {
+  return locateSlideSection(html)?.section;
+}
+
+/** The first slide section, as `extractSlideSection` reads it, and the offset it starts at. */
+function locateSlideSection(html: string): { section: string; start: number } | undefined {
   const mark = uniqueMark(html);
   let found = false;
   let closed = false;
@@ -68,10 +74,13 @@ export function extractSlideSection(html: string): string | undefined {
     : undefined;
   // The parser closes an unclosed slide at the end of its parent, past `</body>`.
   if (slide !== undefined && /<\/section\s*>$/i.test(slide)) {
-    return slide;
+    return { section: slide, start };
   }
   const bodyClose = html.slice(start).search(/<\/body>/i);
-  return bodyClose >= 0 ? html.slice(start, start + bodyClose) : html.slice(start);
+  return {
+    section: bodyClose >= 0 ? html.slice(start, start + bodyClose) : html.slice(start),
+    start,
+  };
 }
 
 /** A deck's slide markup, each file read at most once. */
@@ -86,32 +95,43 @@ export type DeckSlides = {
    * stops on them, because at the venue a deck that shows beats one that does not.
    */
   section(slug: string): string;
+  /** Where the written section is in `slides/<slug>.html`; none for a skeleton. */
+  source(slug: string): SlideSource | undefined;
 };
 
+/** A slide file and the offset its section starts at: the section is `file` from `start`. */
+type SlideSource = { file: string; start: number };
+
 export function deckSlides(deck: ProjectDeck): DeckSlides {
   const paths = deckPaths(deck.dir);
-  const read = new Map<string, string | undefined>();
+  const read = new Map<string, (SlideSource & { section: string }) | undefined>();
   let layouts: SkeletonLayouts | undefined;
   const skeleton = (slug: string): string | undefined => {
     layouts ??= deckLayouts(deck.dir);
     return skeletonHtml(deck.deck, slug, layouts);
   };
-  const written = (slug: string): string | undefined => {
+  const located = (slug: string): (SlideSource & { section: string }) | undefined => {
     if (!read.has(slug)) {
       const path = paths.slide(slug, ".html");
       // A slug from a URL may try to climb out of slides/.
-      const source =
+      const file =
         isSafeSlideSlug(slug) && isInside(path, paths.slides)
           ? readDeckFile(deck.dir, path)
           : undefined;
-      read.set(slug, source === undefined ? undefined : extractSlideSection(source));
+      const found = file === undefined ? undefined : locateSlideSection(file);
+      read.set(slug, file !== undefined && found ? { file, ...found } : undefined);
     }
     return read.get(slug);
   };
+  const written = (slug: string): string | undefined => located(slug)?.section;
   return {
     has: (slug) => written(slug) !== undefined,
     written,
     section: (slug) => written(slug) ?? extractSlideSection(skeleton(slug) ?? "") ?? "",
+    source(slug) {
+      const found = located(slug);
+      return found && { file: found.file, start: found.start };
+    },
   };
 }
 
@@ -140,15 +160,24 @@ export type SlideStamp = {
   beat?: { index: number; step: string };
   /** Inline the deck's files as data: URIs, for a page that stands alone. */
   inline?: { deckDir: string };
+  /**
+   * Where the section is written, for the dev server's pages: every start tag then says where
+   * in the file it is, as `data-dek-source="<line>:<column>"`, and the classes it is written
+   * with, as `data-dek-class`, so annotate mode can name it as the file does whatever a script
+   * adds to it.
+   */
+  source?: SlideSource;
 };
 
 /**
  * One slide section with what the page needs on it, in one parser pass: its `data-slug` unless
- * it names its own, its place as `--dek-slide-number` and `--dek-slide-count`, and for a still
- * page the classes and beat the player would have set.
+ * it names its own, its place as `--dek-slide-number` and `--dek-slide-count`, for a still page
+ * the classes and beat the player would have set, and for the dev server where each tag is
+ * written.
  */
 export function stampSlide(html: string, stamp: SlideStamp): string {
   let done = false;
+  const spots = stamp.source && startTagSpots(html, stamp.source);
   return rewriteHtml(html, (rewriter) => {
     rewriter.on("section", {
       element(el) {
@@ -186,21 +215,77 @@ export function stampSlide(html: string, stamp: SlideStamp): string {
     if (stamp.inline) {
       rewriter.on("*", assetInliner(stamp.inline.deckDir));
     }
+    if (spots) {
+      // The same parser over the same markup meets the start tags in the same order.
+      let index = 0;
+      rewriter.on("*", {
+        element(el) {
+          const spot = spots[index++];
+          if (spot) {
+            el.setAttribute("data-dek-source", `${spot.line}:${spot.column}`);
+            if (spot.classes !== undefined) {
+              el.setAttribute("data-dek-class", spot.classes);
+            }
+          }
+        },
+      });
+    }
+  });
+}
+
+/** Where a start tag is written, and its classes as written; none when it has no `class`. */
+type TagSpot = LineColumn & { classes?: string };
+
+/**
+ * Where each start tag of `html` is written in the file it was taken from, in document order,
+ * read before anything else touches the markup. A marker goes in front of each tag; where the
+ * markers land, less their own length, is where the tags were.
+ */
+function startTagSpots(html: string, source: SlideSource): TagSpot[] {
+  const mark = uniqueMark(html);
+  const classes: Array<string | null> = [];
+  const marked = rewriteHtml(html, (rewriter) => {
+    rewriter.on("*", {
+      element(el) {
+        el.before(mark, { html: true });
+        classes.push(el.getAttribute("class"));
+      },
+    });
   });
+  const spot = lineLocator(source.file);
+  let offset = source.start;
+  return marked
+    .split(mark)
+    .slice(0, -1)
+    .map((before, index) => {
+      offset += before.length;
+      const written = classes[index];
+      return written === null || written === undefined
+        ? spot(offset)
+        : { ...spot(offset), classes: written.split(/\s+/).filter(Boolean).join(" ") };
+    });
 }
 
-/** Every slide of the deck in script order, as the player pages hold them. */
-export function collectSlidesHtml(deck: ProjectDeck, options: { inline: boolean }): string {
+/**
+ * Every slide of the deck in script order, as the player pages hold them. `sources` says where
+ * each tag is written, for the dev server's pages.
+ */
+export function collectSlidesHtml(
+  deck: ProjectDeck,
+  options: { inline: boolean; sources?: boolean },
+): string {
   const slides = deckSlides(deck);
   const { sections } = deck.deck;
   return sections
-    .map((section, index) =>
-      stampSlide(slides.section(section.slug), {
+    .map((section, index) => {
+      const source = options.sources ? slides.source(section.slug) : undefined;
+      return stampSlide(slides.section(section.slug), {
         slug: section.slug,
         place: slidePlace(sections, index),
         ...(options.inline ? { inline: { deckDir: deck.dir } } : {}),
-      }),
-    )
+        ...(source ? { source } : {}),
+      });
+    })
     .join("");
 }
 

package/src/core/page.ts

@@ -28,6 +28,7 @@ export const PAGE_ID = {
   laser: "dek-laser",
   laserToggle: "dek-laser-toggle",
   markToggle: "dek-mark-toggle",
+  annotateToggle: "dek-annotate-toggle",
   hint: "dek-hint",
   announce: "dek-announce",
 } as const;

package/src/runtime/annotate-notes.ts

@@ -0,0 +1,207 @@
+// 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);
+}

package/src/runtime/annotate-pick.ts

@@ -0,0 +1,148 @@
+/// <reference lib="dom" />
+// What annotate mode can point at: the elements of the slide on screen under the pointer, what
+// 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 { 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";
+
+/** 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 };
+
+/**
+ * The points tried around the pointer: the pointer itself first, then rings out to a few pixels,
+ * so a line one pixel thick is found from beside it as well as on it.
+ */
+export function ringPoints(at: Point): Point[] {
+  const points = [at];
+  for (let radius = 1; radius <= 5; radius++) {
+    for (let step = 0; step < 8; step++) {
+      const angle = (step * Math.PI) / 4;
+      points.push({ x: at.x + radius * Math.cos(angle), y: at.y + radius * Math.sin(angle) });
+    }
+  }
+  return points;
+}
+
+/**
+ * The elements of `slide` that can be picked at `at`: what is under the pointer, then what is
+ * only near it, each before anything it is inside, and the slide itself last. A line beside the
+ * pointer so comes before the drawing it is in, which is under the pointer and easy to hit.
+ * `elementsAt` is the document's `elementsFromPoint`, every element at a point, topmost first.
+ */
+export function candidatesAt(
+  at: Point,
+  slide: Element,
+  elementsAt: (x: number, y: number) => readonly Element[],
+): Element[] {
+  const found: Element[] = [];
+  for (const point of ringPoints(at)) {
+    for (const el of elementsAt(point.x, point.y)) {
+      if (el === slide || found.includes(el) || !isCandidate(el, slide)) {
+        continue;
+      }
+      const outer = found.findIndex((other) => other.contains(el));
+      found.splice(outer < 0 ? found.length : outer, 0, el);
+    }
+  }
+  return isCandidate(slide, slide) ? [...found, slide] : found;
+}
+
+function isCandidate(el: Element, slide: Element): boolean {
+  return el.hasAttribute(SOURCE_ATTR) && slide.contains(el) && isShown(el, slide);
+}
+
+/** Whether `el` shows: neither it nor anything it is in on the slide is transparent or hidden. */
+function isShown(el: Element, slide: Element): boolean {
+  const view = el.ownerDocument.defaultView;
+  if (!view) {
+    return true;
+  }
+  if (view.getComputedStyle(el).visibility === "hidden") {
+    return false;
+  }
+  for (let node: Element | null = el; node; node = node.parentElement) {
+    if (view.getComputedStyle(node).opacity === "0") {
+      return false;
+    }
+    if (node === slide) {
+      break;
+    }
+  }
+  return true;
+}
+
+/**
+ * What a note says an element is: where it is written, its tag and its classes as written, and
+ * its text cut short. The classes the player or a slide script added since, such as
+ * `is-current`, are in no file to find. The slide's text is the whole slide, which names
+ * nothing, so it has none.
+ */
+export function describeElement(
+  el: Element,
+  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,
+  };
+}
+
+/** Where `el` is on the slide, in the slide's own pixels, whatever the stage scales it to. */
+export function slideBox(el: Element, deck: HTMLElement): Box {
+  const scale = deckScale(deck);
+  const origin = deck.getBoundingClientRect();
+  const rect = el.getBoundingClientRect();
+  return {
+    x: Math.round((rect.left - origin.left) / scale),
+    y: Math.round((rect.top - origin.top) / scale),
+    width: Math.round(rect.width / scale),
+    height: Math.round(rect.height / scale),
+  };
+}
+
+/** A point in the window as a point on the slide, in the slide's own pixels. */
+export function slidePoint(at: Point, deck: HTMLElement): Point {
+  const scale = deckScale(deck);
+  const origin = deck.getBoundingClientRect();
+  return {
+    x: Math.round((at.x - origin.left) / scale),
+    y: Math.round((at.y - origin.top) / scale),
+  };
+}
+
+/** A point on the slide, in its own pixels, as a point in the window. */
+export function windowPoint(at: Point, deck: HTMLElement): Point {
+  const scale = deckScale(deck);
+  const origin = deck.getBoundingClientRect();
+  return { x: origin.left + at.x * scale, y: origin.top + at.y * scale };
+}
+
+function deckScale(deck: HTMLElement): number {
+  const width = deck.getBoundingClientRect().width;
+  return deck.offsetWidth > 0 && width > 0 ? width / deck.offsetWidth : 1;
+}
+
+/** The slide on screen and its beat, as the hash says and `dekc shot --step` takes it. */
+export function currentStop(
+  hash: string,
+  slides: ReadonlyArray<{ slug: string; beats: BeatRef[] }>,
+): { slideIndex: number; step: string } {
+  const pos = positionFromHash(hash, deckStops(slides));
+  return {
+    slideIndex: pos.slideIndex,
+    step: stepKey(slides[pos.slideIndex]?.beats ?? [], pos.beatIndex),
+  };
+}