@hajimism/dek 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 Release notes for `@hajimism/dek`. From 0.1.0 on, release-please writes this file from the Conventional Commits on `main`.
 
+## [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.5.1",
   "description": "A build system for talks.",
   "license": "MIT",
   "author": "Hajime Nakagawa (https://github.com/hajimism)",
@@ -61,12 +61,12 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.15",
-    "@happy-dom/global-registrator": "21.0.1",
+    "@biomejs/biome": "2.6.2",
+    "@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.42.1",
     "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/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/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/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/lint/context.ts

@@ -26,6 +26,8 @@ type SlideSource = { html: string; scan: HtmlScan; skeleton: boolean };
 export type LintContext = DeckFiles & {
   /** DEK016 and DEK017 of each slide script, by slug: evaluated before the rules run. */
   scripts: Map<string, Diagnostic[]>;
+  /** The source of each slide script lint evaluated, by slug. */
+  scriptCode: Map<string, string>;
 };
 
 /** The deck as read from disk, each file once. */

package/src/core/lint/shared-styles.ts

@@ -2,6 +2,7 @@ import { isKeyframesPrelude, selectorClasses, splitSelectorList, startsAtSlide }
 import { deckPaths } from "../deck-paths.ts";
 import { type Diagnostic, diag } from "../diagnostic.ts";
 import { listed } from "../prose.ts";
+import { RUNTIME_CLASSES } from "../theme-facts.ts";
 import type { LintContext } from "./context.ts";
 
 /** How many slides may style something alike before it belongs in the theme: the third copy. */
@@ -56,6 +57,21 @@ function alsoReaches(ctx: LintContext, selector: string, setters: string[]): str
   });
 }
 
