@hajimism/dek 0.2.1 → 0.3.0

package/src/core/pptx-text.ts

@@ -0,0 +1,363 @@
+/// <reference lib="dom" />
+// What a PPTX takes from a slide as the browser drew it: each line of the text in its HTML flow,
+// where it was laid out and how it was set, so PowerPoint can set it there again; and the slide
+// drawn with that text taken out, as the picture under it.
+
+import type { PptxRun, PptxTextBox } from "./pptx-package.ts";
+
+/** A run as the page measures it: the element that owns its text, for its font to be looked up. */
+type MeasuredRun = Omit<PptxRun, "font"> & { owner: number };
+
+type MeasuredBox = Omit<PptxTextBox, "runs"> & { runs: MeasuredRun[] };
+
+export type PptxPageTexts = {
+  boxes: MeasuredBox[];
+  /** How many elements own text, marked `data-dek-pptx-font="<n>"` for their fonts. */
+  owners: number;
+  /** The alternative texts the slide's pictures carry, for the slide's picture as a whole. */
+  description: string;
+};
+
+/** The attribute that marks each element owning measured text, by its number. */
+export const PPTX_OWNER_ATTR = "data-dek-pptx-font";
+
+/**
+ * Measures every text in the slide's HTML flow, line by line, then hides it from the drawing with
+ * a highlight, which changes no layout, so a shot taken next is the picture under the text. What
+ * is not measured stays drawn: SVG, decoration under `aria-hidden`, what a pseudo-element draws,
+ * text a transform rotates or skews, text with no fill of its own, and every text's shadow.
+ *
+ * Runs in the page, shipped by `page.evaluate`, so it references nothing outside itself.
+ */
+export function measurePptxTextsInPage(): PptxPageTexts {
+  const slide = document.querySelector("#deck > .slide");
+  if (!(slide instanceof HTMLElement)) {
+    return { boxes: [], owners: 0, description: "" };
+  }
+  const origin = slide.getBoundingClientRect();
+
+  const canvas = document.createElement("canvas");
+  canvas.width = 1;
+  canvas.height = 1;
+  const paint = canvas.getContext("2d", { willReadFrequently: true });
+  const colors = new Map<string, { rgb: [number, number, number]; alpha: number }>();
+  /** A computed color as sRGB, whatever space it is written in, by drawing it. */
+  const rgba = (value: string): { rgb: [number, number, number]; alpha: number } => {
+    const known = colors.get(value);
+    if (known) {
+      return known;
+    }
+    let found = { rgb: [0, 0, 0] as [number, number, number], alpha: 0 };
+    if (paint) {
+      paint.clearRect(0, 0, 1, 1);
+      paint.fillStyle = value;
+      paint.fillRect(0, 0, 1, 1);
+      const [r = 0, g = 0, b = 0, a = 0] = paint.getImageData(0, 0, 1, 1).data;
+      found = { rgb: [r, g, b], alpha: a / 255 };
+    }
+    colors.set(value, found);
+    return found;
+  };
+
+  /**
+   * How much the element and what it is in, up to the slide, scale it; none when one of them
+   * rotates or skews it, or scales it unevenly, which a text box cannot follow.
+   */
+  const scaleOf = (el: Element): number | undefined => {
+    let scale = 1;
+    for (
+      let node: Element | null = el;
+      node && node !== slide.parentElement;
+      node = node.parentElement
+    ) {
+      const transform = getComputedStyle(node).transform;
+      if (transform === "none" || transform === "") {
+        continue;
+      }
+      const matrix = new DOMMatrixReadOnly(transform);
+      if (!matrix.is2D || Math.abs(matrix.b) > 1e-6 || Math.abs(matrix.c) > 1e-6) {
+        return undefined;
+      }
+      if (Math.abs(matrix.a - matrix.d) > 1e-6 || matrix.a <= 0) {
+        return undefined;
+      }
+      scale *= matrix.a;
+    }
+    return scale;
+  };
+
+  const opacityOf = (el: Element): number => {
+    let opacity = 1;
+    for (
+      let node: Element | null = el;
+      node && node !== slide.parentElement;
+      node = node.parentElement
+    ) {
+      opacity *= Number(getComputedStyle(node).opacity);
+    }
+    return opacity;
+  };
+
+  /** The nearest element around `el` laid out as a block of its own, `el` included. */
+  const blockOf = (el: Element): Element => {
+    for (let node: Element | null = el; node; node = node.parentElement) {
+      const display = getComputedStyle(node).display;
+      if (node === slide || (display !== "inline" && display !== "contents")) {
+        return node;
+      }
+    }
+    return slide;
+  };
+
+  /** The decorations an element's text is drawn with: its own, and its inline ancestors' up to its block. */
+  const decorationsOf = (el: Element, block: Element): { underline: boolean; strike: boolean } => {
+    let underline = false;
+    let strike = false;
+    for (let node: Element | null = el; node; node = node.parentElement) {
+      const line = getComputedStyle(node).textDecorationLine;
+      underline ||= line.includes("underline");
+      strike ||= line.includes("line-through");
+      if (node === block) {
+        break;
+      }
+    }
+    return { underline, strike };
+  };
+
+  const transformText = (text: string, transform: string, lang: string): string => {
+    if (transform === "uppercase") {
+      return text.toLocaleUpperCase(lang || undefined);
+    }
+    if (transform === "lowercase") {
+      return text.toLocaleLowerCase(lang || undefined);
+    }
+    if (transform === "capitalize") {
+      return text.replace(
+        /(^|\s)(\p{L})/gu,
+        (_, space: string, letter: string) =>
+          `${space}${letter.toLocaleUpperCase(lang || undefined)}`,
+      );
+    }
+    return text;
+  };
+
+  type Fragment = {
+    text: string;
+    /** Where its first glyph that is not a collapsible space starts. */
+    ink: number;
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    block: Element;
+    run: MeasuredRun;
+  };
+  const fragments: Fragment[] = [];
+  const ranges: Range[] = [];
+  const owners = new Map<Element, number>();
+  const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+  const walker = document.createTreeWalker(slide, NodeFilter.SHOW_TEXT);
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    const text = node as Text;
+    const parent = text.parentElement;
+    if (!parent || !/[^ \t\n\r\f]/.test(text.data)) {
+      continue;
+    }
+    if (parent.closest('svg, script, style, template, [aria-hidden="true"]')) {
+      continue;
+    }
+    const style = getComputedStyle(parent);
+    if (style.visibility !== "visible") {
+      continue;
+    }
+    const fill = rgba(style.webkitTextFillColor || style.color);
+    const opacity = opacityOf(parent);
+    const scale = scaleOf(parent);
+    if (fill.alpha === 0 || opacity === 0 || scale === undefined) {
+      continue;
+    }
+    const block = blockOf(parent);
+    const owner = owners.get(parent) ?? owners.size;
+    owners.set(parent, owner);
+    const weight = Number(style.fontWeight);
+    const letterSpacing =
+      style.letterSpacing === "normal" ? 0 : Number.parseFloat(style.letterSpacing);
+    const run: MeasuredRun = {
+      text: "",
+      size: Number.parseFloat(style.fontSize) * scale,
+      bold: weight >= 600,
+      italic: style.fontStyle !== "normal",
+      ...decorationsOf(parent, block),
+      color: fill.rgb,
+      alpha: Math.round(fill.alpha * opacity * 1000) / 1000,
+      letterSpacing: (Number.isFinite(letterSpacing) ? letterSpacing : 0) * scale,
+      owner,
+    };
+    const collapse = !/^(pre|pre-wrap|break-spaces)$/.test(style.whiteSpace);
+    const lang = parent.closest("[lang]")?.getAttribute("lang") ?? "";
+
+    // The lines the text is drawn on, each the graphemes on it and the box they cover.
+    const range = document.createRange();
+    const lines: Array<{
+      text: string;
+      ink: number;
+      left: number;
+      top: number;
+      right: number;
+      bottom: number;
+    }> = [];
+    for (const { segment, index } of segmenter.segment(text.data)) {
+      range.setStart(text, index);
+      range.setEnd(text, index + segment.length);
+      const rect = [...range.getClientRects()].find((box) => box.width > 0 || box.height > 0);
+      // Only the white space CSS collapses; an ideographic space is a character like any other.
+      const space = /^[ \t\n\r\f]+$/.test(segment);
+      if (!rect || (space && rect.width === 0)) {
+        continue;
+      }
+      const glyph = space && collapse ? " " : segment;
+      const line = lines.at(-1);
+      const sameLine =
+        line !== undefined &&
+        rect.top < line.bottom - (line.bottom - line.top) / 2 &&
+        rect.left >= line.right - Math.max(2, run.size / 2);
+      if (sameLine) {
+        if (!(collapse && glyph === " " && line.text.endsWith(" "))) {
+          line.text += glyph;
+        }
+        if (!space && line.ink === Number.POSITIVE_INFINITY) {
+          line.ink = rect.left;
+        }
+        line.left = Math.min(line.left, rect.left);
+        line.top = Math.min(line.top, rect.top);
+        line.right = Math.max(line.right, rect.right);
+        line.bottom = Math.max(line.bottom, rect.bottom);
+      } else {
+        lines.push({
+          text: glyph,
+          ink: space ? Number.POSITIVE_INFINITY : rect.left,
+          left: rect.left,
+          top: rect.top,
+          right: rect.right,
+          bottom: rect.bottom,
+        });
+      }
+    }
+    if (lines.length === 0) {
+      continue;
+    }
+    const all = document.createRange();
+    all.selectNodeContents(text);
+    ranges.push(all);
+    for (const line of lines) {
+      fragments.push({
+        ...line,
+        text: transformText(line.text, style.textTransform, lang),
+        block,
+        run,
+      });
+    }
+  }
+
+  // Pieces of one line in one block that sit together are one box, a run each; a gap wider than
+  // a space, such as the padding of a chip, starts another.
+  const boxes: MeasuredBox[] = [];
+  let open: { box: MeasuredBox; block: Element; right: number } | undefined;
+  for (const fragment of fragments) {
+    const height = fragment.bottom - fragment.top;
+    const gap = open ? fragment.left - open.right : Number.POSITIVE_INFINITY;
+    const joins =
+      open !== undefined &&
+      open.block === fragment.block &&
+      Math.abs(fragment.top - open.box.y - origin.top) < height / 2 &&
+      gap > -fragment.run.size / 2 &&
+      gap <= fragment.run.size * 0.3;
+    if (open && joins) {
+      const { box } = open;
+      const left = Math.min(box.x + origin.left, fragment.left);
+      const top = Math.min(box.y + origin.top, fragment.top);
+      const right = Math.max(box.x + origin.left + box.width, fragment.right);
+      const bottom = Math.max(box.y + origin.top + box.height, fragment.bottom);
+      Object.assign(box, {
+        x: left - origin.left,
+        y: top - origin.top,
+        width: right - left,
+        height: bottom - top,
+        lineHeight: Math.max(box.lineHeight, height),
+      });
+      const last = box.runs.at(-1);
+      if (last && sameStyle(last, fragment.run)) {
+        last.text += fragment.text;
+      } else {
+        box.runs.push({ ...fragment.run, text: fragment.text });
+      }
+      open.right = fragment.right;
+      continue;
+    }
+    // A box starts at its first glyph: a space it would start with is not set.
+    const start = Number.isFinite(fragment.ink) ? fragment.ink : fragment.left;
+    const box: MeasuredBox = {
+      x: start - origin.left,
+      y: fragment.top - origin.top,
+      width: Math.max(0, fragment.right - start),
+      height,
+      lineHeight: height,
+      runs: [{ ...fragment.run, text: fragment.text }],
+    };
+    boxes.push(box);
+    open = { box, block: fragment.block, right: fragment.right };
+  }
+  for (const box of boxes) {
+    const first = box.runs[0];
+    const last = box.runs.at(-1);
+    if (first) {
+      first.text = first.text.replace(/^[ \t\n\r\f]+/, "");
+    }
+    if (last) {
+      last.text = last.text.replace(/[ \t\n\r\f]+$/, "");
+    }
+    box.runs = box.runs.filter((run) => run.text !== "");
+  }
+
+  for (const [el, owner] of owners) {
+    el.setAttribute("data-dek-pptx-font", String(owner));
+  }
+  const style = document.createElement("style");
+  style.textContent =
+    "::highlight(dek-pptx) { color: transparent; -webkit-text-fill-color: transparent; text-decoration-color: transparent; }";
+  document.head.append(style);
+  CSS.highlights.set("dek-pptx", new Highlight(...ranges));
+
+  const described = [...slide.querySelectorAll("img[alt], [aria-label], svg > title")].flatMap(
+    (el) => {
+      if (el.closest('[aria-hidden="true"]')) {
+        return [];
+      }
+      const said =
+        (el.tagName.toLowerCase() === "title"
+          ? el.textContent
+          : (el.getAttribute("alt") ?? el.getAttribute("aria-label"))) ?? "";
+      return said.trim() === "" ? [] : [said.trim()];
+    },
+  );
+  return {
+    boxes: boxes.filter((box) => box.runs.length > 0),
+    owners: owners.size,
+    description: described.join(" / "),
+  };
+
+  function sameStyle(a: MeasuredRun, b: MeasuredRun): boolean {
+    return (
+      a.owner === b.owner &&
+      a.size === b.size &&
+      a.bold === b.bold &&
+      a.italic === b.italic &&
+      a.underline === b.underline &&
+      a.strike === b.strike &&
+      a.alpha === b.alpha &&
+      a.letterSpacing === b.letterSpacing &&
+      a.color.join() === b.color.join()
+    );
+  }
+}

