@hajimism/dek 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 Release notes for `@hajimism/dek`. From 0.1.0 on, release-please writes this file from the Conventional Commits on `main`.
 
+## [0.2.2](https://github.com/hajimism/dek/compare/v0.2.1...v0.2.2) (2026-10-06)
+
+
+### Features
+
+* **agents:** generate llms.txt and ship the official dek skill ([79d8abe](https://github.com/hajimism/dek/commit/79d8abea5d3c8822a865e2e58b687ec898e9f729))
+* **agents:** generate llms.txt and ship the official dek skill ([b9b66ba](https://github.com/hajimism/dek/commit/b9b66ba43b556e35738a66ed492ad699556573ce))
+* **dev:** keep annotations in .dek/ and list them with dekc annotations ([e22671f](https://github.com/hajimism/dek/commit/e22671f2816b517c62b827ca111aadd2edc02dfe))
+* **dev:** keep annotations in .dek/ and list them with dekc annotations ([10195e3](https://github.com/hajimism/dek/commit/10195e3060d5754d36e91f5276b9964ed620ccb8))
+* **lint:** keep runtime state classes out of a theme's vocabulary and slide markup ([83fd36c](https://github.com/hajimism/dek/commit/83fd36c8d2312c709d939bdc2e344d906b13ff82))
+* **lint:** require every picture to say what it shows (DEK034) ([95ebbc2](https://github.com/hajimism/dek/commit/95ebbc2830b67a13288709d593b7d39c006ea806))
+* **lint:** require every picture to say what it shows (DEK034) ([9926f4b](https://github.com/hajimism/dek/commit/9926f4b22c3d9be1abf6fd8681fdc101383c11b3))
+* **pptx:** export a talk as PPTX with editable text over each slide ([12c2ec2](https://github.com/hajimism/dek/commit/12c2ec21b67e0b713e326d9300eff787a5a8ed16))
+* **pptx:** export a talk as PPTX with editable text over each slide ([46d5468](https://github.com/hajimism/dek/commit/46d54686e5ce60d4718015a964791401a2345b3b))
+
+
+### Bug Fixes
+
+* **agents:** write the agent guidance as what the checks and commands do ([97447ca](https://github.com/hajimism/dek/commit/97447cabf543c66cc6231b9b0e5a2378d7060615))
+
+## [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/README.ja.md

@@ -6,7 +6,7 @@
 
 [ドキュメント](https://hajimism.github.io/dek/ja/) · [English README](./README.md)
 
-dek は、ビルドシステムがコードを扱うように発表を扱う CLI です。ソースは Markdown で書くトークの台本で、`##` の見出しひとつが 1 枚の HTML スライドになります。同じソースから、尺を見積もり、どのスライドも lint して描画を測り、1 ファイルの HTML、PDF、読み上げ付きの動画をビルドします。プロジェクトが複数のデッキを持つので、テーマも規約も前回のトークから次のトークへ引き継がれます。AI エージェントと一緒に作ることを、最初から前提に設計しています。
+dek は、ビルドシステムがコードを扱うように発表を扱う CLI です。ソースは Markdown で書くトークの台本で、`##` の見出しひとつが 1 枚の HTML スライドになります。同じソースから、尺を見積もり、どのスライドも lint して描画を測り、1 ファイルの HTML、PDF、文字を編集できる PowerPoint ファイル、読み上げ付きの動画をビルドします。プロジェクトが複数のデッキを持つので、テーマも規約も前回のトークから次のトークへ引き継がれます。AI エージェントと一緒に作ることを、最初から前提に設計しています。
 
 ## なぜ dek か
 
@@ -44,6 +44,8 @@ bunx dekc build     # 3. dist/2026-04-vite.html — トーク全体がこの 1
 
 台本を書いて `dekc` を叩けば、HTML を一行も書かずに同梱テーマで発表できます。
 
+エージェントと作るなら、公式スキルを `npx skills add hajimism/dek` で、Claude Code なら `/plugin marketplace add hajimism/dek` と `/plugin install dek@dek` で入れてください。プロジェクトの外にいるエージェントは [llms.txt](https://hajimism.github.io/dek/llms.txt) から始められます。[AI エージェントと作る](https://hajimism.github.io/dek/ja/guide/ai.html)を参照してください。
+
 続きは [はじめる](https://hajimism.github.io/dek/ja/guide/getting-started.html)へ。通しで 1 本作るなら [チュートリアル](https://hajimism.github.io/dek/ja/guide/tutorial.html)。コマンドの一覧は [CLI リファレンス](https://hajimism.github.io/dek/ja/reference/cli.html)にあります。
 
 ## サンプル

package/README.md

@@ -6,7 +6,7 @@
 
 [Documentation](https://hajimism.github.io/dek/) · [日本語 README](./README.ja.md)
 
-dek treats a talk the way a build system treats code. The source is your talk script, in Markdown; every `##` heading becomes one HTML slide, and from the same source dek estimates the timing, lints and measures every slide, and builds a single HTML file, a PDF, and a narrated video. A project holds many decks, so the theme and conventions carry forward from one talk to the next. It is designed from the start to be worked on together with AI agents.
+dek treats a talk the way a build system treats code. The source is your talk script, in Markdown; every `##` heading becomes one HTML slide, and from the same source dek estimates the timing, lints and measures every slide, and builds a single HTML file, a PDF, a PowerPoint file with its text editable, and a narrated video. A project holds many decks, so the theme and conventions carry forward from one talk to the next. It is designed from the start to be worked on together with AI agents.
 
 ## Why
 
@@ -44,6 +44,8 @@ bunx dekc build     # 3. dist/2026-04-vite.html — the whole talk in one file
 
 Write the script, run `dekc`, and you can present with the bundled theme without writing a line of HTML.
 
+Working with an agent? Install the official skill with `npx skills add hajimism/dek`, or in Claude Code with `/plugin marketplace add hajimism/dek` and `/plugin install dek@dek`; an agent outside any project can start from [llms.txt](https://hajimism.github.io/dek/llms.txt). See [Working with AI Agents](https://hajimism.github.io/dek/guide/ai.html).
+
 Continue with [Getting Started](https://hajimism.github.io/dek/guide/getting-started.html), or build a real deck end to end in the [Tutorial](https://hajimism.github.io/dek/guide/tutorial.html). Every command is listed in the [CLI reference](https://hajimism.github.io/dek/reference/cli.html).
 
 ## Sample

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hajimism/dek",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "A build system for talks.",
   "license": "MIT",
   "author": "Hajime Nakagawa (https://github.com/hajimism)",
@@ -10,6 +10,7 @@
   },
   "files": [
     "src",
+    "skills",
     "LICENSE",
     "README.md",
     "README.ja.md",
@@ -46,6 +47,7 @@
     "typecheck": "tsc --noEmit",
     "knip": "knip",
     "schema": "bun scripts/cli-schema.ts",
+    "llms": "bun scripts/llms.ts",
     "format": "biome format --write .",
     "lint": "biome lint .",
     "check": "biome check --write .",

package/skills/dek/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: dek
+description: Write and fix talks with dek, a build system for talks run as `dekc` on Bun - script first in script.md, one small HTML file per slide, checked by lint and screenshots until lint passes. Use when a project has dek.toml or decks/*/script.md, or when asked to make, fix, or hand over slides for a talk with dek.
+---
+
+# dek
+
+dek builds a talk from its script. `script.md` holds what will be said, in order; each `##` heading is one slide, written as one small HTML file, and lint checks everything a rule can measure. This skill is the loop. The installed dek tells you the rest, and it wins whenever the two disagree.
+
+## Run it as `dekc`, on Bun
+
+- The package is `@hajimism/dek`; the command is `dekc`. Never `bunx dek` or `npx dek`: `dek` on npm is an unrelated package that would be downloaded and run.
+- dek runs on Bun. Inside a project, `bunx dekc`; outside one, `bunx @hajimism/dek`. Not `npx`, not `node`.
+- No project yet: `bunx @hajimism/dek init <dir>`, then `cd <dir>`; where dek is already installed, `bunx dekc init <dir>` does the same.
+- Decide from `--json`: every result command takes it. Branch on `ok`; an error carries a `hint` with the next command to run. Never scrape a verdict from the text output. `show` and `theme` print text meant to be read, and take `--json` too.
+
+## First, ask the dek you have
+
+1. `bunx dekc --version` and `bunx dekc help --agent`: every command and flag of the dek installed in this project. This file names few on purpose; use only what that list shows.
+2. Read dek's block in `AGENTS.md`. dek rewrites it for the installed version: the conventions lint checks, how to check a slide, and what to do before reporting a deck as done. Follow it as written.
+3. In the deck, `bunx dekc theme`: the classes, tokens, and layouts this deck's theme defines, and `bunx dekc theme <layout>` for a layout's markup. Use nothing else.
+
+## Script first
+
+Write or change `script.md` before any slide: `##` is a slide, `###` a beat, and paragraphs are what is said. `bunx dekc sync` writes a skeleton for each new section, and removes the skeletons nobody edited whose section is gone; it never touches a slide you edited. Keep the order and what is said in the script; a slide shows it. `bunx dekc ls` estimates the talk's length from the script against the `duration` in its frontmatter.
+
+## One slide at a time
+
+1. `bunx dekc show <slug>`: the slide's section of the script, its files, and the theme rules it uses.
+2. Edit `slides/<slug>.html`, and `slides/<slug>.css` for what only this slide needs.
+3. `bunx dekc check <slug> --shot --json`: fix every error, then open the shot it names. Read its `fill` before judging the shot.
+4. Next slide. When all are written, `bunx dekc lint --visual --json`, which reports every problem in one run.
+
+A hint that sends a fix to `theme.css` means every slide of the deck shares the problem: fix it in the deck's own `theme.css`.
+
+## When to stop
+
+- `bunx dekc lint --visual` reports no errors. Warnings do not fail it; read them and decide. A check listed in `skipped` did not run: say so, with its hint, rather than count it as passed.
+- You have looked at `bunx dekc shot --sheet` and judged the deck's balance.
+- Say what you could not judge, such as the argument and how the timing feels when spoken, and hand it back to the author. Passing lint means nothing measurable is wrong, not that the talk is good.
+
+## When the human points at something
+
+If the human marked beats while rehearsing or pointed at elements of a slide, `bunx dekc help --agent` lists the commands that read those notes, and `AGENTS.md` says how to use them. Leave clearing them to the human.

package/src/cli/annotations.ts

@@ -0,0 +1,26 @@
+import type { AnnotationRow } from "../core/annotation-rows.ts";
+import { clearAnnotations, listAnnotations } from "../core/annotations.ts";
+import type { DeckTarget } from "./scope.ts";
+
+export type AnnotationsCliResult =
+  | { action: "list"; annotations: AnnotationRow[] }
+  | { action: "clear"; cleared: number };
+
+/**
+ * `dekc annotations`: the notes a human wrote on elements of the slides in annotate mode, each
+ * element where the file has it now. It reads the project's file, so no dev server is needed.
+ */
+export async function annotationsCommand({
+  project,
+  deck,
+}: DeckTarget): Promise<AnnotationsCliResult> {
+  return { action: "list", annotations: listAnnotations(project.root, deck) };
+}
+
+/** `dekc annotations clear`: drop the deck's notes, once the human has seen them dealt with. */
+export async function clearAnnotationsCommand({
+  project,
+  deck,
+}: DeckTarget): Promise<AnnotationsCliResult> {
+  return { action: "clear", cleared: clearAnnotations(project.root, deck) };
+}

package/src/cli/commands.ts

@@ -9,6 +9,7 @@ import type { DeckScope, DecksTarget, ReadableDeck } from "./scope.ts";
 import {
   countSummary,
   displayDiagnostics,
+  formatAnnotations,
   formatBuild,
   formatCheck,
   formatCues,
@@ -540,6 +541,51 @@ export const COMMANDS = {
           : data,
     },
   }),
+  annotations: result({
+    scope: "deck",
+    args: [],
+    flags: [],
+    usage: ["dekc annotations [deck]"],
+    summary:
+      "List the notes written on elements of the slides in annotate mode, by pressing a on the\ndev server's page: each element where the file has it now, and whether the slide changed since.",
+    group: "Slide",
+    overview: [
+      ["dekc annotations", "list the notes written on slide elements in annotate mode (a)"],
+      ["dekc annotations clear", "drop the deck's annotations"],
+    ],
+    agent: [
+      "dekc annotations [clear]   notes a human wrote on slide elements (a): path:line:column, text, shot, status open|edited|gone",
+    ],
+    run: async ({ target }) => {
+      const { annotationsCommand } = await import("./annotations.ts");
+      return annotationsCommand(target);
+    },
+    subcommands: {
+      clear: {
+        args: [],
+        flags: [],
+        usage: ["dekc annotations [deck] clear"],
+        run: async ({ target }) => {
+          const { clearAnnotationsCommand } = await import("./annotations.ts");
+          return clearAnnotationsCommand(target);
+        },
+      },
+    },
+    output: {
+      text: formatAnnotations,
+      paths: (data, display) =>
+        data.action === "list"
+          ? {
+              ...data,
+              annotations: data.annotations.map((row) => ({
+                ...row,
+                targets: row.targets.map((target) => ({ ...target, path: display(target.path) })),
+                changed: row.changed.map(display),
+              })),
+            }
+          : data,
+    },
+  }),
   sync: result({
     scope: "decks",
     args: [],
@@ -738,6 +784,26 @@ export const COMMANDS = {
     },
     output: { text: formatPdf },
   }),
+  pptx: result({
+    scope: "decks",
+    args: [],
+    flags: ["root-dist", "public"],
+    usage: ["dekc pptx [deck] [--root-dist] [--public]"],
+    summary:
+      "Write dist/<deck>.pptx, one slide per slide at its last beat: a picture of it with its text\nin text boxes to edit, and its script in the notes. Needs Playwright.",
+    group: "Output",
+    overview: [
+      ["dekc pptx [--root-dist] [--public]", "write a PowerPoint file with editable text"],
+    ],
+    agent: [
+      "dekc pptx [--root-dist] [--public]   text editable over a picture of each slide; script in notes",
+    ],
+    run: async ({ target, flags }) => {
+      const { pptxCommand } = await import("./pptx.ts");
+      return pptxCommand(target, { rootDist: flags["root-dist"], public: flags.public });
+    },
+    output: { text: formatPdf },
+  }),
   help: {
     kind: "help",
     args: ["command?"],

package/src/cli/contract.ts

@@ -189,13 +189,25 @@ export const RESULT_FIELDS = {
     html: z.string().nullable(),
     css: z.string().nullable(),
     ts: z.string().nullable(),
-    theme: z.string().nullable().describe("The rules of the deck's theme.css this slide uses."),
+    theme: z
+      .string()
+      .nullable()
+      .describe(
+        "The rules of the deck's theme.css this slide uses: those its classes, layout, elements, and attributes match; with a slide script, every element and attribute rule under .slide.",
+      ),
     assets: paths,
     ref: RefInfo.optional(),
   }),
   theme: z.strictObject({
     path: z.string(),
-    classes: z.array(z.string()),
+    classes: z
+      .array(z.string())
+      .describe("The classes slide markup may use; what max_classes counts."),
+    stateClasses: z
+      .array(z.string())
+      .describe(
+        "State classes the theme selects that the player sets at runtime (is-current, is-shown); never written in markup.",
+      ),
     tokens: z.array(z.strictObject({ name: z.string(), value: z.string() })),
     layouts: z.array(z.strictObject({ name: z.string(), example: z.string().optional() })),
     layout: z.strictObject({ name: z.string(), example: z.string() }).optional(),
@@ -249,7 +261,9 @@ export const RESULT_FIELDS = {
       .optional(),
   }),
   shot: z.strictObject({
-    shots: z.array(shotFile),
+    shots: z
+      .array(shotFile)
+      .describe("Each still or morph frame; with --motion, empty: the frames are in motion."),
     sheets: paths.optional().describe("Contact sheets, from --sheet or --motion."),
     motion: z
       .array(
@@ -260,7 +274,8 @@ export const RESULT_FIELDS = {
           ),
         }),
       )
-      .optional(),
+      .optional()
+      .describe("With --motion, each beat in order with its frames, the settled end last."),
   }),
   mv: z.strictObject({
     from: z.string(),
@@ -294,6 +309,61 @@ export const RESULT_FIELDS = {
     }),
     z.strictObject({ action: z.literal("clear"), cleared: z.number().int() }),
   ]),
+  annotations: z.union([
+    z.strictObject({
+      action: z.literal("list"),
+      annotations: z.array(
+        z.strictObject({
+          number: z.number().int().describe("As the dev page's markers and Copy number it."),
+          id: z.string(),
+          slug: z.string(),
+          step: z
+            .string()
+            .describe("The stop as `dekc shot --step` takes it; 0 as the slide arrives."),
+          status: z
+            .enum(["open", "edited", "gone"])
+            .describe(
+              "edited once the slide's own html, css, or ts changed since the note; gone once none of its elements is on the slide.",
+            ),
+          text: z.string().describe("What the human wrote."),
+          targets: z.array(
+            z.strictObject({
+              path: z.string(),
+              line: z
+                .number()
+                .int()
+                .describe("Where the start tag is now; where it was last found when not found."),
+              column: z.number().int().describe("1-based, in UTF-16 units as editors count."),
+              found: z.boolean(),
+              name: z
+                .string()
+                .describe(
+                  "The tag and its classes as written where it was last found, as div.chevron.",
+                ),
+              was: z.string().describe("Its text as written when the note was written, cut short."),
+              text: z.string().nullable().describe("Its text as written now; null when not found."),
+              box: z
+                .strictObject({
+                  x: z.number(),
+                  y: z.number(),
+                  width: z.number(),
+                  height: z.number(),
+                })
+                .describe("On the slide in logical pixels, when the note was written."),
+              point: z
+                .strictObject({ x: z.number(), y: z.number() })
+                .optional()
+                .describe("Where the slide itself was clicked."),
+            }),
+          ),
+          changed: paths.describe("The slide's own files that changed since the note."),
+          shot: z.string().describe("The command that shows the slide at the note's beat."),
+          createdAt: z.string(),
+        }),
+      ),
+    }),
+    z.strictObject({ action: z.literal("clear"), cleared: z.number().int() }),
+  ]),
   sync: z.strictObject({ created: paths, updated: paths, removed: paths, kept: paths }),
   lint: z.strictObject({ diagnostics, skipped }),
   cues: z.strictObject({
@@ -342,6 +412,7 @@ export const RESULT_FIELDS = {
     credits: z.string().optional(),
   }),
   pdf: z.strictObject({ outs: paths }),
+  pptx: z.strictObject({ outs: paths }),
 } satisfies Record<ResultCommand, FieldsSchema>;
 
 type FieldsSchema = z.ZodObject | z.ZodUnion<readonly z.ZodObject[]>;

package/src/cli/files.ts

@@ -18,10 +18,10 @@ export function defaultToml(): string {
 }
 
 /**
- * What dek keeps for itself under .dek/ while it runs: the dev server's lock, and the marks left
- * while rehearsing. Neither belongs in the repository.
+ * What dek keeps for itself under .dek/ while it runs: the dev server's lock, the marks left
+ * while rehearsing, and the notes written in annotate mode. None belongs in the repository.
  */
-const LOCAL_STATE = [".dek/server.json", ".dek/marks.json"];
+const LOCAL_STATE = [".dek/server.json", ".dek/marks.json", ".dek/annotations.json"];
 
 export function defaultGitignore(): string {
   return `# dek

package/src/cli/flags.ts

@@ -89,7 +89,7 @@ export const FLAGS = {
   },
   public: {
     type: "boolean",
-    text: "a page for anyone with the link, without the script's stage directions and comments",
+    text: "for anyone the file reaches: the script without its stage directions and comments",
   },
 } as const satisfies Record<string, FlagSpec>;
 

package/src/cli/format.ts

@@ -141,6 +141,9 @@ function formatLiveEvent(event: LiveEvent, cwd: string | undefined): string | nu
       return event.diagnostics.length === 0 ? null : formatDiagnostics(event.diagnostics, { cwd });
     case "timeline":
       return "timeline";
+    // The page that changed them already shows it; the terminal has nothing to add.
+    case "annotations":
+      return null;
   }
 }
 

package/src/cli/pptx.ts

@@ -0,0 +1,20 @@
+import { pptxDeck } from "../core/pptx.ts";
+import type { DecksTarget } from "./scope.ts";
+
+/** One file per deck, a single deck included, as `dekc pdf` answers. */
+export type PptxCliResult = { outs: string[] };
+
+export async function pptxCommand(
+  { project, decks }: DecksTarget,
+  options: { rootDist?: boolean; public?: boolean } = {},
+): Promise<PptxCliResult> {
+  const outs: string[] = [];
+  for (const entry of decks) {
+    const done = await pptxDeck(
+      { project, deck: entry },
+      { rootDist: options.rootDist, public: options.public },
+    );
+    outs.push(done.outPath);
+  }
+  return { outs };
+}

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/cli/show.ts

@@ -1,7 +1,7 @@
 import { classifyAssetRef } from "../core/assets.ts";
 import { cssUrls, parseCss } from "../core/css.ts";
 import { deckPaths } from "../core/deck-paths.ts";
-import { scanSlideHtml } from "../core/html-scan.ts";
+import { type HtmlScan, scanSlideHtml } from "../core/html-scan.ts";
 import { sectionChunks, splitLines } from "../core/lines.ts";
 import { readDeckFile } from "../core/resolve.ts";
 import type { Section } from "../core/schema.ts";
@@ -24,7 +24,11 @@ export type ShowResult = {
   css: string | null;
   /** `slides/<slug>.ts`. */
   ts: string | null;
-  /** The rules of the deck's theme.css this slide uses; null when the deck has no theme.css. */
+  /**
+   * The rules of the deck's theme.css this slide uses, for the classes, layout, elements, and
+   * attributes its markup has; with a slide script, every element and attribute rule under
+   * `.slide`. Null when the deck has no theme.css.
+   */
   theme: string | null;
   /** Deck-relative paths of the files the slide references that exist. */
   assets: string[];
@@ -52,6 +56,8 @@ export function showCommand({ deck, ref }: ReadableDeck, slug: string): ShowResu
           classes: scan?.classes ?? [],
           ...(scan?.layout !== undefined ? { layout: scan.layout } : {}),
           ...(sheet ? { css: sheet } : {}),
+          // A slide script may add elements and attributes the markup lacks: keep their rules.
+          ...(scan && ts === null ? { markup: slideMarkup(scan) } : {}),
         });
 
   const refs = [
@@ -73,6 +79,15 @@ export function showCommand({ deck, ref }: ReadableDeck, slug: string): ShowResu
   };
 }
 
+/** The tags and attribute names of the slide and the elements inside it. */
+function slideMarkup(scan: HtmlScan): { tags: string[]; attributes: string[] } {
+  const elements = scan.elements.filter((element) => element.inSlide);
+  return {
+    tags: elements.map((element) => element.tag),
+    attributes: elements.flatMap((element) => element.attributes.map((attr) => attr.name)),
+  };
+}
+
 /**
  * Local references that name a file inside the deck, as sorted deck-relative
  * paths. theme.css and the slide's own files are left out: show returns them.

package/src/cli/text.ts

@@ -2,6 +2,7 @@
 // The pieces the dev server's log shares, such as diagnostics and tables, are in format.ts.
 import type { Diagnostic, SkippedCheck } from "../core/diagnostic.ts";
 import { formatClock } from "../core/timing.ts";
+import type { AnnotationsCliResult } from "./annotations.ts";
 import type { BuildCliResult } from "./build.ts";
 import type { CheckCliResult } from "./check.ts";
 import type { CuesResult } from "./cues.ts";
@@ -171,6 +172,41 @@ export function formatMarks(data: MarksCliResult): string {
     .join("\n");
 }
 
+/**
+ * Each note by its number, as the page's markers show it, with its slide and beat, each element
+ * at its line the way an editor jumps to it, the human's words, and the shot that shows it.
+ */
+export function formatAnnotations(data: AnnotationsCliResult): string {
+  if (data.action === "clear") {
+    return data.cleared === 1 ? "cleared 1 annotation" : `cleared ${data.cleared} annotations`;
+  }
+  if (data.annotations.length === 0) {
+    return "no annotations: press a on the dev server's page to point at an element and write a note";
+  }
+  return data.annotations
+    .flatMap((row) => {
+      const beat = row.step === "0" ? row.slug : `${row.slug} › ${row.step}`;
+      const status = row.status === "open" ? "" : ` (${row.status})`;
+      const targets = row.targets.map((target) => {
+        const where = `${target.path}:${target.line}:${target.column}`;
+        if (!target.found) {
+          return `   ${where}  ${target.name} (not found)`;
+        }
+        const text =
+          target.text === "" || target.text === null ? "" : ` ${JSON.stringify(target.text)}`;
+        const was = target.text !== target.was ? ` (was ${JSON.stringify(target.was)})` : "";
+        return `   ${where}  ${target.name}${text}${was}`;
+      });
+      const words = row.text
+        .trim()
+        .split(/\r?\n/)
+        .filter((line) => line.trim() !== "")
+        .map((line) => `   > ${line}`);
+      return [`${row.number}  ${beat}${status}`, ...targets, ...words, `   ${row.shot}`];
+    })
+    .join("\n");
+}
+
 /** The contact sheets when there are any, else each screenshot. */
 export function formatShot(data: ShotCliResult): string {
   return (data.sheets ?? data.shots.map((shot) => shot.path)).join("\n");
@@ -307,6 +343,13 @@ export function formatTheme(data: ThemeResult): string {
     "CLASSES",
     `  ${data.classes.join(" ")}`,
     "",
+    ...(data.stateClasses.length > 0
+      ? [
+          "STATE CLASSES (the player sets these; select them in CSS, never write them in markup)",
+          `  ${data.stateClasses.join(" ")}`,
+          "",
+        ]
+      : []),
     "TOKENS",
     ...data.tokens.map((token) => `  ${token.name.padEnd(width)}  ${token.value}`),
     "",

package/src/cli/theme.ts

@@ -9,7 +9,10 @@ import type { ReadableDeck, RefInfo } from "./scope.ts";
 export type ThemeResult = {
   /** The deck's theme.css: the one lint and the slides use. */
   path: string;
+  /** The classes slide markup may use; what `max_classes` counts. */
   classes: string[];
+  /** The state classes the theme selects that the player sets at runtime; never in markup. */
+  stateClasses: string[];
   /** The tokens every slide can `var()`. */
   tokens: CssToken[];
   layouts: ThemeLayout[];
@@ -28,10 +31,13 @@ export function themeCommand({ deck, ref }: ReadableDeck, name?: string): ThemeR
       hint: "copy the project theme.css into the deck, or run `dekc new <name>` for a fresh deck",
     });
   }
-  const { classes, layouts, tokens } = themeFacts(parseCss(readDeckFile(deck.dir, path) ?? ""));
+  const { classes, stateClasses, layouts, tokens } = themeFacts(
+    parseCss(readDeckFile(deck.dir, path) ?? ""),
+  );
   const result: ThemeResult = {
     path,
     classes: [...classes].sort(),
+    stateClasses: [...stateClasses].sort(),
     tokens,
     layouts,
     ...(ref ? { ref } : {}),