gutterpress 0.10.9-beta.1 → 0.10.9

package/dist/{cli-vhdvkqdd.js → cli-8pg731p5.js}

@@ -13,12 +13,12 @@ import {
   stampCreator,
   stripAnnotations,
   warn
-} from "./cli-fwh6rkev.js";
+} from "./cli-ypfvnhag.js";
 import {
   DEBOUNCE,
   UsageError,
   resolvePort
-} from "./cli-0tgbgwnj.js";
+} from "./cli-rh05byck.js";
 import {
   MARGIN_BOX_IGNORED_PROPERTIES,
   RENDER_TIMEOUT_MS,
@@ -1247,26 +1247,54 @@ function targetsPageWrapper(selector) {
     return false;
   return !/\bgp-(bleed|pin)\b/.test(selector);
 }
+var cssWideResetKeywords = new Set(["initial", "unset", "revert", "revert-layer"]);
+var inertValues = {
+  "z-index": new Set(["auto"]),
+  opacity: new Set(["1", "100%"]),
+  "mix-blend-mode": new Set(["normal"]),
+  "background-blend-mode": new Set(["normal"]),
+  filter: new Set(["none"]),
+  "backdrop-filter": new Set(["none"]),
+  transform: new Set(["none"]),
+  rotate: new Set(["none"]),
+  translate: new Set(["none"]),
+  scale: new Set(["none"]),
+  perspective: new Set(["none"]),
+  "box-shadow": new Set(["none"]),
+  outline: new Set(["none"]),
+  "outline-style": new Set(["none"]),
+  "will-change": new Set(["auto", "none"]),
+  "clip-path": new Set(["none"]),
+  transition: new Set(["none"]),
+  animation: new Set(["none"]),
+  "animation-name": new Set(["none"]),
+  overflow: new Set(["visible"]),
+  "overflow-x": new Set(["visible"]),
+  "overflow-y": new Set(["visible"])
+};
+function isInertValue(prop, value) {
+  const v = value.trim().toLowerCase();
+  return cssWideResetKeywords.has(v) || (inertValues[prop]?.has(v) ?? false);
+}
 function createsStackingContext(decl) {
   const p = decl.prop.toLowerCase();
   const v = decl.value.trim().toLowerCase();
+  if (isInertValue(p, v))
+    return false;
   switch (p) {
-    case "z-index":
-      return v !== "auto" && v !== "initial" && v !== "unset";
     case "isolation":
       return v === "isolate";
+    case "contain":
+      return /\b(paint|layout|strict|content)\b/.test(v);
+    case "z-index":
     case "opacity":
-      return v !== "1" && v !== "100%" && v !== "initial" && v !== "unset";
     case "mix-blend-mode":
-      return v !== "normal" && v !== "initial" && v !== "unset";
     case "filter":
     case "backdrop-filter":
     case "transform":
     case "perspective":
     case "will-change":
-      return v !== "none" && v !== "initial" && v !== "unset";
-    case "contain":
-      return /\b(paint|layout|strict|content)\b/.test(v);
+      return true;
     default:
       return false;
   }
@@ -1276,7 +1304,7 @@ function clipsDescendants(decl) {
   if (p !== "overflow" && p !== "overflow-x" && p !== "overflow-y")
     return false;
   const v = decl.value.trim().toLowerCase();
-  return v !== "" && !/^(visible|initial|unset|revert)$/.test(v);
+  return v !== "" && !isInertValue(p, v);
 }
 function nodeLoc(node) {
   return {
@@ -1317,6 +1345,8 @@ function checkCss(css, from) {
   root.walkAtRules((at) => reportRemoteUrls(at.params || "", at));
   root.walkDecls((decl) => {
     const prop = decl.prop.toLowerCase();
+    if (isInertValue(prop, decl.value))
+      return;
     if (marginBoxIgnoredProperties.has(prop) && isInPageMarginBox(decl)) {
       warnings.push({
         rule: ruleRiskyProps,
@@ -4169,7 +4199,8 @@ async function runLint(opts = {}) {
     linted++;
     const warnings = checkCss(css, file);
     const errors = warnings.filter((w) => w.severity === "error");
-    riskyCount += warnings.filter((w) => w.rule === ruleRiskyProps).length;
+    const risky = warnings.filter((w) => w.rule === ruleRiskyProps);
+    riskyCount += risky.length;
     if (errors.length > 0) {
       log.error(`  ${file}`);
       for (const w of errors) {
@@ -4177,6 +4208,12 @@ async function runLint(opts = {}) {
       }
       errorCount += errors.length;
     }
+    if (risky.length > 0) {
+      log.warn(`  ${file}`);
+      for (const w of risky) {
+        log.warn(`    ${w.line}:${w.column}  ${w.message}  (${w.rule})`);
+      }
+    }
   }
   if (errorCount > 0) {
     log.error("CSS lint errors found");
@@ -4184,7 +4221,6 @@ async function runLint(opts = {}) {
   }
   if (riskyCount > 0) {
     log.warn(`${riskyCount} risky print properties found (may cause rasterization)`);
-    log.warn("The validator will check for actual rasterized pages after PDF generation.");
   } else {
     log.success("CSS lint passed");
   }
@@ -5752,7 +5788,6 @@ registerCheck(check19);
 
 // src/checks/source/local-refs.ts
 import { existsSync as existsSync8 } from "node:fs";
-import { readFile as readFile13 } from "node:fs/promises";
 import { dirname as dirname3, resolve as resolve6 } from "node:path";
 
 // src/lib/asset-inline.ts
@@ -6060,6 +6095,7 @@ async function inlineShapeUrls(html, baseDir) {
 }
 
 // src/checks/source/local-ref-parser.ts
+import { readFile as readFile13 } from "node:fs/promises";
 function newlineOffsets(content) {
   const offsets = [];
   for (let i = 0;i < content.length; i++)
@@ -6104,7 +6140,7 @@ function createRenderedLocalRefCollector(customPlugins) {
         if (!kind)
           continue;
         const ref = child.attrGet(kind === "image" ? "src" : "href");
-        if (!ref)
+        if (ref === null)
           continue;
         const offset = tokenOffsets.get(child);
         refs.push({
@@ -6117,6 +6153,26 @@ function createRenderedLocalRefCollector(customPlugins) {
     return refs;
   };
 }
+async function* renderedLocalRefs(ctx, checkId, results) {
+  const files = (ctx.markdownFiles ?? []).slice().sort();
+  if (files.length === 0)
+    return;
+  const plugins = await loadPlugins(ctx.config.extensions, ctx.inputDir, (ref, error2) => {
+    results.push(inspectionFailed(checkId, `Plugin "${ref}" could not be loaded, so local references it defines were not checked: ${error2.message}`));
+  });
+  const collectRenderedLocalRefs = createRenderedLocalRefCollector(plugins);
+  for (const file of files) {
+    let refs;
+    try {
+      refs = collectRenderedLocalRefs(await readFile13(file, "utf8"));
+    } catch {
+      results.push(inspectionFailed(checkId, `Could not read source file: ${file}`, { file }));
+      continue;
+    }
+    for (const ref of refs)
+      yield { ...ref, file };
+  }
+}
 
 // src/checks/source/local-refs.ts
 var check20 = {
@@ -6126,45 +6182,29 @@ var check20 = {
   category: "source",
   phase: "pre-build",
   async run(ctx) {
-    const files = (ctx.markdownFiles ?? []).slice().sort();
-    if (files.length === 0)
-      return [];
     const results = [];
-    const plugins = await loadPlugins(ctx.config.extensions, ctx.inputDir, (ref, error2) => {
-      results.push(inspectionFailed(check20.id, `Plugin "${ref}" could not be loaded, so local references it defines were not checked: ${error2.message}`));
-    });
-    const collectRenderedLocalRefs = createRenderedLocalRefCollector(plugins);
-    for (const file of files) {
-      try {
-        const content = await readFile13(file, "utf8");
-        for (const { ref, kind, line } of collectRenderedLocalRefs(content)) {
-          if (isNonFilesystemRef(ref))
-            continue;
-          const escape = kind === "image" ? proseImageRefError(ref, ctx.inputDir) : null;
-          if (escape) {
-            results.push(finding(check20.id, {
-              severity: "error",
-              message: escape,
-              file,
-              line
-            }));
-            continue;
-          }
-          if (localRefExists(ref, kind, file, ctx.inputDir))
-            continue;
-          results.push(finding(check20.id, {
-            severity: kind === "image" ? "warning" : "error",
-            code: kind === "image" ? "missing-image-placeholder" : undefined,
-            message: kind === "image" ? `Local image not found; build will substitute a magenta placeholder: ${ref}` : `Local reference not found: ${ref}`,
-            file,
-            line
-          }));
-        }
-      } catch {
-        results.push(inspectionFailed(check20.id, `Could not read source file: ${file}`, {
-          file
+    for await (const { ref, kind, line, file } of renderedLocalRefs(ctx, check20.id, results)) {
+      if (isNonFilesystemRef(ref))
+        continue;
+      const escape = kind === "image" ? proseImageRefError(ref, ctx.inputDir) : null;
+      if (escape) {
+        results.push(finding(check20.id, {
+          severity: "error",
+          message: escape,
+          file,
+          line
         }));
+        continue;
       }
+      if (localRefExists(ref, kind, file, ctx.inputDir))
+        continue;
+      results.push(finding(check20.id, {
+        severity: kind === "image" ? "warning" : "error",
+        code: kind === "image" ? "missing-image-placeholder" : undefined,
+        message: kind === "image" ? `Local image not found; build will substitute a magenta placeholder: ${ref}` : `Local reference not found: ${ref}`,
+        file,
+        line
+      }));
     }
     return results;
   }
@@ -6185,71 +6225,360 @@ function localRefExists(ref, kind, sourceFile, projectRoot) {
 }
 registerCheck(check20);
 
-// src/checks/source/accessibility-alt-text.ts
-import { readFile as readFile14 } from "node:fs/promises";
-var check21 = {
-  id: "source.accessibility.alt-text",
-  name: "Image Alt Text",
-  description: "Checks markdown images include non-empty alt text",
-  category: "source",
-  phase: "pre-build",
-  async run(ctx) {
-    const files = (ctx.markdownFiles ?? []).slice().sort();
-    if (files.length === 0)
-      return [];
-    const results = [];
-    for (const file of files) {
-      try {
-        const content = await readFile14(file, "utf8");
-        const lines = content.split(`
-`);
-        let inFence = false;
-        for (let i = 0;i < lines.length; i++) {
-          const line = lines[i] ?? "";
-          if (/^\s*(```|~~~)/.test(line)) {
-            inFence = !inFence;
+// src/lib/build-staging.ts
+import path5 from "node:path";
+import os from "node:os";
+import fsp from "node:fs/promises";
+
+// src/lib/missing-asset-placeholder.ts
+import { createHash as createHash4 } from "node:crypto";
+import { deflateSync } from "node:zlib";
+function placeholderOutputPath(missingOutputPath) {
+  const hash = createHash4("sha256").update(missingOutputPath).digest("hex").slice(0, 16);
+  return `assets/gutterpress-missing/${hash}.png`;
+}
+function decodeHtmlAttribute(value) {
+  return value.replace(/&quot;/g, '"').replace(/&#39;|&apos;/g, "'").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+}
+function rewriteMissingImageReferences(html, replacements) {
+  if (replacements.size === 0)
+    return html;
+  const replacementFor = (raw) => replacements.get(raw) ?? replacements.get(decodeHtmlAttribute(raw));
+  const cssUrl = /url\(\s*(?:"([^"]*)"|'([^']*)'|&quot;((?:(?!&quot;).)*)&quot;|([^'"()\s]*))\s*\)/giy;
+  const rewriteCssUrls = (css) => {
+    let out = "";
+    let copiedThrough = 0;
+    let index = 0;
+    while (index < css.length) {
+      if (css.startsWith("/*", index)) {
+        const end = css.indexOf("*/", index + 2);
+        index = end < 0 ? css.length : end + 2;
+        continue;
+      }
+      const char = css[index];
+      if (char === '"' || char === "'") {
+        const quote = char;
+        index++;
+        while (index < css.length) {
+          if (css[index] === "\\") {
+            index += 2;
             continue;
           }
-          if (inFence)
+          const current = css[index++];
+          if (current === quote)
+            break;
+        }
+        continue;
+      }
+      const previous = index > 0 ? css[index - 1] : "";
+      if (!/[a-z0-9_-]/i.test(previous) && css.slice(index, index + 3).toLowerCase() === "url") {
+        cssUrl.lastIndex = index;
+        const match = cssUrl.exec(css);
+        if (match) {
+          const raw = match[1] ?? match[2] ?? match[3] ?? match[4] ?? "";
+          const replacement = replacementFor(raw);
+          if (replacement) {
+            out += css.slice(copiedThrough, index);
+            out += match[3] !== undefined ? `url(&quot;${replacement}&quot;)` : `url("${replacement}")`;
+            index = cssUrl.lastIndex;
+            copiedThrough = index;
             continue;
-          for (const alt of extractImageAlts(line)) {
-            if (alt.trim())
-              continue;
-            results.push({
-              checkId: check21.id,
-              severity: "warning",
-              message: "Image is missing alt text",
-              file,
-              line: i + 1
-            });
           }
         }
-      } catch {}
+      }
+      index++;
     }
-    return results;
+    return copiedThrough === 0 ? css : out + css.slice(copiedThrough);
+  };
+  const rewriteTag = (tag) => {
+    let out = tag;
+    if (/^<img\b/i.test(tag)) {
+      out = out.replace(/(\s+src\s*=\s*)(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi, (whole, prefix, double, single, bare) => {
+        const raw = double ?? single ?? bare ?? "";
+        const replacement = replacementFor(raw);
+        if (!replacement)
+          return whole;
+        if (double !== undefined)
+          return `${prefix}"${replacement}"`;
+        if (single !== undefined)
+          return `${prefix}'${replacement}'`;
+        return `${prefix}${replacement}`;
+      });
+    }
+    if (/^<(?:img|source)\b/i.test(tag)) {
+      out = out.replace(/(\s+srcset\s*=\s*)(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi, (whole, prefix, double, single, bare) => {
+        const value = double ?? single ?? bare ?? "";
+        let rewritten = "";
+        let copiedThrough = 0;
+        let changed = false;
+        for (const candidate of parseSrcsetUrlCandidates(value)) {
+          const replacement = replacementFor(candidate.url);
+          if (!replacement)
+            continue;
+          rewritten += value.slice(copiedThrough, candidate.start) + replacement;
+          copiedThrough = candidate.end;
+          changed = true;
+        }
+        if (!changed)
+          return whole;
+        rewritten += value.slice(copiedThrough);
+        if (double !== undefined)
+          return `${prefix}"${rewritten}"`;
+        if (single !== undefined)
+          return `${prefix}'${rewritten}'`;
+        return `${prefix}${rewritten}`;
+      });
+    }
+    out = out.replace(/(\s+style\s*=\s*)(["'])(.*?)\2/gi, (whole, prefix, quote, value) => {
+      const rewritten = rewriteCssUrls(value);
+      return rewritten === value ? whole : `${prefix}${quote}${rewritten}${quote}`;
+    });
+    return out;
+  };
+  return rewriteActiveHtml(html, rewriteTag, (region, element) => {
+    if (element !== "style")
+      return region;
+    const style = /^(<style\b[^>]*>)([\s\S]*)(<\/style\s*>)$/i.exec(region);
+    return style ? `${rewriteTag(style[1])}${rewriteCssUrls(style[2])}${style[3]}` : region;
+  });
+}
+function rewriteActiveHtml(html, rewriteTag, rewriteProtected = (region) => region) {
+  const rewriteTags = (active) => active.replace(/<(?:"[^"]*"|'[^']*'|[^'">])*>/g, rewriteTag);
+  const protectedRegion = /<!--[\s\S]*?-->|<(script|style|pre|code|textarea)\b[^>]*>[\s\S]*?<\/\1\s*>/gi;
+  let out = "";
+  let last = 0;
+  for (const match of html.matchAll(protectedRegion)) {
+    out += rewriteTags(html.slice(last, match.index));
+    out += rewriteProtected(match[0], match[1]?.toLowerCase());
+    last = (match.index ?? 0) + match[0].length;
   }
-};
-function extractImageAlts(line) {
-  const alts = [];
-  const inlinePattern = /!\[([^\]]*)\]\(([^)]+)\)/g;
-  const referencePattern = /!\[([^\]]*)\]\[[^\]]*\]/g;
-  for (const match of line.matchAll(inlinePattern)) {
-    alts.push(match[1] ?? "");
+  return out + rewriteTags(html.slice(last));
+}
+function crc32(buf) {
+  let c = ~0;
+  for (let i = 0;i < buf.length; i++) {
+    c ^= buf[i];
+    for (let k = 0;k < 8; k++)
+      c = c >>> 1 ^ 3988292384 & -(c & 1);
   }
-  for (const match of line.matchAll(referencePattern)) {
-    alts.push(match[1] ?? "");
+  return ~c >>> 0;
+}
+function chunk(type, data) {
+  const out = new Uint8Array(data.length + 12);
+  const view = new DataView(out.buffer);
+  view.setUint32(0, data.length);
+  for (let i = 0;i < 4; i++)
+    out[4 + i] = type.charCodeAt(i);
+  out.set(data, 8);
+  view.setUint32(data.length + 8, crc32(out.subarray(4, data.length + 8)));
+  return out;
+}
+function placeholderPng(width = 640, height = 480, cell = 32) {
+  const A = [217, 70, 239];
+  const B = [26, 26, 26];
+  const raw = new Uint8Array(height * (1 + width * 3));
+  let p = 0;
+  for (let y = 0;y < height; y++) {
+    raw[p++] = 0;
+    for (let x = 0;x < width; x++) {
+      const c = ((x / cell | 0) + (y / cell | 0)) % 2 === 0 ? A : B;
+      raw[p++] = c[0];
+      raw[p++] = c[1];
+      raw[p++] = c[2];
+    }
   }
-  return alts;
+  const ihdr = new Uint8Array(13);
+  const hv = new DataView(ihdr.buffer);
+  hv.setUint32(0, width);
+  hv.setUint32(4, height);
+  ihdr[8] = 8;
+  ihdr[9] = 2;
+  const parts = [
+    new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]),
+    chunk("IHDR", ihdr),
+    chunk("IDAT", new Uint8Array(deflateSync(raw))),
+    chunk("IEND", new Uint8Array(0))
+  ];
+  const total = parts.reduce((n, x) => n + x.length, 0);
+  const png = new Uint8Array(total);
+  let o = 0;
+  for (const part of parts) {
+    png.set(part, o);
+    o += part.length;
+  }
+  return png;
 }
-registerCheck(check21);
 
-// src/checks/source/accessibility-heading-order.ts
-import { readFile as readFile15 } from "node:fs/promises";
-var check22 = {
-  id: "source.accessibility.heading-order",
-  name: "Heading Order",
-  description: "Checks markdown heading levels do not jump by more than one",
-  category: "source",
+// src/lib/build-staging.ts
+async function shipViewerHtml(htmlFile, outDir) {
+  await fsp.mkdir(path5.join(outDir, "engine"), { recursive: true });
+  await fsp.copyFile(await getAssetPath("engine/gutterpress-viewer.js"), path5.join(outDir, "engine/gutterpress-viewer.js"));
+  const tag = `  <script src="engine/gutterpress-viewer.js"></script>
+`;
+  const html = await fsp.readFile(htmlFile, "utf-8");
+  await fsp.writeFile(htmlFile, /<\/head>/i.test(html) ? html.replace(/<\/head>/i, tag + "</head>") : tag + html, "utf-8");
+}
+async function stageBookAssets(options) {
+  const { renderDir, outDir, htmlFile, imageRefs, cssAssets, onPlan, dropRelativeLinks } = options;
+  const { copies: imageCopies, errors, destinations } = await planImageCopies(renderDir, imageRefs);
+  const copies = [...cssAssets, ...imageCopies];
+  onPlan?.({ unresolved: errors, copyCount: copies.length });
+  const missingPlaceholders = copies.length ? await copyReferencedAssets(copies, outDir) : new Map;
+  const rendered = await fsp.readFile(htmlFile, "utf8");
+  let staged = rendered;
+  if (missingPlaceholders.size > 0) {
+    const rewrites = new Map(missingPlaceholders);
+    for (const [ref, dest] of destinations) {
+      const placeholder = missingPlaceholders.get(dest);
+      if (placeholder)
+        rewrites.set(ref, placeholder);
+    }
+    staged = rewriteMissingImageReferences(staged, rewrites);
+  }
+  if (dropRelativeLinks)
+    staged = dropRelativeLinkHrefs(staged);
+  if (staged.includes("--gp-shape:"))
+    staged = await inlineShapeUrls(staged, outDir);
+  if (staged !== rendered)
+    await fsp.writeFile(htmlFile, staged, "utf8");
+  return { missing: [...missingPlaceholders.keys()].sort() };
+}
+async function copyReferencedAssets(copies, outDir) {
+  const dirs = new Set(copies.map((c) => path5.dirname(path5.resolve(outDir, c.to))));
+  await Promise.all([...dirs].map((d) => fsp.mkdir(d, { recursive: true })));
+  const missing = new Map;
+  await Promise.all(copies.map(async (c) => {
+    const dest = path5.resolve(outDir, c.to);
+    try {
+      await fsp.copyFile(c.from, dest);
+    } catch (err) {
+      if (err?.code === "ENOENT") {
+        const placeholder = placeholderOutputPath(c.to);
+        const placeholderDest = path5.resolve(outDir, placeholder);
+        await fsp.mkdir(path5.dirname(placeholderDest), { recursive: true });
+        await fsp.writeFile(placeholderDest, placeholderPng());
+        missing.set(c.to, placeholder);
+        return;
+      }
+      throw new BuildError(`Could not copy asset ${c.from} → ${c.to}: ` + (err instanceof Error ? err.message : String(err)), 1);
+    }
+  }));
+  return missing;
+}
+function isPrintResolvableHref(href) {
+  const value = href.trim();
+  if (value.startsWith("#"))
+    return true;
+  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(value)?.[1]?.toLowerCase();
+  return scheme !== undefined && scheme !== "file";
+}
+function dropRelativeLinkHrefs(html) {
+  const hrefAttr = /\s+href\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i;
+  return rewriteActiveHtml(html, (tag) => {
+    if (!/^<a(?=[\s/>])/i.test(tag))
+      return tag;
+    const m = hrefAttr.exec(tag);
+    if (!m)
+      return tag;
+    const href = decodeHtmlAttribute(m[1] ?? m[2] ?? m[3] ?? "");
+    return isPrintResolvableHref(href) ? tag : tag.replace(hrefAttr, "");
+  });
+}
+async function createStageRoot() {
+  return fsp.mkdtemp(path5.join(os.tmpdir(), "gutterpress-stage-"));
+}
+
+// src/checks/source/dangling-links.ts
+var check21 = {
+  id: "source.links.dangling",
+  name: "Dangling Links",
+  description: "Flags relative links the printed book cannot open (their href is dropped at print time)",
+  category: "source",
+  phase: "pre-build",
+  async run(ctx) {
+    const results = [];
+    for await (const { ref, kind, line, file } of renderedLocalRefs(ctx, check21.id, results)) {
+      if (kind !== "link" || isPrintResolvableHref(ref))
+        continue;
+      results.push(finding(check21.id, {
+        severity: "warning",
+        code: "dangling-link",
+        data: { ref },
+        message: `Link "${ref}" cannot be opened from the printed book: a PDF has no files ` + `beside it and no address of its own, so a relative link (a chapter file of ` + `this same book included) leads nowhere. The link text stays but its href is ` + `dropped at print time. Link to a heading with #anchor, use an absolute URL, ` + `or write it as plain text.`,
+        file,
+        line
+      }));
+    }
+    return results;
+  }
+};
+registerCheck(check21);
+
+// src/checks/source/accessibility-alt-text.ts
+import { readFile as readFile14 } from "node:fs/promises";
+var check22 = {
+  id: "source.accessibility.alt-text",
+  name: "Image Alt Text",
+  description: "Checks markdown images include non-empty alt text",
+  category: "source",
+  phase: "pre-build",
+  async run(ctx) {
+    const files = (ctx.markdownFiles ?? []).slice().sort();
+    if (files.length === 0)
+      return [];
+    const results = [];
+    for (const file of files) {
+      try {
+        const content = await readFile14(file, "utf8");
+        const lines = content.split(`
+`);
+        let inFence = false;
+        for (let i = 0;i < lines.length; i++) {
+          const line = lines[i] ?? "";
+          if (/^\s*(```|~~~)/.test(line)) {
+            inFence = !inFence;
+            continue;
+          }
+          if (inFence)
+            continue;
+          for (const alt of extractImageAlts(line)) {
+            if (alt.trim())
+              continue;
+            results.push({
+              checkId: check22.id,
+              severity: "warning",
+              message: "Image is missing alt text",
+              file,
+              line: i + 1
+            });
+          }
+        }
+      } catch {}
+    }
+    return results;
+  }
+};
+function extractImageAlts(line) {
+  const alts = [];
+  const inlinePattern = /!\[([^\]]*)\]\(([^)]+)\)/g;
+  const referencePattern = /!\[([^\]]*)\]\[[^\]]*\]/g;
+  for (const match of line.matchAll(inlinePattern)) {
+    alts.push(match[1] ?? "");
+  }
+  for (const match of line.matchAll(referencePattern)) {
+    alts.push(match[1] ?? "");
+  }
+  return alts;
+}
+registerCheck(check22);
+
+// src/checks/source/accessibility-heading-order.ts
+import { readFile as readFile15 } from "node:fs/promises";
+var check23 = {
+  id: "source.accessibility.heading-order",
+  name: "Heading Order",
+  description: "Checks markdown heading levels do not jump by more than one",
+  category: "source",
   phase: "pre-build",
   async run(ctx) {
     const files = (ctx.markdownFiles ?? []).slice().sort();
@@ -6277,7 +6606,7 @@ var check22 = {
           const level = match[1].length;
           if (prevLevel != null && level > prevLevel + 1) {
             results.push({
-              checkId: check22.id,
+              checkId: check23.id,
               severity: "warning",
               message: `Heading level jump from h${prevLevel} to h${level}`,
               file,
@@ -6291,11 +6620,11 @@ var check22 = {
     return results;
   }
 };
-registerCheck(check22);
+registerCheck(check23);
 
 // src/checks/source/layout-markers.ts
 import { readFile as readFile16 } from "node:fs/promises";
-var check23 = {
+var check24 = {
   id: "source.markdown.layout-markers",
   name: "Layout Markers",
   description: "Reports @page/@section/@chapter marker arguments Gutterpress could not understand, plus any unknown gp-* class",
@@ -6307,7 +6636,7 @@ var check23 = {
       return [];
     const results = [];
     const plugins = await loadPlugins(ctx.config.extensions, ctx.inputDir, (ref, error2) => {
-      results.push(inspectionFailed(check23.id, `Plugin "${ref}" could not be loaded, so markers it defines were not checked: ${error2.message}`));
+      results.push(inspectionFailed(check24.id, `Plugin "${ref}" could not be loaded, so markers it defines were not checked: ${error2.message}`));
     });
     const md = createMarkdownRenderer(plugins);
     for (const file of files) {
@@ -6316,7 +6645,7 @@ var check23 = {
         const env = {};
         md.render(content, env);
         for (const w of env.layoutWarnings ?? []) {
-          results.push(finding(check23.id, {
+          results.push(finding(check24.id, {
             severity: "warning",
             message: w.message,
             file,
@@ -6325,17 +6654,17 @@ var check23 = {
           }));
         }
       } catch (error2) {
-        results.push(inspectionFailed(check23.id, `Could not check layout markers in ${file}: ${error2 instanceof Error ? error2.message : String(error2)}`, { file }));
+        results.push(inspectionFailed(check24.id, `Could not check layout markers in ${file}: ${error2 instanceof Error ? error2.message : String(error2)}`, { file }));
       }
     }
     return results;
   }
 };
-registerCheck(check23);
+registerCheck(check24);
 
 // src/checks/source/merge-markers.ts
 import { readFile as readFile17 } from "node:fs/promises";
-import path5 from "node:path";
+import path6 from "node:path";
 
 // src/checks/asset/extensions.ts
 var RASTER_INSPECTABLE_EXTS = [
@@ -6364,7 +6693,7 @@ var CLOSE_SENTINEL = ">>>>>>> online version";
 function withoutOnlineTag(relPath) {
   return relPath.replace(/\.online(?=\.[^./]*$|$)/, "");
 }
-var check24 = {
+var check25 = {
   id: "source.sync.merge-markers",
   name: "Combined Versions",
   description: "Finds passages and files still holding two versions (yours and the online copy) after a sync",
@@ -6378,7 +6707,7 @@ var check24 = {
       try {
         content = await readFile17(file, "utf8");
       } catch {
-        results.push(inspectionFailed(check24.id, `Could not read source file: ${file}`, { file }));
+        results.push(inspectionFailed(check25.id, `Could not read source file: ${file}`, { file }));
         continue;
       }
       if (!content.includes(OPEN_SENTINEL) && !content.includes(CLOSE_SENTINEL))
@@ -6390,7 +6719,7 @@ var check24 = {
         const line = lines[i].endsWith("\r") ? lines[i].slice(0, -1) : lines[i];
         if (line === OPEN_SENTINEL) {
           inBlock = true;
-          results.push(finding(check24.id, {
+          results.push(finding(check25.id, {
             severity: "error",
             code: "two-versions-passage",
             message: "This passage has two versions (yours and the online copy) — keep what you want, then delete the marker lines.",
@@ -6399,7 +6728,7 @@ var check24 = {
           }));
         } else if (line === CLOSE_SENTINEL) {
           if (!inBlock) {
-            results.push(finding(check24.id, {
+            results.push(finding(check25.id, {
               severity: "error",
               code: "leftover-version-marker",
               message: "This marker line is left over from combining two versions — delete it.",
@@ -6419,8 +6748,8 @@ var check24 = {
         ignore: [...ASSET_SCAN_IGNORE_GLOBS]
       });
       for (const sibling of siblings.sort()) {
-        const rel = path5.relative(ctx.inputDir, sibling).split(path5.sep).join("/");
-        results.push(finding(check24.id, {
+        const rel = path6.relative(ctx.inputDir, sibling).split(path6.sep).join("/");
+        results.push(finding(check25.id, {
           severity: "warning",
           code: "kept-both-versions",
           message: `Two versions of ${withoutOnlineTag(rel)} are in your project — keep the one you want, then delete the other.`,
@@ -6428,12 +6757,12 @@ var check24 = {
         }));
       }
     } catch (error2) {
-      results.push(inspectionFailed(check24.id, `Could not scan for kept-both files: ${error2 instanceof Error ? error2.message : String(error2)}`));
+      results.push(inspectionFailed(check25.id, `Could not scan for kept-both files: ${error2 instanceof Error ? error2.message : String(error2)}`));
     }
     return results;
   }
 };
-registerCheck(check24);
+registerCheck(check25);
 
 // src/checks/asset/image-file-size.ts
 import { stat as stat3 } from "node:fs/promises";
@@ -6442,24 +6771,24 @@ import { stat as stat3 } from "node:fs/promises";
 import { stat as stat2, readFile as readFile18 } from "node:fs/promises";
 var DEFAULT_DPI = 72;
 var cache = new Map;
-async function inspectImage(path6) {
+async function inspectImage(path7) {
   let st;
   try {
-    st = await stat2(path6);
+    st = await stat2(path7);
   } catch {
     return null;
   }
-  const hit = cache.get(path6);
+  const hit = cache.get(path7);
   if (hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size)
     return hit.info;
   let info2 = null;
   try {
-    const buf = await readFile18(path6);
+    const buf = await readFile18(path7);
     info2 = parseImage(buf);
   } catch {
     info2 = null;
   }
-  cache.set(path6, { mtimeMs: st.mtimeMs, size: st.size, info: info2 });
+  cache.set(path7, { mtimeMs: st.mtimeMs, size: st.size, info: info2 });
   return info2;
 }
 function parseImage(b) {
@@ -6659,7 +6988,7 @@ async function collectImageFiles(dirs, exts, ignore = ASSET_SCAN_IGNORE_GLOBS) {
 }
 
 // src/checks/asset/image-file-size.ts
-var check25 = {
+var check26 = {
   id: "asset.image.file-size",
   name: "Image File Size",
   description: "Checks that image files do not exceed the maximum size limit",
@@ -6680,14 +7009,14 @@ var check25 = {
         if (info2.size > maxSize) {
           const sizeMb = (info2.size / 1e6).toFixed(1);
           const maxMb = (maxSize / 1e6).toFixed(1);
-          results.push(finding(check25.id, {
+          results.push(finding(check26.id, {
             severity: "warning",
             message: `Image file too large: ${sizeMb}MB (max ${maxMb}MB)`,
             file
           }));
         }
       } catch {
-        results.push(inspectionFailed(check25.id, `Could not stat image file: ${file}`, {
+        results.push(inspectionFailed(check26.id, `Could not stat image file: ${file}`, {
           file
         }));
       }
@@ -6695,10 +7024,10 @@ var check25 = {
     return results;
   }
 };
-registerCheck(check25);
+registerCheck(check26);
 
 // src/checks/asset/image-resolution.ts
-var check26 = {
+var check27 = {
   id: "asset.image.resolution",
   name: "Image Resolution",
   description: "Checks source image DPI from embedded density metadata",
@@ -6720,7 +7049,7 @@ var check26 = {
       const { xDpi, yDpi } = info2;
       if (xDpi > 0 && yDpi > 0 && (xDpi < minDpi || yDpi < minDpi)) {
         results.push({
-          checkId: check26.id,
+          checkId: check27.id,
           severity: "warning",
           message: `Image resolution too low: ${xDpi}x${yDpi} DPI (minimum ${minDpi} DPI)`,
           file
@@ -6730,7 +7059,7 @@ var check26 = {
     return results;
   }
 };
-registerCheck(check26);
+registerCheck(check27);
 
 // src/checks/asset/image-color-space.ts
 var LABEL = {
@@ -6738,7 +7067,7 @@ var LABEL = {
   gray: "Gray",
   cmyk: "CMYK"
 };
-var check27 = {
+var check28 = {
   id: "asset.image.color-space",
   name: "Image Color Space",
   description: "Validates image color spaces against allowed list",
@@ -6759,7 +7088,7 @@ var check27 = {
       const cs = info2?.colorSpace;
       if (cs && !allowedLower.has(cs)) {
         results.push({
-          checkId: check27.id,
+          checkId: check28.id,
           severity: "warning",
           message: `Image uses ${LABEL[cs] ?? cs} color space (allowed: ${allowed.join(", ")})`,
           file
@@ -6769,10 +7098,10 @@ var check27 = {
     return results;
   }
 };
-registerCheck(check27);
+registerCheck(check28);
 
 // src/checks/asset/image-alpha.ts
-var check28 = {
+var check29 = {
   id: "asset.image.alpha-channel",
   name: "Image Alpha Channel",
   description: "Checks for alpha channels in PNG/TIFF images",
@@ -6790,7 +7119,7 @@ var check28 = {
       const info2 = await inspectImage(file);
       if (info2?.hasAlpha) {
         results.push({
-          checkId: check28.id,
+          checkId: check29.id,
           severity: "warning",
           message: "Image contains alpha channel, which may cause print issues",
           file
@@ -6800,10 +7129,10 @@ var check28 = {
     return results;
   }
 };
-registerCheck(check28);
+registerCheck(check29);
 
 // src/checks/asset/image-tac.ts
-var check29 = {
+var check30 = {
   id: "asset.image.tac-raster",
   name: "Image TAC (Raster)",
   description: "Rasterizes and checks TAC per image using Ghostscript",
@@ -6822,7 +7151,7 @@ var check29 = {
     const ghostscript = await resolveGhostscript();
     if (!ghostscript) {
       return [
-        inspectionFailed(check29.id, "Could not inspect image ink coverage: Ghostscript executable not found")
+        inspectionFailed(check30.id, "Could not inspect image ink coverage: Ghostscript executable not found")
       ];
     }
     for (const file of files) {
@@ -6840,7 +7169,7 @@ var check29 = {
           if (nums.length === 4 && nums.every((n) => Number.isFinite(n))) {
             const tac = (nums[0] + nums[1] + nums[2] + nums[3]) * 100;
             if (tac > maxTac) {
-              results.push(finding(check29.id, {
+              results.push(finding(check30.id, {
                 severity: "warning",
                 message: `Image TAC exceeds limit: ${tac.toFixed(1)}% (max ${maxTac}%)`,
                 file,
@@ -6852,16 +7181,16 @@ var check29 = {
           }
         }
       } catch {
-        results.push(inspectionFailed(check29.id, `Could not inspect image ink coverage: ${file}`, { file }));
+        results.push(inspectionFailed(check30.id, `Could not inspect image ink coverage: ${file}`, { file }));
       }
     }
     return results;
   }
 };
-registerCheck(check29);
+registerCheck(check30);
 
 // src/checks/asset/approved-fonts.ts
-var check30 = {
+var check31 = {
   id: "asset.font.approved-files",
   name: "Approved Font Files",
   description: "Checks font files against the approved file patterns",
@@ -6900,7 +7229,7 @@ var check30 = {
     for (const font of allFonts) {
       if (!approvedFonts.has(font)) {
         results.push({
-          checkId: check30.id,
+          checkId: check31.id,
           severity: "warning",
           message: "Font file not in approved list",
           file: font
@@ -6910,7 +7239,7 @@ var check30 = {
     return results;
   }
 };
-registerCheck(check30);
+registerCheck(check31);
 
 // src/checks/asset/font-license.ts
 import { existsSync as existsSync9 } from "node:fs";
@@ -6925,7 +7254,7 @@ var LICENSE_NAMES = [
   "OFL-1.1.txt",
   "COPYING"
 ];
-var check31 = {
+var check32 = {
   id: "asset.font.license",
   name: "Font License",
   description: "Checks for license files in font directories",
@@ -6952,7 +7281,7 @@ var check31 = {
       const hasLicense = LICENSE_NAMES.some((name) => existsSync9(resolve7(fontDir, name)));
       if (!hasLicense) {
         results.push({
-          checkId: check31.id,
+          checkId: check32.id,
           severity: "warning",
           message: `No font license file found in directory`,
           file: fontDir
@@ -6962,10 +7291,10 @@ var check31 = {
     return results;
   }
 };
-registerCheck(check31);
+registerCheck(check32);
 
 // src/checks/heuristic/text-density.ts
-var check32 = {
+var check33 = {
   id: "heuristic.whitespace.text-density",
   name: "Text Density",
   description: "Checks characters-per-page ratio",
@@ -6994,7 +7323,7 @@ var check32 = {
     });
     if (lowPages.length > 0) {
       results.push({
-        checkId: check32.id,
+        checkId: check33.id,
         severity: "info",
         message: `Low text density on pages: ${lowPages.join(", ")} (below ${range.min} chars)`,
         file: ctx.pdfPath
@@ -7002,7 +7331,7 @@ var check32 = {
     }
     if (highPages.length > 0) {
       results.push({
-        checkId: check32.id,
+        checkId: check33.id,
         severity: "info",
         message: `High text density on pages: ${highPages.join(", ")} (above ${range.max} chars)`,
         file: ctx.pdfPath
@@ -7011,11 +7340,11 @@ var check32 = {
     return results;
   }
 };
-registerCheck(check32);
+registerCheck(check33);
 
 // src/checks/heuristic/section-density.ts
 import { readFile as readFile19 } from "node:fs/promises";
-var check33 = {
+var check34 = {
   id: "heuristic.chunking.section-density",
   name: "Section Density",
   description: "Checks heading/paragraph/callout density from source Markdown",
@@ -7041,7 +7370,7 @@ var check33 = {
           const line = lines[i];
           if (/^#{1,6}\s/.test(line)) {
             if (paragraphCount > maxParas) {
-              results.push(finding(check33.id, {
+              results.push(finding(check34.id, {
                 severity: "info",
                 message: `Section has ${paragraphCount} paragraphs (max recommended: ${maxParas})`,
                 file,
@@ -7061,7 +7390,7 @@ var check33 = {
           }
         }
         if (paragraphCount > maxParas) {
-          results.push(finding(check33.id, {
+          results.push(finding(check34.id, {
             severity: "info",
             message: `Section has ${paragraphCount} paragraphs (max recommended: ${maxParas})`,
             file,
@@ -7069,7 +7398,7 @@ var check33 = {
           }));
         }
       } catch {
-        results.push(inspectionFailed(check33.id, `Could not read source file: ${file}`, {
+        results.push(inspectionFailed(check34.id, `Could not read source file: ${file}`, {
           file
         }));
       }
@@ -7077,10 +7406,10 @@ var check33 = {
     return results;
   }
 };
-registerCheck(check33);
+registerCheck(check34);
 
 // src/checks/heuristic/layer-count.ts
-var check34 = {
+var check35 = {
   id: "heuristic.decoration.layer-count",
   name: "Layer Count",
   description: "Counts image objects per page",
@@ -7105,7 +7434,7 @@ var check34 = {
       heavyPages.sort((a, b) => a - b);
       return [
         {
-          checkId: check34.id,
+          checkId: check35.id,
           severity: "info",
           message: `Pages with many image layers (>${maxLayers}): ${heavyPages.join(", ")}`,
           file: ctx.pdfPath
@@ -7115,10 +7444,10 @@ var check34 = {
     return [];
   }
 };
-registerCheck(check34);
+registerCheck(check35);
 
 // src/checks/heuristic/placement-variance.ts
-var check35 = {
+var check36 = {
   id: "heuristic.layout.placement-variance",
   name: "Placement Variance",
   description: "Analyzes text baseline coordinates for layout consistency",
@@ -7136,7 +7465,7 @@ var check35 = {
     const uniqueX = new Set(positions.map((p) => Math.round(p.x)));
     return [
       {
-        checkId: check35.id,
+        checkId: check36.id,
         severity: "info",
         message: `Layout analysis: ${uniqueX.size} unique horizontal text positions across ${positions.length} text blocks.`,
         file: ctx.pdfPath
@@ -7144,21 +7473,21 @@ var check35 = {
     ];
   }
 };
-registerCheck(check35);
+registerCheck(check36);
 
 // src/checks/tool-check.ts
 async function checkToolAvailability(config, opts = {}) {
   const { checks: checks2 } = selectChecks(opts, config);
   const toolToChecks = new Map;
-  for (const check36 of checks2) {
-    if (!check36.requiredTools?.length)
+  for (const check37 of checks2) {
+    if (!check37.requiredTools?.length)
       continue;
-    for (const tool of check36.requiredTools) {
+    for (const tool of check37.requiredTools) {
       const existing = toolToChecks.get(tool);
       if (existing) {
-        existing.push(check36.id);
+        existing.push(check37.id);
       } else {
-        toolToChecks.set(tool, [check36.id]);
+        toolToChecks.set(tool, [check37.id]);
       }
     }
   }
@@ -7174,11 +7503,11 @@ async function checkToolAvailability(config, opts = {}) {
   const missing = results.filter((r) => !r.found).map((r) => r.tool);
   const missingSet = new Set(missing);
   const skippedChecks = [];
-  for (const check36 of checks2) {
-    if (!check36.requiredTools?.length)
+  for (const check37 of checks2) {
+    if (!check37.requiredTools?.length)
       continue;
-    if (check36.requiredTools.some((t) => missingSet.has(t))) {
-      skippedChecks.push(check36.id);
+    if (check37.requiredTools.some((t) => missingSet.has(t))) {
+      skippedChecks.push(check37.id);
     }
   }
   return { available, missing, skippedChecks, toolToChecks };
@@ -7200,7 +7529,7 @@ import { existsSync as existsSync10 } from "node:fs";
 import { dirname as dirname4, join as join3, resolve as resolve8 } from "node:path";
 
 // src/lib/output-paths.ts
-import path6 from "node:path";
+import path7 from "node:path";
 
 // src/lib/slug.ts
 function slugify(name, fallback = "") {
@@ -7218,7 +7547,7 @@ function bookSlug(title) {
   return slugify(title ?? "", "book");
 }
 function resolveOutputDir(manifestDir, title) {
-  return path6.resolve(manifestDir, DIST_DIRNAME, bookSlug(title));
+  return path7.resolve(manifestDir, DIST_DIRNAME, bookSlug(title));
 }
 function artifactName(title, format) {
   return `${bookSlug(title)}-${format}.pdf`;
@@ -7473,25 +7802,25 @@ async function runChecks(ctx, opts = {}) {
   }
   const release = retainPdfCache();
   try {
-    for (const check36 of checks2) {
+    for (const check37 of checks2) {
       try {
-        const results = await check36.run(ctx);
-        const severityOverride = getCheckSeverityOverride(check36.id, ctx.config);
+        const results = await check37.run(ctx);
+        const severityOverride = getCheckSeverityOverride(check37.id, ctx.config);
         if (severityOverride) {
           for (const r of results) {
             r.severity = severityOverride;
           }
         }
         if (results.length === 0) {
-          passed.push(check36.id);
+          passed.push(check37.id);
         } else {
           allResults.push(...results);
         }
       } catch (err) {
         allResults.push({
-          checkId: check36.id,
+          checkId: check37.id,
           severity: "error",
-          message: `Check "${check36.id}" threw: ${err instanceof Error ? err.message : String(err)}`
+          message: `Check "${check37.id}" threw: ${err instanceof Error ? err.message : String(err)}`
         });
       }
     }
@@ -7862,8 +8191,8 @@ import { randomBytes } from "node:crypto";
 // src/lib/build-fingerprint.ts
 import * as fs from "node:fs";
 import { mkdir as mkdir3, readFile as readFile21, writeFile as writeFile3 } from "node:fs/promises";
-import { createHash as createHash4 } from "node:crypto";
-import path7 from "node:path";
+import { createHash as createHash5 } from "node:crypto";
+import path8 from "node:path";
 import git from "isomorphic-git";
 var FINGERPRINT_FILENAME = "build-fingerprint.json";
 var VERSION_TIMEOUT_MS = 4000;
@@ -7912,7 +8241,7 @@ async function getGitRevision(sourceDir) {
   const candidateDirs = [sourceDir, process.cwd()].filter((v) => Boolean(v));
   const seen = new Set;
   for (const dir of candidateDirs) {
-    const abs = path7.resolve(dir);
+    const abs = path8.resolve(dir);
     if (seen.has(abs))
       continue;
     seen.add(abs);
@@ -7951,7 +8280,7 @@ async function getEngineBundleHash() {
       readFile21(viewerPath),
       readFile21(agentPath)
     ]);
-    const hash = createHash4("sha256");
+    const hash = createHash5("sha256");
     hash.update(viewerBytes);
     hash.update(agentBytes);
     return hash.digest("hex").slice(0, 12);
@@ -7997,8 +8326,8 @@ function sanitizeArgs(args) {
   return out;
 }
 async function writeBuildFingerprint(input) {
-  const outputDir = path7.resolve(input.outputDir);
-  const outPath = path7.join(outputDir, FINGERPRINT_FILENAME);
+  const outputDir = path8.resolve(input.outputDir);
+  const outPath = path8.join(outputDir, FINGERPRINT_FILENAME);
   const [tools, sourceRevision] = await Promise.all([
     getToolVersions(),
     getGitRevision(input.sourceDir)
@@ -8014,7 +8343,7 @@ async function writeBuildFingerprint(input) {
         iccPath: input.pdfx.iccPath,
         stripAnnotations: input.pdfx.stripAnnotations
       },
-      outputDir: input.recordedOutputDir ? path7.resolve(input.recordedOutputDir) : outputDir
+      outputDir: input.recordedOutputDir ? path8.resolve(input.recordedOutputDir) : outputDir
     },
     sourceRevision,
     tools
@@ -8089,245 +8418,6 @@ function computeGates(format, opts, config) {
   return { lint: lint2, preValidate, postValidate };
 }
 
-// src/lib/build-staging.ts
-import path8 from "node:path";
-import os from "node:os";
-import fsp from "node:fs/promises";
-
-// src/lib/missing-asset-placeholder.ts
-import { createHash as createHash5 } from "node:crypto";
-import { deflateSync } from "node:zlib";
-function placeholderOutputPath(missingOutputPath) {
-  const hash = createHash5("sha256").update(missingOutputPath).digest("hex").slice(0, 16);
-  return `assets/gutterpress-missing/${hash}.png`;
-}
-function decodeHtmlAttribute(value) {
-  return value.replace(/&quot;/g, '"').replace(/&#39;|&apos;/g, "'").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
-}
-function rewriteMissingImageReferences(html, replacements) {
-  if (replacements.size === 0)
-    return html;
-  const replacementFor = (raw) => replacements.get(raw) ?? replacements.get(decodeHtmlAttribute(raw));
-  const cssUrl = /url\(\s*(?:"([^"]*)"|'([^']*)'|&quot;((?:(?!&quot;).)*)&quot;|([^'"()\s]*))\s*\)/giy;
-  const rewriteCssUrls = (css) => {
-    let out2 = "";
-    let copiedThrough = 0;
-    let index = 0;
-    while (index < css.length) {
-      if (css.startsWith("/*", index)) {
-        const end = css.indexOf("*/", index + 2);
-        index = end < 0 ? css.length : end + 2;
-        continue;
-      }
-      const char = css[index];
-      if (char === '"' || char === "'") {
-        const quote = char;
-        index++;
-        while (index < css.length) {
-          if (css[index] === "\\") {
-            index += 2;
-            continue;
-          }
-          const current = css[index++];
-          if (current === quote)
-            break;
-        }
-        continue;
-      }
-      const previous = index > 0 ? css[index - 1] : "";
-      if (!/[a-z0-9_-]/i.test(previous) && css.slice(index, index + 3).toLowerCase() === "url") {
-        cssUrl.lastIndex = index;
-        const match = cssUrl.exec(css);
-        if (match) {
-          const raw = match[1] ?? match[2] ?? match[3] ?? match[4] ?? "";
-          const replacement = replacementFor(raw);
-          if (replacement) {
-            out2 += css.slice(copiedThrough, index);
-            out2 += match[3] !== undefined ? `url(&quot;${replacement}&quot;)` : `url("${replacement}")`;
-            index = cssUrl.lastIndex;
-            copiedThrough = index;
-            continue;
-          }
-        }
-      }
-      index++;
-    }
-    return copiedThrough === 0 ? css : out2 + css.slice(copiedThrough);
-  };
-  const rewriteTag = (tag) => {
-    let out2 = tag;
-    if (/^<img\b/i.test(tag)) {
-      out2 = out2.replace(/(\s+src\s*=\s*)(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi, (whole, prefix, double, single, bare) => {
-        const raw = double ?? single ?? bare ?? "";
-        const replacement = replacementFor(raw);
-        if (!replacement)
-          return whole;
-        if (double !== undefined)
-          return `${prefix}"${replacement}"`;
-        if (single !== undefined)
-          return `${prefix}'${replacement}'`;
-        return `${prefix}${replacement}`;
-      });
-    }
-    if (/^<(?:img|source)\b/i.test(tag)) {
-      out2 = out2.replace(/(\s+srcset\s*=\s*)(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi, (whole, prefix, double, single, bare) => {
-        const value = double ?? single ?? bare ?? "";
-        let rewritten = "";
-        let copiedThrough = 0;
-        let changed = false;
-        for (const candidate of parseSrcsetUrlCandidates(value)) {
-          const replacement = replacementFor(candidate.url);
-          if (!replacement)
-            continue;
-          rewritten += value.slice(copiedThrough, candidate.start) + replacement;
-          copiedThrough = candidate.end;
-          changed = true;
-        }
-        if (!changed)
-          return whole;
-        rewritten += value.slice(copiedThrough);
-        if (double !== undefined)
-          return `${prefix}"${rewritten}"`;
-        if (single !== undefined)
-          return `${prefix}'${rewritten}'`;
-        return `${prefix}${rewritten}`;
-      });
-    }
-    out2 = out2.replace(/(\s+style\s*=\s*)(["'])(.*?)\2/gi, (whole, prefix, quote, value) => {
-      const rewritten = rewriteCssUrls(value);
-      return rewritten === value ? whole : `${prefix}${quote}${rewritten}${quote}`;
-    });
-    return out2;
-  };
-  const rewriteActiveHtml = (active) => active.replace(/<(?:"[^"]*"|'[^']*'|[^'">])*>/g, (tag) => rewriteTag(tag));
-  const protectedRegion = /<!--[\s\S]*?-->|<(script|style|pre|code|textarea)\b[^>]*>[\s\S]*?<\/\1\s*>/gi;
-  let out = "";
-  let last = 0;
-  for (const match of html.matchAll(protectedRegion)) {
-    out += rewriteActiveHtml(html.slice(last, match.index));
-    if (match[1]?.toLowerCase() === "style") {
-      const style = /^(<style\b[^>]*>)([\s\S]*)(<\/style\s*>)$/i.exec(match[0]);
-      out += style ? `${rewriteTag(style[1])}${rewriteCssUrls(style[2])}${style[3]}` : match[0];
-    } else {
-      out += match[0];
-    }
-    last = (match.index ?? 0) + match[0].length;
-  }
-  out += rewriteActiveHtml(html.slice(last));
-  return out;
-}
-function crc32(buf) {
-  let c = ~0;
-  for (let i = 0;i < buf.length; i++) {
-    c ^= buf[i];
-    for (let k = 0;k < 8; k++)
-      c = c >>> 1 ^ 3988292384 & -(c & 1);
-  }
-  return ~c >>> 0;
-}
-function chunk(type, data) {
-  const out = new Uint8Array(data.length + 12);
-  const view = new DataView(out.buffer);
-  view.setUint32(0, data.length);
-  for (let i = 0;i < 4; i++)
-    out[4 + i] = type.charCodeAt(i);
-  out.set(data, 8);
-  view.setUint32(data.length + 8, crc32(out.subarray(4, data.length + 8)));
-  return out;
-}
-function placeholderPng(width = 640, height = 480, cell = 32) {
-  const A = [217, 70, 239];
-  const B = [26, 26, 26];
-  const raw = new Uint8Array(height * (1 + width * 3));
-  let p = 0;
-  for (let y = 0;y < height; y++) {
-    raw[p++] = 0;
-    for (let x = 0;x < width; x++) {
-      const c = ((x / cell | 0) + (y / cell | 0)) % 2 === 0 ? A : B;
-      raw[p++] = c[0];
-      raw[p++] = c[1];
-      raw[p++] = c[2];
-    }
-  }
-  const ihdr = new Uint8Array(13);
-  const hv = new DataView(ihdr.buffer);
-  hv.setUint32(0, width);
-  hv.setUint32(4, height);
-  ihdr[8] = 8;
-  ihdr[9] = 2;
-  const parts = [
-    new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]),
-    chunk("IHDR", ihdr),
-    chunk("IDAT", new Uint8Array(deflateSync(raw))),
-    chunk("IEND", new Uint8Array(0))
-  ];
-  const total = parts.reduce((n, x) => n + x.length, 0);
-  const png = new Uint8Array(total);
-  let o = 0;
-  for (const part of parts) {
-    png.set(part, o);
-    o += part.length;
-  }
-  return png;
-}
-
-// src/lib/build-staging.ts
-async function shipViewerHtml(htmlFile, outDir) {
-  await fsp.mkdir(path8.join(outDir, "engine"), { recursive: true });
-  await fsp.copyFile(await getAssetPath("engine/gutterpress-viewer.js"), path8.join(outDir, "engine/gutterpress-viewer.js"));
-  const tag = `  <script src="engine/gutterpress-viewer.js"></script>
-`;
-  const html = await fsp.readFile(htmlFile, "utf-8");
-  await fsp.writeFile(htmlFile, /<\/head>/i.test(html) ? html.replace(/<\/head>/i, tag + "</head>") : tag + html, "utf-8");
-}
-async function stageBookAssets(options) {
-  const { renderDir, outDir, htmlFile, imageRefs, cssAssets, onPlan } = options;
-  const { copies: imageCopies, errors, destinations } = await planImageCopies(renderDir, imageRefs);
-  const copies = [...cssAssets, ...imageCopies];
-  onPlan?.({ unresolved: errors, copyCount: copies.length });
-  const missingPlaceholders = copies.length ? await copyReferencedAssets(copies, outDir) : new Map;
-  let staged = await fsp.readFile(htmlFile, "utf8");
-  if (missingPlaceholders.size > 0) {
-    const rewrites = new Map(missingPlaceholders);
-    for (const [ref, dest] of destinations) {
-      const placeholder = missingPlaceholders.get(dest);
-      if (placeholder)
-        rewrites.set(ref, placeholder);
-    }
-    staged = rewriteMissingImageReferences(staged, rewrites);
-    await fsp.writeFile(htmlFile, staged, "utf8");
-  }
-  if (staged.includes("--gp-shape:")) {
-    await fsp.writeFile(htmlFile, await inlineShapeUrls(staged, outDir), "utf8");
-  }
-  return { missing: [...missingPlaceholders.keys()].sort() };
-}
-async function copyReferencedAssets(copies, outDir) {
-  const dirs = new Set(copies.map((c) => path8.dirname(path8.resolve(outDir, c.to))));
-  await Promise.all([...dirs].map((d) => fsp.mkdir(d, { recursive: true })));
-  const missing = new Map;
-  await Promise.all(copies.map(async (c) => {
-    const dest = path8.resolve(outDir, c.to);
-    try {
-      await fsp.copyFile(c.from, dest);
-    } catch (err) {
-      if (err?.code === "ENOENT") {
-        const placeholder = placeholderOutputPath(c.to);
-        const placeholderDest = path8.resolve(outDir, placeholder);
-        await fsp.mkdir(path8.dirname(placeholderDest), { recursive: true });
-        await fsp.writeFile(placeholderDest, placeholderPng());
-        missing.set(c.to, placeholder);
-        return;
-      }
-      throw new BuildError(`Could not copy asset ${c.from} → ${c.to}: ` + (err instanceof Error ? err.message : String(err)), 1);
-    }
-  }));
-  return missing;
-}
-async function createStageRoot() {
-  return fsp.mkdtemp(path8.join(os.tmpdir(), "gutterpress-stage-"));
-}
-
 // src/lib/build-runner.ts
 function splitOutPath(outArg, format) {
   if (typeof outArg !== "string" || outArg.length === 0) {
@@ -8423,7 +8513,7 @@ async function runQualityGates(ctx) {
   }
 }
 async function renderBook(ctx) {
-  const { config, gates, renderDir, workDir, opts } = ctx;
+  const { config, gates, renderDir, workDir, opts, format } = ctx;
   if (config.source.files && config.source.files.length > 0) {
     log.info(`Using specified files (${config.source.files.length} total)`);
   } else {
@@ -8461,6 +8551,7 @@ async function renderBook(ctx) {
     htmlFile,
     imageRefs,
     cssAssets,
+    dropRelativeLinks: format !== "html",
     onPlan: ({ unresolved, copyCount }) => {
       if (unresolved.length > 0) {
         throw new BuildError(`Cannot resolve ${unresolved.length} image reference(s):