package/src/core/pptx.ts

@@ -0,0 +1,75 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type DistOptions, distFile } from "./path.ts";
+import { type PlaywrightRunner, requirePlaywright } from "./playwright.ts";
+import { pptxPackage } from "./pptx-package.ts";
+import { presenterSlides } from "./presenter.ts";
+import { asResolvedDeck, type ResolvedDeck } from "./resolve.ts";
+import { writeInside } from "./safe-fs.ts";
+import { logicalSize } from "./size.ts";
+import { lastStop } from "./step.ts";
+import { loadSlideSources, renderSlideHtml } from "./still-page.ts";
+
+export type PptxResult = { outPath: string };
+
+export type PptxOptions = DistOptions & {
+  /** For anyone who has the file: the notes leave out the stage directions and comments. */
+  public?: boolean;
+  runner?: PlaywrightRunner;
+};
+
+/**
+ * The deck as a PowerPoint file: each slide at its last beat, as the PDF prints it, drawn as a
+ * picture with its text laid over it in text boxes a recipient can edit, and its script in the
+ * notes. A slide script that cannot run stops it, as it stops the PDF.
+ */
+export async function pptxDeck(dir: string, options?: PptxOptions): Promise<PptxResult>;
+export async function pptxDeck(source: ResolvedDeck, options?: PptxOptions): Promise<PptxResult>;
+export async function pptxDeck(
+  input: string | ResolvedDeck,
+  options: PptxOptions = {},
+): Promise<PptxResult> {
+  const { project, deck } = asResolvedDeck(input);
+  const outPath = distFile(project, deck, "pptx", options);
+  const size = logicalSize(deck.deck.ratio);
+  const sources = loadSlideSources(deck, { strict: true });
+  const { sections } = deck.deck;
+  // Rendered before Chromium starts, so a slide that cannot be drawn stops it with nothing written.
+  const pages = sections.map((section, index) => ({
+    html: renderSlideHtml(sources, section.slug, lastStop(section.beats)),
+    slug: section.slug,
+    index,
+  }));
+  const shots = mkdtempSync(join(tmpdir(), "dek-pptx-"));
+  try {
+    const answer = await requirePlaywright(
+      {
+        kind: "pptx",
+        viewport: size,
+        pages: pages.map(({ html, slug, index }) => ({
+          html,
+          slug,
+          screenshotPath: join(shots, `${index + 1}.png`),
+        })),
+      },
+      options.runner,
+    );
+    const scripts = presenterSlides(deck, options.public ? "audience" : "speaker");
+    const bytes = pptxPackage({
+      title: deck.deck.title,
+      lang: deck.deck.lang,
+      size,
+      slides: answer.slides.map((slide, index) => ({
+        picture: readFileSync(join(shots, `${index + 1}.png`)),
+        description: slide.description || (sections[index]?.title ?? slide.slug),
+        texts: slide.boxes,
+        notes: scripts[index]?.script ?? "",
+      })),
+    });
+    writeInside(outPath, bytes, project.root);
+  } finally {
+    rmSync(shots, { recursive: true, force: true });
+  }
+  return { outPath };
+}

