@entropicwarrior/sdoc 0.2.20 → 0.2.22

package/docs/reference/slide-authoring.sdoc

@@ -107,6 +107,18 @@
             reserved. \`--pptx\` runs the same check for free, because it has
             already measured the deck.
 
+            To override what a format does with the optional slides:
+
+            ```
+            node tools/build-slides.js deck.sdoc --pdf --with-optional
+            node tools/build-slides.js deck.sdoc --no-optional
+            ```
+
+            A slide marked \`optional: true\` is kept in the HTML build and
+            left out of \`--pdf\` and \`--pptx\`. Either default can be
+            overridden in any format: \`--with-optional\` keeps them,
+            \`--no-optional\` drops them. See [Optional Slides](#optional).
+
             To use a custom theme:
 
             ```
@@ -138,6 +150,7 @@
                 \`footnote:\` | Small print pinned under the body: provenance, caveats, sources.
                 \`status:\` | A second line under the kicker on a title slide, for a distribution notice.
                 \`accent:\` | \`primary\`, \`secondary\`, \`tertiary\` or \`neutral\`. An accent names a role; the theme chooses the colour.
+                \`optional:\` | \`true\` holds the slide back from the exports, and from any build passed \`--no-optional\`. See [Optional Slides](#optional).
                 \`numbered:\` | \`columns\` and \`rows\`. \`true\` numbers the children 01, 02, 03.
                 \`variant:\` | \`columns\` and \`rows\`. A named treatment, such as \`panel\` or \`mono\`.
                 \`weights:\` | \`split\` only. The ratio between panes, as in \`48 52\`.
@@ -150,11 +163,11 @@
             }
 
             A key is only configuration where it means something. \`config:\`,
-            \`kicker:\`, \`lede:\`, \`footnote:\`, \`accent:\` and \`status:\` are
-            understood by every scope; the rest are understood only by the
-            layout named against them above. Anywhere else they are ordinary
-            text — a slide opening "Value: the customer keeps their data."
-            renders that sentence, it does not silently swallow it. A
+            \`kicker:\`, \`lede:\`, \`footnote:\`, \`accent:\`, \`status:\` and
+            \`optional:\` are understood by every scope; the rest are understood
+            only by the layout named against them above. Anywhere else they are
+            ordinary text — a slide opening "Value: the customer keeps their
+            data." renders that sentence, it does not silently swallow it. A
             paragraph spanning more than one source line is never
             configuration.
 
@@ -445,9 +458,13 @@
             \`variant: card\`, an image at the top of each column with a heading
             and a line of body beneath gives the standard figure row.
 
-            Paths are resolved relative to the \`.sdoc\` file. They are embedded
-            in the PPTX export; a remote URL is left out of it, and the build
-            says which.
+            Paths are resolved relative to the \`.sdoc\` file, in every format.
+            A local image is embedded in the built deck itself — HTML, PDF and
+            PPTX alike — so the file you send someone carries its own pictures
+            and can be moved anywhere. A remote URL is left as a link, and the
+            PPTX export says which ones it could not embed. An image the build
+            cannot read is left as a plain reference and named in a warning,
+            rather than becoming a broken picture nobody was told about.
         }
     }
 
@@ -526,6 +543,114 @@
             spine 2, its details in order, and so on. This is the same order
             slides appear in the HTML, so PDF export needs no special case —
             every slide is just one page.
+
+            Every detail is a page, then, including the ones the audience
+            never saw. Mark a detail `optional: true` to keep it out of the
+            exported file — see [Optional Slides](#optional).
+        }
+    }
+
+    # Optional Slides @optional
+    {
+        Some slides exist for the room and not for the file that gets sent
+        on: the answer to a question that may not be asked, the figure
+        behind a figure, the rebuttal you hope to leave unused. Set
+        \`optional: true\` on the slide and it stays in the HTML build, which
+        is what you present from, and leaves the PDF and the PPTX, which are
+        what you send.
+
+        # Syntax @optional-syntax
+        {
+            ```
+            # Unit economics @unit-economics {
+                Headline numbers.
+
+                # Gross margin by cohort @margin :detail {
+                    optional: true
+
+                    The cohort table, if anyone asks for it.
+                }
+            }
+
+            # Pricing objections @objections {
+                optional: true
+
+                Held back unless pricing comes up.
+            }
+            ```
+
+            \`optional:\` is a slide property, not a scope annotation, and that
+            is deliberate: a heading carries one \`:type\`, and a drilldown has
+            already spent it on \`:detail\`. Reading optional-ness off the
+            configuration run keeps the two independent, so all four
+            combinations are available — a required spine, an optional spine,
+            a required detail, an optional detail.
+
+            A slide is the unit. Setting it on a cell inside a structured
+            layout — a column, a pipeline row, a pane of a \`split\` — has no
+            effect: the whole slide travels or none of it does. Mark the slide
+            that holds the cell.
+
+            It is set the way the other boolean properties are: \`true\`,
+            \`yes\`, \`on\` or \`1\` mark the slide; \`false\`, \`no\`, \`off\` or \`0\`
+            leave it alone. Like every slide property it must come before any
+            content.
+
+            A value that is none of those words is not configuration at all.
+            A slide whose first line is "Optional: a second seat costs
+            nothing" renders that sentence — a boolean key discards what it
+            cannot read, so it declines the line rather than swallowing it.
+        }
+
+        # What each format does @optional-formats
+        {
+            {[table]
+                Format | Default | Why
+                HTML | Included | It is the format you present from, and an optional slide is one you may want in the room.
+                PDF | Excluded | It is a format you send on.
+                PPTX | Excluded | The same.
+            }
+
+            The default is a guess about intent, not a property of the format,
+            so either can be overridden anywhere. An HTML deck is also
+            something you send someone:
+
+            ```
+            node tools/build-slides.js deck.sdoc --pdf --with-optional
+            node tools/build-slides.js deck.sdoc --no-optional
+            ```
+
+            When both are given the last one wins, as with \`--fit\`.
+
+            An optional spine takes its details with it. A detail belongs to
+            its spine, and there is nowhere for it to stand once the spine is
+            gone, so it goes whether or not it is marked itself.
+        }
+
+        # Numbering @optional-numbering
+        {
+            Optional slides are dropped before the deck is numbered, not
+            hidden afterwards, so the slide indicator counts what the reader
+            actually holds. A deck of four spines with one of them optional
+            reads \`3 / 3\` on its last page in the exported file and \`4 / 4\`
+            in the HTML build. The pages are consecutive either way; there is
+            no gap where a slide was removed.
+
+            A spine whose only details are optional loses its
+            \`slide-has-details\` class in the export too, so no theme draws a
+            drilldown chevron pointing at nothing.
+        }
+
+        # Themes @optional-theme
+        {
+            An optional slide carries the \`slide-optional\` class wherever it
+            is kept. A theme can use it to mark the slide on screen — a corner
+            tab, a tinted rule — so the presenter can see which slides are off
+            the main path. The built-in theme does not style it, so an optional
+            slide looks like any other until a theme says otherwise.
+
+            Nothing marked optional reaches a build it was excluded from, so
+            the class cannot appear in one.
         }
     }
 
@@ -768,6 +893,10 @@
             rather than an outlined box, so a hairline under a heading is a
             hairline rather than a rectangle with three invisible edges.
 
+            What is not in the file at all: slides marked \`optional: true\`,
+            unless \`--with-optional\` was passed. See
+            [Optional Slides](#optional).
+
             What does not carry: web fonts are named, not embedded, so the
             fonts a theme uses must be available to the viewer. Choosing faces
             that are on Google Fonts is the reliable route, because Slides

package/package.json

@@ -2,7 +2,7 @@
   "name": "@entropicwarrior/sdoc",
   "displayName": "SDOC - Docs for Human/Agent Teams",
   "description": "A plain-text documentation format with explicit brace scoping — deterministic parsing, AI-agent efficiency, and 10-50x token savings vs Markdown.",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "publisher": "entropicwarrior-msenfin",
   "license": "MIT",
   "repository": {

package/src/slide-geometry.js

@@ -143,7 +143,12 @@ const MEASURE_SCRIPT = `
       // The nav chevrons are a screen affordance, not deck content: nothing
       // clicks them in a PDF or a .pptx. (The theme runtime also hides one of
       // the pair at load time, so measuring them exported a lone arrow.)
