@hajimism/dek 0.1.0 → 0.2.1

package/src/core/lint/keys.ts

@@ -5,7 +5,9 @@ import {
   unknownTomlKeys,
 } from "../config-keys.ts";
 import { type Diagnostic, diag } from "../diagnostic.ts";
+import { readFrontmatterYaml } from "../parse.ts";
 import { type Project, readTextIfExists } from "../resolve.ts";
+import type { DeckSettings } from "../schema.ts";
 import type { LintContext } from "./context.ts";
 
 /*
@@ -21,10 +23,51 @@ export function tomlKeyDiagnostics(project: Project): Diagnostic[] {
 }
 
 /** DEK008 for the deck's frontmatter. */
-export function frontmatterKeyDiagnostics({ deck, script }: LintContext): Diagnostic[] {
-  return (script ? unknownFrontmatterKeys(script.yaml, 2) : []).map((key) =>
-    unknownKeyDiagnostic(key, { file: "frontmatter", path: deck.scriptPath }),
-  );
+export function frontmatterKeyDiagnostics(ctx: LintContext): Diagnostic[] {
+  const { deck, script } = ctx;
+  return [
+    ...(script ? unknownFrontmatterKeys(script.yaml, 2) : []).map((key) =>
+      unknownKeyDiagnostic(key, { file: "frontmatter", path: deck.scriptPath }),
+    ),
+    ...unfollowedSeedDiagnostics(ctx),
+  ];
+}
+
+/**
+ * DEK008 for a deck setting dek.toml sets and the deck leaves out. dek.toml only seeds `dekc new`,
+ * so a deck made before it, or without the key, keeps the default: said where the key would go,
+ * and only when the two differ, since otherwise the verdict is the same either way.
+ */
+function unfollowedSeedDiagnostics({ config, deck, script }: LintContext): Diagnostic[] {
+  if (!script || !config.seed) {
+    return [];
+  }
+  const written = readFrontmatterKeys(script.yaml);
+  return Object.entries(config.seed).flatMap(([key, value]) => {
+    const used = deck.deck[key as keyof DeckSettings];
+    if (written.has(key) || value === used) {
+      return [];
+    }
+    return [
+      diag("DEK008", {
+        message: `dek.toml sets ${key} = ${value}, which this deck does not follow; it uses ${used}`,
+        path: deck.scriptPath,
+        line: script.bodyStartLine - 1,
+        hint: `to keep ${value}, add \`${key}: ${value}\` to the frontmatter; dek.toml only seeds \`dekc new\``,
+        data: { file: "frontmatter", key, value },
+      }),
+    ];
+  });
+}
+
+/** The top-level keys the frontmatter writes; none when its YAML does not parse. */
+function readFrontmatterKeys(yaml: string): Set<string> {
+  try {
+    const parsed = readFrontmatterYaml(yaml);
+    return new Set(parsed && typeof parsed === "object" ? Object.keys(parsed) : []);
+  } catch {
+    return new Set();
+  }
 }
 
 function unknownKeyDiagnostic(

package/src/core/lint/slide-html.ts

@@ -272,7 +272,7 @@ function morphDiagnostics({ section, path, scan }: SlideHtml): Diagnostic[] {
 /**
  * DEK011: style or script inside the markup, which belongs in the slide's own .css or .ts. Every
  * occurrence is its own finding: a `<style>` or `<script>` element, a `style` attribute, an event
- * handler attribute, and a `javascript:` URL.
+ * handler attribute, and a URL that runs script.
  */
 function inlineCodeDiagnostics({ section, path, scan }: SlideHtml): Diagnostic[] {
   return scan.elements
@@ -346,8 +346,11 @@ function inlineAttribute(
       hint: `remove it; a slide takes no input, and motion goes in slides/${slug}.ts as a draw(t) function`,
     };
   }
-  if (isUrlAttribute(tag, attribute.name) && isJavascriptUrl(attribute.value)) {
-    return { message: "slide contains a javascript: URL", hint: motionHint(slug) };
+  const scheme = isUrlAttribute(tag, attribute.name)
+    ? scriptUrlScheme(tag, attribute.value)
+    : undefined;
+  if (scheme) {
+    return { message: `slide contains a ${scheme} URL`, hint: motionHint(slug) };
   }
   return undefined;
 }
@@ -358,13 +361,34 @@ function motionHint(slug: string): string {
 
 /** `onclick`, `onload`, and every other attribute the browser runs as script. */
 const EVENT_HANDLER_RE = /^on[a-z]+$/;
-/** Read the way the URL parser reads it: tabs and newlines dropped, leading space trimmed, any case. */
-function isJavascriptUrl(value: string): boolean {
-  return value
+/** Tags that load a URL as a document of its own, so an SVG there runs its scripts. */
+const DOCUMENT_TAGS = new Set(["iframe", "frame", "object", "embed"]);
+
+/**
+ * The scheme of a URL that runs script, or undefined: `javascript:` and `vbscript:` always, and a
+ * `data:` URL holding HTML, or SVG where a tag loads it as a document. An image's `data:` stays.
+ * Read the way the URL parser reads it: tabs and newlines dropped, leading space trimmed, any case.
+ */
+function scriptUrlScheme(tag: string, value: string): string | undefined {
+  const url = value
     .replace(/[\t\n\r]/g, "")
     .trimStart()
-    .toLowerCase()
-    .startsWith("javascript:");
+    .toLowerCase();
+  if (url.startsWith("javascript:")) {
+    return "javascript:";
+  }
+  if (url.startsWith("vbscript:")) {
+    return "vbscript:";
+  }
+  if (url.startsWith("data:")) {
+    const type = url.slice("data:".length).split(/[;,]/, 1)[0]?.trim();
+    const runs =
+      type === "text/html" ||
+      type === "application/xhtml+xml" ||
+      (type === "image/svg+xml" && DOCUMENT_TAGS.has(tag));
+    return runs ? "data:" : undefined;
+  }
+  return undefined;
 }
 
 /**

package/src/core/lint/theme-css.ts

@@ -290,6 +290,6 @@ function themeScopeHint(selector: string): string {
 /** The theme's own findings, or DEK018 when there is no theme. */
 export function themeDiagnostics(ctx: LintContext): Diagnostic[] {
   return ctx.theme
-    ? lintTheme(ctx.theme, { maxClasses: ctx.config.maxClasses, deckDir: ctx.deck.dir })
+    ? lintTheme(ctx.theme, { maxClasses: ctx.deck.deck.max_classes, deckDir: ctx.deck.dir })
     : [missingThemeDiagnostic(ctx)];
 }

package/src/core/lint/timing.ts

@@ -1,4 +1,3 @@
-import type { DekConfig } from "../config.ts";
 import { type Diagnostic, diag } from "../diagnostic.ts";
 import type { ProjectDeck } from "../resolve.ts";
 import type { Timeline } from "../timeline.ts";
@@ -13,7 +12,7 @@ const ESTIMATE_DRIFT_RATIO = 0.35;
 /** DEK041 against the voice timeline when there is one, else against the reading-time estimate. */
 export function timingDiagnostics(ctx: LintContext): Diagnostic[] {
   const timeline = tryLoadCachedTimeline(ctx.deck.dir);
-  return timeline ? lintDuration(ctx.deck, timeline) : lintEstimate(ctx.deck, ctx.config);
+  return timeline ? lintDuration(ctx.deck, timeline) : lintEstimate(ctx.deck);
 }
 
 function lintDuration(deck: ProjectDeck, timeline: Timeline): Diagnostic[] {
@@ -37,15 +36,12 @@ function lintDuration(deck: ProjectDeck, timeline: Timeline): Diagnostic[] {
 }
 
 /** DEK041 before any voice: the reading-time estimate `dekc ls` shows, against the budget. */
-function lintEstimate(deck: ProjectDeck, config: DekConfig): Diagnostic[] {
+function lintEstimate(deck: ProjectDeck): Diagnostic[] {
   const budget = parseDurationSeconds(deck.deck.duration);
   if (budget === undefined || budget <= 0) {
     return [];
   }
-  const estimate = sectionTiming(deck.deck.sections, deck.deck.duration, config).reduce(
-    (sum, row) => sum + row.estimateSeconds,
-    0,
-  );
+  const estimate = sectionTiming(deck.deck).reduce((sum, row) => sum + row.estimateSeconds, 0);
   if (Math.abs(estimate - budget) / budget < ESTIMATE_DRIFT_RATIO) {
     return [];
   }

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/core/presenter.ts

@@ -1,4 +1,3 @@
-import type { DekConfig } from "./config.ts";
 import type { PresenterSlide } from "./presenter-state.ts";
 import type { ProjectDeck } from "./resolve.ts";
 import { type ScriptLine, scriptLines } from "./script-lines.ts";
@@ -18,10 +17,9 @@ export type ScriptReader = "speaker" | "audience";
 
 export function presenterSlides(
   deck: ProjectDeck,
-  config: DekConfig,
   reader: ScriptReader = "speaker",
 ): PresenterSlide[] {
-  const timing = sectionTiming(deck.deck.sections, deck.deck.duration, config);
+  const timing = sectionTiming(deck.deck);
   const budgetBySlug = new Map(timing.map((row) => [row.slug, row.budgetSeconds]));
   return deck.deck.sections.map((section) => {
     const script = formatSectionScript(section);

package/src/core/schema.ts

@@ -52,6 +52,25 @@ export function inferLang(text: string): string {
   return "en";
 }
 
+/**
+ * How a deck is judged: the theme's class budget and the speaking rate the estimate reads. A deck
+ * owns them in its frontmatter, so a project that changes later leaves a finished talk as it was;
+ * dek.toml may set the same keys, and `dekc new` copies them into the deck it makes.
+ */
+export const DeckSettings = z.object({
+  max_classes: z.number().describe("The most classes theme.css may define (DEK013)."),
+  cjk_per_minute: z.number().describe("Speaking rate for CJK text, in characters a minute."),
+  latin_per_minute: z.number().describe("Speaking rate for other text, in words a minute."),
+});
+
+export type DeckSettings = z.infer<typeof DeckSettings>;
+
+export const DECK_SETTING_DEFAULTS: DeckSettings = {
+  max_classes: 40,
+  cjk_per_minute: 300,
+  latin_per_minute: 130,
+};
+
 /** Frontmatter fields written to `.dek/schema.json` for yaml-language-server. */
 export const Frontmatter = z.object({
   title: z.string(),
@@ -69,6 +88,11 @@ export const Frontmatter = z.object({
   lang: Lang.optional().describe(
     "BCP 47 tag for the page. Omit it to follow the script: kana → ja, Hangul → ko, Han → zh, else en.",
   ),
+  max_classes: DeckSettings.shape.max_classes.default(DECK_SETTING_DEFAULTS.max_classes),
+  cjk_per_minute: DeckSettings.shape.cjk_per_minute.default(DECK_SETTING_DEFAULTS.cjk_per_minute),
+  latin_per_minute: DeckSettings.shape.latin_per_minute.default(
+    DECK_SETTING_DEFAULTS.latin_per_minute,
+  ),
 });
 
 export type Frontmatter = z.infer<typeof Frontmatter>;

package/src/core/sync.ts

@@ -252,7 +252,7 @@ A build system for talks. Write what you will say; dek builds, measures, and shi
 - One \`##\` heading is one slide. HTML lives in \`slides/<id>.html\`.
 - Each deck owns its \`theme.css\`. Before writing a slide, run \`dekc theme\` in the deck for the classes, tokens, and layouts it defines, and \`dekc theme <layout>\` for a layout's markup.
 - Shared look lives in \`theme.css\`. Decoration only one slide uses lives in \`slides/<id>.css\`, which is scoped to that slide.
-- Use only classes defined in \`theme.css\` or in that slide's own \`slides/<id>.css\`. The theme holds at most \`max_classes\` in \`dek.toml\`, 40 by default (\`DEK013\`); classes in \`slides/<id>.css\` do not count, so keep a class only one slide uses there.
+- Use only classes defined in \`theme.css\` or in that slide's own \`slides/<id>.css\`. The theme holds at most \`max_classes\` in the frontmatter of \`script.md\`, 40 by default (\`DEK013\`); classes in \`slides/<id>.css\` do not count, so keep a class only one slide uses there.
 - A rule in \`slides/<id>.css\` weighs as if it were written at the end of \`theme.css\`: it beats the theme's \`.slide .x\`, but not a more specific rule such as a layout's \`.slide[data-layout="split"] .x\` or the beat state \`.slide.is-current [data-step]\`. To override one of those, write the same selector.
 - Color, type, space, radius, and motion in either stylesheet use token \`var()\` only. A value only one slide uses can be a token of its own on that slide's \`.slide\` rule in \`slides/<id>.css\`.
 - Do not add \`<style>\`, \`style=\`, \`<script>\`, event handler attributes (\`onclick=\` and the like), or \`javascript:\` URLs inside slide HTML.

package/src/core/timing.ts

@@ -1,4 +1,4 @@
-import type { DekConfig } from "./config.ts";
+import type { Deck } from "./schema.ts";
 
 type SectionBodies = {
   body: string;
@@ -28,14 +28,23 @@ function speechChars(text: string): number {
   return stripBlockquotes(text).replace(/\s+/g, "").length;
 }
 
-function estimateSeconds(text: string, config: DekConfig): number {
+/** The rate a deck is spoken at, from its own frontmatter. */
+type SpeakingRate = Pick<Deck, "cjk_per_minute" | "latin_per_minute">;
+
+/** What timing reads of a deck: its sections, its budget, and the rate it is spoken at. */
+type TimedDeck = SpeakingRate & {
+  sections: Array<{ slug: string } & SectionBodies>;
+  duration?: string | undefined;
+};
+
+function estimateSeconds(text: string, rate: SpeakingRate): number {
   const stripped = stripBlockquotes(text);
   const cjk = [...stripped.matchAll(/[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/gu)]
     .length;
   const rest = stripped.replace(/[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/gu, " ");
   const words = rest.split(/\s+/).filter(Boolean).length;
-  const cjkMinutes = config.cjkPerMinute > 0 ? cjk / config.cjkPerMinute : 0;
-  const latinMinutes = config.latinPerMinute > 0 ? words / config.latinPerMinute : 0;
+  const cjkMinutes = rate.cjk_per_minute > 0 ? cjk / rate.cjk_per_minute : 0;
+  const latinMinutes = rate.latin_per_minute > 0 ? words / rate.latin_per_minute : 0;
   return Math.round((cjkMinutes + latinMinutes) * 60);
 }
 
@@ -62,21 +71,17 @@ export type TimedSection = {
   budgetSeconds?: number;
 };
 
-export function sectionTiming(
-  sections: Array<{ slug: string; body: string; beats: Array<{ body: string }> }>,
-  duration: string | undefined,
-  config: DekConfig,
-): TimedSection[] {
-  const rows = sections.map((section) => {
+export function sectionTiming(deck: TimedDeck): TimedSection[] {
+  const rows = deck.sections.map((section) => {
     const text = speechText(section);
     return {
       slug: section.slug,
       chars: speechChars(text),
-      estimateSeconds: estimateSeconds(text, config),
+      estimateSeconds: estimateSeconds(text, deck),
     };
   });
   const totalChars = rows.reduce((sum, row) => sum + row.chars, 0);
-  const durationSeconds = parseDurationSeconds(duration);
+  const durationSeconds = parseDurationSeconds(deck.duration);
 
   return rows.map((row) => ({
     slug: row.slug,

package/src/core/video-document.ts

@@ -1,4 +1,3 @@
-import { loadConfig } from "./config.ts";
 import { renderDeckDocument } from "./document.ts";
 import type { ResolvedDeck } from "./resolve.ts";
 
@@ -6,9 +5,8 @@ import type { ResolvedDeck } from "./resolve.ts";
  * The whole deck as `dekc video` plays it: every slide, assets inlined, no notes, and the player
  * runtime that walks it. Motion stills, morph frames and the video itself all run on this page.
  */
-export function videoDocument({ project, deck }: ResolvedDeck, playerScript: string): string {
+export function videoDocument({ deck }: ResolvedDeck, playerScript: string): string {
   return renderDeckDocument(deck, {
-    config: loadConfig(project.configPath),
     playerScript,
     target: { kind: "video" },
   });

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