@hajimism/dek 0.5.1 → 0.6.1

package/src/core/plugin.ts

@@ -0,0 +1,442 @@
+import { z } from "zod";
+import { formatZodIssues } from "./zod.ts";
+
+/**
+ * A plugin is an executable `dek-<name>` the user installed. It prints a manifest of what it promises,
+ * which dek checks and the project pins in `plugins/<name>/plugin.json`, and it checks a deck in a
+ * process of its own, answering in SARIF. This file is the part with no I/O: what a manifest may
+ * say, the lock it is pinned in, and the words dek writes about it. See ADR 32.
+ */
+
+/** The manifest schema and check protocol this dek reads; a plugin that needs a newer one is skipped. */
+const MANIFEST_SCHEMA = 1;
+export const CHECK_PROTOCOL = 1;
+/** The page API this dek gives a plugin's page (ADR 33). */
+const PAGE_API = 1;
+
+/** The letters the player binds, which no plugin's page may take; a test reads them from the runtime. */
+export const DEK_KEYS: readonly string[] = ["a", "f", "l", "m", "p", "s"];
+
+const NAME_RE = /^[a-z][a-z0-9-]*$/;
+const NAME_MAX = 40;
+
+/** Names whose rule ids would read as another tool's: dek's own, and rumdl's MD rules. */
+const RESERVED_NAMES: Record<string, string> = {
+  dek: "DEK is the prefix of dek's own rules",
+  md: "MD is the prefix of rumdl's rules",
+};
+
+/** What is wrong with `name` as a plugin's, or undefined when it is one. */
+export function pluginNameProblem(name: string): string | undefined {
+  if (!NAME_RE.test(name) || name.length > NAME_MAX) {
+    return `a plugin's name is a lowercase letter, then lowercase letters, digits, and hyphens, at most ${NAME_MAX}`;
+  }
+  const reserved = RESERVED_NAMES[name];
+  return reserved === undefined ? undefined : `\`${name}\` is not a plugin's name: ${reserved}`;
+}
+
+/** The prefix of a plugin's rule ids: `acme-talks` checks ACME_TALKS001 and on. */
+export function rulePrefix(name: string): string {
+  return name.toUpperCase().replaceAll("-", "_");
+}
+
+/** A rule's summary: one line of fact, which dek shows only where a tool lists rules, as SARIF. */
+const SUMMARY_MAX = 120;
+const VERSION_RE = /^[0-9A-Za-z][0-9A-Za-z.+-]{0,63}$/;
+
+/** The first folders of a deck that are dek's, and the files at its top, in lowercase. */
+const DEK_DECK_ENTRIES = new Set(["script.md", "theme.css", "slides", "assets", "voice", "dist"]);
+
+const Rule = z.object({
+  severity: z.enum(["error", "warning"]),
+  summary: z
+    .string()
+    .min(1)
+    .max(SUMMARY_MAX)
+    // Control characters, and the line and paragraph separators, would end the line.
+    .refine((text) => !/[\p{Cc}\p{Zl}\p{Zp}]/u.test(text), "summary: one line"),
+});
+
+const Check = z.object({
+  protocol: z.literal(CHECK_PROTOCOL),
+  rules: z.record(z.string(), Rule),
+});
+
+/**
+ * A data file: a path in the deck, or, with `in: "project"`, in the plugin's own `plugins/<name>/`
+ * in the project (ADR 35).
+ */
+const Data = z.object({ path: z.string(), in: z.literal("project").optional() });
+
+/** A page in the player and the build. Its script is the plugin's to ship; this dek reads only these. */
+const Page = z.object({
+  api: z.literal(PAGE_API),
+  keys: z.array(z.string()).optional(),
+});
+
+/** A manifest as this dek reads it. Fields it does not know are dropped, never passed on. */
+const Manifest = z.object({
+  schema: z.literal(MANIFEST_SCHEMA),
+  name: z.string(),
+  version: z.string().regex(VERSION_RE, "version: one token of letters, digits, and . + -"),
+  check: Check.optional(),
+  page: Page.optional(),
+  data: z.array(Data).optional(),
+});
+
+export type PluginManifest = z.output<typeof Manifest>;
+type PluginRule = z.output<typeof Rule>;
+
+/** A manifest dek can use, or why not; `unsupported` when it asks for a newer dek. */
+export type ManifestReading =
+  | { ok: true; manifest: PluginManifest }
+  | { ok: false; reason: string; unsupported?: true };
+
+/**
+ * What `dek-<name> manifest` printed, checked: its shape and versions, that it names the plugin
+ * dek ran, that every rule id has the plugin's prefix, and that each data file is the deck's own
+ * and not dek's. Only what this dek knows is kept, so the lock pins what it can act on.
+ */
+export function readManifest(value: unknown, name: string): ManifestReading {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { ok: false, reason: "the manifest is not a JSON object" };
+  }
+  const fields = value as Record<string, unknown>;
+  if (above(fields.schema, MANIFEST_SCHEMA)) {
+    return newer(`manifest schema ${fields.schema}`);
+  }
+  const check = fields.check as Record<string, unknown> | undefined;
+  if (typeof check === "object" && check !== null && above(check.protocol, CHECK_PROTOCOL)) {
+    return newer(`check protocol ${check.protocol}`);
+  }
+  const page = fields.page as Record<string, unknown> | undefined;
+  if (typeof page === "object" && page !== null && above(page.api, PAGE_API)) {
+    return newer(`page API ${page.api}`);
+  }
+  const parsed = Manifest.safeParse(value);
+  if (!parsed.success) {
+    return { ok: false, reason: formatZodIssues(parsed.error) };
+  }
+  const manifest = parsed.data;
+  const problem =
+    (manifest.name === name
+      ? undefined
+      : `it names itself \`${manifest.name}\`, not \`${name}\``) ??
+    ruleProblem(manifest, name) ??
+    keyProblem(manifest) ??
+    dataProblem(manifest);
+  return problem === undefined
+    ? { ok: true, manifest: canonical(manifest) }
+    : { ok: false, reason: problem };
+}
+
+/** A version a later dek may read: a whole number past this dek's. Any other is malformed. */
+function above(version: unknown, supported: number): version is number {
+  return Number.isInteger(version) && (version as number) > supported;
+}
+
+function newer(what: string): ManifestReading {
+  return {
+    ok: false,
+    unsupported: true,
+    reason: `it needs ${what}; this dek reads manifest schema ${MANIFEST_SCHEMA}, check protocol ${CHECK_PROTOCOL}, and page API ${PAGE_API}`,
+  };
+}
+
+/** A page's keys are single lowercase letters, each once, none of them the player's. */
+function keyProblem(manifest: PluginManifest): string | undefined {
+  const keys = manifest.page?.keys ?? [];
+  const wrong = keys.find((key) => !/^[a-z]$/.test(key));
+  if (wrong !== undefined) {
+    return "page.keys: a key is one lowercase letter, a to z";
+  }
+  const taken = keys.find((key) => DEK_KEYS.includes(key));
+  if (taken !== undefined) {
+    return `page.keys: \`${taken}\` is a key of dek's player; take a letter other than ${DEK_KEYS.join(" ")}`;
+  }
+  const twice = keys.find((key, index) => keys.indexOf(key) !== index);
+  return twice === undefined ? undefined : `page.keys: \`${twice}\` is named twice`;
+}
+
+function ruleProblem(manifest: PluginManifest, name: string): string | undefined {
+  const prefix = rulePrefix(name);
+  const id = new RegExp(`^${prefix}\\d{3}$`);
+  const wrong = Object.keys(manifest.check?.rules ?? {}).find((rule) => !id.test(rule));
+  return wrong === undefined
+    ? undefined
+    : `check.rules: \`${wrong}\` is no rule id of this plugin's; write ${prefix} and three digits, like ${prefix}001`;
+}
+
+function dataProblem(manifest: PluginManifest): string | undefined {
+  const seen = new Set<string>();
+  for (const entry of manifest.data ?? []) {
+    const shown = dataPath(manifest.name, entry);
+    const problem = dataPathProblem(entry);
+    if (problem) {
+      return `data: \`${entry.path}\` ${problem}`;
+    }
+    if (seen.has(shown)) {
+      return `data: \`${shown}\` is named twice`;
+    }
+    seen.add(shown);
+  }
+  return undefined;
+}
+
+type DataEntry = NonNullable<PluginManifest["data"]>[number];
+
+/** A data file as an agent finds it: in the deck, or in the project when it is the project's. */
+function dataPath(name: string, entry: DataEntry): string {
+  return entry.in === "project" ? `plugins/${name}/${entry.path}` : entry.path;
+}
+
+/**
+ * A data file is a path inside its folder, `/`-separated, through no hidden folder. In a deck it
+ * is none of the files and folders dek reads or writes there; in `plugins/<name>/` it is not the
+ * lock.
+ */
+function dataPathProblem({ path, in: level }: DataEntry): string | undefined {
+  const folder = level === "project" ? "plugins/<name>/" : "the deck";
+  if (path === "" || path.startsWith("/") || path.includes("\\")) {
+    return `is not a path relative to ${folder}`;
+  }
+  const segments = path.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    return `is not a path inside ${folder}`;
+  }
+  if (segments.some((segment) => segment.startsWith("."))) {
+    return "is hidden, and dek reads no hidden file of a plugin's";
+  }
+  // A Mac's disk and Windows' take `Slides` for `slides`.
+  const first = (segments[0] ?? "").normalize("NFC").toLowerCase();
+  if (level === "project") {
+    return segments.length === 1 && first === "plugin.json" ? "is the plugin's lock" : undefined;
+  }
+  if (DEK_DECK_ENTRIES.has(first)) {
+    return "is dek's";
+  }
+  return undefined;
+}
+
+/** The manifest with its keys in one order, so the same promise is always the same lock. */
+function canonical(manifest: PluginManifest): PluginManifest {
+  const rules = manifest.check?.rules;
+  return {
+    schema: manifest.schema,
+    name: manifest.name,
+    version: manifest.version,
+    ...(manifest.check && rules
+      ? {
+          check: {
+            protocol: manifest.check.protocol,
+            rules: Object.fromEntries(
+              Object.keys(rules)
+                .sort()
+                .map((id) => {
+                  const rule = rules[id] as PluginRule;
+                  return [id, { severity: rule.severity, summary: rule.summary }];
+                }),
+            ),
+          },
+        }
+      : {}),
+    ...(manifest.page
+      ? { page: { api: manifest.page.api, keys: [...(manifest.page.keys ?? [])].sort() } }
+      : {}),
+    ...(manifest.data
+      ? {
+          data: manifest.data.map((entry) =>
+            entry.in === "project" ? { path: entry.path, in: entry.in } : { path: entry.path },
+          ),
+        }
+      : {}),
+  };
+}
+
+/** `plugins/<name>/plugin.json`: the manifest the project accepted, which is its lock. */
+export function lockText(manifest: PluginManifest): string {
+  return `${JSON.stringify({ accepted: canonical(manifest) }, null, 2)}\n`;
+}
+
+/** The manifest a lock pins, read as `manifest`'s output is, so a newer dek's fields are left out. */
+export function readLock(text: string, name: string): ManifestReading {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { ok: false, reason: "it is not JSON" };
+  }
+  const accepted =
+    typeof parsed === "object" && parsed !== null
+      ? (parsed as { accepted?: unknown }).accepted
+      : undefined;
+  if (accepted === undefined) {
+    return { ok: false, reason: "it has no `accepted` manifest" };
+  }
+  return readManifest(accepted, name);
+}
+
+/**
+ * What changed from the manifest the project accepted to the one installed, one line per change
+ * in dek's words: the version, each rule added, removed, or changed, and each data file.
+ */
+export function manifestChanges(accepted: PluginManifest, installed: PluginManifest): string[] {
+  const changes: string[] = [];
+  if (accepted.version !== installed.version) {
+    changes.push(`version ${accepted.version} → ${installed.version}`);
+  }
+  changes.push(...checkChanges(accepted.check, installed.check));
+  changes.push(...pageChanges(accepted.page, installed.page));
+  const paths = (manifest: PluginManifest) =>
+    new Set((manifest.data ?? []).map((entry) => dataPath(manifest.name, entry)));
+  const before = paths(accepted);
+  const after = paths(installed);
+  for (const path of before) {
+    if (!after.has(path)) {
+      changes.push(`data ${path} removed`);
+    }
+  }
+  for (const path of after) {
+    if (!before.has(path)) {
+      changes.push(`data ${path} added`);
+    }
+  }
+  return changes;
+}
+
+function pageChanges(
+  accepted: PluginManifest["page"],
+  installed: PluginManifest["page"],
+): string[] {
+  const keys = (page: PluginManifest["page"]) => (page?.keys ?? []).join(", ") || "none";
+  if (!accepted && !installed) {
+    return [];
+  }
+  if (!installed) {
+    return ["page removed"];
+  }
+  if (!accepted) {
+    return [`page added (keys ${keys(installed)})`];
+  }
+  return keys(accepted) === keys(installed)
+    ? []
+    : [`page keys ${keys(accepted)} → ${keys(installed)}`];
+}
+
+function checkChanges(
+  accepted: PluginManifest["check"],
+  installed: PluginManifest["check"],
+): string[] {
+  if (!accepted && !installed) {
+    return [];
+  }
+  if (!installed) {
+    return ["check removed"];
+  }
+  if (!accepted) {
+    const rules = Object.entries(installed.rules)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([id, rule]) => `${id} (${rule.severity})`);
+    return [`check added: ${rules.join(", ")}`];
+  }
+  const changes: string[] = [];
+  const ids = [
+    ...new Set([...Object.keys(accepted.rules), ...Object.keys(installed.rules)]),
+  ].sort();
+  for (const id of ids) {
+    const before = accepted.rules[id];
+    const after = installed.rules[id];
+    if (!after) {
+      changes.push(`${id} removed`);
+    } else if (!before) {
+      changes.push(`${id} added (${after.severity})`);
+    } else if (before.severity !== after.severity) {
+      changes.push(`${id} ${before.severity} → ${after.severity}`);
+    } else if (before.summary !== after.summary) {
+      changes.push(`${id} summary changed`);
+    }
+  }
+  return changes;
+}
+
+/**
+ * A plugin dek.toml names, with the manifest its lock pins when it has one, and dek's own page on
+ * how to write its data when dek ships it.
+ */
+export type PinnedPlugin = { name: string; manifest: PluginManifest | undefined; guide?: string };
+
+/**
+ * The plugins in AGENTS.md: one line each, made from the lock and never from the executable, so
+ * every sync writes the same block, the dev server's included. Each line is dek's words about
+ * checked fields; the plugin's own summaries stay out. A data file says whether it is the
+ * project's or each deck's, since the two can share a name. Empty when dek.toml names no plugin.
+ */
+export function pluginsSection(plugins: PinnedPlugin[]): string {
+  if (plugins.length === 0) {
+    return "";
+  }
+  const lines = plugins.map(({ name, manifest, guide }) => {
+    if (!manifest) {
+      return `- \`${name}\`: not pinned yet; \`dekc sync\` pins it.`;
+    }
+    const facts = [
+      ...(manifest.check ? [`It checks ${ruleList(Object.keys(manifest.check.rules))}.`] : []),
+      ...(manifest.data && manifest.data.length > 0
+        ? [
+            `Its data: ${projectFirst(manifest.data)
+              .map(
+                (entry) =>
+                  `\`${dataPath(name, entry)}\` ${entry.in === "project" ? "in the project" : "in each deck"}`,
+              )
+              .join(", ")}.`,
+          ]
+        : []),
+      ...(manifest.page?.keys && manifest.page.keys.length > 0
+        ? [
+            `Its page takes the ${manifest.page.keys.length === 1 ? "key" : "keys"} ${manifest.page.keys.map((key) => `\`${key}\``).join(", ")}.`,
+          ]
+        : []),
+      ...(guide && manifest.data && manifest.data.length > 0 ? [`How to write it: ${guide}`] : []),
+    ];
+    return `- \`${name}\` ${manifest.version}${facts.length > 0 ? `: ${facts.join(" ")}` : ""}`;
+  });
+  return `
+## Plugins
+
+Checks installed beside dek, named in \`dek.toml\` \`[plugins]\` and pinned in \`plugins/<name>/plugin.json\`. \`dekc lint\` runs them with dek's own rules, and \`dekc check <slug>\` reports what they find on that slide; their findings carry the plugin's rule ids.
+
+${lines.join("\n")}
+`;
+}
+
+/** The project's data files, then the deck's, each in the order the manifest gave them. */
+function projectFirst(data: DataEntry[]): DataEntry[] {
+  return [...data.filter((entry) => entry.in === "project"), ...data.filter((e) => !e.in)];
+}
+
+function ruleList(ids: string[]): string {
+  const sorted = [...ids].sort();
+  if (sorted.length === 0) {
+    return "no rules";
+  }
+  if (sorted.length === 1) {
+    return sorted[0] as string;
+  }
+  if (sorted.length === 2) {
+    return `${sorted[0]} and ${sorted[1]}`;
+  }
+  const numbers = sorted.map((id) => Number(id.slice(-3)));
+  const contiguous = numbers.every((n, i) => i === 0 || n === (numbers[i - 1] as number) + 1);
+  return contiguous ? `${sorted[0]} to ${sorted.at(-1)}` : sorted.join(", ");
+}
+
+/**
+ * A plugin's page as the player and the build carry it: its script, the keys its manifest
+ * declares, and each declared data file the deck has, with a version that changes with the text.
+ */
+export type PluginPage = {
+  name: string;
+  keys: string[];
+  script: string;
+  data: Record<string, { text: string; version: string }>;
+};

package/src/core/sarif.ts

@@ -1,6 +1,13 @@
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { type Diagnostic, type DiagnosticValue, RULES, type SkippedCheck } from "./diagnostic.ts";
+import {
+  type Diagnostic,
+  type DiagnosticValue,
+  RULES,
+  type SkippedCheck,
+  skippedLabel,
+} from "./diagnostic.ts";
+import type { PluginManifest } from "./plugin.ts";
 
 type SarifLevel = "error" | "warning" | "note" | "none";
 
@@ -11,8 +18,14 @@ export type SarifLog = {
     tool: {
       driver: {
         name: string;
+        version?: string;
         informationUri?: string;
-        rules?: Array<{ id: string; defaultConfiguration: { level: SarifLevel }; helpUri: string }>;
+        rules?: Array<{
+          id: string;
+          shortDescription?: { text: string };
+          defaultConfiguration: { level: SarifLevel };
+          helpUri?: string;
+        }>;
       };
     };
     invocations?: Array<{
@@ -74,10 +87,11 @@ export function toSarif(
                   executionSuccessful: true,
                   toolExecutionNotifications: skipped.map((entry) => ({
                     level: "warning" as const,
-                    message: { text: `${entry.check}: skipped (${entry.reason})` },
+                    message: { text: `${skippedLabel(entry)}: skipped (${entry.reason})` },
                     descriptor: { id: `skipped/${entry.check}` },
                     properties: {
                       check: entry.check,
+                      ...(entry.plugin === undefined ? {} : { plugin: entry.plugin }),
                       ...(entry.hint === undefined ? {} : { hint: entry.hint }),
                     },
                   })),
@@ -91,6 +105,33 @@ export function toSarif(
   };
 }
 
+/**
+ * Each plugin's findings as a run of its own, under the plugin's name and version, with the rules
+ * its accepted manifest declares. A plugin that found nothing still has its run: it ran.
+ */
+export function pluginSarif(
+  plugins: Array<{ name: string; manifest: PluginManifest; diagnostics: Diagnostic[] }>,
+): SarifLog {
+  return {
+    version: "2.1.0",
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    runs: plugins.map(({ name, manifest, diagnostics }) => ({
+      tool: {
+        driver: {
+          name: `dek-${name}`,
+          version: manifest.version,
+          rules: Object.entries(manifest.check?.rules ?? {}).map(([id, rule]) => ({
+            id,
+            shortDescription: { text: rule.summary },
+            defaultConfiguration: { level: rule.severity },
+          })),
+        },
+      },
+      results: diagnostics.map(sarifResult),
+    })),
+  };
+}
+
 function sarifResult(diagnostic: Diagnostic): SarifLog["runs"][number]["results"][number] {
   const properties = {
     ...(diagnostic.slug === undefined ? {} : { slug: diagnostic.slug }),
@@ -126,10 +167,11 @@ function sarifResult(diagnostic: Diagnostic): SarifLog["runs"][number]["results"
   };
 }
 
-export function mergeSarif(dek: SarifLog, rumdl?: SarifLog): SarifLog {
+/** One log of every run in `dek` and the logs after it, such as rumdl's and the plugins'. */
+export function mergeSarif(dek: SarifLog, ...others: Array<SarifLog | undefined>): SarifLog {
   return {
     version: "2.1.0",
     $schema: dek.$schema,
-    runs: [...dek.runs, ...(rumdl?.runs ?? [])],
+    runs: [...dek.runs, ...others.flatMap((log) => log?.runs ?? [])],
   };
 }

package/src/core/script-lines.ts

@@ -51,3 +51,14 @@ function commentOpenAfter(text: string, open: boolean): boolean {
   }
   return inside;
 }
+
+/**
+ * The slide a line of script.md belongs to: the `##` section it is in, heading included. Above the
+ * first heading it belongs to the deck, and to no slide.
+ */
+export function slugAtLine(
+  sections: ReadonlyArray<{ line: number; slug: string }>,
+  line: number,
+): string | undefined {
+  return sections.filter((section) => section.line <= line).at(-1)?.slug;
+}

package/src/core/sync.ts

@@ -3,6 +3,8 @@ import { join } from "node:path";
 import { loadConfig } from "./config.ts";
 import { type DeckPaths, deckPaths } from "./deck-paths.ts";
 import { foreignLine, TITLE_MAX } from "./foreign-text.ts";
+import { pluginsSection } from "./plugin.ts";
+import { pinnedPlugins } from "./plugin-host.ts";
 import { parseRefSource, refDir, refTitle } from "./ref.ts";
 import { asResolvedDeck, listSlides, type ResolvedDeck, SLIDE_SIDECARS } from "./resolve.ts";
 import { outputDir, readSourceIfExists, removeInside, writeInside } from "./safe-fs.ts";
@@ -286,10 +288,10 @@ A build system for talks. Write what you will say; dek builds, measures, and shi
 
 ## Before you report a deck as done
 
-- \`dekc lint --visual\` passes.
+- \`dekc lint --visual\` passes. Warnings do not fail it: fix each one, or tell the author which you kept and why.
 - You have read \`dekc shot --sheet\` and judged the deck's balance.
 - Say what you could not judge, such as the argument and the timing, and leave it to the author.
-${referencesSection(root)}
+${referencesSection(root)}${pluginsSection(pinnedPlugins(root))}
 For commands, run \`dekc help --agent\`.
 `;
 }

package/src/plugin-api.ts

@@ -0,0 +1,126 @@
+/// <reference lib="dom" />
+
+/**
+ * The types a dek plugin is written against, published as `@hajimism/dek/plugin` (ADR 32). They
+ * are types only: a plugin runs in a process of its own and shares no code with dek, only these
+ * shapes, which travel as JSON. Each grows only by adding; a change to one is a new `schema` or
+ * `protocol`.
+ */
+
+export type Severity = "error" | "warning";
+
+/** One rule a check can report. Only `error` fails `dekc lint`. */
+export type PluginRule = {
+  severity: Severity;
+  /** One line of fact, at most 120 characters; dek shows it only in SARIF's rule list. */
+  summary: string;
+};
+
+/** A plugin's rules by id: `<PREFIX>` and three digits, the prefix the name in capitals with `_` for `-`. */
+export type PluginRules<Prefix extends string = string> = Record<`${Prefix}${number}`, PluginRule>;
+
+/** What `dek-<name> manifest` prints: the promise the project pins in `plugins/<name>/plugin.json`. */
+export type PluginManifest<Prefix extends string = string> = {
+  schema: 1;
+  /** The `<name>` of `dek-<name>`. */
+  name: string;
+  /** Letters, digits, `.`, `+`, and `-`, at most 64 characters. */
+  version: string;
+  /** Without it, dek runs no check. */
+  check?: { protocol: 1; rules: PluginRules<Prefix> };
+  /** A page in the player and the build, which calls `dek.plugin` (page API 1). */
+  page?: {
+    api: 1;
+    /** Single letters the page binds; none of dek's own (a f l m p s). */
+    keys?: string[];
+  };
+  /**
+   * Files the plugin reads, which AGENTS.md names: relative to the deck's folder, or, with
+   * `in: "project"`, to `plugins/<name>/` in the project, for data the whole project shares. Only
+   * the deck's are served to a page.
+   */
+  data?: Array<{ path: string; in?: "project" }>;
+};
+
+/** One slide of the deck, as `check` reads it. Each path is relative to the deck's folder, or null when the file is not there. */
+export type CheckSlide = {
+  slug: string;
+  title: string;
+  html: string | null;
+  css: string | null;
+  ts: string | null;
+};
+
+/** What `dek-<name> check --protocol 1` reads on stdin, run in the deck's folder. */
+export type CheckInput = {
+  protocol: 1;
+  /** The version of the dek that runs the check. */
+  dek: string;
+  deck: { name: string; lang: string; slides: CheckSlide[] };
+  /**
+   * The absolute path of `plugins/<name>/` in the project, where the project's data files are,
+   * whether or not the folder exists (ADR 35). An older dek does not send it: read that as no
+   * project data.
+   */
+  pluginDir?: string;
+};
+
+/** One finding in a check's SARIF: the fields dek reads, and no others. */
+export type CheckResult<RuleId extends string = string> = {
+  /** A rule the manifest declares; its severity is the manifest's, whatever `level` says. */
+  ruleId: RuleId;
+  message: { text: string };
+  locations?: Array<{
+    physicalLocation: {
+      /**
+       * Relative to the deck's folder, or a `file:` URL inside it or inside `pluginDir`. dek drops
+       * a location anywhere else.
+       */
+      artifactLocation: { uri: string };
+      region?: { startLine: number; startColumn?: number };
+    };
+  }>;
+  /** What to do next. */
+  properties?: { hint?: string };
+};
+
+/** What `dek-<name> check` prints on stdout: SARIF 2.1.0, of which dek reads each run's results. */
+export type CheckOutput<RuleId extends string = string> = {
+  version: "2.1.0";
+  $schema?: string;
+  runs: Array<{
+    tool?: { driver: { name: string; version?: string } };
+    results: Array<CheckResult<RuleId>>;
+  }>;
+};
+
+/** Where the deck stands: the slide, its index, and the beat (0 is the slide's arrival). */
+export type PagePosition = { slug: string; index: number; beat: number };
+
+/**
+ * A slide drawn on the stage, for a page to draw over. `root` is the slide, to read and never to
+ * change: lint checked what is in it. `layer` lies over the slide, in the slide's own pixels, and
+ * is the plugin's alone. A slide a live reload replaced is mounted again.
+ */
+export type PageMount = { slug: string; root: HTMLElement; layer: ShadowRoot; view: "stage" };
+
+/** What `dek.plugin` hands a plugin's page: page API 1. */
+export type PageApi = {
+  deck: { name: string };
+  slides: Array<{ slug: string; title: string }>;
+  current(): PagePosition;
+  /** After the deck settles at a position, at the start and after every move, wherever it came from. */
+  on(event: "change", listener: (position: PagePosition) => void): void;
+  on(event: "mount", listener: (mount: PageMount) => void): void;
+  /** Whether `element` shows at the current beat: no beat that hides it is still to come. */
+  shown(element: Element): boolean;
+  /** A data file the manifest declares, as the project has it; `version` changes with the text. */
+  data(path: string): { text: string; version: string } | null;
+  /** Binds a key the manifest declares; false for any other. */
+  key(letter: string, listener: () => void): boolean;
+};
+
+/** The one global a plugin's page touches. */
+export type DekPage = {
+  plugin(name: string, options: { api: 1 }, setup: (api: PageApi) => void): void;
+};