-      if (el.classList && (el.classList.contains("nav-prev") || el.classList.contains("nav-next"))) return;
+      // .nav-vert is the vertical drilldown pair and its container; it sits in
+      // the bottom margin, so counting it would report an overflow on any
+      // slide whose content reaches near the bottom of the design box.
+      if (el.classList && (el.classList.contains("nav-prev") ||
+                           el.classList.contains("nav-next") ||
+                           el.classList.contains("nav-vert"))) return;
 
       var cs = getComputedStyle(el);
       if (cs.display === "none" || cs.visibility === "hidden" || parseFloat(cs.opacity) === 0) return;

package/src/slide-layouts.js

@@ -32,6 +32,7 @@ const COMMON_KEYS = new Set([
   "footnote",
   "accent",
   "status",
+  "optional",
 ]);
 
 const LAYOUT_KEYS = {
@@ -53,6 +54,17 @@ const CELL_KEYS = {
   bars: ["value", "fill"],
 };
 
+// Keys whose value is a boolean. Every other key renders the text it is given,
+// so consuming the line is visible in the output; a boolean key discards
+// anything it does not recognise, which would make an opening sentence
+// disappear. These therefore only take the line when the value is a word they
+// actually understand — "Optional: a second seat costs nothing" is prose.
+const BOOLEAN_KEYS = new Set(["optional", "numbered", "rule"]);
+const BOOLEAN_WORDS = new Set([
+  "true", "yes", "on", "1",
+  "false", "no", "off", "0",
+]);
+
 // Every key any scope might understand. A leading paragraph opening with one
 // of these is a configuration *candidate*; whether it is kept depends on the
 // context resolved below.
@@ -136,6 +148,13 @@ function extractConfig(children, parentLayout) {
       rejected.push(candidate.node);
       continue;
     }
+    if (
+      BOOLEAN_KEYS.has(candidate.key) &&
+      !BOOLEAN_WORDS.has(candidate.value.trim().toLowerCase())
+    ) {
+      rejected.push(candidate.node);
+      continue;
+    }
     if (candidate.key === "config" || candidate.key === "layout") {
       config.layout = candidate.value.toLowerCase();
     } else {
@@ -505,10 +524,12 @@ function buildBody(layout, cell, ctx) {
 }
 
 module.exports = {
+  BOOLEAN_KEYS,
   CONFIG_KEYS,
   STRUCTURED_LAYOUTS,
   extractConfig,
   buildBody,
   accentClass,
   slug,
+  truthy,
 };

package/src/slide-renderer.js

@@ -7,8 +7,101 @@
 //   const { nodes, meta } = extractMeta(parsed.nodes);
 //   const html = renderSlides(nodes, { meta, themeCss, themeJs });
 
+const fs = require("fs");
+const path = require("path");
 const { parseInline, renderKatex, escapeHtml, escapeAttr, sanitizeSvg, colorSwatchHtml } = require("./sdoc");
-const { extractConfig, buildBody, accentClass, slug } = require("./slide-layouts");
+const { extractConfig, buildBody, accentClass, slug, truthy } = require("./slide-layouts");
+
+// ---------------------------------------------------------------------------
+// Image inlining
+//
+// renderSlides emits `<img src>` exactly as the document wrote it, and the
+// documentation is explicit that those paths are relative to the .sdoc file.
+// A built deck, though, is a single file that gets written wherever -o says
+// and then moved, mailed and opened from somewhere else entirely, at which
+// point a relative path no longer names anything. The PDF and PPTX exporters
+// dodged this by reading the deck from a temp copy beside the input; the HTML
+// build had no such trick and silently shipped broken images whenever the
+// output went to another directory.
+//
+// Inlining resolves the paths once, against the .sdoc, and makes the question
+// of where the file ends up irrelevant for every format. It is the same thing
+// loadTheme already does for a theme's fonts and backgrounds, for the same
+// reason, and readImage in slide-pptx.js already decodes data: URIs, so the
+// PPTX export embeds them exactly as it did loose files.
+//
+// This reads from disk, so it is not part of renderSlides: the renderer stays
+// a pure AST-to-HTML function and the builder calls this afterwards.
+// ---------------------------------------------------------------------------
+
+const INLINE_IMAGE_TYPES = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".bmp": "image/bmp",
+  ".ico": "image/x-icon",
+};
+
+// Returns { html, inlined, missing }. `missing` describes every local image
+// that could not be embedded — the silent failure this exists to stop — as
+// { src, resolved, reason }, so the caller can say where it looked and not
+// just what it wanted. Naming the resolved path is what makes the rule
+// visible at the moment it bites: a deck written against a different
+// convention otherwise sees only that a file it can see plainly is "missing".
+// A remote or data: URI is neither inlined nor missing: nothing to resolve.
+function inlineDeckImages(html, baseDir) {
+  const inlined = [];
+  const missing = [];
+
+  const out = html.replace(/(<img\b[^>]*?\bsrc=")([^"]*)(")/gi, (match, pre, src, post) => {
+    const raw = src.trim();
+    if (!raw) return match;
+    // Already embedded, or somewhere this build cannot reach.
+    if (/^data:/i.test(raw)) return match;
+    if (/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(raw)) return match;
+
+    // The src sits in an HTML attribute, so entities are decoded before it is
+    // read as a path, and any ?query or #fragment dropped.
+    const decoded = raw
+      .replace(/&amp;/g, "&")
+      .replace(/&#39;/g, "'")
+      .replace(/&quot;/g, '"')
+      .replace(/[?#].*$/, "");
+
+    let filePath;
+    try {
+      filePath = path.isAbsolute(decoded)
+        ? decoded
+        : path.resolve(baseDir, decodeURIComponent(decoded));
+    } catch {
+      filePath = path.isAbsolute(decoded) ? decoded : path.resolve(baseDir, decoded);
+    }
+
+    const ext = path.extname(filePath).toLowerCase();
+    const mime = INLINE_IMAGE_TYPES[ext];
+    if (!mime) {
+      missing.push({ src: decoded, resolved: filePath, reason: "unsupported-type" });
+      return match;
+    }
+
+    let data;
+    try {
+      data = fs.readFileSync(filePath);
+    } catch {
+      missing.push({ src: decoded, resolved: filePath, reason: "not-found" });
+      return match;
+    }
+
+    inlined.push(decoded);
+    return `${pre}data:${mime};base64,${data.toString("base64")}${post}`;
+  });
+
+  return { html: out, inlined, missing };
+}
 
 // ---------------------------------------------------------------------------
 // Inline rendering — produces clean HTML without sdoc-* classes
@@ -211,6 +304,23 @@ function extractDetails(children) {
   return { details, contentNodes: rest };
 }
 
+// Whether a slide scope carries `optional: true`.
+//
+// Optional-ness is a slide *property*, not a scope type: a heading carries one
+// `:type` annotation and a drilldown has already spent it on `:detail`, so a
+// detail slide could not also be annotated optional. Reading it off the
+// configuration run keeps the two orthogonal — every combination of
+// spine/detail and required/optional is expressible.
+//
+// The details are pulled out first and the config read without a parent
+// layout, exactly as renderSlide() does it, so this answer and the one the
+// slide renders under can never disagree.
+function isOptionalSlide(scope) {
+  const { contentNodes } = extractDetails(scope.children || []);
+  const { config } = extractConfig(contentNodes);
+  return truthy(config.optional);
+}
+
 // ---------------------------------------------------------------------------
 // Slide rendering
 // ---------------------------------------------------------------------------
@@ -246,6 +356,11 @@ function renderSlide(scope, slideIndex, overlayHtml, position) {
   if (position && position.detail > 0) {
     classes.push("slide-detail");
   }
+  // Present in the HTML build, which is the presenting format; dropped before
+  // this point when the deck is rendered for PDF or PPTX export.
+  if (truthy(config.optional)) {
+    classes.push("slide-optional");
+  }
 
   // On a title slide the kicker sits beneath the statement rather than above
   // it, so the eye lands on the name first.
@@ -312,7 +427,8 @@ function renderSlides(nodes, options = {}) {
     themeJs = "",
     darkMode = false,
     themeConfig = {},
-    fit = null
+    fit = null,
+    includeOptional = true
   } = options;
 
   // The design box and print page come from the theme (themes/<name>/theme.json).
@@ -371,16 +487,53 @@ function renderSlides(nodes, options = {}) {
   }
   footerParts.push(`<span class="slide-indicator">__SLIDE_INDICATOR__</span>`);
   footerParts.push(`<span class="nav-next">&rsaquo;</span>`);
-  const overlayHtml = `\n<div class="slide-footer">${footerParts.join("")}</div>`;
+
+  // The vertical pair, stacked up-over-down at bottom centre. Both are emitted
+  // on every slide and start hidden; the theme runtime turns each on only when
+  // that move exists from the slide you are actually on. That is the same
+  // contract as .nav-prev / .nav-next, and it is why these cannot be a CSS
+  // pseudo-element on a build-time class: whether you can go up or down is a
+  // property of the current position, not of the slide.
+  // One chevron path, drawn twice, mirrored for the up arrow. Text arrowheads
+  // cannot do this: U+2303 and U+2304 are not designed as a pair and measure
+  // ~26% apart in ink width, and because few fonts carry either codepoint the
+  // metrics come from whatever the OS falls back to — so the mismatch is not
+  // even consistent between platforms. A path is identical by construction
+  // everywhere. The viewBox is symmetric about its own centre (y spans
+  // 1.25..5.75 of 7), so the mirrored copy occupies the same box.
+  const chevronSvg =
+    `<svg viewBox="0 0 12 7" aria-hidden="true" focusable="false">` +
+    `<path d="M1 1.25 L6 5.75 L11 1.25" fill="none" stroke="currentColor" ` +
+    `stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/></svg>`;
+  const vertNavHtml =
+    `\n<div class="nav-vert">` +
+    `<span class="nav-up">${chevronSvg}</span>` +
+    `<span class="nav-down">${chevronSvg}</span>` +
+    `</div>`;
+  const overlayHtml = `\n<div class="slide-footer">${footerParts.join("")}</div>${vertNavHtml}`;
+
+  // Optional slides are for the room, not the file that gets sent on. They are
+  // kept in the HTML build (includeOptional defaults to true, so every existing
+  // caller sees the deck it saw before) and dropped here when a deck is
+  // rendered for export. Dropping them before numbering — rather than hiding
+  // them later in print CSS — is what keeps the indicator honest: the
+  // denominator counts the spine slides the reader actually has.
+  //
+  // An optional spine takes its details with it. A detail belongs to its spine;
+  // there is nowhere for it to go once the spine is gone.
+  const kept = includeOptional ? slides : slides.filter((s) => !isOptionalSlide(s));
 
   // Build a flat emission order: each spine slide, followed immediately by its
   // :detail children in source order. The flat order matches what we want for
   // PDF export, so PDF needs no special case.
-  const totalSpines = slides.length;
+  const totalSpines = kept.length;
   const emitted = [];
-  slides.forEach((scope, i) => {
+  kept.forEach((scope, i) => {
     const spineIndex = i + 1; // 1-based
-    const { details } = extractDetails(scope.children);
+    const { details: allDetails } = extractDetails(scope.children);
+    const details = includeOptional
+      ? allDetails
+      : allDetails.filter((d) => !isOptionalSlide(d));
     emitted.push({
       scope,
       position: {
@@ -465,6 +618,43 @@ function renderSlides(nodes, options = {}) {
   cursor: pointer; pointer-events: auto;
   user-select: none;
 }
+/* Vertical drilldown pair. The container is anchored by its bottom edge and
+   grows upward, so .nav-down keeps the exact position the old pseudo-element
+   chevron had and .nav-up stacks above it. */
+.nav-vert {
+  position: absolute;
+  /* 16px, not 18px: the old chevron was a text glyph whose ink ran to the
+     bottom of its line box, so an 18px box offset put the visible mark 18px
+     up. The SVG carries a little padding below the stroke, so the box sits
+     2px lower to land the mark in the same place. Measured, not guessed. */
+  bottom: 16px; left: 50%;
+  transform: translateX(-50%);
+  display: flex; flex-direction: column; align-items: center;
+  /* The two arrows are sized by their own boxes now, not by a line box with
+     leading around a small glyph, which is where the old slack came from. */
+  gap: 0.42em;
+  line-height: 0;
+  pointer-events: none;
+}
+.nav-up, .nav-down {
+  /* Hidden until a runtime turns them on. A custom theme.js written before
+     these elements existed does not know to hide them, and a dead arrowhead
+     on every slide is worse than no arrowhead at all, so the safe state is
+     the default and the runtime opts in. */
+  visibility: hidden;
+  display: block;
+  font-size: 1.2em; color: #ccc;
+  cursor: pointer; pointer-events: auto;
+  user-select: none;
+}
+.nav-up svg, .nav-down svg {
+  display: block;
+  width: 0.62em; height: auto;
+  stroke: currentColor;
+}
+/* The mirror. Same path, flipped about its own centre, so the pair matches to
+   the pixel whatever font or platform the deck is presented on. */
+.nav-up svg { transform: scaleY(-1); }
 .sdoc-company-footer {
   font-size: 0.7em; color: rgba(0,0,0,0.35);
   letter-spacing: 0.04em;
@@ -524,6 +714,7 @@ function renderSlides(nodes, options = {}) {
     transform-origin: top left;
   }
   .nav-prev, .nav-next { display: none !important; }
+  .nav-vert { display: none !important; }
   .notes { display: none; }
 }`;
 
@@ -540,6 +731,7 @@ p code, li code { background: rgba(255, 255, 255, 0.08); }
 blockquote { border-left-color: #5b9bd5; color: #9d9d9d; }
 blockquote p { color: #9d9d9d; }
 .nav-prev, .nav-next { color: rgba(255, 255, 255, 0.7); }
+.nav-up, .nav-down { color: rgba(255, 255, 255, 0.5); }
 .sdoc-company-footer { color: rgba(255, 255, 255, 0.35); }
 .sdoc-confidential-notice { color: rgba(235, 120, 120, 0.7); }
 .slide-indicator { color: rgba(255, 255, 255, 0.35); }
@@ -573,4 +765,4 @@ ${jsTag}${mermaidTag}
 </html>`;
 }
 
-module.exports = { renderSlides, renderSlide, renderNode, renderInline };
+module.exports = { renderSlides, renderSlide, renderNode, renderInline, isOptionalSlide, inlineDeckImages };

package/src/theme.js

@@ -100,6 +100,44 @@ function readThemeConfig(themeDir) {
   }
 }
 
+// The drilldown chevron used to be a pseudo-element on .slide-has-details.
+// It is now two real elements, .nav-up and .nav-down, which the runtime shows
+// and hides per position. A theme derived from the default before that change
+// still carries the old rule, and the old rule still renders: `content` on
+// .slide-has-details::after paints a chevron of its own whatever the renderer
+// emits. The result is two chevrons a few pixels apart on every spine slide
+// that has details, and nothing in the build otherwise notices, because the
+// duplicate is in the theme and the original is in the renderer.
+//
+// Only a rule that actually paints something is worth warning about, so a
+// `content` of none/normal/empty is left alone.
+const NO_CONTENT = new Set(["none", "normal", '""', "''"]);
+
+function staleChevronWarnings(css) {
+  // Comments first: a theme that merely *documents* the old rule is fine.
+  const stripped = css.replace(/\/\*[\s\S]*?\*\//g, "");
+  const warnings = [];
+  // Innermost declaration blocks: the selector cannot contain braces, so this
+  // also reaches rules nested inside @media without tripping on the wrapper.
+  const rule = /([^{}]*)\{([^{}]*)\}/g;
+  let match;
+  while ((match = rule.exec(stripped)) !== null) {
+    const selector = match[1];
+    if (!/\.slide-has-details\s*::?after\b/.test(selector)) continue;
+    const content = /(?:^|[;{\s])content\s*:\s*([^;]+)/i.exec(match[2]);
+    if (!content) continue;
+    if (NO_CONTENT.has(content[1].trim().toLowerCase())) continue;
+    warnings.push(
+      "theme still draws the old drilldown chevron with " +
+      "`.slide-has-details::after { content: ... }`. That is now a duplicate of " +
+      ".nav-down, which the renderer emits and the runtime drives, so spine " +
+      "slides with details show two chevrons. Remove the rule from the theme."
+    );
+    break; // one rule is enough to say it; listing every copy adds no information
+  }
+  return warnings;
+}
+
 // Reads a theme directory. `fallbackDir` supplies theme.js when the theme
 // ships none, which is how a theme opts into the default runtime (keyboard
 // navigation, touch, fit-to-window scaling) without copying it.
@@ -122,6 +160,7 @@ function loadTheme(themeDir, fallbackDir) {
     for (const ref of missing) {
       warnings.push(`theme asset not found, left as a plain reference: ${ref}`);
     }
+    warnings.push(...staleChevronWarnings(raw));
   } else {
     warnings.push(`theme.css not found at ${cssPath}`);
   }
@@ -138,4 +177,4 @@ function loadTheme(themeDir, fallbackDir) {
   return { themeCss, themeJs, themeConfig, warnings, dir: resolved };
 }
 
-module.exports = { loadTheme, inlineCssAssets, readThemeConfig, DEFAULT_THEME_CONFIG };
+module.exports = { loadTheme, inlineCssAssets, readThemeConfig, staleChevronWarnings, DEFAULT_THEME_CONFIG };