+/**
+ * How many classes theme.css would define with a rule under `selector` moved into it, when that
+ * is more than the deck's `max_classes` (DEK013); nothing while the move stays within it.
+ */
+function overBudget(ctx: LintContext, selector: string): number | undefined {
+  const defined = ctx.theme?.classes ?? new Set<string>();
+  const added = new Set(
+    selectorClasses(themeSelector(selector)).filter(
+      (name) => !defined.has(name) && !RUNTIME_CLASSES.has(name),
+    ),
+  );
+  const after = defined.size + added.size;
+  return added.size > 0 && after > ctx.deck.deck.max_classes ? after : undefined;
+}
+
 /**
  * DEK026: the same declaration under the same selector in the stylesheets of SHARED_BY slides
  * or more. Each slide fixed alike on its own, as agents working on one slide each will, is one
@@ -146,18 +162,27 @@ export function sharedStyleDiagnostics(ctx: LintContext): Diagnostic[] {
                 .join(
                   "",
                 )} without it, so check ${reaches.length === 1 ? "that slide" : "those slides"} after the move`;
+        // Following the hint must not trade this warning for DEK013's error.
+        const themeClasses = overBudget(ctx, selector);
+        const budget =
+          themeClasses === undefined
+            ? ""
+            : `; theme.css would then define ${themeClasses} classes, past max_classes ${ctx.deck.deck.max_classes}, so set \`max_classes: ${themeClasses}\` in the frontmatter too, or leave the rule in the slides`;
         return diag("DEK026", {
           message: `${rule} is also in ${listed(others)}`,
           path: paths.slide(slug, ".css"),
           line,
           slug,
-          hint: `write ${themeRule} once in theme.css and delete it from ${listed(slugs.map(cssOf))}${affected}`,
+          hint: `write ${themeRule} once in theme.css and delete it from ${listed(slugs.map(cssOf))}${affected}${budget}`,
           data: {
             selector,
             declarations,
             slides: slugs,
             ...(atPath.length > 0 ? { atRules: atPath } : {}),
             ...(reaches.length > 0 ? { alsoReaches: reaches } : {}),
+            ...(themeClasses !== undefined
+              ? { themeClasses, limit: ctx.deck.deck.max_classes }
+              : {}),
           },
         });
       }),

package/src/core/lint/theme-css.ts

@@ -12,6 +12,8 @@ import {
 } from "../css.ts";
 import { deckPaths } from "../deck-paths.ts";
 import { type Diagnostic, diag } from "../diagnostic.ts";
+import { escapeRegExp } from "../escape.ts";
+import { listed } from "../prose.ts";
 import { assetRefDiagnostics } from "./asset-refs.ts";
 import type { LintContext } from "./context.ts";
 import { isRawThemeValue, isRawTokenValue, REQUIRED_TOKENS, tokenSuggestion } from "./tokens.ts";
@@ -24,14 +26,18 @@ function missingThemeDiagnostic(ctx: LintContext): Diagnostic {
   return diag("DEK018", {
     message: "theme.css not found",
     path: deckPaths(ctx.deck.dir).theme,
-    hint: "copy theme.css from the project root or another deck into the deck directory",
+    hint: "copy the project's template, ../../theme.css, or another deck's theme into the deck directory",
   });
 }
 
 /** DEK012, DEK013, DEK015, DEK014, and what its `url()`s load (DEK020 to DEK023) for theme.css. */
 function lintTheme(
   { path, sheet, classes, tokens }: NonNullable<LintContext["theme"]>,
-  { maxClasses, deckDir }: { maxClasses: number; deckDir: string },
+  {
+    maxClasses,
+    deckDir,
+    usedBy,
+  }: { maxClasses: number; deckDir: string; usedBy: Map<string, string[]> | undefined },
 ): Diagnostic[] {
   const diagnostics: Diagnostic[] = [];
   // A rule inside `@media` reaches the page as surely as one outside it.
@@ -56,6 +62,7 @@ function lintTheme(
       diag("DEK013", {
         message: `theme.css has ${classCount} classes; limit is ${maxClasses}`,
         path,
+        hint: classBudgetHint(classCount, usedBy),
         data: { classes: classCount, limit: maxClasses },
       }),
     );
@@ -287,9 +294,63 @@ function themeScopeHint(selector: string): string {
   return `write it as ${scoped.join(", ")}`;
 }
 
+/**
+ * How to bring the theme back within its class budget: first what frees a class without changing
+ * a slide, a class no slide uses and one only one slide uses, then raising the budget itself.
+ */
+function classBudgetHint(classCount: number, usedBy: Map<string, string[]> | undefined): string {
+  if (usedBy === undefined) {
+    return `set \`max_classes: ${classCount}\` in the frontmatter`;
+  }
+  const unused = [...usedBy].filter(([, slugs]) => slugs.length === 0).map(([name]) => `.${name}`);
+  const single = [...usedBy].flatMap(([name, slugs]) =>
+    slugs.length === 1 ? [`.${name} into slides/${slugs[0]}.css`] : [],
+  );
+  return [
+    ...(unused.length > 0 ? [`delete ${listed(unused)}, which no slide uses`] : []),
+    ...(single.length > 0
+      ? [`move each class only one slide uses into that slide's stylesheet: ${listed(single)}`]
+      : []),
+    `set \`max_classes: ${classCount}\` in the frontmatter`,
+  ].join("; or ");
+}
+
+/**
+ * Each class the theme defines but `.slide`, which every slide is, to the slides that use it, in
+ * script order: in their markup, or anywhere in their script, which may set it with `classList`.
+ * None while a section has no HTML yet or only its skeleton: what it will use is unknown.
+ */
+function slidesUsing(ctx: LintContext, classes: Set<string>): Map<string, string[]> | undefined {
+  const usedBy = new Map(
+    [...classes].filter((name) => name !== "slide").map((name) => [name, [] as string[]]),
+  );
+  for (const slug of ctx.sectionsBySlug.keys()) {
+    const source = ctx.slideSource(slug);
+    if (source === undefined || source.skeleton) {
+      return undefined;
+    }
+    const code = ctx.scriptCode.get(slug);
+    for (const [name, slugs] of usedBy) {
+      if (source.scan.classes.includes(name) || (code !== undefined && namesClass(code, name))) {
+        slugs.push(slug);
+      }
+    }
+  }
+  return usedBy;
+}
+
+/** Whether `code` holds `name` as a class token: a word of its own, wherever it stands. */
+function namesClass(code: string, name: string): boolean {
+  return new RegExp(`(^|[^\\w-])${escapeRegExp(name)}($|[^\\w-])`).test(code);
+}
+
 /** The theme's own findings, or DEK018 when there is no theme. */
 export function themeDiagnostics(ctx: LintContext): Diagnostic[] {
   return ctx.theme
-    ? lintTheme(ctx.theme, { maxClasses: ctx.deck.deck.max_classes, deckDir: ctx.deck.dir })
+    ? lintTheme(ctx.theme, {
+        maxClasses: ctx.deck.deck.max_classes,
+        deckDir: ctx.deck.dir,
+        usedBy: slidesUsing(ctx, ctx.theme.classes),
+      })
     : [missingThemeDiagnostic(ctx)];
 }

package/src/core/lint.ts

@@ -18,6 +18,7 @@ import { timingDiagnostics } from "./lint/timing.ts";
 import { voiceDiagnostics } from "./lint/voice.ts";
 import { asResolvedDeck, type Project, type ProjectDeck } from "./resolve.ts";
 import type { Section } from "./schema.ts";
+import type { SlideScriptProblem } from "./slide-script.ts";
 import { evaluateSlideScripts, slideScriptsProblems } from "./slide-script-eval.ts";
 import { RUNTIME_CLASSES } from "./theme-facts.ts";
 
@@ -53,7 +54,7 @@ export function lintDeck(
 export function lintDeck(input: DeckInput, options?: LintDeckOptions): Diagnostic[] {
   const { files, scripted } = readLintInput(input);
   const problems = slideScriptsProblems(scripted.map((entry) => entry.input));
-  return runRules({ ...files, scripts: slideScriptDiagnostics(scripted, problems) }, options);
+  return runRules(lintContext(files, scripted, problems), options);
 }
 
 /**
@@ -66,7 +67,19 @@ export async function lintDeckAsync(
 ): Promise<Diagnostic[]> {
   const { files, scripted } = readLintInput(input);
   const problems = await evaluateSlideScripts(scripted.map((entry) => entry.input));
-  return runRules({ ...files, scripts: slideScriptDiagnostics(scripted, problems) }, options);
+  return runRules(lintContext(files, scripted, problems), options);
+}
+
+function lintContext(
+  files: DeckFiles,
+  scripted: LintedScript[],
+  problems: SlideScriptProblem[][],
+): LintContext {
+  return {
+    ...files,
+    scripts: slideScriptDiagnostics(scripted, problems),
+    scriptCode: new Map(scripted.map(({ section, input }) => [section.slug, input.code])),
+  };
 }
 
 function readLintInput(input: DeckInput): { files: DeckFiles; scripted: LintedScript[] } {

package/src/core/sandbox.ts

@@ -46,7 +46,7 @@ const CHROMIUM_SAYS = /\[err\]|FATAL/;
 const REASON_CHARS = 280;
 
 /** A sentence: up to a `.`, `!`, or `?` that ends a word, outside parentheses, as `(0 vs. 1)` is. */
-const SENTENCE = /(?:\([^)]*\)|\((?!\)|$)|[^()!?\.]|[.!?](?!\s|$))+(?:[.!?]+|$)/g;
+const SENTENCE = /(?:\([^)]*\)|\((?!\)|$)|[^()!?.]|[.!?](?!\s|$))+(?:[.!?]+|$)/g;
 
 /**
  * What Chromium said when it failed: its words for a sandbox that cannot start, else its first

package/src/core/slide-measure.ts

@@ -251,6 +251,7 @@ export function measureSlideInPage(): SlideMeasure {
     const own = squash(textNodes.map((node) => node.textContent ?? "").join(" "));
     // innerText separates block children; textContent would run "item 0item 1" together.
     // SVG and MathML have no innerText, so they fall back to textContent.
+    // biome-ignore lint/performance/useDomNodeTextContent: the rendered line breaks are the point here.
     const whole = el instanceof HTMLElement ? el.innerText : el.textContent;
     const text = own || squash(whole ?? "");
     const parentEl = el.parentElement;

package/src/core/spawn.ts

@@ -75,10 +75,16 @@ export async function runPiped(cmd: string[], options: PipedOptions): Promise<Pi
       hint: `it did not finish within ${Math.round(options.timeoutMs / 1000)}s and was stopped`,
     });
   try {
-    if (options.stdin !== undefined) {
-      proc.stdin.write(options.stdin);
+    try {
+      if (options.stdin !== undefined) {
+        // A write the pipe cannot take at once returns a promise, which can reject with the pipe.
+        await proc.stdin.write(options.stdin);
+      }
+      await proc.stdin.end();
+    } catch {
+      // The pipe broke: the command exited without reading all of its stdin, as `head` does, or
+      // was killed at its timeout while a write waited on it. Its exit says which, and how it went.
     }
-    await proc.stdin.end();
     const exitCode = await proc.exited;
     // It finished in time, however long what it left behind keeps the pipes open.
     stop.clear();
@@ -91,10 +97,6 @@ export async function runPiped(cmd: string[], options: PipedOptions): Promise<Pi
     if (error instanceof DekError) {
       throw error;
     }
-    // Killing the command breaks the pipe a write to its stdin was waiting on.
-    if (stop.fired()) {
-      throw overrun();
-    }
     throw new DekError(options.label, { hint: options.hint, cause: error });
   } finally {
     stop.clear();

package/src/server/dev.ts

@@ -76,9 +76,9 @@ export async function startDevServer(options: DevServerOptions): Promise<DevServ
   if (options.deck !== undefined && isRefName(options.deck)) {
     throw refReadOnlyError(options.deck);
   }
-  // Before the port and the watchers; writing the lock checks again, for a server that raced us.
-  assertNoDevServer(project.root);
   const { scopedDeckName, deckDir } = serverScope(project, options);
+  // Before the port and the watchers; writing the lock checks again, for a server that raced us.
+  assertNoDevServer(project.root, scopedDeckName);
   const access = accessFor(options);
   const embed = {
     playerScript: await livePlayerScript(),

package/src/server/lock.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { DekError } from "../core/error.ts";
+import { isDeckName } from "../core/path.ts";
 import { readSourceIfExists, removeInside, writeInside } from "../core/safe-fs.ts";
 
 export type DevServerLock = {
@@ -88,30 +89,59 @@ export function readDevServerLock(root: string): DevServerLock | undefined {
   return undefined;
 }
 
-/** The URL of each root a server in this process holds, which two racing servers both see. */
-const claimedRoots = new Map<string, string>();
+/** The server each root a server in this process holds, which two racing servers both see. */
+const claimedRoots = new Map<string, Omit<DevServerLock, "password">>();
 
