@hajimism/dek 0.4.0 → 0.5.1

package/src/core/html-scan.ts

@@ -1,3 +1,9 @@
+import {
+  attributeOf,
+  attributeTokens,
+  decodeAttribute,
+  trimAsciiWhitespace,
+} from "./attribute-value.ts";
 import { hasSlideClass, uniqueMark } from "./html.ts";
 import { lineLocator } from "./lines.ts";
 import { attributeUrls, type UrlUse } from "./url-attributes.ts";
@@ -5,7 +11,7 @@ import { attributeUrls, type UrlUse } from "./url-attributes.ts";
 /** Where something is written: 1-based line, and 1-based column in UTF-16 units, as editors count. */
 export type SourceSpot = { line: number; column: number };
 
-/** One attribute as the parser read it, located at its name. */
+/** One attribute, its value as the browser reads it, located at its name. */
 export type HtmlAttribute = SourceSpot & { name: string; value: string };
 
 /**
@@ -59,7 +65,8 @@ const UNDRAWN_TAGS = new Set(["title", "desc"]);
 /**
  * What a slide's markup uses and references, read in one pass of the real parser and located in
  * the source. The parser has no positions, so each start tag gets a marker in front of it; where
- * the markers land, less their own length, is where the tags were written.
+ * the markers land, less their own length, is where the tags were written. Each value is read as
+ * the browser reads it, its character references decoded.
  */
 export function scanSlideHtml(html: string): HtmlScan {
   const mark = uniqueMark(html);
@@ -81,9 +88,10 @@ export function scanSlideHtml(html: string): HtmlScan {
       element(el) {
         el.before(mark, { html: true });
         const tag = el.tagName.toLowerCase();
-        const attributes = [...el.attributes].map(([name, value]): [string, string] => [
+        // As written: each is decoded once the tag is located, which maps a URL back into it.
+        const attributes = [...el.attributes].map(([name, written]): [string, string] => [
           name.toLowerCase(),
-          value,
+          written,
         ]);
         if (CONTENT_TAGS.has(tag)) {
           for (const heading of open) {
@@ -99,7 +107,7 @@ export function scanSlideHtml(html: string): HtmlScan {
               undrawn--;
             });
           }
-        } else if (el.getAttribute("aria-hidden")?.trim() === "true" && el.canHaveContent) {
+        } else if (isAriaHidden(attributeOf(el, "aria-hidden")) && el.canHaveContent) {
           const entry = { index: parsed.length, text: "" };
           hidden.push(entry);
           hiding = entry;
@@ -116,8 +124,8 @@ export function scanSlideHtml(html: string): HtmlScan {
           }
         } else if (
           !hiding &&
-          el.getAttribute("aria-hidden")?.trim() !== "true" &&
-          isPicture(tag, el.getAttribute("role"))
+          !isAriaHidden(attributeOf(el, "aria-hidden")) &&
+          isPicture(tag, attributeOf(el, "role"))
         ) {
           const entry = { index: parsed.length, text: false, titled: false };
           pictures.push(entry);
@@ -131,7 +139,7 @@ export function scanSlideHtml(html: string): HtmlScan {
         if (HEADING_TAGS.has(tag) && el.canHaveContent) {
           const heading = {
             index: parsed.length,
-            content: (el.getAttribute("aria-label") ?? "").trim() !== "",
+            content: isName(attributeOf(el, "aria-label")),
           };
           headings.push(heading);
           open.push(heading);
@@ -139,7 +147,7 @@ export function scanSlideHtml(html: string): HtmlScan {
             open.splice(open.indexOf(heading), 1);
           });
         }
-        if (tag === "section" && hasSlideClass(el.getAttribute("class")) && el.canHaveContent) {
+        if (tag === "section" && hasSlideClass(attributeOf(el, "class")) && el.canHaveContent) {
           slidesOpen++;
           el.onEndTag(() => {
             slidesOpen--;
@@ -181,23 +189,24 @@ export function scanSlideHtml(html: string): HtmlScan {
       inSlide: false,
     };
     const offsets = attributeOffsets(html, start);
+    const decoded = attributes.map(([name, written]) => ({ name, ...decodeAttribute(written) }));
     const element: HtmlElement = {
       tag,
       inSlide,
       ...spot(start),
-      attributes: attributes.map(([name, value]) => ({
+      attributes: decoded.map(({ name, value }) => ({
         name,
         value,
         ...spot(offsets.get(name)?.name ?? start),
       })),
     };
     elements.push(element);
-    for (const attribute of element.attributes) {
-      const valueAt = offsets.get(attribute.name)?.value;
+    for (const { name, value, writtenAt } of decoded) {
+      const valueAt = offsets.get(name)?.value;
       refs.push(
-        ...attributeRefs(element.tag, attribute).map(({ ref, offset }) => ({
+        ...attributeRefs(element.tag, name, value).map(({ ref, offset }) => ({
           ...ref,
-          ...(valueAt === undefined ? spot(start) : spot(valueAt + offset)),
+          ...(valueAt === undefined ? spot(start) : spot(valueAt + writtenAt(offset))),
         })),
       );
     }
@@ -213,9 +222,7 @@ export function scanSlideHtml(html: string): HtmlScan {
     slides,
     ...(slug === undefined ? {} : { slug }),
     ...(layout === undefined ? {} : { layout }),
-    classes: elements.flatMap((element) =>
-      (attributeValue(element, "class") ?? "").split(/\s+/).filter(Boolean),
-    ),
+    classes: elements.flatMap((element) => attributeTokens(attributeValue(element, "class"))),
     refs,
     emptyHeadings: headings
       .filter((heading) => !heading.content)
@@ -237,14 +244,28 @@ export function scanSlideHtml(html: string): HtmlScan {
  * or `"none"` says it is decoration, as `aria-hidden` does.
  */
 function isPicture(tag: string, role: string | null): boolean {
-  const roles = (role ?? "").trim().toLowerCase().split(/\s+/);
-  if (roles[0] === "presentation" || roles[0] === "none") {
+  const first = attributeTokens(role)[0]?.toLowerCase();
+  if (first === "presentation" || first === "none") {
     return false;
   }
-  return tag === "img" || tag === "svg" || roles[0] === "img";
+  return tag === "img" || tag === "svg" || first === "img";
 }
 
-/** The value of `name` on `element`, as the parser read it. */
+/** Whether `aria-hidden` marks decoration: `true`, give or take ASCII whitespace. */
+function isAriaHidden(value: string | null): boolean {
+  return value !== null && trimAsciiWhitespace(value) === "true";
+}
+
+/**
+ * Whether a label gives a name. Chromium's accessible name keeps an `aria-label` of no-break
+ * spaces or other spaces outside ASCII, and drops one of ASCII whitespace alone; dek reads a
+ * `title` or an `aria-labelledby` of whitespace alone as no name too.
+ */
+export function isName(label: string | null | undefined): boolean {
+  return label != null && trimAsciiWhitespace(label) !== "";
+}
+
+/** The value of `name` on `element`, as the browser reads it. */
 function attributeValue(element: HtmlElement, name: string): string | undefined {
   return element.attributes.find((attribute) => attribute.name === name)?.value;
 }
@@ -253,24 +274,25 @@ function isDefined<T>(value: T | undefined): value is T {
   return value !== undefined;
 }
 
-/** The URLs one attribute names, each with its offset into the value. */
+/** The URLs one attribute names, each with its offset into the decoded value. */
 function attributeRefs(
   tag: string,
-  attribute: HtmlAttribute,
+  attr: string,
+  value: string,
 ): Array<{ ref: Omit<HtmlRef, keyof SourceSpot>; offset: number }> {
-  const named = attributeUrls(tag, attribute.name, attribute.value);
+  const named = attributeUrls(tag, attr, value);
   if (!named) {
     return [];
   }
   return named.urls.map(({ url, offset }) => ({
-    ref: { tag, attr: attribute.name, value: url, use: named.use },
+    ref: { tag, attr, value: url, use: named.use },
     offset,
   }));
 }
 
 /**
- * Where each attribute of the start tag at `start` is written: its name, and its value when it
- * has one. Only positions come from here; names and values are the parser's.
+ * Where each attribute of the start tag at `start` is written: its name, and its value as
+ * written when it has one. Only positions come from here; names and values are the parser's.
  */
 function attributeOffsets(
   html: string,

package/src/core/html.ts

@@ -1,5 +1,11 @@
 import { cutText } from "./annotation-rows.ts";
 import { assetInliner } from "./assets.ts";
+import {
+  attributeOf,
+  attributeTokens,
+  decodeAttribute,
+  trimAsciiWhitespace,
+} from "./attribute-value.ts";
 import { deckPaths } from "./deck-paths.ts";
 import { escapeAttr, escapeHtml } from "./escape.ts";
 import { type LineColumn, lineLocator } from "./lines.ts";
@@ -33,7 +39,7 @@ export function htmlShell(options: {
 }
 
 export function hasSlideClass(className: string | null | undefined): boolean {
-  return (className ?? "").split(/\s+/).some((token) => token.toLowerCase() === "slide");
+  return attributeTokens(className).some((token) => token.toLowerCase() === "slide");
 }
 
 /**
@@ -54,7 +60,7 @@ function locateSlideSection(html: string): { section: string; start: number } |
   const marked = rewriteHtml(html, (rewriter) => {
     rewriter.on("section", {
       element(el) {
-        if (found || !hasSlideClass(el.getAttribute("class"))) {
+        if (found || !hasSlideClass(attributeOf(el, "class"))) {
           return;
         }
         found = true;
@@ -182,16 +188,17 @@ export function stampSlide(html: string, stamp: SlideStamp): string {
   return rewriteHtml(html, (rewriter) => {
     rewriter.on("section", {
       element(el) {
-        if (done || !hasSlideClass(el.getAttribute("class"))) {
+        if (done || !hasSlideClass(attributeOf(el, "class"))) {
           return;
         }
         done = true;
         if (el.getAttribute("data-slug") === null) {
           el.setAttribute("data-slug", stamp.slug);
         }
-        // Ahead of the author's own style, so a slide can still set its own.
+        // Ahead of the author's own style, so a slide can still set its own. The style goes back
+        // into the markup, so it stays as written.
         const place = `--dek-slide-number: ${stamp.place.number}; --dek-slide-count: ${stamp.place.count}`;
-        const own = el.getAttribute("style")?.trim();
+        const own = trimAsciiWhitespace(el.getAttribute("style") ?? "");
         el.setAttribute("style", own ? `${place}; ${own}` : place);
         if (stamp.shown) {
           addClass(el, "is-current");
@@ -206,7 +213,7 @@ export function stampSlide(html: string, stamp: SlideStamp): string {
     if (shown) {
       rewriter.on("[data-step]", {
         element(el) {
-          const step = el.getAttribute("data-step");
+          const step = attributeOf(el, "data-step");
           if (step !== null && shown.has(step)) {
             addClass(el, "is-shown");
           }
@@ -225,7 +232,7 @@ export function stampSlide(html: string, stamp: SlideStamp): string {
           if (spot) {
             el.setAttribute("data-dek-source", `${spot.line}:${spot.column}`);
             if (spot.classes !== undefined) {
-              el.setAttribute("data-dek-class", spot.classes);
+              el.setAttribute("data-dek-class", escapeAttr(spot.classes));
             }
           }
         },
@@ -235,8 +242,8 @@ export function stampSlide(html: string, stamp: SlideStamp): string {
 }
 
 /**
- * Where a start tag is written, its tag, its classes as written (none when it has no `class`),
- * and the text inside it as written, whitespace collapsed.
+ * Where a start tag is written, its tag, its classes as written and read as the browser reads
+ * them (none when it has no `class`), and the text inside it as written, whitespace collapsed.
  */
 type TagSpot = LineColumn & { tag: string; classes?: string; text: string };
 
@@ -254,7 +261,7 @@ function startTagSpots(html: string, source: SlideSource): TagSpot[] {
       element(el) {
         el.before(mark, { html: true });
         const index = tags.length;
-        tags.push({ tag: el.tagName.toLowerCase(), classes: el.getAttribute("class"), text: "" });
+        tags.push({ tag: el.tagName.toLowerCase(), classes: attributeOf(el, "class"), text: "" });
         if (el.canHaveContent) {
           open.push(index);
           el.onEndTag(() => {
@@ -283,9 +290,7 @@ function startTagSpots(html: string, source: SlideSource): TagSpot[] {
       offset += before.length;
       const { tag = "", classes = null, text = "" } = tags[index] ?? {};
       const found = { ...spot(offset), tag, text: text.replace(/\s+/g, " ").trim() };
-      return classes === null
-        ? found
-        : { ...found, classes: classes.split(/\s+/).filter(Boolean).join(" ") };
+      return classes === null ? found : { ...found, classes: attributeTokens(classes).join(" ") };
     });
 }
 
@@ -334,12 +339,13 @@ export function collectSlidesHtml(
     .join("");
 }
 
+/** `className` added to the classes as written, unless the browser reads it among them already. */
 function addClass(el: HTMLRewriterTypes.Element, className: string): void {
   const current = el.getAttribute("class");
-  const tokens = current ? current.split(/\s+/).filter(Boolean) : [];
-  if (tokens.includes(className)) {
+  if (current !== null && attributeTokens(decodeAttribute(current).value).includes(className)) {
     return;
   }
+  const tokens = attributeTokens(current);
   tokens.push(className);
   el.setAttribute("class", tokens.join(" "));
 }

package/src/core/lint/asset-refs.ts

@@ -5,6 +5,7 @@ import { type Diagnostic, diag } from "../diagnostic.ts";
 import { isPlainWord } from "../escape.ts";
 import type { HtmlRef } from "../html-scan.ts";
 import { isInside } from "../path.ts";
+import { trimUrl } from "../url-attributes.ts";
 
 /**
  * DEK020 to DEK023 for one reference, whether it comes from a slide's markup
@@ -56,9 +57,9 @@ export function assetRefDiagnostics(
   if (kind === "missing") {
     return [
       diag("DEK021", {
-        message: `missing ${ref.tag === "img" ? "image" : "file"} "${ref.value}"`,
+        message: `missing ${ref.tag === "img" ? "image" : "file"} "${visibleSpaces(ref.value)}"`,
         ...location,
-        ...missingImageHint(ref.value, deckDir),
+        ...(strayedSpaceHint(ref.value, deckDir, from) ?? missingImageHint(ref.value, deckDir)),
         data: { src: ref.value },
       }),
     ];
@@ -66,7 +67,7 @@ export function assetRefDiagnostics(
   if (!isCanonicalAssetPath(ref.value)) {
     return [
       diag("DEK023", {
-        message: `asset "${ref.value}" must be referenced as assets/${posix.basename(ref.value.trim())}`,
+        message: `asset "${ref.value}" must be referenced as assets/${posix.basename(trimUrl(ref.value))}`,
         ...location,
         data: { src: ref.value },
       }),
@@ -76,19 +77,56 @@ export function assetRefDiagnostics(
 }
 
 function leavesFromEither(value: string, deckDir: string, from: string): boolean {
-  const path = value.trim().split(/[?#]/)[0] ?? "";
+  const path = trimUrl(value).split(/[?#]/)[0] ?? "";
   return (
     path !== "" &&
     [resolve(deckDir, path), resolve(from, path)].some((target) => !isInside(target, deckDir))
   );
 }
 
+/** `value` with each space but the plain one written as `\uXXXX`, so a message shows it. */
+function visibleSpaces(value: string): string {
+  return value.replace(
+    /[^\S ]/g,
+    (char) => `\\u${char.charCodeAt(0).toString(16).toUpperCase().padStart(4, "0")}`,
+  );
+}
+
+/**
+ * The hint for a path that names a deck file once the spaces outside ASCII at its ends are gone,
+ * as ` assets/a.png` does: the browser keeps those spaces, so the path names nothing.
+ */
+function strayedSpaceHint(
+  value: string,
+  deckDir: string,
+  from: string,
+): { hint: string } | undefined {
+  const url = trimUrl(value);
+  const bare = url.trim();
+  if (bare === url || classifyAssetRef(bare, { deckDir, from }).kind !== "file") {
+    return undefined;
+  }
+  const at = url.indexOf(bare);
+  const before = url.slice(0, at);
+  const after = url.slice(at + bare.length);
+  const where = before && after ? "around" : before ? "before" : "after";
+  const spaces = [...new Set(before + after)].map((char) => {
+    const point = `U+${char.charCodeAt(0).toString(16).toUpperCase().padStart(4, "0")}`;
+    return char === "\u00A0" ? `no-break space (${point})` : `space (${point})`;
+  });
+  // The path is the slide's text: one that is no plain word is left out of the hint.
+  const path = isPlainWord(bare) ? bare : "the path";
+  return {
+    hint: `remove the ${spaces.join(" and the ")} ${where} ${path}: the browser keeps ${spaces.length > 1 ? "them" : "it"} as part of the path, which then names no file`,
+  };
+}
+
 /**
  * Decks copy what they use from the project's `assets/` (so a deck stays whole when moved);
  * when the project has the file, the fix is that copy.
  */
 function missingImageHint(value: string, deckDir: string): { hint?: string } {
-  const name = value.trim().split(/[?#]/)[0] ?? "";
+  const name = trimUrl(value).split(/[?#]/)[0] ?? "";
   if (!name.startsWith("assets/")) {
     return {};
   }
@@ -104,7 +142,7 @@ function missingImageHint(value: string, deckDir: string): { hint?: string } {
 function remoteHint(value: string): string {
   let name = "";
   try {
-    name = posix.basename(new URL(value.trim(), "https://dek.invalid").pathname);
+    name = posix.basename(new URL(trimUrl(value), "https://dek.invalid").pathname);
   } catch {}
   // The name is the remote URL's: one that is no plain word is left out of the hint.
   return name && isPlainWord(name)

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/slide-html.ts

@@ -1,6 +1,13 @@
+import { attributeTokens } from "../attribute-value.ts";
 import { type Diagnostic, diag } from "../diagnostic.ts";
 import { isPlainWord } from "../escape.ts";
-import type { HtmlAttribute, HtmlScan, Picture, SourceSpot } from "../html-scan.ts";
+import {
+  type HtmlAttribute,
+  type HtmlScan,
+  isName,
+  type Picture,
+  type SourceSpot,
+} from "../html-scan.ts";
 import type { Section } from "../schema.ts";
 import { beatAt, formatStepChoices, resolveStep, stepChoices } from "../step.ts";
 import { suggest } from "../suggest.ts";
@@ -368,24 +375,22 @@ const EVENT_HANDLER_RE = /^on[a-z]+$/;
 /** Tags that load a URL as a document of its own, so an SVG there runs its scripts. */
 const DOCUMENT_TAGS = new Set(["iframe", "frame", "object", "embed"]);
 
+/** What a relative URL resolves against; only a URL's own scheme can run script. */
+const SOME_PAGE = "https://dek.invalid/";
+
 /**
  * The scheme of a URL that runs script, or undefined: `javascript:` and `vbscript:` always, and a
  * `data:` URL holding HTML, or SVG where a tag loads it as a document. An image's `data:` stays.
- * Read the way the URL parser reads it: tabs and newlines dropped, leading space trimmed, any case.
+ * The value comes decoded, and the URL parser reads it as the browser's does: C0 controls and
+ * spaces trimmed, tabs and newlines dropped anywhere, the scheme in any case.
  */
 function scriptUrlScheme(tag: string, value: string): string | undefined {
-  const url = value
-    .replace(/[\t\n\r]/g, "")
-    .trimStart()
-    .toLowerCase();
-  if (url.startsWith("javascript:")) {
-    return "javascript:";
-  }
-  if (url.startsWith("vbscript:")) {
-    return "vbscript:";
+  const url = URL.parse(value, SOME_PAGE);
+  if (url?.protocol === "javascript:" || url?.protocol === "vbscript:") {
+    return url.protocol;
   }
-  if (url.startsWith("data:")) {
-    const type = url.slice("data:".length).split(/[;,]/, 1)[0]?.trim();
+  if (url?.protocol === "data:") {
+    const type = url.href.slice("data:".length).split(/[;,]/, 1)[0]?.trim().toLowerCase();
     const runs =
       type === "text/html" ||
       type === "application/xhtml+xml" ||
@@ -478,14 +483,12 @@ function unnamedPicture({
 }: Picture): { message: string; hint: string; data: Record<string, string> } | undefined {
   const value = (name: string): string | undefined =>
     element.attributes.find((attribute) => attribute.name === name)?.value;
-  const named = [value("aria-label"), value("aria-labelledby"), value("title")].some(
-    (name) => name !== undefined && name.trim() !== "",
-  );
+  const named = [value("aria-label"), value("aria-labelledby"), value("title")].some(isName);
   const { tag } = element;
   if (named || (tag === "img" && value("alt") !== undefined)) {
     return undefined;
   }
-  if ((value("role") ?? "").trim().toLowerCase().split(/\s+/)[0] === "img") {
+  if (attributeTokens(value("role"))[0]?.toLowerCase() === "img") {
     if (titled) {
       return undefined;
     }
@@ -543,7 +546,7 @@ function unknownClassDiagnostics(
       : `define it in slides/${section.slug}.css, or use one of: ${shown.join(", ")}${scriptHint}`;
   const unknown = new Map<string, HtmlAttribute>();
   for (const attribute of attributesNamed(scan, "class")) {
-    for (const name of attribute.value.split(/\s+/).filter(Boolean)) {
+    for (const name of attributeTokens(attribute.value)) {
       if (!classes.has(name) && !unknown.has(name)) {
         unknown.set(name, attribute);
       }

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)];
 }