@entropicwarrior/sdoc 0.2.17 → 0.2.19

package/src/slide-renderer.js

@@ -8,6 +8,7 @@
 //   const html = renderSlides(nodes, { meta, themeCss, themeJs });
 
 const { parseInline, renderKatex, escapeHtml, escapeAttr, sanitizeSvg, colorSwatchHtml } = require("./sdoc");
+const { extractConfig, buildBody, accentClass, slug } = require("./slide-layouts");
 
 // ---------------------------------------------------------------------------
 // Inline rendering — produces clean HTML without sdoc-* classes
@@ -164,35 +165,18 @@ function renderChildren(nodes) {
   return nodes.map((node) => renderNode(node)).join("\n");
 }
 
+// Callbacks handed to the layout builders so slide-layouts.js stays free of
+// parser and KaTeX dependencies.
+const LAYOUT_CONTEXT = { renderChildren, renderInline, escapeHtml };
+
+// Layouts whose bare name is also emitted as a slide class, for themes written
+// before `layout-*` existed. New layouts are not added here.
+const LEGACY_LAYOUT_CLASSES = new Set(["center", "two-column"]);
+
 // ---------------------------------------------------------------------------
 // Slide-level extraction
 // ---------------------------------------------------------------------------
 
-// Extracts config: lines from the beginning of a scope's children.
-// Returns { config: { key: value, ... }, contentNodes: [...] }
-function extractSlideConfig(children) {
-  const config = {};
-  const contentNodes = [];
-  let pastConfig = false;
-
-  for (const child of children) {
-    if (!pastConfig && child.type === "paragraph") {
-      const match = child.text.match(/^config\s*:\s*(.+)$/i);
-      if (match) {
-        const value = match[1].trim();
-        // Support multiple config lines; last one wins for the same key
-        // For now, config values are simple strings; primary use is layout
-        config.layout = value;
-        continue;
-      }
-    }
-    pastConfig = true;
-    contentNodes.push(child);
-  }
-
-  return { config, contentNodes };
-}
-
 // Separates @notes child scope from other children
 function extractNotes(children) {
   const notes = [];
@@ -237,13 +221,25 @@ function renderSlide(scope, slideIndex, overlayHtml, position) {
   // Pull :detail children out first so they don't appear inline in the spine
   // slide's content; they're rendered as sibling vertical slides instead.
   const { contentNodes: afterDetails } = extractDetails(scope.children);
-  const { config, contentNodes: afterConfig } = extractSlideConfig(afterDetails);
+  const { config, contentNodes: afterConfig } = extractConfig(afterDetails);
   const { notes, contentNodes } = extractNotes(afterConfig);
 
+  const layout = config.layout || "";
   const classes = ["slide"];
-  if (config.layout) {
-    classes.push(config.layout);
+  if (layout) {
+    // `layout-*` is the class themes target. The bare layout name is emitted
+    // only for the two layouts that predate it, because themes in the wild
+    // are written against `.center` and `.two-column`. It is not emitted for
+    // the structured layouts: those put a container class of the same name
+    // inside the slide (`.columns`, `.stats`, `.rows`…), and a slide also
+    // carrying that class would match the container's own rules.
+    if (LEGACY_LAYOUT_CLASSES.has(layout)) classes.push(layout);
+    // Slugged, so no configuration value can close the class attribute.
+    const layoutSlug = slug(layout);
+    if (layoutSlug) classes.push(`layout-${layoutSlug}`);
   }
+  const accent = accentClass(config.accent).trim();
+  if (accent) classes.push(accent);
   if (position && position.detail === 0 && position.hasDetails) {
     classes.push("slide-has-details");
   }
@@ -251,29 +247,33 @@ function renderSlide(scope, slideIndex, overlayHtml, position) {
     classes.push("slide-detail");
   }
 
-  const title = scope.hasHeading !== false && scope.title
-    ? `<h2>${renderInline(scope.title)}</h2>`
+  // On a title slide the kicker sits beneath the statement rather than above
+  // it, so the eye lands on the name first.
+  const isTitleLayout = layout === "title";
+  const kickerHtml = config.kicker
+    ? `<div class="kicker">${renderInline(config.kicker)}</div>`
     : "";
 
-  let bodyHtml;
-  if (config.layout === "two-column") {
-    // In two-column layout, child scopes become columns
-    const columns = contentNodes.filter((n) => n.type === "scope" && n.scopeType !== "comment");
-    const nonColumns = contentNodes.filter((n) => n.type !== "scope" || n.scopeType === "comment");
-    const preamble = nonColumns.length ? renderChildren(nonColumns) : "";
-    const columnsHtml = columns
-      .map((col) => {
-        const colTitle = col.hasHeading !== false && col.title
-          ? `<h3>${renderInline(col.title)}</h3>`
-          : "";
-        const colContent = renderChildren(col.children);
-        return `<div class="column">${colTitle}\n${colContent}</div>`;
-      })
-      .join("\n");
-    bodyHtml = preamble + `\n<div class="columns">\n${columnsHtml}\n</div>`;
-  } else {
-    bodyHtml = renderChildren(contentNodes);
+  const headParts = [];
+  if (kickerHtml && !isTitleLayout) headParts.push(kickerHtml);
+  if (scope.hasHeading !== false && scope.title) {
+    const tag = isTitleLayout ? "h1" : "h2";
+    headParts.push(`<${tag}>${renderInline(scope.title)}</${tag}>`);
   }
+  if (config.lede) headParts.push(`<p class="lede">${renderInline(config.lede)}</p>`);
+  const title = headParts.length
+    ? `<header class="slide-head">\n${headParts.join("\n")}\n</header>`
+    : "";
+
+  const bodyInner = buildBody(layout, { config, contentNodes }, LAYOUT_CONTEXT);
+
+  const tailParts = [];
+  if (kickerHtml && isTitleLayout) tailParts.push(kickerHtml);
+  if (config.status) tailParts.push(`<div class="status">${renderInline(config.status)}</div>`);
+  if (config.footnote) tailParts.push(`<div class="footnote">${renderInline(config.footnote)}</div>`);
+  const tailHtml = tailParts.length ? `\n${tailParts.join("\n")}` : "";
+
+  const bodyHtml = `<div class="slide-body">\n${bodyInner}\n</div>${tailHtml}`;
 
   const notesHtml = notes.length
     ? `\n<aside class="notes">${notes.map((n) => renderChildren(n.children)).join("\n")}</aside>`
@@ -310,9 +310,27 @@ function renderSlides(nodes, options = {}) {
     meta = {},
     themeCss = "",
     themeJs = "",
-    darkMode = false
+    darkMode = false,
+    themeConfig = {},
+    fit = null
   } = options;
 
+  // The design box and print page come from the theme (themes/<name>/theme.json).
+  // They must agree: the box in CSS pixels is the page in inches at 96 dpi, which
+  // is what makes screen and PDF the same geometry.
+  const slideW = (themeConfig.slide && themeConfig.slide.width) || 1280;
+  const slideH = (themeConfig.slide && themeConfig.slide.height) || 720;
+  const pageW = (themeConfig.page && themeConfig.page.width) || 13.333;
+  const pageH = (themeConfig.page && themeConfig.page.height) || 7.5;
+
+  // How the design box meets a window of a different shape.
+  //   contain — scale to fit, letterbox the remainder (the default)
+  //   cover   — scale to fill, crop the overflow
+  //   stretch — scale each axis independently, distorting the slide
+  const FIT_MODES = new Set(["contain", "cover", "stretch"]);
+  const requested = (fit || themeConfig.fit || "contain").toLowerCase();
+  const fitMode = FIT_MODES.has(requested) ? requested : "contain";
+
   // The nodes from extractMeta have @meta already stripped.
   // If there's a document scope wrapper, unwrap it to get the slides.
   let slideScopes;
@@ -322,8 +340,15 @@ function renderSlides(nodes, options = {}) {
     slideScopes = nodes;
   }
 
-  // Filter to scope nodes only (skip stray paragraphs and :comment scopes)
-  const slides = slideScopes.filter((n) => n.type === "scope" && n.scopeType !== "comment");
+  // Filter to scope nodes only (skip stray paragraphs, :comment scopes, and the
+  // reserved @meta / @about metadata scopes — these are document metadata, not slides).
+  const RESERVED_SCOPE_IDS = new Set(["meta", "about"]);
+  const slides = slideScopes.filter(
+    (n) =>
+      n.type === "scope" &&
+      n.scopeType !== "comment" &&
+      !(n.id && RESERVED_SCOPE_IDS.has(n.id.toLowerCase()))
+  );
 
   // Build per-slide footer:
   //   <  CONFIDENTIAL  ---gap---  Company  N/Total  >
@@ -387,7 +412,48 @@ function renderSlides(nodes, options = {}) {
 
   // Structural styles — always injected regardless of theme.
   const structuralCss = `
-.slide { position: relative; }
+/* --- Fixed design box + fit-to-window scaling ---------------------------
+   Slides are laid out at a fixed design size (1280x720 CSS px, which is
+   exactly the 13.333in x 7.5in print page at 96dpi) and then scaled as a
+   whole to fill the window.  This is the standard deck technique: the
+   author's layout is preserved verbatim at every window size, and screen
+   and PDF are the same geometry by construction.
+
+   --sdoc-slide-scale and --sdoc-slide-scale-y are written by the theme
+   runtime (fitSlidesToWindow in themes/default/theme.js) on load and on
+   resize, according to the fit mode on <html data-sdoc-fit>.  If JS never runs the
+   scale stays 1 and the deck renders at its natural design size, which is
+   the pre-scaling behaviour rather than a broken one.
+
+   Themes must NOT set width/height/max-width/margin on .slide — those come
+   from the design-box variables below.  A theme that wants a different
+   aspect ratio should override --sdoc-slide-w / --sdoc-slide-h on :root
+   (and the @page size in the print block, if PDF output matters). */
+:root {
+  --sdoc-slide-w: ${slideW}px;
+  --sdoc-slide-h: ${slideH}px;
+  --sdoc-slide-scale: 1;
+  /* Defaults to the horizontal scale, so a theme shipping its own runtime
+     that writes only --sdoc-slide-scale still scales uniformly. Only the
+     stretch fit mode ever sets these two to different values. */
+  --sdoc-slide-scale-y: var(--sdoc-slide-scale);
+  /* The ground behind the slide, seen wherever the window is not the slide's
+     shape. A theme that leaves this equal to its slide background gets an
+     invisible letterbox: the slide has no edge and anything pinned to its
+     bottom looks stranded. */
+  --sdoc-letterbox: #000;
+}
+.slide {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: var(--sdoc-slide-w);
+  height: var(--sdoc-slide-h);
+  transform: translate(-50%, -50%)
+             scale(var(--sdoc-slide-scale), var(--sdoc-slide-scale-y));
+  transform-origin: center center;
+  overflow: hidden;
+}
 .slide-footer {
   position: absolute; bottom: 20px; left: 32px; right: 32px;
   display: flex; align-items: baseline;
@@ -424,8 +490,15 @@ function renderSlides(nodes, options = {}) {
    beforeprint handler to shrink overflowing content to fit the page. */
 .slide-content-scale { display: contents; }
 
+/* Head and body wrappers are transparent to layout by default, so a theme
+   written before they existed sees exactly the box tree it saw then: the
+   heading and the content as direct children of the slide.  A theme that
+   wants a real header band or a body that fills the remaining height
+   overrides these two rules. */
+.slide-head, .slide-body { display: contents; }
+
 @media print {
-  @page { size: 13.333in 7.5in; margin: 0; }
+  @page { size: ${pageW}in ${pageH}in; margin: 0; }
   body { overflow: visible; height: auto; }
   .slide {
     display: block !important;
@@ -433,7 +506,14 @@ function renderSlides(nodes, options = {}) {
     opacity: 1 !important;
     pointer-events: auto !important;
     page-break-after: always; break-after: page;
-    width: 100vw; height: 100vh; max-width: none;
+    /* The design box IS the page (the theme's px box at 96dpi),
+       so no fit-to-window scaling applies here — each slide flows as one
+       page at its natural size.  Overflowing content is still shrunk by
+       the inner .slide-content-scale wrapper (see fitSlidesForPrint). */
+    top: auto !important; left: auto !important;
+    transform: none !important;
+    margin: 0 !important;
+    width: var(--sdoc-slide-w); height: var(--sdoc-slide-h); max-width: none;
     overflow: hidden;
     page-break-inside: avoid; break-inside: avoid;
   }
@@ -478,7 +558,7 @@ blockquote p { color: #9d9d9d; }
     : "";
 
   return `<!DOCTYPE html>
-<html lang="en">
+<html lang="en" data-sdoc-fit="${fitMode}">
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">

package/src/theme.js

@@ -0,0 +1,141 @@
+// SDOC Slides — theme loading.
+//
+// A theme is a directory holding `theme.css`, optionally `theme.js`, and
+// optionally assets the CSS refers to: web fonts, background images, textures.
+//
+// Loading a theme inlines those assets. Every `url(...)` in the stylesheet
+// that names a path relative to the theme directory is replaced by a `data:`
+// URI, so the built deck stays a single self-contained file that renders the
+// same offline, on another machine, and inside headless Chrome during PDF
+// export. Absolute URLs, protocol-relative URLs and existing `data:` URIs are
+// left alone.
+
+const fs = require("fs");
+const path = require("path");
+
+const MIME_TYPES = {
+  ".woff2": "font/woff2",
+  ".woff": "font/woff",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".eot": "application/vnd.ms-fontobject",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+};
+
+function isExternal(url) {
+  return /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(url);
+}
+
+// Replaces relative url(...) references in `css` with data: URIs read from
+// `baseDir`. Returns { css, inlined, missing }.
+function inlineCssAssets(css, baseDir) {
+  const inlined = [];
+  const missing = [];
+
+  const out = css.replace(/url\(\s*(['"]?)([^'")]+)\1\s*\)/gi, (match, _quote, url) => {
+    const target = url.trim();
+    if (!target || isExternal(target)) return match;
+
+    // Strip any ?query or #fragment before resolving against the file system.
+    const clean = target.replace(/[?#].*$/, "");
+    const filePath = path.resolve(baseDir, clean);
+
+    // Refuse to read outside the theme directory.
+    const relative = path.relative(baseDir, filePath);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+      missing.push(target);
+      return match;
+    }
+
+    if (!fs.existsSync(filePath)) {
+      missing.push(target);
+      return match;
+    }
+
+    const mime = MIME_TYPES[path.extname(filePath).toLowerCase()] || "application/octet-stream";
+    const data = fs.readFileSync(filePath).toString("base64");
+    inlined.push(relative);
+    return `url("data:${mime};base64,${data}")`;
+  });
+
+  return { css: out, inlined, missing };
+}
+
+// The design box and print page a theme uses when it declares none.
+// 1280 x 720 CSS px is exactly 13.333 x 7.5 in at 96 dpi, so screen and PDF
+// are the same geometry by construction.
+const DEFAULT_THEME_CONFIG = {
+  slide: { width: 1280, height: 720 },
+  page: { width: 13.333, height: 7.5 },
+  // How the slide meets a window of a different shape: contain, cover or
+  // stretch. The CLI's --fit overrides whatever a theme declares.
+  fit: "contain",
+};
+
+function readThemeConfig(themeDir) {
+  const jsonPath = path.join(themeDir, "theme.json");
+  if (!fs.existsSync(jsonPath)) return { config: { ...DEFAULT_THEME_CONFIG }, warning: null };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(jsonPath, "utf-8"));
+    return {
+      config: {
+        fit: DEFAULT_THEME_CONFIG.fit,
+        ...parsed,
+        slide: { ...DEFAULT_THEME_CONFIG.slide, ...(parsed.slide || {}) },
+        page: { ...DEFAULT_THEME_CONFIG.page, ...(parsed.page || {}) },
+      },
+      warning: null,
+    };
+  } catch (err) {
+    return {
+      config: { ...DEFAULT_THEME_CONFIG },
+      warning: `theme.json could not be parsed (${err.message}); using the default design box`,
+    };
+  }
+}
+
+// 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.
+function loadTheme(themeDir, fallbackDir) {
+  const resolved = path.resolve(themeDir);
+  const cssPath = path.join(resolved, "theme.css");
+  const jsPath = path.join(resolved, "theme.js");
+
+  const warnings = [];
+  let themeCss = "";
+  let themeJs = "";
+
+  const { config: themeConfig, warning: configWarning } = readThemeConfig(resolved);
+  if (configWarning) warnings.push(configWarning);
+
+  if (fs.existsSync(cssPath)) {
+    const raw = fs.readFileSync(cssPath, "utf-8");
+    const { css, missing } = inlineCssAssets(raw, resolved);
+    themeCss = css;
+    for (const ref of missing) {
+      warnings.push(`theme asset not found, left as a plain reference: ${ref}`);
+    }
+  } else {
+    warnings.push(`theme.css not found at ${cssPath}`);
+  }
+
+  if (fs.existsSync(jsPath)) {
+    themeJs = fs.readFileSync(jsPath, "utf-8");
+  } else if (fallbackDir) {
+    const fallbackJs = path.join(path.resolve(fallbackDir), "theme.js");
+    if (fs.existsSync(fallbackJs)) {
+      themeJs = fs.readFileSync(fallbackJs, "utf-8");
+    }
+  }
+
+  return { themeCss, themeJs, themeConfig, warnings, dir: resolved };
+}
+
+module.exports = { loadTheme, inlineCssAssets, readThemeConfig, DEFAULT_THEME_CONFIG };

package/src/zip.js

@@ -0,0 +1,102 @@
+// SDOC — minimal ZIP writer.
+//
+// Enough of the format to build an OOXML package: stored or deflated entries,
+// local headers, a central directory and an end-of-central-directory record.
+// Node's zlib supplies the compression, so this stays dependency-free.
+
+const zlib = require("zlib");
+
+const CRC_TABLE = (() => {
+  const table = new Int32Array(256);
+  for (let i = 0; i < 256; i++) {
+    let c = i;
+    for (let k = 0; k < 8; k++) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    table[i] = c;
+  }
+  return table;
+})();
+
+function crc32(buffer) {
+  let crc = -1;
+  for (let i = 0; i < buffer.length; i++) {
+    crc = (crc >>> 8) ^ CRC_TABLE[(crc ^ buffer[i]) & 0xff];
+  }
+  return (crc ^ -1) >>> 0;
+}
+
+// Fixed timestamp so the same input produces the same archive byte for byte.
+const DOS_TIME = 0; // 00:00:00
+const DOS_DATE = (1980 - 1980) << 9 | (1 << 5) | 1; // 1980-01-01
+
+// files: [{ name, data: Buffer|string, store?: boolean }]
+function zip(files) {
+  const locals = [];
+  const central = [];
+  let offset = 0;
+
+  for (const file of files) {
+    const nameBuf = Buffer.from(file.name, "utf-8");
+    const raw = Buffer.isBuffer(file.data) ? file.data : Buffer.from(file.data, "utf-8");
+    const crc = crc32(raw);
+
+    // Already-compressed payloads (PNG, JPEG, woff2) gain nothing from
+    // deflate and cost time, so they go in stored.
+    const store = file.store === true;
+    const body = store ? raw : zlib.deflateRawSync(raw, { level: 9 });
+    const method = store ? 0 : 8;
+
+    const localHeader = Buffer.alloc(30);
+    localHeader.writeUInt32LE(0x04034b50, 0);
+    localHeader.writeUInt16LE(20, 4); // version needed
+    localHeader.writeUInt16LE(0, 6); // flags
+    localHeader.writeUInt16LE(method, 8);
+    localHeader.writeUInt16LE(DOS_TIME, 10);
+    localHeader.writeUInt16LE(DOS_DATE, 12);
+    localHeader.writeUInt32LE(crc, 14);
+    localHeader.writeUInt32LE(body.length, 18);
+    localHeader.writeUInt32LE(raw.length, 22);
+    localHeader.writeUInt16LE(nameBuf.length, 26);
+    localHeader.writeUInt16LE(0, 28); // extra length
+
+    locals.push(localHeader, nameBuf, body);
+
+    const centralHeader = Buffer.alloc(46);
+    centralHeader.writeUInt32LE(0x02014b50, 0);
+    centralHeader.writeUInt16LE(20, 4); // version made by
+    centralHeader.writeUInt16LE(20, 6); // version needed
+    centralHeader.writeUInt16LE(0, 8);
+    centralHeader.writeUInt16LE(method, 10);
+    centralHeader.writeUInt16LE(DOS_TIME, 12);
+    centralHeader.writeUInt16LE(DOS_DATE, 14);
+    centralHeader.writeUInt32LE(crc, 16);
+    centralHeader.writeUInt32LE(body.length, 20);
+    centralHeader.writeUInt32LE(raw.length, 24);
+    centralHeader.writeUInt16LE(nameBuf.length, 28);
+    centralHeader.writeUInt16LE(0, 30); // extra
+    centralHeader.writeUInt16LE(0, 32); // comment
+    centralHeader.writeUInt16LE(0, 34); // disk
+    centralHeader.writeUInt16LE(0, 36); // internal attrs
+    centralHeader.writeUInt32LE(0, 38); // external attrs
+    centralHeader.writeUInt32LE(offset, 42);
+
+    central.push(centralHeader, nameBuf);
+    offset += localHeader.length + nameBuf.length + body.length;
+  }
+
+  const centralBuf = Buffer.concat(central);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(0, 4);
+  end.writeUInt16LE(0, 6);
+  end.writeUInt16LE(files.length, 8);
+  end.writeUInt16LE(files.length, 10);
+  end.writeUInt32LE(centralBuf.length, 12);
+  end.writeUInt32LE(offset, 16);
+  end.writeUInt16LE(0, 20);
+
+  return Buffer.concat([...locals, centralBuf, end]);
+}
+
+module.exports = { zip, crc32 };