-/** Throw when a live server, in this process or another, already holds `root`. */
-export function assertNoDevServer(root: string): void {
+/**
+ * Throw when a live server, in this process or another, already holds `root`. `deck` is the one
+ * deck the server about to start would serve, none for the whole project.
+ */
+export function assertNoDevServer(root: string, deck?: string): void {
   const existing = readDevServerLock(root);
   const running =
-    claimedRoots.get(root) ?? (existing && isPidAlive(existing.pid) ? existing.url : undefined);
+    claimedRoots.get(root) ?? (existing && isPidAlive(existing.pid) ? existing : undefined);
   if (running !== undefined) {
-    throw new DekError(`dev server already running at ${running}`, {
+    throw new DekError(`dev server already running at ${running.url}`, {
       path: serverLockPath(root),
-      hint: `open ${running}`,
+      hint: runningServerHint(root, running, deck),
     });
   }
 }
 
+/**
+ * Where the running server shows what was asked for, or, when it serves one other deck only, how
+ * to get one that serves both: `dekc` started inside a deck's folder serves that deck alone.
+ */
+function runningServerHint(
+  root: string,
+  running: Omit<DevServerLock, "password">,
+  deck: string | undefined,
+): string {
+  if (running.deck === deck) {
+    return `open ${running.url}`;
+  }
+  if (running.deck === undefined && deck !== undefined) {
+    return `open ${running.url}decks/${encodeURIComponent(deck)}/`;
+  }
+  // The lock is a file a repository could bring along: name only a deck this project has.
+  const named =
+    running.deck !== undefined &&
+    isDeckName(running.deck) &&
+    existsSync(join(root, "decks", running.deck, "script.md"))
+      ? `decks/${running.deck}`
+      : "one deck";
+  const wanted = deck === undefined ? "the whole project" : `decks/${deck}`;
+  return `it serves only ${named}; to serve ${wanted}, stop it (pid ${running.pid}) and run \`dekc\` at the project root, which serves every deck`;
+}
+
 export function writeDevServerLock(
   root: string,
   url: string,
   password?: string,
   deck?: string,
 ): void {
-  assertNoDevServer(root);
-  claimedRoots.set(root, url);
+  assertNoDevServer(root, deck);
+  claimedRoots.set(root, { url, pid: process.pid, ...(deck ? { deck } : {}) });
   try {
     // A fresh file renamed into place, so it may hold the --remote password: its owner's only.
     writeInside(

package/tsconfig.json

@@ -22,5 +22,5 @@
     "noUnusedParameters": false,
     "noPropertyAccessFromIndexSignature": false
   },
-  "include": ["src", "tests"]
+  "include": ["src", "tests", "evals"]
 }