package/src/core/slide-measure.ts

@@ -90,6 +90,7 @@ export function measureSlideInPage(): SlideMeasure {
   if (!slide) {
     return { slideBox: undefined, elements: [], pseudoTexts: [] };
   }
+  // RUNTIME_CLASSES from theme-facts.ts, written out: this function cannot import.
   const runtimeClasses = new Set(["is-current", "is-shown"]);
   const pictures = new Set(["img", "svg", "video", "canvas", "iframe", "object", "embed"]);
   // Computed colors come back as rgba() or, from a newer syntax, with a "/ alpha" at the end.

package/src/core/slide-script-eval.ts

@@ -7,6 +7,7 @@ import {
   type SlideScriptProblem,
   staticProblems,
 } from "./slide-script.ts";
+import { BUN_FLAGS } from "./spawn.ts";
 import { suggest } from "./suggest.ts";
 
 /** One slide script as lint checks it: its source, and the slide's step keys to check `motion` by. */
@@ -149,7 +150,7 @@ const EVALUATOR_OPTIONS = { stdout: "pipe", stderr: "ignore", env: {} } as const
 
 function evaluatorCommand(): string[] {
   const worker = moduleFilePath(new URL("./slide-eval-worker.ts", import.meta.url));
-  return [process.execPath, "--no-install", worker];
+  return [process.execPath, ...BUN_FLAGS, worker];
 }
 
 /** A worker that was killed still wrote a line for every script it finished. */

package/src/core/spawn.ts

@@ -13,9 +13,16 @@ export async function awaitPiped(proc: {
   return { stdout, stderr, exitCode };
 }
 
+/**
+ * How dek runs bun: with no auto install, and without the working directory's `.env` or
+ * `bunfig.toml`, which a repository someone else wrote can commit to set variables or preload code.
+ * The dekc bin's shebang passes the last two to dek itself; a child does not inherit them.
+ */
+export const BUN_FLAGS = ["--no-install", "--no-env-file", "--config=/dev/null"];
+
 /** `bin` as a command line: a .ts worker runs under bun, anything else as is. */
 export function workerCommand(bin: string, args: string[] = []): string[] {
-  return bin.endsWith(".ts") ? ["bun", "--no-install", bin, ...args] : [bin, ...args];
+  return bin.endsWith(".ts") ? ["bun", ...BUN_FLAGS, bin, ...args] : [bin, ...args];
 }
 
 /** A browser that hangs must not hang dek; a whole visual run or capture fits well inside this. */

package/src/core/sync.ts

@@ -250,13 +250,16 @@ A build system for talks. Write what you will say; dek builds, measures, and shi
 ## Conventions
 
 - 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.
+- Each deck owns its \`theme.css\`, \`decks/<deck>/theme.css\`: lint, the build, and \`dekc theme\` read that one, and it is the \`theme.css\` this file and every hint mean. The \`theme.css\` at the project root is only the template \`dekc new\` copies into a new deck; editing it changes no deck that exists.
+- 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 the deck's \`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 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.
+- \`is-current\` and \`is-shown\` are states the player sets: \`is-current\` on the slide on screen, \`is-shown\` on each \`data-step\` element once its beat plays. \`dekc theme\` lists them apart, as state classes. Select them in CSS, never write them in markup (\`DEK010\`).
 - 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\`.
+- In either stylesheet, colors, font families, easings, and lengths and times in an absolute, viewport, container, or root unit (\`px\`, \`rem\`, \`vw\`, \`ms\`, and the like) come from a token's \`var()\` (\`DEK014\`). Keywords such as \`bold\` or \`thin\`, unitless numbers, \`%\`, and units of the element's own font (\`em\`, \`ch\`, \`lh\`) are not raw values and pass. 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.
 - Motion CSS cannot express lives in \`slides/<id>.ts\`: \`export default { motion: { <step>: ms }, draw(slide, { index, step, t }) {} } satisfies DekSlide\`. \`DekSlide\` is global, from \`.dek/slide.d.ts\`; do not import it. Key the slide's arrival, before its first beat, as \`"0"\`: every \`data-step\` element is hidden there, so draw what the slide shows before anything happens. Draw from \`t\` alone and set everything you touch on every call, with no timers and no imports, so video and screenshots can seek it. In \`draw\`, find elements by data-* attributes from the slide it is given, never by class or through \`document\`: the built deck holds every slide.
+- Every picture says what it shows, or that it is decoration (\`DEK034\`). An \`<img>\` takes \`alt\`, \`alt=""\` for decoration. An \`<svg>\` with no text of its own takes \`role="img"\` and an \`aria-label\`, or \`aria-hidden="true"\` when it is decoration; one with \`<text>\` is read as it is. An element with \`role="img"\` takes an \`aria-label\`.
 - Keep the deck self-contained: no remote URLs and no paths outside the deck.
 - Every slide carries its place in \`script.md\` as \`--dek-slide-number\` and \`--dek-slide-count\`. Print a folio from them in \`theme.css\`, never by hand: \`.slide { counter-reset: folio var(--dek-slide-number) }\`, then \`content: counter(folio)\`. It follows the script as slides move.
 
@@ -267,14 +270,19 @@ A build system for talks. Write what you will say; dek builds, measures, and shi
 - A shot's path names what it drew, and an edit to the slide or the theme replaces the file. Never reuse a shot's path from before an edit: run \`dekc shot <slug>\` again, which shoots only what changed, and read the path it prints.
 - \`dekc shot --sheet\` tiles every slide on one image: read it to judge the deck's balance in one look, then open a slide's own shot for detail.
 - Mark decoration \`aria-hidden="true"\`: a glow that bleeds off the slide, or a sample of text the talk shows as unreadable. Lint measures neither overflow nor contrast on it, and screen readers skip it, so never mark text the audience should read: \`DEK029\` warns of text under it.
-- When a hint sends a fix to \`theme.css\`, make it there, not in \`slides/<id>.css\`: the theme alone draws it that way, so other slides share the problem, and one change fixes them all.
-- One shot shows no motion. \`dekc shot <slug> --motion\` lays the slide's beats out as rows, each held at moments through everything it moves and ending as the shot does. \`dekc shot <a> --to <b> --at 0.5\` freezes the view transition between any two slides.
+- When a hint sends a fix to the deck's \`theme.css\`, make it there, not in \`slides/<id>.css\`: the theme alone draws it that way, so other slides share the problem, and one change fixes them all.
+- One shot shows no motion. \`dekc shot <slug> --motion\` lays the slide's beats out as rows, each held at moments through everything it moves and ending as the shot does. Its \`--json\` puts the sheets under \`sheets\` and each beat's frames under \`motion\`; \`shots\` is empty. \`dekc shot <a> --to <b> --at 0.5\` freezes the view transition between any two slides.
 
 ## After a rehearsal
 
 - \`dekc marks\` lists the beats the speaker marked while rehearsing aloud (\`m\` in the presenter view): the words they stumbled over are \`was\`, at \`line\` in \`script.md\`. Rewrite those beats to be easier to say, and keep each beat's heading so its mark follows it; \`status\` turns \`edited\` once the words changed.
 - Leave \`dekc marks clear\` to the speaker: only saying the new words aloud tells whether they work.
 
+## When the human points at an element
+
+- \`dekc annotations\` lists the notes the human wrote on elements of the slides (\`a\` on the dev server's page): each element at \`path\`, \`line\`, and \`column\` in the file as it is now, with its \`name\`, the note's \`text\`, and the \`shot\` that shows the slide at the beat the human saw. Read them yourself when the human says to deal with their notes. Fix each, then list them again: \`status\` turns \`edited\` once the slide's own files changed and \`gone\` once none of the note's elements is left. \`edited\` does not mean a note is dealt with: compare the \`shot\` with the note.
+- Leave \`dekc annotations clear\` to the human: they wrote the notes and judge the result.
+
 ## Before you report a deck as done
 
 - \`dekc lint --visual\` passes.
@@ -285,6 +293,25 @@ For commands, run \`dekc help --agent\`.
 `;
 }
 
+/** The longest ref title AGENTS.md shows: a title names a deck, it does not describe one. */
+const REF_TITLE_MAX = 80;
+
+/**
+ * A ref's title as it goes into AGENTS.md. Someone else wrote it, and agents read dek's block as
+ * dek's own guidance, so a title must not start a line of its own there, such as a heading or an
+ * instruction: line breaks and control characters become one space, and it is cut to
+ * REF_TITLE_MAX characters.
+ */
+function refTitleLine(title: string | undefined): string | undefined {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: matching them is the point.
+  const line = title?.replace(/[\s\x00-\x1f\x7f-\x9f]+/gu, " ").trim();
+  if (!line) {
+    return undefined;
+  }
+  const chars = [...line];
+  return chars.length > REF_TITLE_MAX ? `${chars.slice(0, REF_TITLE_MAX - 1).join("")}…` : line;
+}
+
 /**
  * The refs dek.toml pins, one line each, so an agent knows which decks it may
  * read as models. Empty when there are none, leaving AGENTS.md as before. A
@@ -303,7 +330,7 @@ function referencesSection(root: string): string {
     return "";
   }
   const lines = refs.map((name) => {
-    const title = refTitle(refDir(root, name), parseRefSource(name).deck)?.title;
+    const title = refTitleLine(refTitle(refDir(root, name), parseRefSource(name).deck)?.title);
     return title ? `- \`${name}\`: ${title}` : `- \`${name}\``;
   });
   return `