@hajimism/dek 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 Release notes for `@hajimism/dek`. From 0.1.0 on, release-please writes this file from the Conventional Commits on `main`.
 
+## [0.4.0](https://github.com/hajimism/dek/compare/v0.3.4...v0.4.0) (2026-10-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* **theme:** `dekc theme --json` lists in `layouts` only layouts whose names are plain words: letters, marks, and digits of any script and `@%+=:,./_-`, not starting with `=`. A layout whose name holds anything else, such as a space, a quote, `$`, `;`, or a backtick, is no longer in `layouts`; `unprintedLayouts`, present only when there are some, says how many were left out. `dekc theme <layout>` still prints such a layout's example.
+* **ref:** a dek.toml whose [refs] pins a deck name with any other character, starting with a dash, not in NFC, or longer than 64 characters or 200 bytes, such as `owner/repo/talk(1)` or `file/a+b`, no longer loads. Delete the line the error points at, and for a pack its packs/<deck>.tgz and refs/file/<deck>, then pin the deck again under a name a ref can carry.
+
+### Bug Fixes
+
+* **annotations:** show a deck, slide, or beat that is no plain word as a placeholder in the notes ([3b04e89](https://github.com/hajimism/dek/commit/3b04e89dc22f9ea421919c920594f53a9c02d3be))
+* **cli:** say once where to find a deck's name a retyped command leaves as &lt;deck&gt; ([d4a57d9](https://github.com/hajimism/dek/commit/d4a57d9f7836b2ba2433dc634a136bb7e97be509))
+* **config:** show a key that is no plain word as &lt;key&gt; in an error ([22476a7](https://github.com/hajimism/dek/commit/22476a712ecf0ee4e3c552b1e0fe6f35ac10cacf))
+* **dev:** read .dek/server.json only as the dev server writes it ([c402cb6](https://github.com/hajimism/dek/commit/c402cb6282783425611274fbc0337cd6652add7e))
+* **dev:** read the lock a dev server on port 80 writes ([665e0e2](https://github.com/hajimism/dek/commit/665e0e237c3a639a45fa36dc14ed8bd2e7ad9168))
+* keep reads, writes, and suggested commands inside what the project and dek wrote ([23a667d](https://github.com/hajimism/dek/commit/23a667d199ee5f0b34040c4c33f0c0bcfd47f819))
+* **lint:** name a remote file in DEK020's hint only when it is a plain word ([fb77d02](https://github.com/hajimism/dek/commit/fb77d028db1bb38bea6b43695838d52776b192a7))
+* **lint:** name a slide or asset file in a hint only when it is a plain word ([eeb240c](https://github.com/hajimism/dek/commit/eeb240c418b615067bd66ff45ac6b70361d3bd1b))
+* **lint:** show an unknown key that is no plain word as &lt;key&gt; in DEK008 ([f950def](https://github.com/hajimism/dek/commit/f950def7f80f06da46bd8c913ae84c8c849d5ddf))
+* never follow a link under refs/ when writing a snapshot ([0c843ea](https://github.com/hajimism/dek/commit/0c843ea4193270dd1cc0fde4a04768e210efd911))
+* never write or remove a pack's copy through a link under packs/ ([95980a6](https://github.com/hajimism/dek/commit/95980a631e90ee97eda24784ded50b042111512d))
+* quote every name in a command dek suggests ([d1e608d](https://github.com/hajimism/dek/commit/d1e608d5676e46b7947bd5f43a3315269fd27773))
+* read a project's files only through links that stay inside it ([7ae3815](https://github.com/hajimism/dek/commit/7ae38152eadd6f58d67034169ade9dd749038002))
+* **ref:** accept only letters, digits, dots, dashes, and underscores in a ref's deck name ([1b430e1](https://github.com/hajimism/dek/commit/1b430e1ea3d0f66af2642a5f257af1cefcae3ac0))
+* **ref:** fold names as macOS does when telling whether two refs share a folder ([fdb32ee](https://github.com/hajimism/dek/commit/fdb32ee103facc5a661f20dabf79fe8f91ae48cd))
+* **ref:** refuse a pin whose folders another ref already takes ([0d550d8](https://github.com/hajimism/dek/commit/0d550d897b0cdad86ac3de181bf7fd031061bd66))
+* refuse a decks folder that links out of the project ([83f2ff0](https://github.com/hajimism/dek/commit/83f2ff00079893b8e2dbb2fc5d5b7588435aa4dd))
+* refuse to serve or write inside a ref, as every other command does ([665b2de](https://github.com/hajimism/dek/commit/665b2de7a3e6aa3b67ce6140d3eb2a15fb398ee6))
+* serve a deck's assets only from inside the project ([86743cf](https://github.com/hajimism/dek/commit/86743cf731d97f664e95b75f1441dd238f0eeb11))
+* take a folder for a ref only where dek wrote one, and name it from there ([62cc8df](https://github.com/hajimism/dek/commit/62cc8df0a509a99a55d9db7698683bc3be5523d4))
+* **theme:** leave layouts whose names are no plain word out of --json ([625f6d3](https://github.com/hajimism/dek/commit/625f6d3dab0dfe16dacb272e371b551214621a86))
+* **theme:** print only layout names that are plain words ([62b15d1](https://github.com/hajimism/dek/commit/62b15d18afb91d6adbc2641376d9ca899cb6bf20))
+
+
+### Documentation
+
+* say dek follows no link under packs/ either ([5a11b2c](https://github.com/hajimism/dek/commit/5a11b2ca9960a134e261f09f80408fc770aa44da))
+
+## [0.3.4](https://github.com/hajimism/dek/compare/v0.3.3...v0.3.4) (2026-10-27)
+
+
+### Features
+
+* **pptx:** lay out boxes, pictures, text, the theme, and backgrounds as PowerPoint's own ([#27](https://github.com/hajimism/dek/issues/27)) ([eb854e9](https://github.com/hajimism/dek/commit/eb854e9835508792d3e8cfb9dd4046e8750dab7f))
+* **skills:** teach the review in the browser, and add an optional dek-design skill ([2c18b0e](https://github.com/hajimism/dek/commit/2c18b0e339160fb03ca6ce3915b89e37d82c9522))
+* **skills:** teach the review in the browser, and add an optional dek-design skill ([1b04394](https://github.com/hajimism/dek/commit/1b04394023a239706a2fa29d168811e1a1be05d2))
+* **visual:** report awkward line breaks and edges a few pixels off (DEK035, DEK036) ([#28](https://github.com/hajimism/dek/issues/28)) ([ce75fc1](https://github.com/hajimism/dek/commit/ce75fc14937d76ab457298a5aca9116a0fe3778e))
+
+
+### Bug Fixes
+
+* refuse a slide script's imports before Bun reads it, so none runs while dek compiles ([2752356](https://github.com/hajimism/dek/commit/275235647869f1e0a040c080476141d3aaa1aaa6))
+* refuse a slide script's imports before Bun reads it, so none runs while dek compiles ([198930c](https://github.com/hajimism/dek/commit/198930c1d41639cc9943f36a3a187ff6eab0f364))
+
+
+### Documentation
+
+* **adr:** keep dependency code away from the tokens that publish ([103f17c](https://github.com/hajimism/dek/commit/103f17cebb37dd1750caa4cc242acedf55703809))
+* **adr:** renumber the PPTX records after the line-break ones ([ca43352](https://github.com/hajimism/dek/commit/ca4335267b6eeed7131c4123a8a543a230d65875))
+* **adr:** renumber the PPTX records after the line-break ones ([bef6e12](https://github.com/hajimism/dek/commit/bef6e12915ac301843297fb972cf36288bbf612c))
+* **adr:** ship an optional design skill and raise the official skill's floor to 0.2.2 ([6f39dd1](https://github.com/hajimism/dek/commit/6f39dd1e8234297cb0fb72d93722a419d1921f23))
+* name the optional dek-design skill, and the review the official skill teaches ([6908fa1](https://github.com/hajimism/dek/commit/6908fa195e16d79c75d5b77cda72f708798de34c))
+
 ## [0.3.3](https://github.com/hajimism/dek/compare/v0.3.2...v0.3.3) (2026-10-21)
 
 

package/README.ja.md

@@ -44,7 +44,7 @@ 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)を参照してください。
+エージェントと作るなら、公式スキルを `npx skills add hajimism/dek --skill dek` で、Claude Code なら `/plugin marketplace add hajimism/dek` と `/plugin install dek@dek` で入れてください。`dek-design` も、同じ方法で選んで入れられます。プロジェクトの外にいるエージェントは [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

@@ -44,7 +44,7 @@ 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).
+Working with an agent? Install the official skill with `npx skills add hajimism/dek --skill dek`, or in Claude Code with `/plugin marketplace add hajimism/dek` and `/plugin install dek@dek`; `dek-design` is an optional skill installed the same way; 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).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hajimism/dek",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "A build system for talks.",
   "license": "MIT",
   "author": "Hajime Nakagawa (https://github.com/hajimism)",
@@ -67,6 +67,7 @@
     "happy-dom": "21.0.1",
     "knip": "6.41.0",
     "playwright": "^1.63.0",
+    "publint": "0.3.25",
     "typescript": "^7.0.2",
     "vitepress": "^1.6.4"
   },

package/skills/dek/SKILL.md

@@ -16,7 +16,7 @@ dek builds a talk from its script. `script.md` holds what will be said, in order
 
 ## 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.
+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. It is written for dek 0.2.2 or newer; with an older one, follow only that list and `AGENTS.md`.
 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.
 
@@ -39,6 +39,13 @@ A hint that sends a fix to `theme.css` means every slide of the deck shares the
 - 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
+## When the human reviews the deck
 
-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.
+The human sees what lint cannot. Let them point at it:
+
+1. Start the dev server in the background, since it keeps running: `bunx dekc <deck> --port <free port>`, or your harness's preview tool if it has one.
+2. Give them the URL and ask them to press `a`, click what they want changed, write a note, and tell you when they are done. They may not know dek: name the keys, not the commands.
+3. `bunx dekc annotations <deck> --json`, and fix every note. Shoot the slide again with `bunx dekc shot <slug>` and compare it with the note's `shot`. Tell them in short what you changed.
+4. Ask them to look again, until they say the deck is done. Stop the dev server you started.
+
+Leave `dekc annotations clear` to the human. If they marked beats while rehearsing, `AGENTS.md` says how to read those too.

package/skills/dek-design/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: dek-design
+description: Make dek slides that read at a glance - a heading that states a claim, one focal point, and no visual difference without a meaning. Use when writing or reviewing the look of slides in a dek deck, or when a deck lints clean but still looks off.
+---
+
+# dek-design
+
+The audience sees a slide, holds it in mind, then understands it. Make each step cost as little as it can. Lint measures what a rule can decide, such as overflow and contrast; this skill is for what it cannot. Use only the classes, tokens, and layouts `bunx dekc theme` lists.
+
+## Before you start
+
+- Projected or read: a talk is spoken, so the words live in `script.md` and a slide shows what the voice cannot. A deck sent to be read alone needs sentences that stand without the speaker.
+- What the audience knows: do not use a term they do not know. If you must, tie it to something they do.
+
+## One slide
+
+- The `##` heading is the slide's claim, in one sentence: "Builds fail on cold caches", not "Problems". Read in order, the headings tell the whole talk.
+- The body is the evidence for the heading. Show it as a figure, a chart, or a short table where you can.
+- Keep about four groups on a slide at most. With more, nest them or split the slide.
+
+## How it looks
+
+- One thing stands out most on each slide, and it is the main point. Emphasis used everywhere is emphasis nowhere.
+- Change color, type, or layout only when the meaning changes; the audience looks for a reason in every change, so never vary for variety. Mark sections with one layout used the same way each time.
+- When things differ, make them differ clearly. A small difference is not seen as one.
+- Line things up. Items side by side share their top, their bottom, and the line their text starts on; a row of cards is one height even when one holds less. Items stacked share their left edge. An edge a little off reads as a mistake, not a choice, and a shot shows it where markup does not.
+- What sits close, aligns, or shares a color reads as one group. Do not set items of different rank as a row of equal cards.
+- Position means something: time and steps run left to right, more or better goes up, the general sits above the specific. A person or anything with a direction faces into the slide or toward what it points at.
+- The eye goes from the heading at top left, to the body in the middle, to the conclusion or next step at bottom right.
+
+## Charts
+
+- A line for a trend, bars to compare values. Show amounts by position or length, not by area, angle, or hue.
+- Label lines and bars directly instead of using a legend. Put each note next to what it explains.
+- No icon or picture that only decorates.
+
+## Check
+
+1. `bunx dekc ls <deck>` lists the headings in order. Read only them: does the talk hold?
+2. `bunx dekc shot --sheet`, then each slide's own shot: where does the eye land first, and is that the main point? Read `fill` in `bunx dekc check <slug> --json` for where the slide is empty.
+3. In each slide's shot, edges line up: in a row, tops, bottoms, and the first lines of text; in a column, left edges. Fix any that do not.
+4. Every difference in position, color, size, and look has a reason you can say. Remove the ones that do not.

package/src/cli/address.ts

@@ -1,7 +1,8 @@
 import { existsSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
+import { shellName } from "../core/escape.ts";
 import { isInside } from "../core/path.ts";
-import { COMMANDS } from "./commands.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 };
@@ -10,20 +11,72 @@ 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. A command that already names a deck,
- * or takes none, is left as written.
+ * 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 addressHint(hint: string, deck: HintDeck | undefined, cwd: string): string {
+export function addressHint(
+  hint: string,
+  deck: HintDeck | undefined,
+  cwd: string,
+  { note: noted = true }: { note?: boolean } = {},
+): string {
   if (deck === undefined || isInside(cwd, deck.dir)) {
     return hint;
   }
-  const naming = deckAround(cwd) === undefined ? deck.name : `--deck ${deck.name}`;
-  return hint.replace(COMMAND_RE, (whole, command: string, rest: string) => {
-    if (!DECK_COMMANDS.has(command) || namesDeck(rest, deck.name)) {
-      return whole;
-    }
-    return `\`dekc ${command} ${naming}${rest}\``;
-  });
+  const word = shellName(deck.name) ?? DECK_PLACEHOLDER;
+  const inOther = deckAround(cwd) !== undefined;
+  // The note a placeholder adds names `dekc ls` for the project, not for the deck.
+  const note = hint.indexOf(PLACEHOLDER_NOTE);
+  let placed = false;
+  const addressed = hint.replace(
+    COMMAND_RE,
+    (whole, command: string, rest: string, offset: number) => {
+      const subcommand = SUBCOMMAND_WORDS.get(command)?.has(deck.name) === true;
+      // A first word that is a subcommand, or a flag, is never the deck's name.
+      const positional = !subcommand && !deck.name.startsWith("-");
+      if (
+        !DECK_COMMANDS.has(command) ||
+        namesDeck(rest, positional ? word : undefined) ||
+        (note >= 0 && offset >= note && offset < note + PLACEHOLDER_NOTE.length)
+      ) {
+        return whole;
+      }
+      placed ||= word === DECK_PLACEHOLDER;
+      const flag = inOther || subcommand;
+      return `\`dekc ${command} ${flag ? deckFlag(deck.name) : deckWord(deck.name)}${rest}\``;
+    },
+  );
+  return placed && note < 0 && noted ? `${addressed}${PLACEHOLDER_NOTE}` : addressed;
+}
+
+/** `hint` with where to find a deck's name, once, when one of its commands has `<deck>` for it. */
+export function withPlaceholderNote(hint: string): string {
+  return hint.includes(DECK_PLACEHOLDER) && !hint.includes(PLACEHOLDER_NOTE)
+    ? `${hint}${PLACEHOLDER_NOTE}`
+    : hint;
+}
+
+/** Where a hint with `<deck>` in it says to find the deck's name. */
+const PLACEHOLDER_NOTE = "; for <deck>, name the deck as `dekc ls` lists it";
+
+/** What a command shows for a deck no word holds alike in every shell. */
+const DECK_PLACEHOLDER = "<deck>";
+
+/**
+ * A deck's name as the first word of a command: one shell word, `<deck>` when there is none, or
+ * `--deck=` when the name starts with a dash, which a first word would read as a flag.
+ */
+export function deckWord(name: string): string {
+  return name.startsWith("-") ? deckFlag(name) : (shellName(name) ?? DECK_PLACEHOLDER);
+}
+
+/** A deck's name as `--deck`, joined with `=` when it starts with a dash, as a value must be. */
+export function deckFlag(name: string): string {
+  const word = shellName(name) ?? DECK_PLACEHOLDER;
+  return name.startsWith("-") ? `--deck=${word}` : `--deck ${word}`;
 }
 
 /** A backquoted command: `dekc`, a command word, and what follows it up to the closing quote. */
@@ -33,9 +86,26 @@ const DECK_COMMANDS = new Set(
   Object.entries(COMMANDS).flatMap(([name, spec]) => ("scope" in spec && spec.scope ? [name] : [])),
 );
 
-function namesDeck(rest: string, name: string): boolean {
-  const [first] = rest.trim().split(/\s+/);
-  return first === name || first?.includes("/") === true || /(?:^| )--deck(?: |$)/.test(rest);
+/** The first word of each command's subcommands, which a deck's name in its place would read as. */
+const SUBCOMMAND_WORDS = new Map(
+  Object.entries(COMMANDS).map(([name, spec]) => [
+    name,
+    new Set(Object.keys(subcommandsOf(spec as AnySpec)).map((sub) => sub.split(" ")[0])),
+  ]),
+);
+
+/**
+ * Whether a command's words already name a deck: as `word`, the deck's name as one shell word,
+ * when the deck can be named first, as a ref, or with --deck.
+ */
+function namesDeck(rest: string, word: string | undefined): boolean {
+  const words = rest.trim();
+  const [first] = words.split(/\s+/);
+  return (
+    (word !== undefined && (words === word || words.startsWith(`${word} `))) ||
+    first?.includes("/") === true ||
+    /(?:^| )--deck(?:[ =]|$)/.test(rest)
+  );
 }
 
 /**

package/src/cli/build.ts

@@ -5,7 +5,7 @@ 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 { type SkippedCheck, skippedChecks, visualSkipped } from "./result.ts";
+import { RENDERED_RULES, type SkippedCheck, skippedChecks, visualSkipped } from "./result.ts";
 import type { DecksTarget } from "./scope.ts";
 
 /**
@@ -77,7 +77,7 @@ export async function buildCommand(
     ...skippedChecks([
       ...skipped,
       visualSkipped("dekc lint --visual", {
-        reason: "overflow and contrast are measured only by `dekc lint --visual`",
+        reason: `${RENDERED_RULES} are measured only by \`dekc lint --visual\``,
         ...(options.runner ? { runner: options.runner } : {}),
       }),
     ]),

package/src/cli/check.ts

@@ -1,5 +1,6 @@
 import type { Diagnostic } from "../core/diagnostic.ts";
 import { DekError } from "../core/error.ts";
+import { shellQuote } from "../core/escape.ts";
 import type { Fill } from "../core/fill.ts";
 import { lintDeck } from "../core/lint.ts";
 import { type PlaywrightRunner, playwrightMissingError } from "../core/playwright.ts";
@@ -53,7 +54,7 @@ export async function checkCommand(
 
   const skipped: SkippedCheck[] = visual
     ? []
-    : [visualSkipped(`dekc check ${slug}`, { reason: "Playwright is not installed" })];
+    : [visualSkipped(`dekc check ${shellQuote(slug)}`, { reason: "Playwright is not installed" })];
 
   // A live-only deck is done without voice, so asking for it skips the check rather than failing,
   // the way a missing Playwright skips visual.

package/src/cli/commands.ts

@@ -1,4 +1,5 @@
 import { hasErrors } from "../core/diagnostic.ts";
+import { shellQuote } from "../core/escape.ts";
 import { isRefName } from "../core/ref-name.ts";
 import { mergeSarif, toSarif } from "../core/sarif.ts";
 import type { CheckCliResult } from "./check.ts";
@@ -24,6 +25,7 @@ import {
   formatNew,
   formatPack,
   formatPdf,
+  formatPptx,
   formatRef,
   formatReport,
   formatShot,
@@ -444,7 +446,7 @@ export const COMMANDS = {
       text: formatCheck,
       notes: (data, color) => formatSkipped(data.skipped, color) || undefined,
       paths: withDisplayDiagnostics,
-      failure: (data) => diagnosticFailure("check", data, `dekc check ${data.slug}`),
+      failure: (data) => diagnosticFailure("check", data, `dekc check ${shellQuote(data.slug)}`),
     },
   }),
   shot: result({
@@ -659,7 +661,7 @@ export const COMMANDS = {
     group: "Output",
     overview: [
       ["dekc lint [--fix]", "check script.md against slides; --fix syncs first"],
-      ["dekc lint --visual", "add overflow and contrast rules"],
+      ["dekc lint --visual", "add overflow, contrast, line-break, and alignment rules"],
       ["dekc lint --format sarif", "print diagnostics as SARIF, for code scanning"],
     ],
     agent: ["dekc lint [--fix] [--visual] [--format sarif]"],
@@ -827,19 +829,22 @@ export const COMMANDS = {
     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.",
+      "Write dist/<deck>.pptx, one slide per slide at its last beat: its plain boxes, pictures, and\ntext as PowerPoint's own over a picture of the rest, in the deck's theme, and its script in\nthe notes. Needs Playwright.",
     group: "Output",
     overview: [
-      ["dekc pptx [--root-dist] [--public]", "write a PowerPoint file with editable text"],
+      [
+        "dekc pptx [--root-dist] [--public]",
+        "write a PowerPoint file with editable shapes and text",
+      ],
     ],
     agent: [
-      "dekc pptx [--root-dist] [--public]   text editable over a picture of each slide; script in notes",
+      "dekc pptx [--root-dist] [--public]   boxes, pictures, and text editable over a picture of the rest; 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 },
+    output: { text: formatPptx, json: ({ outs }) => ({ outs }) },
   }),
   help: {
     kind: "help",

package/src/cli/contract.ts

@@ -214,7 +214,15 @@ export const RESULT_FIELDS = {
         "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() })),
+    layouts: z
+      .array(z.strictObject({ name: z.string(), example: z.string().optional() }))
+      .describe("The layouts whose names are plain words, which dek prints."),
+    unprintedLayouts: z
+      .number()
+      .optional()
+      .describe(
+        "How many layouts the theme has whose names are no plain word, left out of layouts; absent when none.",
+      ),
     layout: z.strictObject({ name: z.string(), example: z.string() }).optional(),
     ref: RefInfo.optional(),
   }),

package/src/cli/files.ts

@@ -4,6 +4,7 @@ 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 { shellQuote } from "../core/escape.ts";
 import { walkUp } from "../core/optional.ts";
 import { PLAYWRIGHT_INSTALL } from "../core/playwright.ts";
 import { readSourceIfExists, writeInside } from "../core/safe-fs.ts";
@@ -316,8 +317,3 @@ function inNodeModules(root: string, ...path: string[]): boolean {
     walkUp(root, (dir) => existsSync(join(dir, "node_modules", ...path)) || undefined) === true
   );
 }
-
-/** `word` as one shell word: as it is when that is safe, else single-quoted. */
-export function shellQuote(word: string): string {
-  return /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`;
-}

package/src/cli/flags.ts

@@ -41,7 +41,7 @@ export const FLAGS = {
   fix: { type: "boolean", text: "create missing skeleton slides before linting" },
   visual: {
     type: "boolean",
-    text: "add the rendered rules: overflow and contrast (needs Playwright)",
+    text: "add the rendered rules: overflow, contrast, line breaks, and alignment (needs Playwright)",
   },
   shot: { type: "boolean", text: "also write a screenshot and return its path" },
   voice: { type: "boolean", text: "also return each sentence's reading and duration" },

package/src/cli/goto.ts

@@ -1,6 +1,8 @@
 import { DekError } from "../core/error.ts";
 import { deckRoutePath } from "../runtime/routes.ts";
 import { isPidAlive, readDevServerLock } from "../server/lock.ts";
+import { deckFlag, deckWord } from "./address.ts";
+import { isTypedCommand } from "./commands.ts";
 import { type DeckTarget, requireSection } from "./scope.ts";
 
 export type NavResult = {
@@ -82,7 +84,7 @@ function refusal(
 ): DekError {
   if (status === 404 && lock.deck !== undefined && lock.deck !== deckName) {
     return new DekError(`the running dev server serves deck "${lock.deck}", not "${deckName}"`, {
-      hint: `pass --deck ${lock.deck}, or stop the server at ${lock.url} and run \`dekc ${deckName}\``,
+      hint: `pass ${deckFlag(lock.deck)}, or stop the server at ${lock.url} and run \`dekc ${isTypedCommand(deckName) ? deckFlag(deckName) : deckWord(deckName)}\``,
     });
   }
   if (status === 401) {

package/src/cli/init.ts

@@ -3,10 +3,12 @@ import { basename, join, resolve } from "node:path";
 import { parseCss, publishedTokens } from "../core/css.ts";
 import { deckPaths } from "../core/deck-paths.ts";
 import { DekError } from "../core/error.ts";
+import { shellQuote } from "../core/escape.ts";
 import { REQUIRED_TOKENS } from "../core/lint/tokens.ts";
 import { walkUp } from "../core/optional.ts";
 import { DECK_NAME_HINT, isDeckName } from "../core/path.ts";
-import { readTextIfExists } from "../core/resolve.ts";
+import { refuseInsideRef } from "../core/ref.ts";
+import { readSourceIfExists } from "../core/safe-fs.ts";
 import {
   defaultTsconfig,
   dekFilePaths,
@@ -25,7 +27,6 @@ import {
   nextSteps,
   type PlannedPath,
   playwrightStep,
-  shellQuote,
 } from "./files.ts";
 
 export type InitResult = {
@@ -84,7 +85,7 @@ export function initCommand(options: { cwd: string; dir?: string; deck?: string
 /** The tokens every deck needs that the project's theme.css does not publish on `.slide`. */
 function missingThemeTokens(root: string): string[] {
   const published = new Set(
-    publishedTokens(parseCss(readTextIfExists(join(root, "theme.css")) ?? "")).map(
+    publishedTokens(parseCss(readSourceIfExists(join(root, "theme.css"), root) ?? "")).map(
       (token) => token.name,
     ),
   );
@@ -100,8 +101,10 @@ function syncDeckFiles(deckDir: string, created: string[]): FileChanges {
 /** Everything init writes but `.dek/` and AGENTS.md, in the order a reader meets it. */
 function projectPlan(root: string, deck: string | undefined): PlannedPath[] {
   const themePath = join(root, "theme.css");
-  // A first deck is drawn in the theme that will be there: the one kept, or dek's.
-  const theme = readTextIfExists(themePath) ?? defaultTheme();
+  // A first deck is drawn in the theme that will be there: the one kept, or dek's. A folder that
+  // is not there yet holds no theme.
+  const theme =
+    (existsSync(root) ? readSourceIfExists(themePath, root) : undefined) ?? defaultTheme();
   return [
     { path: join(root, "dek.toml"), contents: defaultToml() },
     { path: themePath, contents: defaultTheme() },
@@ -123,6 +126,8 @@ function checkTarget(root: string): void {
   if (existsSync(root) && !statSync(root).isDirectory()) {
     throw new DekError("not a directory", { path: root, hint: "pass a directory to init" });
   }
+  // A ref is someone else's project, read where it is: init would write its files into it.
+  refuseInsideRef(root);
   const outer = walkUp(root, (dir) => {
     const config = join(dir, "dek.toml");
     return existsSync(config) && statSync(config).isFile() ? dir : undefined;

package/src/cli/lint.ts

@@ -1,13 +1,14 @@
 import { existsSync } from "node:fs";
 import { relative } from "node:path";
 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 { resolveRumdlBin, runRumdl } from "../core/rumdl.ts";
 import { mergeSarif, type SarifLog } from "../core/sarif.ts";
 import { syncDeck } from "../core/sync.ts";
 import { lintVisualDeck } from "../core/visual.ts";
-import { type SkippedCheck, skippedChecks, visualSkipped } from "./result.ts";
+import { RENDERED_RULES, type SkippedCheck, skippedChecks, visualSkipped } from "./result.ts";
 import type { DecksTarget } from "./scope.ts";
 
 export type LintCliResult = {
@@ -60,7 +61,7 @@ export async function lintCommand(
         ? []
         : [
             visualSkipped("dekc lint --visual", {
-              reason: "overflow and contrast are measured only with --visual",
+              reason: `${RENDERED_RULES} are measured only with --visual`,
             }),
           ]),
     ]),
@@ -79,6 +80,6 @@ function rumdlSkipped(scriptPath: string, cwd: string): SkippedCheck {
   return {
     check: "rumdl",
     reason: "rumdl ran but gave no result",
-    hint: `run \`${bin} check ${relative(cwd, scriptPath) || scriptPath}\` to see why`,
+    hint: `run \`${shellQuote(bin)} check ${shellQuote(relative(cwd, scriptPath) || scriptPath)}\` to see why`,
   };
 }

package/src/cli/main.ts

@@ -1,8 +1,9 @@
 import { DekError } from "../core/error.ts";
+import { shellQuote } from "../core/escape.ts";
 import { either } from "../core/prose.ts";
 import { isRefName } from "../core/ref-name.ts";
 import { resolveProject } from "../core/resolve.ts";
-import { addressHint } from "./address.ts";
+import { addressHint, deckWord, type HintDeck, withPlaceholderNote } from "./address.ts";
 import {
   type AnySpec,
   type CliResult,
@@ -13,7 +14,6 @@ import {
   subcommandAt,
   subcommandsOf,
 } from "./commands.ts";
-import { shellQuote } from "./files.ts";
 import { type CommandLine, parseCommandLine, wantsJson } from "./flags.ts";
 import { writeFailure, writeSuccess } from "./result.ts";
 import { DeckRequiredError, namesDeck, peelDeckArg, resolveTarget } from "./scope.ts";
@@ -197,12 +197,14 @@ function retypedWithDeck<T>(line: CommandLine, cwd: string, resolve: () => T): T
     }
     const typed = `\`dekc ${line.typed.map(shellQuote).join(" ")}\``;
     const [first] = error.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 hint = !first
       ? "run `dekc new <name>` to make a deck"
       : error.decks.length > NAMED_DECKS
-        ? `run ${addressHint(typed, first, cwd)}, or name another deck in place of ${first.name}; \`dekc ls\` lists them`
-        : `run ${either(error.decks.map((deck) => addressHint(typed, deck, cwd)))}`;
-    throw new DekError(error.message, { hint, cause: error });
+        ? `run ${retyped(first)}, or name another deck in place of ${deckWord(first.name)}; \`dekc ls\` lists them`
+        : `run ${either(error.decks.map(retyped))}`;
+    throw new DekError(error.message, { hint: withPlaceholderNote(hint), cause: error });
   }
 }
 

package/src/cli/new.ts

@@ -1,10 +1,12 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { loadConfig } from "../core/config.ts";
 import { deckPaths } from "../core/deck-paths.ts";
 import { DekError } from "../core/error.ts";
 import { DECK_NAME_HINT, isDeckName } from "../core/path.ts";
 import { isRefName } from "../core/ref-name.ts";
+import { readDeckFile } from "../core/resolve.ts";
+import { readSourceIfExists } from "../core/safe-fs.ts";
 import { syncDeck } from "../core/sync.ts";
 import { applyPlan, deckPlan, nextSteps } from "./files.ts";
 import { type RefInfo, requireDeckFromCwd, requireProject, resolveTarget } from "./scope.ts";
@@ -44,12 +46,17 @@ export function newCommand(options: { cwd: string; name: string; themeFrom?: str
       ? resolveTarget(options.cwd, "deck", { refs: true, deck: options.themeFrom })
       : undefined;
   const ref = fromRef?.ref;
-  const themeSource = fromRef
-    ? deckPaths(fromRef.deck.dir).theme
+  const fromDeck = fromRef
+    ? fromRef.deck
     : options.themeFrom
-      ? deckPaths(requireDeckFromCwd(options.cwd, options.themeFrom).deck.dir).theme
-      : join(project.root, "theme.css");
-  if (!existsSync(themeSource)) {
+      ? requireDeckFromCwd(options.cwd, options.themeFrom).deck
+      : undefined;
+  const themeSource = fromDeck ? deckPaths(fromDeck.dir).theme : join(project.root, "theme.css");
+  // What is copied is published with the new deck: a link out of its project is refused.
+  const source = fromDeck
+    ? readDeckFile(fromDeck.dir, themeSource)
+    : readSourceIfExists(themeSource, project.root);
+  if (source === undefined) {
     throw new DekError("theme.css not found", {
       path: themeSource,
       hint: ref
@@ -60,7 +67,7 @@ export function newCommand(options: { cwd: string; name: string; themeFrom?: str
     });
   }
 
-  const theme = `${ref ? provenance(ref) : ""}${readFileSync(themeSource, "utf8")}`;
+  const theme = `${ref ? provenance(ref) : ""}${source}`;
   const { created } = applyPlan(
     deckPlan(project.root, name, theme, loadConfig(project.configPath)),
   );