@hajimism/dek 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+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)
+
+
+### ⚠ BREAKING CHANGES
+
+* max_classes, cjk_per_minute and latin_per_minute in dek.toml no longer apply to existing decks. Add them to each deck's script.md frontmatter to keep them; lint's DEK008 names each one.
+
+### Features
+
+* let a deck own its class budget and speaking rate ([8dc9a07](https://github.com/hajimism/dek/commit/8dc9a07efb32b803e685a353ee628cae21a8bc56))
+
+
+### Bug Fixes
+
+* **lint:** count vbscript: and script-running data: URLs in DEK011 ([1b825b1](https://github.com/hajimism/dek/commit/1b825b1bffc33809ef0bdf3a8e5a1d45794a41a7))
+
+## 0.1.0 (2026-10-01)
+
+The first release on npm.
+
+### Features
+
+* Published as `@hajimism/dek`. Create a project with `bunx @hajimism/dek init`, then install it with `bun add -d @hajimism/dek`.
+
+### ⚠ BREAKING CHANGES
+
+* The command is `dekc`, not `dek`. `dek` on npm is an unrelated package, and `bunx dek` ran it anywhere dek was not installed. Run `bunx dekc` inside a project; the package, `dek.toml`, `.dek/`, and the `DEK` lint codes keep their names.

package/README.ja.md

@@ -1,5 +1,7 @@
 # dek
 
+[![npm](https://img.shields.io/npm/v/@hajimism/dek)](https://www.npmjs.com/package/@hajimism/dek) [![CI](https://github.com/hajimism/dek/actions/workflows/ci.yml/badge.svg)](https://github.com/hajimism/dek/actions/workflows/ci.yml) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hajimism/dek/badge)](https://scorecard.dev/viewer/?uri=github.com/hajimism/dek)
+
 **発表のビルドシステム。** 喋ることを書けば、あとは dek が組み立て、測り、届ける。
 
 [ドキュメント](https://hajimism.github.io/dek/ja/) · [English README](./README.md)
@@ -20,7 +22,7 @@ dek は、ビルドシステムがコードを扱うように発表を扱う CLI
 
 ## クイックスタート
 
-[Bun](https://bun.sh) 1.4 以上。
+[Bun](https://bun.sh) 1.4 以上が必要です。dek は Bun でだけ動き、Node では動きません。`npx` ではなく `bunx` を使ってください。
 
 ```bash
 bunx @hajimism/dek init my-talks --deck 2026-04-vite
@@ -66,10 +68,12 @@ bun run check             # Biome の format + lint
 bun run docs:dev          # VitePress
 ```
 
-CI では `biome ci`、`typecheck`、全テスト（ブラウザを使うものは Chromium で）、`docs:build` を走らせます。
+CI では `biome ci`、`typecheck`、`knip`、全テスト（ブラウザを使うものは Chromium で）、`docs:build`、`scripts/check-package.sh`（npm に出す tarball を入れて動かす）を走らせます。
 
 ドキュメントサイトは GitHub Actions 経由で GitHub Pages に出します。初回だけ、リポジトリの設定で **Pages → Source** を **GitHub Actions** にしてください。
 
+プルリクエストで通すチェックは [CONTRIBUTING.md](./CONTRIBUTING.md)、リリースごとの変更は [CHANGELOG.md](./CHANGELOG.md) にあります。脆弱性は [SECURITY.md](./SECURITY.md) のとおり非公開で報告してください。
+
 ## ライセンス
 
 MIT

package/README.md

@@ -1,5 +1,7 @@
 # dek
 
+[![npm](https://img.shields.io/npm/v/@hajimism/dek)](https://www.npmjs.com/package/@hajimism/dek) [![CI](https://github.com/hajimism/dek/actions/workflows/ci.yml/badge.svg)](https://github.com/hajimism/dek/actions/workflows/ci.yml) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hajimism/dek/badge)](https://scorecard.dev/viewer/?uri=github.com/hajimism/dek)
+
 **A build system for talks.** Write what you will say; dek builds, measures, and ships the rest.
 
 [Documentation](https://hajimism.github.io/dek/) · [日本語 README](./README.ja.md)
@@ -20,7 +22,7 @@ The three principles and the comparison with Slidev are in [Why dek](https://haj
 
 ## Quick start
 
-[Bun](https://bun.sh) 1.4 or later.
+Requires [Bun](https://bun.sh) 1.4 or later. dek runs on Bun only: it does not run on Node, so use `bunx`, not `npx`.
 
 ```bash
 bunx @hajimism/dek init my-talks --deck 2026-04-vite
@@ -66,10 +68,12 @@ bun run check             # Biome format + lint
 bun run docs:dev          # VitePress
 ```
 
-CI runs `biome ci`, `typecheck`, the full test suite (the browser tests in Chromium), and `docs:build`.
+CI runs `biome ci`, `typecheck`, `knip`, the full test suite (the browser tests in Chromium), `docs:build`, and `scripts/check-package.sh`, which installs the packed tarball and runs it.
 
 The documentation site deploys to GitHub Pages through Actions. Once, in the repository settings, set **Pages → Source** to **GitHub Actions**.
 
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the checks a pull request runs, and [CHANGELOG.md](./CHANGELOG.md) for what each release changed. Report security issues privately, as [SECURITY.md](./SECURITY.md) describes.
+
 ## License
 
 MIT

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@hajimism/dek",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "A build system for talks.",
   "license": "MIT",
+  "author": "Hajime Nakagawa (https://github.com/hajimism)",
   "type": "module",
   "bin": {
     "dekc": "src/cli.ts"
@@ -11,7 +12,8 @@
     "src",
     "LICENSE",
     "README.md",
-    "README.ja.md"
+    "README.ja.md",
+    "CHANGELOG.md"
   ],
   "repository": {
     "type": "git",
@@ -31,9 +33,12 @@
     "slides",
     "presentation",
     "talk",
+    "markdown",
     "build",
     "cli",
-    "html"
+    "html",
+    "bun",
+    "ai-agents"
   ],
   "scripts": {
     "test": "bun test --parallel=4",
@@ -61,5 +66,8 @@
     "playwright": "^1.63.0",
     "typescript": "^7.0.2",
     "vitepress": "^1.6.4"
+  },
+  "overrides": {
+    "vite": "^6.4.3"
   }
 }

package/src/cli/files.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { bundledTheme } from "../core/bundled-theme.ts";
+import type { DekConfig } from "../core/config.ts";
 import { deckPaths } from "../core/deck-paths.ts";
 import { DekError } from "../core/error.ts";
 import { walkUp } from "../core/optional.ts";
@@ -72,12 +73,17 @@ const INSTALL_DEK = "bun add -d @hajimism/dek";
  * shows sections, beats, and an estimate against the budget. A deck with a
  * voice starts in Japanese, the language dek's voice reads; any other in English.
  */
-export function defaultScript(title: string, lang: "en" | "ja" = "en"): string {
+export function defaultScript(
+  title: string,
+  lang: "en" | "ja" = "en",
+  settings: DekConfig["seed"] = {},
+): string {
+  const lines = Object.entries(settings).map(([key, value]) => `${key}: ${value}\n`);
   return `---
 # yaml-language-server: $schema=../../.dek/schema.json
 title: ${JSON.stringify(title)}
 duration: 1m
----
+${lines.join("")}---
 ${STARTER_BODY[lang]}`;
 }
 
@@ -230,18 +236,19 @@ function placeable(path: string, kind: "file" | "directory"): boolean {
 }
 
 /**
- * A deck's files: its directories, the starter script, the theme it starts
- * from, and voice settings when the project has a voice. The skeleton slides
- * are sync's to write, once the theme they are drawn in is in place.
+ * A new deck's files: its directories, the starter script, the theme it starts from, and what the
+ * project's dek.toml seeds, its deck settings and `[voice]`. From then on the deck owns them: a
+ * later change to dek.toml leaves it alone. The skeleton slides are sync's to write, once the
+ * theme they are drawn in is in place.
  */
 export function deckPlan(
   root: string,
   name: string,
   theme: string,
-  voice?: { engine: string; speaker: string; speed?: number },
+  { seed, voice }: Pick<DekConfig, "seed" | "voice"> = {},
 ): PlannedPath[] {
   const paths = deckPaths(join(root, "decks", name));
-  const script = defaultScript(name, voice ? "ja" : "en");
+  const script = defaultScript(name, voice ? "ja" : "en", seed);
   const plan: PlannedPath[] = [
     { path: paths.slides },
     { path: paths.assets },

package/src/cli/ls.ts

@@ -1,4 +1,3 @@
-import { type DekConfig, loadConfig } from "../core/config.ts";
 import type { Diagnostic } from "../core/diagnostic.ts";
 import { lintDeck, lintProject } from "../core/lint.ts";
 import { listSlides, type Project, type ProjectDeck } from "../core/resolve.ts";
@@ -54,7 +53,7 @@ export function lsCommand(target: DecksTarget): LsListResult | LsDeckResult {
   const { project, deck, ref } = target;
   if (deck && ref) {
     return {
-      ...formatDeck(deck, loadConfig(project.configPath), project, { lint: false }),
+      ...formatDeck(deck, project, { lint: false }),
       ...skippedChecks([
         { check: "lint", reason: "a ref is read-only; its problems are not yours to fix" },
       ]),
@@ -62,7 +61,7 @@ export function lsCommand(target: DecksTarget): LsListResult | LsDeckResult {
     };
   }
   if (deck) {
-    return formatDeck(deck, loadConfig(project.configPath), project);
+    return formatDeck(deck, project);
   }
   return {
     kind: "list",
@@ -85,11 +84,10 @@ function summarizeDeck(deck: ProjectDeck, project: Project): LsListResult["decks
 
 function formatDeck(
   deck: ProjectDeck,
-  config: DekConfig,
   project: Project,
   options: { lint: boolean } = { lint: true },
 ): LsDeckResult {
-  const timing = sectionTiming(deck.deck.sections, deck.deck.duration, config);
+  const timing = sectionTiming(deck.deck);
   const estimateTotal = timing.reduce((sum, row) => sum + row.estimateSeconds, 0);
   const timeline = tryLoadCachedTimeline(deck.dir);
 

package/src/cli/new.ts

@@ -48,8 +48,9 @@ export function newCommand(options: { cwd: string; name: string; themeFrom?: str
   }
 
   const theme = readFileSync(themeSource, "utf8");
-  const voice = loadConfig(project.configPath).voice;
-  const { created } = applyPlan(deckPlan(project.root, name, theme, voice));
+  const { created } = applyPlan(
+    deckPlan(project.root, name, theme, loadConfig(project.configPath)),
+  );
   // As sync would. AGENTS.md and .dek/ follow the project theme and dek, so they change here
   // only when either moved on since the last command that wrote them: say which.
   const synced = syncDeck(dir);

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/build.ts

@@ -49,7 +49,6 @@ export async function buildDeck(
     removeInside(imagePath, project.root);
   }
   const html = renderDeckDocument(deck, {
-    config,
     playerScript: options.playerScript,
     target: {
       kind: "build",

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/config.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { z } from "zod";
 import { parsePublicUrl } from "./ogp.ts";
 import { isPinnedRev, isPlainRefName } from "./ref-name.ts";
+import { DeckSettings } from "./schema.ts";
 import { parseTomlWith } from "./zod.ts";
 
 export const Voice = z.object({
@@ -18,9 +19,7 @@ export const DekToml = z.object({
         "write the absolute http(s) URL dist/ is served from, like https://example.com/talks/",
     })
     .optional(),
-  max_classes: z.number().optional(),
-  cjk_per_minute: z.number().optional(),
-  latin_per_minute: z.number().optional(),
+  ...DeckSettings.partial().shape,
   voice: Voice.optional(),
   refs: z
     .record(z.string(), z.string())
@@ -49,20 +48,16 @@ type VoiceDefaults = {
 export type DekConfig = {
   /** Where dist/ is served from, ending in a slash; link previews need it for og:image. */
   url?: string;
-  maxClasses: number;
-  cjkPerMinute: number;
-  latinPerMinute: number;
+  /**
+   * The deck settings `dekc new` writes into a new deck's frontmatter. Nothing else reads them: a
+   * deck is judged by its own, so changing dek.toml leaves the decks already made as they were.
+   */
+  seed?: Partial<DeckSettings>;
   voice?: VoiceDefaults;
   /** `[refs]`: each ref name and the commit it is pinned to. */
   refs?: Record<string, string>;
 };
 
-export const DEFAULT_CONFIG: DekConfig = {
-  maxClasses: 40,
-  cjkPerMinute: 300,
-  latinPerMinute: 130,
-};
-
 export function parseDekToml(source: string, path?: string): DekConfig {
   const data = parseTomlWith(DekToml, source, {
     label: "dek.toml",
@@ -77,11 +72,10 @@ export function parseDekToml(source: string, path?: string): DekConfig {
       }
     : undefined;
   const url = data.url === undefined ? undefined : parsePublicUrl(data.url);
+  const seed = DeckSettings.partial().parse(data);
   return {
     ...(url ? { url } : {}),
-    maxClasses: data.max_classes ?? DEFAULT_CONFIG.maxClasses,
-    cjkPerMinute: data.cjk_per_minute ?? DEFAULT_CONFIG.cjkPerMinute,
-    latinPerMinute: data.latin_per_minute ?? DEFAULT_CONFIG.latinPerMinute,
+    ...(Object.keys(seed).length > 0 ? { seed } : {}),
     ...(voice ? { voice } : {}),
     ...(data.refs && Object.keys(data.refs).length > 0 ? { refs: data.refs } : {}),
   };
@@ -89,7 +83,7 @@ export function parseDekToml(source: string, path?: string): DekConfig {
 
 export function loadConfig(configPath: string): DekConfig {
   if (!existsSync(configPath)) {
-    return { ...DEFAULT_CONFIG };
+    return {};
   }
   return parseDekToml(readFileSync(configPath, "utf8"), configPath);
 }

package/src/core/document.ts

@@ -1,6 +1,5 @@
 import { readTheme } from "./assets.ts";
 import { playerChromeCss } from "./chrome.ts";
-import { type DekConfig, loadConfig } from "./config.ts";
 import { escapeAttr, escapeHtml } from "./escape.ts";
 import { collectSlidesHtml, htmlShell } from "./html.ts";
 import { type OgpImage, ogpHead } from "./ogp.ts";
@@ -25,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
@@ -50,13 +51,12 @@ export function renderDeckHtml(
   dir: string,
   options: { playerScript: string; target: PageTarget },
 ): string {
-  const { project, deck } = resolveDeck(dir);
-  return renderDeckDocument(deck, { ...options, config: loadConfig(project.configPath) });
+  return renderDeckDocument(resolveDeck(dir).deck, options);
 }
 
 export function renderDeckDocument(
   deck: ProjectDeck,
-  options: { config: DekConfig; playerScript: string; target: PageTarget },
+  options: { playerScript: string; target: PageTarget },
 ): string {
   const { target } = options;
   const mode: PageMode =
@@ -69,10 +69,10 @@ export function renderDeckDocument(
   const standalone = !live;
   const strictScripts = target.kind === "video";
   const includeNotes = target.kind === "dev" ? target.includeNotes : target.kind === "build";
-  const data = presenterSlides(deck, options.config, scriptReader(target)).map((slide) =>
+  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;
@@ -107,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>`
@@ -159,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>` : ""}`,
   });
 }
 
@@ -199,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("");
 }