@hajimism/dek 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 Release notes for `@hajimism/dek`. From 0.1.0 on, release-please writes this file from the Conventional Commits on `main`.
 
+## [0.6.0](https://github.com/hajimism/dek/compare/v0.5.1...v0.6.0) (2026-11-07)
+
+
+### ⚠ BREAKING CHANGES
+
+* a skipped check can now be "plugin" in --json (ADR 31).
+
+### Features
+
+* let a plugin the user installed check a deck in dekc lint ([847822c](https://github.com/hajimism/dek/commit/847822cdfb34f4931c284b103007cb10d0dfc450))
+* **plugins:** lay dek-study's sheet over the slides ([8886efc](https://github.com/hajimism/dek/commit/8886efc9b8a0b9bd4bc47290574654e79be32368))
+* **plugins:** let a plugin keep data for the whole project in plugins/<name>/ ([84add8a](https://github.com/hajimism/dek/commit/84add8ab77918fdbfd60bfced6c18a103b1de0b1))
+* **plugins:** ship dek-study inside dek as its first official plugin ([96595d5](https://github.com/hajimism/dek/commit/96595d5f3996c597a1c47564a736ef0ca5ae9413))
+* **plugins:** ship dek-study inside dek, with a sheet of stickers over the slides ([855908c](https://github.com/hajimism/dek/commit/855908c03305aa8e8284c890bea0e19e25986994))
+* **plugins:** ship dek-words, a check for a project's word list ([9eff6d1](https://github.com/hajimism/dek/commit/9eff6d13cb2727b0f0cf1aa8bdc9595ee4d5c1c1))
+* **plugins:** ship dek-words, a check for a project's word list ([07d8f54](https://github.com/hajimism/dek/commit/07d8f54908ef8cd1e52cbf9cec5e576f929e55fb))
+* **plugins:** show a plugin's page in the player and builds behind page API 1 ([b815ef6](https://github.com/hajimism/dek/commit/b815ef625444c572a13af1a6e0ab0dddfbffcb22))
+
+## [0.5.1](https://github.com/hajimism/dek/compare/v0.5.0...v0.5.1) (2026-10-30)
+
+
+### Bug Fixes
+
+* **cli:** stop a dev server whose parent died before the server was up ([80b533f](https://github.com/hajimism/dek/commit/80b533fc691cfc104b6c83f7d99be4d73fc75c8d))
+* **dev:** say when the running server serves another deck only ([333ae06](https://github.com/hajimism/dek/commit/333ae06818fa8ad09f5ed492ae33148cce9254fd))
+* judge a command that skips its stdin by how it exits, not as one that cannot start ([103152c](https://github.com/hajimism/dek/commit/103152cd2132ba9c430ede4d7020844f7a8dcf9a))
+* **lint:** free no DEK013 class a skeleton or a slide script may use ([e32638b](https://github.com/hajimism/dek/commit/e32638b12220055d8a5a329b9e93f9eda47371e8))
+* **lint:** name the files a hint sends you to as paths from where the command ran ([5943dbe](https://github.com/hajimism/dek/commit/5943dbe1b11ac4529faae9cc1b98f22b4c63d214))
+* **lint:** name the files a hint sends you to as paths from where the command ran ([c5fcce3](https://github.com/hajimism/dek/commit/c5fcce3101061a6eaad55b27d94019f5b028e762))
+* **lint:** say how to stay within max_classes in DEK013 and DEK026 ([9c3078b](https://github.com/hajimism/dek/commit/9c3078bad4d93e5f381c99f5b6e0dd2c059f32dc))
+
+
+### Documentation
+
+* say that DEK035 leaves a deck that breaks by phrase to Chromium ([c21b428](https://github.com/hajimism/dek/commit/c21b4284db4a46a231778a4fa8d42aac38c46b0d))
+* say that DEK035 leaves a deck that breaks by phrase to Chromium ([dfef085](https://github.com/hajimism/dek/commit/dfef085bedf2d120c62a0f7418fd3d69f0a77001))
+
 ## [0.5.0](https://github.com/hajimism/dek/compare/v0.4.0...v0.5.0) (2026-10-27)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hajimism/dek",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A build system for talks.",
   "license": "MIT",
   "author": "Hajime Nakagawa (https://github.com/hajimism)",
@@ -8,6 +8,13 @@
   "bin": {
     "dekc": "src/cli.ts"
   },
+  "exports": {
+    "./plugin": {
+      "types": "./src/plugin-api.ts",
+      "default": "./src/plugin-api.ts"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "src",
     "skills",
@@ -61,12 +68,12 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.15",
-    "@happy-dom/global-registrator": "21.0.1",
+    "@biomejs/biome": "2.6.4",
+    "@happy-dom/global-registrator": "21.0.4",
     "@types/bun": "^1.4.2",
     "fast-check": "4.10.2",
-    "happy-dom": "21.0.1",
-    "knip": "6.41.0",
+    "happy-dom": "21.0.4",
+    "knip": "6.43.0",
     "playwright": "^1.63.0",
     "publint": "0.3.25",
     "typescript": "^7.0.2",

package/src/cli/address.ts

@@ -1,30 +1,49 @@
 import { existsSync, statSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
-import { shellName } from "../core/escape.ts";
+import { basename, dirname, join, relative } from "node:path";
+import { isPlainWord, shellName } from "../core/escape.ts";
 import { isInside } from "../core/path.ts";
 import { snapshotName } from "../core/ref.ts";
+import { isRefName } from "../core/ref-name.ts";
 import { type AnySpec, COMMANDS, subcommandsOf } from "./commands.ts";
 
 /** A deck a hint is about: the name a command takes, and the directory that makes it implicit. */
 export type HintDeck = { name: string; dir: string };
 
 /**
- * A hint's commands as they run from `cwd`. Hints are written as if run inside the deck they are
- * about, where a command finds its deck by itself. Run anywhere else, a command that takes a deck
- * needs its name: as the first word outside every deck, and as `--deck` inside another deck,
- * where a first word names something in that deck instead, or where the name would read as a
- * subcommand or a flag. The name is one shell word, however it is spelled, or `<deck>` when no
- * word holds it alike in every shell, with where to find it unless `note` is false, for a hint
- * that joins several and says it once. A command that already names a deck, or takes none, is
- * left as written.
+ * A hint as it reads from `cwd`. Hints are written as if read inside the deck they are about:
+ * its commands are addressed as `addressCommands` says, and the deck files it names become paths
+ * from `cwd`, as the path of the diagnostic beside it is, except in a ref.
  */
 export function addressHint(
   hint: string,
   deck: HintDeck | undefined,
   cwd: string,
+  options: { note?: boolean } = {},
+): string {
+  if (deck === undefined) {
+    return hint;
+  }
+  const addressed = addressCommands(hint, deck, cwd, options);
+  // A ref's files are its author's to fix, so a hint about one names them as the ref does.
+  return isRefName(deck.name) ? addressed : addressFiles(addressed, deck.dir, cwd);
+}
+
+/**
+ * A hint's commands as they run from `cwd`. Inside the deck they are about, a command finds its
+ * deck by itself. Run anywhere else, a command that takes a deck needs its name: as the first
+ * word outside every deck, and as `--deck` inside another deck, where a first word names
+ * something in that deck instead, or where the name would read as a subcommand or a flag. The
+ * name is one shell word, however it is spelled, or `<deck>` when no word holds it alike in every
+ * shell, with where to find it unless `note` is false, for a hint that joins several and says it
+ * once. A command that already names a deck, or takes none, is left as written.
+ */
+export function addressCommands(
+  hint: string,
+  deck: HintDeck,
+  cwd: string,
   { note: noted = true }: { note?: boolean } = {},
 ): string {
-  if (deck === undefined || isInside(cwd, deck.dir)) {
+  if (isInside(cwd, deck.dir)) {
     return hint;
   }
   const word = shellName(deck.name) ?? DECK_PLACEHOLDER;
@@ -80,6 +99,24 @@ export function deckFlag(name: string): string {
   return name.startsWith("-") ? `--deck=${word}` : `--deck ${word}`;
 }
 
+/**
+ * A deck file as a hint names it from the deck: a slide's own file, a voice file, theme.css, or
+ * script.md, or a project file reached with `../../`. Not part of a longer path or word. A path
+ * from `cwd` that is no plain word, through a folder a hint may not name, is left as written.
+ */
+const DECK_FILE_RE =
+  /(?<![\w./-])(\.\.\/\.\.\/[\w./-]*[\w-]|(?:slides|voice)\/[\w.-]*[\w-]|theme\.css|script\.md)(?![\w/-])/g;
+
+function addressFiles(hint: string, dir: string, cwd: string): string {
+  if (cwd === dir) {
+    return hint;
+  }
+  return hint.replace(DECK_FILE_RE, (file) => {
+    const path = relative(cwd, join(dir, file)) || ".";
+    return isPlainWord(path) ? path : file;
+  });
+}
+
 /** A backquoted command: `dekc`, a command word, and what follows it up to the closing quote. */
 const COMMAND_RE = /`dekc ([a-z]+)((?: [^`]*)?)`/g;
 

package/src/cli/build.ts

@@ -4,7 +4,7 @@ import { DekError } from "../core/error.ts";
 import { lintDeck, lintProject } from "../core/lint.ts";
 import { parsePublicUrl } from "../core/ogp.ts";
 import { PLAYWRIGHT_INSTALL, type PlaywrightRunner } from "../core/playwright.ts";
-import { playerScript } from "../runtime/player.ts";
+import { playerScript, pluginPageScripts } from "../runtime/player.ts";
 import { RENDERED_RULES, type SkippedCheck, skippedChecks, visualSkipped } from "./result.ts";
 import type { DecksTarget } from "./scope.ts";
 
@@ -47,12 +47,14 @@ export async function buildCommand(
     });
   }
   const script = await playerScript();
+  const pluginScripts = await pluginPageScripts();
   const results = await Promise.all(
     decks.map((entry) =>
       buildDeck(
         { project, deck: entry },
         {
           playerScript: script,
+          pluginScripts,
           rootDist: options.rootDist,
           ...(url ? { url } : {}),
           ...(options.public ? { public: true } : {}),

package/src/cli/commands.ts

@@ -1,4 +1,4 @@
-import { hasErrors } from "../core/diagnostic.ts";
+import { hasErrors, RULES } from "../core/diagnostic.ts";
 import { shellQuote } from "../core/escape.ts";
 import type { HiddenText } from "../core/foreign-text.ts";
 import { isRefName } from "../core/ref-name.ts";
@@ -27,6 +27,7 @@ import {
   formatNew,
   formatPack,
   formatPdf,
+  formatPluginNotes,
   formatPptx,
   formatRef,
   formatReport,
@@ -658,23 +659,31 @@ export const COMMANDS = {
   sync: result({
     scope: "decks",
     args: [],
-    flags: [],
-    usage: ["dekc sync [deck]"],
+    flags: ["accept"],
+    usage: ["dekc sync [deck] [--accept <plugin>]"],
     summary:
       "Create a skeleton for each section without slide HTML, refresh the skeletons\nnobody has edited since, and remove the ones whose section is gone.",
     group: "Slide",
-    overview: [["dekc sync", "create missing skeletons; refresh or drop the ones nobody edited"]],
+    overview: [
+      ["dekc sync", "create missing skeletons; refresh or drop the ones nobody edited"],
+      ["dekc sync --accept <plugin>", "pin a plugin whose manifest changed since its lock"],
+    ],
     agent: [
       "dekc sync            create missing skeletons; refresh or drop untouched ones; never edits your slides",
+      "dekc sync --accept <plugin>  pin a plugin's changed manifest, once the user has read the change",
     ],
-    run: async ({ target }) => {
+    run: async ({ target, flags }) => {
       const { syncCommand } = await import("./sync.ts");
-      return syncCommand(target);
+      return syncCommand(target, { accept: flags.accept });
     },
     output: {
       text: (data) => formatCreated(data.created, data.updated, data.removed),
-      notes: (data, color) => formatKept(data.kept, color) || undefined,
+      notes: (data, color) =>
+        [formatKept(data.kept, color), formatPluginNotes(data.plugins, color)]
+          .filter(Boolean)
+          .join("\n") || undefined,
       paths: (data, display) => ({
+        ...data,
         created: data.created.map(display),
         updated: data.updated.map(display),
         removed: data.removed.map(display),
@@ -703,14 +712,19 @@ export const COMMANDS = {
     output: {
       text: (data, color) => formatReport(data.diagnostics, { color }),
       notes: (data, color) => formatSkipped(data.skipped, color) || undefined,
-      json: ({ rumdlSarif: _rumdlSarif, ...data }) => data,
+      json: ({ rumdlSarif: _rumdlSarif, pluginSarif: _pluginSarif, ...data }) => data,
       paths: withDisplayDiagnostics,
       // The rerun measures what this run did: without --visual, the errors it found may not show.
       failure: (data, flags) =>
         diagnosticFailure("lint", data, flags.visual ? "dekc lint --visual" : "dekc lint"),
+      // dek's run holds its own rules; rumdl and each plugin have runs of their own.
       sarif: (data) => {
-        const dek = data.diagnostics.filter((diagnostic) => diagnostic.id.startsWith("DEK"));
-        return mergeSarif(toSarif(dek, { skipped: data.skipped ?? [] }), data.rumdlSarif);
+        const dek = data.diagnostics.filter((diagnostic) => Object.hasOwn(RULES, diagnostic.id));
+        return mergeSarif(
+          toSarif(dek, { skipped: data.skipped ?? [] }),
+          data.rumdlSarif,
+          data.pluginSarif,
+        );
       },
     },
   }),

package/src/cli/contract.ts

@@ -41,7 +41,8 @@ const Diagnostic = z
 
 const SkippedCheck = z
   .strictObject({
-    check: z.enum(["lint", "preview", "rumdl", "visual", "voice"]),
+    check: z.enum(["lint", "plugin", "preview", "rumdl", "visual", "voice"]),
+    plugin: z.string().optional().describe("For a plugin's check, its name in dek.toml [plugins]."),
     reason: z.string(),
     hint: z.string().optional().describe("What to do so that the check runs."),
   })
@@ -421,7 +422,32 @@ export const RESULT_FIELDS = {
     }),
     z.strictObject({ action: z.literal("clear"), cleared: z.number().int() }),
   ]),
-  sync: z.strictObject({ created: paths, updated: paths, removed: paths, kept: paths }),
+  sync: z.strictObject({
+    created: paths,
+    updated: paths,
+    removed: paths,
+    kept: paths,
+    plugins: z
+      .array(
+        z.strictObject({
+          name: z.string().describe("The plugin's name in dek.toml [plugins]."),
+          status: z
+            .enum(["accepted", "current", "changed", "missing", "invalid", "unsupported"])
+            .describe(
+              "accepted: pinned now; current: as pinned; changed: differs from its lock, which was left as it was; missing: not installed; invalid: printed no manifest dek can use; unsupported: needs a newer dek.",
+            ),
+          version: z.string().optional().describe("The installed plugin's version."),
+          changes: z
+            .array(z.string())
+            .optional()
+            .describe("For changed: what differs from the lock, one change each."),
+          reason: z.string().optional(),
+          hint: z.string().optional(),
+        }),
+      )
+      .optional()
+      .describe("Each plugin dek.toml names, in name order; absent when it names none."),
+  }),
   lint: z.strictObject({ diagnostics, skipped, unsandboxed }),
   cues: z.strictObject({
     name: z.string(),

package/src/cli/flags.ts

@@ -52,6 +52,11 @@ export const FLAGS = {
     note: "for JSON, pass --json",
     text: "print diagnostics as SARIF",
   },
+  accept: {
+    type: "string",
+    value: "PLUGIN",
+    text: "pin the installed plugin's manifest though it changed from plugins/<name>/plugin.json",
+  },
   before: { type: "string", value: "SLUG", text: "move the section before this one" },
   after: { type: "string", value: "SLUG", text: "move the section after this one" },
   step: { type: "string", value: "ID|N", text: "the beat to capture (default: the last)" },

package/src/cli/keep-alive.ts

@@ -7,6 +7,13 @@ const PARENT_POLL_MS = 1_000;
 /** How long a stop waits for the server to close before the process exits anyway. */
 const SHUTDOWN_GRACE_MS = 2_000;
 
+/**
+ * The process that started this one, read as the CLI loads. A parent read once the server is up
+ * would come too late: whoever waits for the URL can be killed before the next line runs, and the
+ * parent read then is already init, which never goes away.
+ */
+const startedBy = process.ppid;
+
 /**
  * Serve until told to stop: Ctrl-C, a kill, a closed terminal, or the process that started the
  * server going away, so a test run or an editor that dies without cleaning up leaves no server
@@ -51,16 +58,15 @@ export function stopOnce(
 }
 
 /**
- * Call `fn` once this process is reparented, which is how Unix says the parent died: a SIGKILL
- * leaves it no chance to stop its children. A process started with no parent of its own to lose
- * (already under init) is never orphaned.
+ * Call `fn` once this process is no longer under `parent`, the one that started it, which is how
+ * Unix says the parent died: a SIGKILL leaves it no chance to stop its children. A process started
+ * with no parent of its own to lose (already under init) is never orphaned.
  */
 export function onOrphaned(
   fn: () => void,
-  options: { ppid?: () => number; intervalMs?: number } = {},
+  options: { parent?: number; ppid?: () => number; intervalMs?: number } = {},
 ): () => void {
-  const ppid = options.ppid ?? (() => process.ppid);
-  const parent = ppid();
+  const { parent = startedBy, ppid = () => process.ppid } = options;
   const timer = setInterval(() => {
     if (ppid() !== parent) {
       clearInterval(timer);

package/src/cli/lint.ts

@@ -4,8 +4,9 @@ import type { Diagnostic } from "../core/diagnostic.ts";
 import { shellQuote } from "../core/escape.ts";
 import { lintDeck, lintProject, unreadableScriptDiagnostics } from "../core/lint.ts";
 import { playwrightMissingError } from "../core/playwright.ts";
+import { checkDeck, onProjectData, pluginChecks } from "../core/plugin-host.ts";
 import { type RumdlRunner, type RumdlSkip, resolveRumdlBin, runRumdl } from "../core/rumdl.ts";
-import { mergeSarif, type SarifLog } from "../core/sarif.ts";
+import { mergeSarif, pluginSarif, type SarifLog } from "../core/sarif.ts";
 import { syncDeck } from "../core/sync.ts";
 import { lintVisualDeck } from "../core/visual.ts";
 import { RENDERED_RULES, type SkippedCheck, skippedChecks, visualSkipped } from "./result.ts";
@@ -16,6 +17,8 @@ export type LintCliResult = {
   /** Checks that did not run, each with why and how to run it, so an empty list is not a pass. */
   skipped?: SkippedCheck[];
   rumdlSarif?: SarifLog;
+  /** A run per plugin that ran, for `--format sarif`. */
+  pluginSarif?: SarifLog;
 };
 
 /** `cwd` is where a skipped rumdl's hint says to run it from; `rumdl` runs it, dek's by default. */
@@ -32,6 +35,16 @@ export async function lintCommand(
   let rumdlSarif: SarifLog | undefined;
   // A rumdl that hung on one deck would hang on each, half a minute apiece.
   let rumdlHung = false;
+  // The plugins as the project accepted them; one that hung is run on no deck after, as rumdl.
+  const plugins = await pluginChecks(project);
+  diagnostics.push(...plugins.diagnostics);
+  const pluginRuns = plugins.ready.map((plugin) => ({
+    ...plugin,
+    diagnostics: [] as Diagnostic[],
+    hungOn: undefined as string | undefined,
+    skippedDecks: 0,
+    seen: new Set<string>(),
+  }));
 
   for (const deck of decks) {
     if (options.fix) {
@@ -50,6 +63,31 @@ export async function lintCommand(
         rumdlSarif = rumdlSarif ? mergeSarif(rumdlSarif, markdown.sarif) : markdown.sarif;
       }
     }
+    for (const plugin of pluginRuns) {
+      if (plugin.hungOn !== undefined) {
+        plugin.skippedDecks += 1;
+        continue;
+      }
+      const outcome = await checkDeck(plugin, project, deck);
+      // A finding on the project's data comes back from each deck; it is reported once (ADR 35).
+      const fresh = outcome.diagnostics.filter((finding) => {
+        if (!onProjectData(finding, project.root, plugin.name)) {
+          return true;
+        }
+        const { id, path, line, column, message } = finding;
+        const key = JSON.stringify([id, path, line, column, message]);
+        if (plugin.seen.has(key)) {
+          return false;
+        }
+        plugin.seen.add(key);
+        return true;
+      });
+      diagnostics.push(...fresh);
+      plugin.diagnostics.push(...fresh.filter(({ id }) => id !== "DEK046"));
+      if (outcome.hung) {
+        plugin.hungOn = deck.name;
+      }
+    }
     if (options.visual) {
       const visual = await lintVisualDeck({ project, deck });
       if (visual === null) {
@@ -63,6 +101,19 @@ export async function lintCommand(
     diagnostics,
     ...skippedChecks([
       ...(rumdlSkip ? [rumdlSkip] : []),
+      ...plugins.skipped,
+      ...pluginRuns.flatMap((plugin): SkippedCheck[] =>
+        plugin.skippedDecks > 0
+          ? [
+              {
+                check: "plugin",
+                plugin: plugin.name,
+                reason: `dek-${plugin.name} hung on ${plugin.hungOn}, so it ran on no deck after`,
+                hint: `tell the user: dek-${plugin.name} hangs, and its author can fix it`,
+              },
+            ]
+          : [],
+      ),
       ...(options.visual
         ? []
         : [
@@ -72,6 +123,7 @@ export async function lintCommand(
           ]),
     ]),
     ...(rumdlSarif ? { rumdlSarif } : {}),
+    ...(pluginRuns.length > 0 ? { pluginSarif: pluginSarif(pluginRuns) } : {}),
   };
 }
 

package/src/cli/main.ts

@@ -7,7 +7,7 @@ import { isRefName } from "../core/ref-name.ts";
 import { type ProjectDeck, readDeckFile, resolveProject } from "../core/resolve.ts";
 import { takeUnsandboxed } from "../core/sandbox.ts";
 import { themeFacts } from "../core/theme-facts.ts";
-import { addressHint, deckWord, type HintDeck, withPlaceholderNote } from "./address.ts";
+import { addressCommands, deckWord, type HintDeck, withPlaceholderNote } from "./address.ts";
 import {
   type AnySpec,
   type CliResult,
@@ -207,7 +207,7 @@ function retypedWithDeck<T>(line: CommandLine, cwd: string, call: Call, resolve:
     const decks = error.decks.filter((deck) => runsIn(call, deck));
     const [first] = decks;
     // Each command is retyped for one deck; where to find a name left as <deck> is said once.
-    const retyped = (deck: HintDeck) => addressHint(typed, deck, cwd, { note: false });
+    const retyped = (deck: HintDeck) => addressCommands(typed, deck, cwd, { note: false });
     const hint =
       error.decks.length === 0
         ? "run `dekc new <name>` to make a deck"

package/src/cli/sync.ts

@@ -1,22 +1,37 @@
 import { join } from "node:path";
+import { type PluginSync, syncPlugins } from "../core/plugin-host.ts";
 import { syncDeck } from "../core/sync.ts";
 import { ignoreLocalState } from "./files.ts";
 import type { DecksTarget } from "./scope.ts";
 
 /**
- * Every file the sync wrote or removed: the decks' slides, then dek's own files, then .gitignore
- * when it lacked what dek keeps for itself; and the slides it kept though their section is gone,
- * which lint reports as DEK002.
+ * Every file the sync wrote or removed: the plugins' locks, the decks' slides, then dek's own
+ * files, then .gitignore when it lacked what dek keeps for itself; the slides it kept though their
+ * section is gone, which lint reports as DEK002; and what it did with each plugin dek.toml names.
  */
 export type SyncCliResult = {
   created: string[];
   updated: string[];
   removed: string[];
   kept: string[];
+  plugins?: PluginSync[];
 };
 
-export function syncCommand({ project, decks }: DecksTarget): SyncCliResult {
-  const result: SyncCliResult = { created: [], updated: [], removed: [], kept: [] };
+/**
+ * `accept` names a plugin whose changed manifest to pin anyway. The plugins go first, so the
+ * AGENTS.md the decks' sync writes lists them as they now stand.
+ */
+export async function syncCommand(
+  { project, decks }: DecksTarget,
+  options: { accept?: string } = {},
+): Promise<SyncCliResult> {
+  const plugins = await syncPlugins(project, options);
+  const result: SyncCliResult = {
+    created: [...plugins.created],
+    updated: [...plugins.updated],
+    removed: [],
+    kept: [],
+  };
   const dek = { created: [] as string[], updated: [] as string[] };
   for (const deck of decks) {
     const synced = syncDeck({ project, deck });
@@ -33,5 +48,5 @@ export function syncCommand({ project, decks }: DecksTarget): SyncCliResult {
   if (ignoreLocalState(project.root)) {
     result.updated.push(join(project.root, ".gitignore"));
   }
-  return result;
+  return plugins.plugins.length > 0 ? { ...result, plugins: plugins.plugins } : result;
 }

package/src/cli/text.ts

@@ -1,9 +1,10 @@
 // How each command's result reads as text; commands.ts says which command prints which.
 // 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 { type Diagnostic, type SkippedCheck, skippedLabel } from "../core/diagnostic.ts";
 import { shellQuote } from "../core/escape.ts";
 import { foreignLine, type HiddenText, TITLE_MAX } from "../core/foreign-text.ts";
 import { compareCodeUnits } from "../core/order.ts";
+import type { PluginSync } from "../core/plugin-host.ts";
 import { unprinted } from "../core/prose.ts";
 import { packFile, parseRefSource } from "../core/ref-name.ts";
 import { formatClock } from "../core/timing.ts";
@@ -65,7 +66,7 @@ export function formatSkipped(skipped: SkippedCheck[] | undefined, color = false
   const c = ansi(color);
   return (skipped ?? [])
     .flatMap((entry) => [
-      `${entry.check}: skipped (${entry.reason})`,
+      `${skippedLabel(entry)}: skipped (${entry.reason})`,
       ...(entry.hint ? [`  ${c.yellow("help:")} ${entry.hint}`] : []),
     ])
     .join("\n");
@@ -118,6 +119,23 @@ export function formatKept(kept: string[], color = false): string {
     .join("\n");
 }
 
+/**
+ * The plugins sync could not pin as they are, for stderr: one whose manifest changed, with what
+ * changed, and one dek could not find or read, with why; a plugin pinned or current says nothing.
+ */
+export function formatPluginNotes(plugins: PluginSync[] | undefined, color = false): string {
+  const c = ansi(color);
+  return (plugins ?? [])
+    .filter(({ status }) => status !== "accepted" && status !== "current")
+    .flatMap((plugin) => [
+      plugin.status === "changed"
+        ? `plugin ${plugin.name} changed: ${(plugin.changes ?? [plugin.reason ?? ""]).join("; ")}`
+        : `plugin ${plugin.name}: ${plugin.reason ?? plugin.status}`,
+      ...(plugin.hint ? [`  ${c.yellow("help:")} ${plugin.hint}`] : []),
+    ])
+    .join("\n");
+}
+
 /**
  * A theme.css init kept that is no dekc theme, for stderr: every deck copies it, so each would fail
  * lint on its first run with a DEK015 per token.

package/src/cli/theme.ts

@@ -36,7 +36,7 @@ export function themeCommand({ deck, ref }: ReadableDeck, name?: string): ThemeR
   if (!existsSync(path)) {
     throw new DekError("theme.css not found", {
       path,
-      hint: "copy the project theme.css into the deck, or run `dekc new <name>` for a fresh deck",
+      hint: "copy the project's template, ../../theme.css, into the deck, or run `dekc new <name>` for a fresh deck",
     });
   }
   const css = readDeckFile(deck.dir, path) ?? "";

package/src/core/build.ts

@@ -4,6 +4,7 @@ import { loadConfig } from "./config.ts";
 import { renderDeckDocument } from "./document.ts";
 import { type DistOptions, distFile } from "./path.ts";
 import type { PlaywrightRunner } from "./playwright.ts";
+import { pluginPages } from "./plugin-host.ts";
 import { asResolvedDeck, type ResolvedDeck } from "./resolve.ts";
 import { removeInside, writeInside } from "./safe-fs.ts";
 import { coverShot } from "./shot/still.ts";
@@ -22,6 +23,8 @@ export type BuildResult = { outPath: string } & (
 
 export type BuildOptions = DistOptions & {
   playerScript: string;
+  /** The pages of the plugins dek ships, compiled, by name; a pinned one's goes into the page. */
+  pluginScripts?: Record<string, string>;
   /** Where dist/ is served from, ending in a slash; overrides `url` in dek.toml. */
   url?: string;
   /** For anyone with the link: the presenter view carries only what is said aloud. */
@@ -50,6 +53,7 @@ export async function buildDeck(
   }
   const html = renderDeckDocument(deck, {
     playerScript: options.playerScript,
+    plugins: pluginPages(project.root, deck.dir, options.pluginScripts ?? {}),
     target: {
       kind: "build",
       ...(options.public ? { public: true } : {}),

package/src/core/config-keys.ts

@@ -1,4 +1,5 @@
-import { DekToml, Pack, Voice } from "./config.ts";
+import { z } from "zod";
+import { DekToml, Pack, PluginTable, Voice } from "./config.ts";
 import { splitLines } from "./lines.ts";
 import { readFrontmatterYaml } from "./parse.ts";
 import { Frontmatter } from "./schema.ts";
@@ -9,10 +10,14 @@ import { unrecognizedKeys } from "./zod.ts";
 /** A key dek does not read, where it is, and the known key it most likely meant. */
 export type UnknownKey = { key: string; line: number; suggestion?: string };
 
-/** dek.toml's schema, but a key it does not read is an issue; `refs` still takes any key. */
+/**
+ * dek.toml's schema, but a key it does not read is an issue; `refs` and `plugins` still take any
+ * name, and a plugin's table, none of its own.
+ */
 const StrictDekToml = DekToml.extend({
   voice: Voice.strict().optional(),
   pack: Pack.strict().optional(),
+  plugins: z.record(z.string(), PluginTable.strict()).optional(),
 }).strict();
 
 /** Every key dek.toml may hold, as dotted paths. */