gutterpress 0.11.21 → 0.11.22-alpha.2

package/dist/index-ew7cyk7c.js

@@ -0,0 +1,2208 @@
+import {
+  EXTENSION_MANIFEST_FILENAME,
+  TWO_VERSIONS_OPEN,
+  extensionCarries,
+  extensionStyleList,
+  loadPlugin,
+  log,
+  prettify,
+  readExtensionMeta,
+  resolveExtension,
+  slugify
+} from "./index-kx03e4m4.js";
+import {
+  BuildError,
+  EXIT_CODES,
+  getAssetsDir
+} from "./index-jsz0s3dy.js";
+import {
+  PLUGINS_DIR,
+  VENDORED_NPM_DIR,
+  assertWindowsSafeRelativePath,
+  isExactNpmVersion,
+  parseNpmPluginSpec,
+  resolvePackageEntry,
+  resolveVendoredPluginInstallRoot,
+  vendoredNpmPluginPackageDir,
+  vendoredNpmPluginRoot,
+  windowsPathKey
+} from "./index-r7jcsk6h.js";
+import {
+  __require
+} from "./index-37x76zdn.js";
+
+// src/lib/extension-restore.ts
+import path5 from "node:path";
+
+// src/lib/fetch-timeout.ts
+class FetchPassthroughError extends Error {
+}
+
+class FriendlyHttpError extends FetchPassthroughError {
+}
+
+class FetchUnavailableError extends Error {
+}
+function composeSignal(signal, timeoutMs) {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  return {
+    signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+    timeout
+  };
+}
+async function withFetchTimeout(options, run) {
+  const composed = composeSignal(options.signal, options.timeoutMs);
+  try {
+    return await run(composed.signal);
+  } catch (cause) {
+    if (cause instanceof FetchPassthroughError)
+      throw cause;
+    if (options.signal?.aborted)
+      throw cause;
+    const offline = typeof options.offlineMessage === "function" ? options.offlineMessage(cause) : options.offlineMessage;
+    const timedOut = composed.timeout.aborted || cause instanceof Error && cause.name === "TimeoutError";
+    if (cause instanceof Error && cause.name === "AbortError" && !timedOut)
+      throw cause;
+    throw new FetchUnavailableError(timedOut ? options.timeoutMessage ?? offline : offline, { cause });
+  }
+}
+
+// src/lib/extension-manager.ts
+import { cp, mkdir as mkdir3, readdir, readFile as readFile5, rm as rm3, stat } from "node:fs/promises";
+import { existsSync as existsSync3 } from "node:fs";
+import path4 from "node:path";
+import { isSeq as isSeq2, isMap, isScalar, YAMLMap, Scalar } from "yaml";
+
+// src/lib/manifest-doc.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile as readFile2, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { parseDocument, isSeq, YAMLSeq } from "yaml";
+
+// src/lib/manifest.ts
+import { readFile } from "node:fs/promises";
+import { existsSync, statSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { parse as parseYaml, YAMLParseError } from "yaml";
+
+// src/lib/extension-specifier.ts
+var BUNDLED_EXTENSIONS = [
+  "markdown-it-mark",
+  "markdown-it-sub",
+  "markdown-it-sup",
+  "markdown-it-abbr",
+  "gutterpress-gfm-alerts"
+];
+function isBundledExtension(name) {
+  return BUNDLED_EXTENSIONS.includes(name);
+}
+function isPathSpecifier(use) {
+  return use.startsWith("./") || use.startsWith("../") || use.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(use);
+}
+function parseExtensionSpecifier(use) {
+  const spec = use.trim();
+  if (!spec) {
+    throw new Error("An extension specifier is required — an npm package name, or a ./ path.");
+  }
+  if (isPathSpecifier(spec))
+    return { kind: "path", path: spec };
+  if (/\.(m?js|cjs)$/i.test(spec) || !spec.startsWith("@") && spec.includes("/")) {
+    throw new Error(`"${spec}" looks like a path — write it as "./${spec}". A specifier that does not ` + "start with ./, ../ or / is an npm package name.");
+  }
+  const parsed = parseNpmPluginSpec(spec);
+  if (isBundledExtension(parsed.name)) {
+    if (parsed.selector !== undefined) {
+      throw new Error(`"${parsed.name}" is bundled with Gutterpress and always resolves to the bundled copy — ` + `drop "@${parsed.selector}".`);
+    }
+    return { kind: "bundled", name: parsed.name };
+  }
+  return parsed.selector === undefined ? { kind: "npm", name: parsed.name } : { kind: "npm", name: parsed.name, version: parsed.selector };
+}
+function pinnedNpmSpecifier(name, version) {
+  return `${name}@${version}`;
+}
+
+// src/constants.ts
+var NETWORK = {
+  DEFAULT_PORT: 3579
+};
+var DEBOUNCE = {
+  FILE_WATCH: 100
+};
+
+// src/lib/cli-args.ts
+class UsageError extends Error {
+  exitCode;
+  constructor(message, exitCode = EXIT_CODES.USAGE) {
+    super(message);
+    this.name = "UsageError";
+    this.exitCode = exitCode;
+  }
+}
+function resolvePort(raw) {
+  if (raw === undefined)
+    return NETWORK.DEFAULT_PORT;
+  if (raw === "" || typeof raw === "string" && raw.trim() === "") {
+    throw new UsageError("--port requires a value.");
+  }
+  const n = typeof raw === "number" || typeof raw === "string" ? Number(raw) : NaN;
+  if (!Number.isFinite(n) || !Number.isInteger(n) || n < 0 || n > 65535) {
+    throw new UsageError(`Invalid --port value: "${raw}". Expected an integer from 0 to 65535 (0 = OS-assigned).`);
+  }
+  return n;
+}
+
+// src/lib/presets.ts
+var PRESET_IDS = ["dtrpg", "book", "custom"];
+var DTRPG_PRESET = {
+  id: "dtrpg",
+  spec: {
+    label: "DriveThruRPG — Quick Specifications for Print Books",
+    url: "https://help.drivethrupartners.com/hc/en-us/articles/12780800178583-Quick-Specifications-for-Print-Books"
+  },
+  defaultTargets: ["dtrpg"],
+  extensions: [],
+  source: {
+    files: null
+  },
+  print: { signature: 4, reserveLastPage: true, lastPage: undefined },
+  pdfx: {
+    flavor: "x1a",
+    icc: "profiles/CGATS21_CRPC1.icc",
+    stripAnnotations: true,
+    blackText: "k-only",
+    transparency: "flatten-page",
+    flattenPages: [],
+    rasterDpi: undefined
+  },
+  page: {
+    width: 621,
+    height: 810,
+    tolerance: 0.5,
+    bleed: 9,
+    safe: 36,
+    artSafe: 18,
+    gutter: 36
+  },
+  ink: {
+    maxTac: 240,
+    tacTolerance: 0.5
+  },
+  lint: {
+    enabled: true,
+    configPath: null,
+    rules: {}
+  },
+  validate: {
+    enabled: true,
+    checks: {
+      "pdf.structure.qpdf": {
+        enabled: true,
+        severity: "error"
+      },
+      "pdf.print.pdfx-markers": {
+        enabled: true,
+        severity: "error"
+      },
+      "pdf.print.pdfx-metadata": {
+        enabled: true,
+        severity: "error"
+      },
+      "pdf.print.embedded-fonts": {
+        enabled: true,
+        severity: "error"
+      },
+      "pdf.print.safe-margins": {
+        enabled: true,
+        severity: "error"
+      }
+    },
+    source: {
+      markdownlint: null,
+      htmlhint: null,
+      stylelint: null,
+      cssOwnership: null
+    },
+    assets: {
+      maxImageSize: 1e7,
+      allowAlpha: false,
+      approvedFontFiles: [],
+      requireFontLicense: false
+    },
+    pdf: {
+      requireBookmarks: false,
+      requireTocLinks: false,
+      minImageResolution: 300,
+      forbidTransparency: true,
+      requireBleed: false,
+      bleedSize: 9
+    },
+    heuristics: {
+      maxDecorativeLayers: 5,
+      textDensityRange: { min: 200, max: 5000 },
+      maxParagraphsPerSection: 10
+    }
+  }
+};
+var BOOK_PRESET = {
+  id: "book",
+  defaultTargets: [],
+  extensions: [],
+  source: {
+    files: null
+  },
+  print: { signature: 1, reserveLastPage: false, lastPage: undefined },
+  pdfx: {
+    flavor: "x1a",
+    icc: "profiles/CGATS21_CRPC1.icc",
+    stripAnnotations: true,
+    blackText: "icc",
+    transparency: "flatten-page",
+    flattenPages: [],
+    rasterDpi: undefined
+  },
+  page: {
+    width: 432,
+    height: 648,
+    tolerance: 0.5,
+    bleed: undefined,
+    safe: 18,
+    artSafe: undefined,
+    gutter: undefined
+  },
+  ink: {
+    maxTac: 400,
+    tacTolerance: 0.5
+  },
+  lint: {
+    enabled: true,
+    configPath: null,
+    rules: {}
+  },
+  validate: {
+    enabled: true,
+    checks: {
+      "pdf.structure.qpdf": {
+        enabled: true,
+        severity: "error"
+      },
+      "pdf.print.embedded-fonts": {
+        enabled: true,
+        severity: "error"
+      },
+      "pdf.print.safe-margins": {
+        enabled: true,
+        severity: "warning"
+      },
+      "pdf.print.pdfx-markers": false,
+      "pdf.print.pdfx-metadata": false
+    },
+    source: {
+      markdownlint: null,
+      htmlhint: null,
+      stylelint: null,
+      cssOwnership: null
+    },
+    assets: {
+      maxImageSize: 1e7,
+      allowAlpha: true,
+      approvedFontFiles: [],
+      requireFontLicense: false
+    },
+    pdf: {
+      requireBookmarks: false,
+      requireTocLinks: false,
+      minImageResolution: 300,
+      forbidTransparency: false,
+      requireBleed: false,
+      bleedSize: 9
+    },
+    heuristics: {
+      maxDecorativeLayers: 5,
+      textDensityRange: { min: 200, max: 5000 },
+      maxParagraphsPerSection: 10
+    }
+  }
+};
+var CUSTOM_PRESET = {
+  ...BOOK_PRESET,
+  id: "custom",
+  page: null,
+  defaultTargets: []
+};
+var PRESETS = {
+  dtrpg: DTRPG_PRESET,
+  book: BOOK_PRESET,
+  custom: CUSTOM_PRESET
+};
+var warnedIds = new Set;
+function warnOnce(id, message, sink = defaultWarnSink) {
+  if (warnedIds.has(id))
+    return;
+  warnedIds.add(id);
+  sink(message);
+}
+function defaultWarnSink(message) {
+  console.warn(message);
+}
+function resolvePreset(presetName) {
+  if (presetName === undefined) {
+    warnOnce("no-preset-set", '[gutterpress] No `preset` in manifest.yaml — using "dtrpg" ' + "(DriveThruRPG print-ready defaults). Set `preset: dtrpg`, `book`, " + "or `custom` to choose explicitly.");
+    return DTRPG_PRESET;
+  }
+  const preset = PRESETS[presetName];
+  if (!preset) {
+    throw new UsageError(`Unknown preset "${presetName}". Known presets: ${Object.keys(PRESETS).join(", ")}.`);
+  }
+  return preset;
+}
+
+// src/lib/targets.ts
+var DTRPG_TARGET = {
+  id: "dtrpg",
+  label: "DriveThruRPG",
+  overlay: {
+    pdfx: { flavor: DTRPG_PRESET.pdfx.flavor },
+    ink: {
+      maxTac: DTRPG_PRESET.ink.maxTac,
+      tacTolerance: DTRPG_PRESET.ink.tacTolerance
+    },
+    validate: {
+      checks: {
+        "pdf.structure.qpdf": { enabled: true, severity: "error" },
+        "pdf.print.pdfx-markers": { enabled: true, severity: "error" },
+        "pdf.print.pdfx-metadata": { enabled: true, severity: "error" },
+        "pdf.print.embedded-fonts": { enabled: true, severity: "error" },
+        "pdf.print.safe-margins": { enabled: true, severity: "error" }
+      },
+      pdf: {
+        forbidTransparency: DTRPG_PRESET.validate.pdf.forbidTransparency,
+        minImageResolution: DTRPG_PRESET.validate.pdf.minImageResolution
+      }
+    }
+  },
+  requiredChecks: [
+    "pdf.structure.qpdf",
+    "pdf.print.pdfx-markers",
+    "pdf.print.pdfx-metadata",
+    "pdf.print.embedded-fonts",
+    "pdf.print.safe-margins"
+  ],
+  requiredTools: ["qpdf", "gs"]
+};
+var ITCH_TARGET = {
+  id: "itch",
+  label: "itch.io",
+  overlay: {
+    validate: {
+      checks: {
+        "pdf.structure.qpdf": { enabled: true, severity: "error" },
+        "pdf.print.embedded-fonts": { enabled: true, severity: "error" },
+        "pdf.print.pdfx-markers": false,
+        "pdf.print.pdfx-metadata": false,
+        "pdf.print.ink-coverage": false,
+        "pdf.print.safe-margins": false
+      },
+      assets: {
+        allowAlpha: true,
+        maxImageSize: 0
+      },
+      pdf: {
+        forbidTransparency: false,
+        requireBleed: false,
+        minImageResolution: 0
+      }
+    }
+  },
+  requiredChecks: ["pdf.structure.qpdf", "pdf.print.embedded-fonts"],
+  requiredTools: []
+};
+var TARGETS = {
+  dtrpg: DTRPG_TARGET,
+  itch: ITCH_TARGET
+};
+var TARGET_IDS = Object.keys(TARGETS);
+function publishTargetFor(id) {
+  const target = TARGETS[id];
+  if (!target) {
+    throw new UsageError(`Unknown publish target "${id}". Known targets: ${TARGET_IDS.join(", ")}.`);
+  }
+  return target;
+}
+function resolveTargets(requested, fallback) {
+  const ids = requested ?? fallback;
+  const seen = new Set;
+  const out = [];
+  for (const id of ids) {
+    publishTargetFor(id);
+    if (!seen.has(id)) {
+      seen.add(id);
+      out.push(id);
+    }
+  }
+  return out;
+}
+function overlayPreset(preset, target) {
+  const o = target.overlay;
+  return {
+    ...preset,
+    pdfx: { ...preset.pdfx, ...o.pdfx },
+    ink: { ...preset.ink, ...o.ink },
+    validate: {
+      ...preset.validate,
+      checks: { ...preset.validate.checks, ...o.validate?.checks },
+      assets: { ...preset.validate.assets, ...o.validate?.assets },
+      pdf: { ...preset.validate.pdf, ...o.validate?.pdf }
+    }
+  };
+}
+var DEFAULT_STRICT_PDF_CHECKS = [
+  "pdf.structure.qpdf",
+  "pdf.print.pdfx-markers",
+  "pdf.print.pdfx-metadata",
+  "pdf.print.embedded-fonts"
+];
+function applyDefaultPdfStrictChecks(config) {
+  const next = structuredClone(config);
+  for (const checkId of DEFAULT_STRICT_PDF_CHECKS) {
+    if (next.validate.checks[checkId] === undefined) {
+      next.validate.checks[checkId] = { enabled: true, severity: "error" };
+    }
+  }
+  return next;
+}
+
+// src/lib/manifest.ts
+var MANIFEST_FILENAMES = [
+  "manifest.yaml"
+];
+function hasProjectManifest(dir) {
+  return MANIFEST_FILENAMES.some((name) => {
+    const candidate = resolve(dir, name);
+    try {
+      return statSync(candidate).isFile();
+    } catch {
+      return false;
+    }
+  });
+}
+async function loadManifest(pathOrDir) {
+  const { manifest } = await loadManifestWithPath(pathOrDir);
+  return manifest;
+}
+async function loadManifestWithPath(pathOrDir, opts) {
+  const candidates = pathOrDir ? [resolve(pathOrDir), ...MANIFEST_FILENAMES.map((name) => resolve(pathOrDir, name))] : MANIFEST_FILENAMES.map((name) => resolve(name));
+  for (const p of candidates) {
+    if (existsSync(p) && statSync(p).isFile()) {
+      const raw = await readFile(p, "utf8");
+      if (raw.split(/\r?\n/).includes(TWO_VERSIONS_OPEN)) {
+        throw new UsageError(`"${p}" has two versions of a setting — yours and the online version — left by a sync. Open it, keep the one you want and delete the marker lines.`);
+      }
+      try {
+        const manifest = parseYaml(raw) ?? {};
+        return { manifest, manifestDir: dirname(p), manifestPath: p };
+      } catch (error) {
+        if (!(error instanceof YAMLParseError))
+          throw error;
+        const position = error.linePos?.[0];
+        const location = position ? ` at line ${position.line}, column ${position.col}` : "";
+        const summary = (error.message.split(`
+`, 1)[0] ?? error.message).replace(/\s+at line \d+, column \d+:?$/, "");
+        throw new UsageError(`Invalid YAML in "${p}"${location}: ${summary}`);
+      }
+    }
+  }
+  if (opts?.explicit && pathOrDir !== undefined) {
+    throw new UsageError(`manifest not found: ${pathOrDir}. Pass an existing file or a directory containing ${MANIFEST_FILENAMES.join(" or ")}.`);
+  }
+  const manifestDir = pathOrDir ? resolve(pathOrDir) : resolve(".");
+  return { manifest: {}, manifestDir, manifestPath: null };
+}
+var EXTENSION_ENTRY_KEYS = new Set(["use", "export", "options", "enabled"]);
+function normalizeExtensionEntry(entry, index) {
+  const where = `extensions[${index}]`;
+  let use;
+  let rest;
+  if (typeof entry === "string") {
+    use = entry;
+  } else if (entry && typeof entry === "object") {
+    const obj = entry;
+    if ("priority" in obj) {
+      throw new UsageError(`${where}: \`priority\` was removed — the \`extensions:\` list order is the load order. ` + "An entry later in the list is registered later, sees earlier entries' output, and its " + "CSS wins ties; move the entry instead.");
+    }
+    if ("path" in obj || "name" in obj) {
+      throw new UsageError(`${where}: an \`extensions\` entry carries its specifier in \`use:\` — write ` + `\`use: ${String(obj.path ?? obj.name)}\` (or just the bare string).`);
+    }
+    const unknown = Object.keys(obj).filter((k) => !EXTENSION_ENTRY_KEYS.has(k));
+    if (unknown.length > 0) {
+      throw new UsageError(`${where}: unknown key(s) ${unknown.map((k) => `\`${k}\``).join(", ")} — an entry takes ` + "`use`, `options`, `export`, `enabled`.");
+    }
+    if (typeof obj.use !== "string" || !obj.use.trim()) {
+      throw new UsageError(`${where}: an object entry needs \`use: <specifier>\`.`);
+    }
+    use = obj.use;
+    rest = entry;
+  } else {
+    throw new UsageError(`${where}: expected a specifier string or an object with \`use:\`.`);
+  }
+  let parsed;
+  try {
+    parsed = parseExtensionSpecifier(use);
+  } catch (error) {
+    throw new UsageError(`${where}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return {
+    use: use.trim(),
+    ...parsed.kind === "path" ? { path: parsed.path } : { name: parsed.name },
+    ...parsed.kind === "npm" && parsed.version ? { version: parsed.version } : {},
+    ...rest?.export ? { export: rest.export } : {},
+    options: rest?.options ?? {}
+  };
+}
+function pluginsRemovedMessage(raw) {
+  const specifierOf = (s) => isPathSpecifier(s) || s.startsWith("@") || !/[\\/]/.test(s) ? s : `./${s}`;
+  const priorityOf = (e) => e && typeof e === "object" && typeof e.priority === "number" ? e.priority : 100;
+  const entries = Array.isArray(raw) ? [...raw] : [];
+  entries.sort((a, b) => priorityOf(b) - priorityOf(a));
+  const lines = [];
+  for (const e of entries) {
+    if (typeof e === "string") {
+      lines.push(`  - ${specifierOf(e)}`);
+      continue;
+    }
+    if (!e || typeof e !== "object")
+      continue;
+    const o = e;
+    const spec = typeof o.path === "string" ? specifierOf(o.path) : typeof o.name === "string" ? `${o.name}${typeof o.version === "string" ? `@${o.version}` : ""}` : "<specifier>";
+    const extra = ["export", "options", "enabled"].filter((k) => (k in o) && (k !== "enabled" || o[k] === false));
+    if (extra.length === 0) {
+      lines.push(`  - ${spec}`);
+      continue;
+    }
+    lines.push(`  - use: ${spec}`);
+    for (const k of extra) {
+      lines.push(`    ${k}: ${k === "options" ? JSON.stringify(o[k]) : String(o[k])}`);
+    }
+  }
+  return "Manifest field `plugins` was replaced by `extensions` — one list of bare specifiers in " + "load order (no `path:`/`name:` wrappers, no `priority`; a later entry loads later and " + "its CSS wins ties). Rewrite it as:" + `
+` + "extensions:" + `
+` + (lines.length > 0 ? lines.join(`
+`) : "  - ./plugins/my-plugin.js");
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function mergeShape(cli, manifest, preset) {
+  const out = {};
+  for (const key of Object.keys(preset)) {
+    const presetValue = preset[key];
+    const manifestValue = manifest ? manifest[key] : undefined;
+    const cliValue = cli ? cli[key] : undefined;
+    out[key] = isPlainObject(presetValue) ? mergeShape(cliValue, manifestValue, presetValue) : cliValue ?? manifestValue ?? presetValue;
+  }
+  return out;
+}
+function resolveConfig(cliOverrides, manifest) {
+  const presetName = cliOverrides.preset ?? manifest.preset;
+  return resolveWithPreset(cliOverrides, manifest, resolvePreset(presetName));
+}
+function resolveConfigForTarget(cliOverrides, manifest, targetId) {
+  const presetName = cliOverrides.preset ?? manifest.preset;
+  const preset = resolvePreset(presetName);
+  return resolveWithPreset(cliOverrides, manifest, overlayPreset(preset, publishTargetFor(targetId)));
+}
+function resolveCustomPage(c, m) {
+  const width = c.page?.width ?? m.page?.width;
+  const height = c.page?.height ?? m.page?.height;
+  const missing = [
+    width === undefined ? "page.width" : null,
+    height === undefined ? "page.height" : null
+  ].filter((f) => f !== null);
+  if (missing.length > 0) {
+    throw new UsageError(`preset: custom requires ${missing.join(" and ")} in manifest.yaml ` + `(points; 72pt = 1in). Example for US Letter:
+` + `  page:
+    width: 612
+    height: 792`);
+  }
+  return {
+    width,
+    height,
+    tolerance: c.page?.tolerance ?? m.page?.tolerance ?? 0.5,
+    bleed: c.page?.bleed ?? m.page?.bleed,
+    safe: c.page?.safe ?? m.page?.safe,
+    artSafe: c.page?.artSafe ?? m.page?.artSafe,
+    gutter: c.page?.gutter ?? m.page?.gutter
+  };
+}
+function resolveWithPreset(cliOverrides, manifest, preset) {
+  const m = manifest;
+  const c = cliOverrides;
+  const legacy = m;
+  if (legacy.output !== undefined || legacy.source?.assets !== undefined) {
+    const stale = [
+      legacy.output !== undefined ? "`output`" : null,
+      legacy.source?.assets !== undefined ? "`source.assets`" : null
+    ].filter(Boolean);
+    throw new UsageError(`Manifest field(s) ${stale.join(" and ")} are no longer supported — remove them.
+` + "  Output goes to `dist/<title-slug>/` automatically (use `--out` for a one-off location).\n" + "  Assets are discovered from what your book actually references, so no list is needed.");
+  }
+  if ((m.validate?.source?.allowedCallouts?.length ?? 0) > 0 || (c.validate?.source?.allowedCallouts?.length ?? 0) > 0) {
+    warnOnce("allowed-callouts-deprecated", "[gutterpress] manifest field `validate.source.allowedCallouts` is " + "deprecated and ignored. The `:::` container syntax it gated was " + "removed 2026-05-17. See docs/migrations/2026-05-removing-container-syntax.md.");
+  }
+  for (const key of ["minImageDpi", "allowedColorSpaces"]) {
+    if (m.validate?.assets?.[key] !== undefined || c.validate?.assets?.[key] !== undefined) {
+      warnOnce(`assets-${key}-deprecated`, `[gutterpress] manifest field \`validate.assets.${key}\` is deprecated and ` + "ignored. The source-image check it configured was removed; the build " + "and the PDF checks measure what actually prints.");
+    }
+  }
+  const removed = m;
+  if (removed.engine !== undefined) {
+    throw new UsageError("Manifest field `engine` was removed — delete it. The Gutterpress engine " + "(native Chromium pagination) is the only engine, so there is nothing to select.");
+  }
+  if (removed.engineStyles !== undefined) {
+    throw new UsageError("Manifest field `engineStyles` was removed — move its entries to the END of " + "`styles:`. They were always loaded last; their place in that list is the " + "only thing the field ever expressed.");
+  }
+  const legacyPlugins = m.plugins;
+  if (legacyPlugins !== undefined) {
+    throw new UsageError(pluginsRemovedMessage(legacyPlugins));
+  }
+  const lastPage = c.print?.lastPage ?? m.print?.lastPage;
+  if (lastPage !== undefined && lastPage !== "blank" && lastPage !== "short-by-one") {
+    throw new UsageError(`Manifest field \`print.lastPage\` must be "blank" or "short-by-one", got ${JSON.stringify(lastPage)}.`);
+  }
+  const transparency = c.pdfx?.transparency ?? m.pdfx?.transparency;
+  if (transparency !== undefined && transparency !== "flatten-page" && transparency !== "preserve-text") {
+    throw new UsageError(`Manifest field \`pdfx.transparency\` must be "flatten-page" or "preserve-text", got ${JSON.stringify(transparency)}.`);
+  }
+  const flattenPages = c.pdfx?.flattenPages ?? m.pdfx?.flattenPages;
+  if (flattenPages !== undefined && !(Array.isArray(flattenPages) && flattenPages.every((n) => Number.isInteger(n) && n >= 1))) {
+    throw new UsageError(`Manifest field \`pdfx.flattenPages\` must be a list of page numbers (1, 2, …), got ${JSON.stringify(flattenPages)}.`);
+  }
+  const rasterDpi = c.pdfx?.rasterDpi ?? m.pdfx?.rasterDpi;
+  if (rasterDpi !== undefined && !(Number.isInteger(rasterDpi) && rasterDpi >= 72 && rasterDpi <= 1200)) {
+    throw new UsageError(`Manifest field \`pdfx.rasterDpi\` must be a whole number from 72 to 1200, got ${JSON.stringify(rasterDpi)}.`);
+  }
+  const rawExtensions = c.extensions ?? m.extensions ?? [];
+  if (!Array.isArray(rawExtensions)) {
+    throw new UsageError("Manifest field `extensions` must be a list of specifiers.");
+  }
+  const extensions = rawExtensions.map((entry, index) => ({ entry, index })).filter(({ entry }) => typeof entry === "string" || entry?.enabled !== false).map(({ entry, index }) => normalizeExtensionEntry(entry, index));
+  return {
+    title: c.title ?? m.title ?? "Document",
+    authors: c.authors ?? m.authors ?? [],
+    preset: preset.id,
+    spec: preset.spec,
+    styles: c.styles ?? m.styles,
+    extensions,
+    targets: resolveTargets(c.targets ?? m.targets, preset.defaultTargets),
+    source: mergeShape(c.source, m.source, preset.source),
+    pdfx: mergeShape(c.pdfx, m.pdfx, preset.pdfx),
+    print: mergeShape(c.print, m.print, preset.print),
+    page: preset.page ? mergeShape(c.page, m.page, preset.page) : resolveCustomPage(c, m),
+    ink: mergeShape(c.ink, m.ink, preset.ink),
+    lint: {
+      ...mergeShape(c.lint, m.lint, preset.lint),
+      rules: { ...preset.lint.rules, ...m.lint?.rules, ...c.lint?.rules }
+    },
+    validate: {
+      enabled: c.validate?.enabled ?? m.validate?.enabled ?? preset.validate.enabled,
+      checks: { ...preset.validate.checks, ...m.validate?.checks, ...c.validate?.checks },
+      source: mergeShape(c.validate?.source, m.validate?.source, preset.validate.source),
+      assets: mergeShape(c.validate?.assets, m.validate?.assets, preset.validate.assets),
+      pdf: mergeShape(c.validate?.pdf, m.validate?.pdf, preset.validate.pdf),
+      heuristics: mergeShape(c.validate?.heuristics, m.validate?.heuristics, preset.validate.heuristics)
+    }
+  };
+}
+
+// src/lib/manifest-doc.ts
+function resolveManifestPath(projectDir) {
+  const existing = MANIFEST_FILENAMES.find((name) => existsSync2(path.join(projectDir, name)));
+  return path.join(projectDir, existing ?? MANIFEST_FILENAMES[0]);
+}
+async function loadManifestDoc(projectDir) {
+  const file = resolveManifestPath(projectDir);
+  let text = "";
+  try {
+    text = await readFile2(file, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+  return { doc: parseDocument(text), file };
+}
+async function writeManifestDoc(file, doc) {
+  const dir = path.dirname(file);
+  await mkdir(dir, { recursive: true });
+  const temporary = path.join(dir, `.${path.basename(file)}.tmp-${process.pid}-${randomUUID()}`);
+  try {
+    const handle = await open(temporary, "wx", 438);
+    try {
+      await handle.writeFile(doc.toString(), "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temporary, file);
+    const directory = await open(dir, "r").catch(() => null);
+    if (directory) {
+      await directory.sync().catch(() => {});
+      await directory.close();
+    }
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+function ensureSeq(doc, key) {
+  let seq = doc.get(key, true);
+  if (!isSeq(seq)) {
+    const fresh = new YAMLSeq(doc.schema);
+    doc.set(key, fresh);
+    seq = fresh;
+  }
+  return seq;
+}
+function scalarString(item) {
+  if (item && typeof item === "object" && "value" in item) {
+    const v = item.value;
+    return typeof v === "string" ? v : null;
+  }
+  return typeof item === "string" ? item : null;
+}
+
+// src/lib/npm-plugin-installer.ts
+import { createHash, randomUUID as randomUUID2, timingSafeEqual } from "node:crypto";
+import { createReadStream } from "node:fs";
+import {
+  lstat,
+  mkdir as mkdir2,
+  mkdtemp,
+  open as open2,
+  readFile as readFile3,
+  realpath,
+  rename as rename2,
+  rm as rm2,
+  rmdir
+} from "node:fs/promises";
+import path2 from "node:path";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+import { maxSatisfying, satisfies, validRange } from "semver";
+
+// src/lib/npm-registry.ts
+var DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
+var ENV_OVERRIDE = "GUTTERPRESS_NPM_REGISTRY";
+function npmRegistryUrl() {
+  const configured = process.env[ENV_OVERRIDE]?.trim();
+  if (!configured)
+    return DEFAULT_NPM_REGISTRY;
+  let scheme;
+  try {
+    scheme = new URL(configured).protocol;
+  } catch {
+    throw new Error(`Invalid ${ENV_OVERRIDE} URL "${configured}".`);
+  }
+  if (scheme !== "http:" && scheme !== "https:") {
+    throw new Error(`${ENV_OVERRIDE} must be an http(s) URL — got "${scheme}".`);
+  }
+  return configured.replace(/\/+$/, "");
+}
+
+// src/lib/npm-plugin-installer.ts
+var DEFAULT_LIMITS = {
+  metadataBytes: 15 * 1024 * 1024,
+  packageTarballBytes: 50 * 1024 * 1024,
+  totalNetworkBytes: 250 * 1024 * 1024,
+  packageFileBytes: 50 * 1024 * 1024,
+  totalUnpackedBytes: 512 * 1024 * 1024,
+  totalFiles: 50000,
+  totalPackages: 512,
+  dependencyDepth: 64
+};
+var METADATA_TIMEOUT_MS = 30000;
+var TARBALL_TIMEOUT_MS = 120000;
+
+class SecurityInstallError extends FetchPassthroughError {
+}
+
+class PackageUnavailableError extends Error {
+}
+function isOptionalAvailabilityError(error) {
+  return error instanceof PackageUnavailableError || error instanceof FriendlyHttpError || error instanceof FetchUnavailableError;
+}
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function stringMap(value) {
+  const map = object(value);
+  if (!map)
+    return {};
+  const result = {};
+  for (const [name, selector] of Object.entries(map)) {
+    if (typeof selector === "string" && selector.trim())
+      result[name] = selector.trim();
+  }
+  return result;
+}
+function mb(bytes) {
+  return `${Math.ceil(bytes / 1024 / 1024)}MB`;
+}
+function isContained(root, candidate) {
+  const relative = path2.relative(root, candidate);
+  return relative === "" || !relative.startsWith("..") && !path2.isAbsolute(relative);
+}
+function mergeLimits(overrides) {
+  const limits = { ...DEFAULT_LIMITS, ...overrides };
+  for (const [name, value] of Object.entries(limits)) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+      throw new Error(`Invalid npm plugin install limit ${name}: ${value}`);
+    }
+  }
+  return limits;
+}
+async function streamResponse(ctx, response, maxBytes, totalLimitMessage, onChunk) {
+  if (!response.body)
+    throw new Error("Registry response had no body.");
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    throw new SecurityInstallError(`Registry response is too large (max ${mb(maxBytes)}).`);
+  }
+  if (Number.isFinite(declared) && declared > ctx.limits.totalNetworkBytes - ctx.totalNetworkBytes) {
+    throw new SecurityInstallError(totalLimitMessage);
+  }
+  const reader = response.body.getReader();
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      total += value.length;
+      if (total > maxBytes) {
+        await reader.cancel("size limit exceeded").catch(() => {});
+        throw new SecurityInstallError(`Registry response is too large (max ${mb(maxBytes)}).`);
+      }
+      if (ctx.totalNetworkBytes + value.length > ctx.limits.totalNetworkBytes) {
+        await reader.cancel("total size limit exceeded").catch(() => {});
+        throw new SecurityInstallError(totalLimitMessage);
+      }
+      ctx.totalNetworkBytes += value.length;
+      await onChunk(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return total;
+}
+async function fetchPackument(ctx, name) {
+  let pending = ctx.packuments.get(name);
+  if (pending)
+    return pending;
+  pending = withFetchTimeout({
+    timeoutMs: METADATA_TIMEOUT_MS,
+    signal: ctx.signal,
+    timeoutMessage: `Looking up ${name} on npm timed out. Check your connection and try again.`,
+    offlineMessage: (cause) => `Looking up ${name} on npm failed (${cause instanceof Error ? cause.message : String(cause)}).`
+  }, async (signal) => {
+    const response = await ctx.fetch(`${npmRegistryUrl()}/${encodeURIComponent(name)}`, {
+      signal,
+      redirect: "error",
+      headers: { accept: "application/vnd.npm.install-v1+json" }
+    });
+    if (response.status === 404) {
+      throw new FriendlyHttpError(`npm package "${name}" was not found.`);
+    }
+    if (!response.ok) {
+      throw new FriendlyHttpError(`Looking up ${name} on npm failed (HTTP ${response.status}).`);
+    }
+    const chunks = [];
+    const size = await streamResponse(ctx, response, ctx.limits.metadataBytes, `Plugin dependency metadata exceeds the ${mb(ctx.limits.totalNetworkBytes)} total download limit.`, (chunk) => {
+      chunks.push(chunk);
+    });
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.length;
+    }
+    let metadata = null;
+    try {
+      metadata = object(JSON.parse(new TextDecoder().decode(bytes)));
+    } catch {}
+    if (!metadata || metadata.name !== name) {
+      throw new FriendlyHttpError(`npm returned invalid metadata for "${name}".`);
+    }
+    return metadata;
+  }).catch((error) => {
+    ctx.packuments.delete(name);
+    throw error;
+  });
+  ctx.packuments.set(name, pending);
+  return pending;
+}
+function parseIntegrity(dist) {
+  const integrity = typeof dist.integrity === "string" ? dist.integrity.trim() : "";
+  const parsed = integrity.split(/\s+/).map((token) => token.match(/^(sha512|sha384|sha256|sha1)-([A-Za-z0-9+/]+={0,2})(?:\?.*)?$/)).filter((match) => Boolean(match?.[1] && match[2]));
+  for (const algorithm of ["sha512", "sha384", "sha256"]) {
+    const match = parsed.find((candidate) => candidate[1] === algorithm);
+    if (!match)
+      continue;
+    const digest = Buffer.from(match[2], "base64");
+    if (digest.length > 0) {
+      return { algorithm, digest, label: `${algorithm}-${match[2]}`, legacySha1: false };
+    }
+  }
+  const sha1 = parsed.find((candidate) => candidate[1] === "sha1");
+  if (sha1) {
+    return {
+      algorithm: "sha1",
+      digest: Buffer.from(sha1[2], "base64"),
+      label: `sha1-${sha1[2]}`,
+      legacySha1: true
+    };
+  }
+  if (integrity) {
+    throw new SecurityInstallError("The npm registry supplied integrity data, but no supported SHA-256-or-stronger hash.");
+  }
+  const shasum = typeof dist.shasum === "string" ? dist.shasum.trim().toLowerCase() : "";
+  if (/^[a-f0-9]{40}$/.test(shasum)) {
+    return {
+      algorithm: "sha1",
+      digest: Buffer.from(shasum, "hex"),
+      label: `sha1-hex-${shasum}`,
+      legacySha1: true
+    };
+  }
+  throw new SecurityInstallError("The npm registry provided no usable integrity hash, so the package was not installed.");
+}
+function unsupportedSelector(selector) {
+  return /^(?:file:|git\+|https?:|ssh:|github:|workspace:|link:|npm:)/i.test(selector);
+}
+async function selectPackage(ctx, name, selector) {
+  if (selector && unsupportedSelector(selector)) {
+    throw new PackageUnavailableError(`Dependency selector "${selector}" for ${name} is not a registry semver range or dist-tag.`);
+  }
+  const metadata = await fetchPackument(ctx, name);
+  const versions = object(metadata.versions);
+  const tags = object(metadata["dist-tags"]);
+  if (!versions || !tags)
+    throw new PackageUnavailableError(`npm metadata for "${name}" has no versions.`);
+  let version;
+  if (!selector) {
+    if (typeof tags.latest === "string")
+      version = tags.latest;
+  } else if (object(versions[selector])) {
+    version = selector;
+  } else if (typeof tags[selector] === "string") {
+    version = tags[selector];
+  } else if (validRange(selector)) {
+    version = maxSatisfying(Object.keys(versions), selector) ?? undefined;
+  }
+  if (!version || !isExactNpmVersion(version)) {
+    throw new PackageUnavailableError(`No exact npm version of "${name}" satisfies "${selector ?? "latest"}".`);
+  }
+  const selected = object(versions[version]);
+  if (!selected || selected.name !== name || selected.version !== version) {
+    throw new SecurityInstallError(`npm metadata identity failed for "${name}@${version}".`);
+  }
+  const dist = object(selected.dist);
+  if (!dist || typeof dist.tarball !== "string") {
+    throw new PackageUnavailableError(`npm metadata for "${name}@${version}" has no tarball.`);
+  }
+  let tarball;
+  try {
+    tarball = new URL(dist.tarball);
+  } catch {
+    throw new SecurityInstallError(`npm returned an invalid tarball URL for "${name}@${version}".`);
+  }
+  if (tarball.origin !== new URL(npmRegistryUrl()).origin || tarball.username || tarball.password) {
+    throw new SecurityInstallError(`npm returned an unexpected tarball host for "${name}@${version}".`);
+  }
+  return { name, version, tarball: tarball.href, integrity: parseIntegrity(dist) };
+}
+async function downloadTarball(ctx, pkg, archivePath) {
+  const file = await open2(archivePath, "wx");
+  const hash = createHash(pkg.integrity.algorithm);
+  try {
+    await withFetchTimeout({
+      timeoutMs: TARBALL_TIMEOUT_MS,
+      signal: ctx.signal,
+      timeoutMessage: `Downloading ${pkg.name}@${pkg.version} timed out.`,
+      offlineMessage: (cause) => `Downloading ${pkg.name}@${pkg.version} failed (${cause instanceof Error ? cause.message : String(cause)}).`
+    }, async (signal) => {
+      const response = await ctx.fetch(pkg.tarball, { signal, redirect: "error" });
+      if (!response.ok) {
+        throw new FriendlyHttpError(`Downloading ${pkg.name}@${pkg.version} failed (HTTP ${response.status}).`);
+      }
+      await streamResponse(ctx, response, ctx.limits.packageTarballBytes, `Plugin dependency downloads exceed the ${mb(ctx.limits.totalNetworkBytes)} total limit.`, async (chunk) => {
+        hash.update(chunk);
+        try {
+          await file.write(chunk);
+        } catch (cause) {
+          throw new SecurityInstallError(`Could not store ${pkg.name}@${pkg.version} while downloading.`, { cause });
+        }
+      });
+    });
+  } finally {
+    await file.close();
+  }
+  const actual = hash.digest();
+  if (actual.length !== pkg.integrity.digest.length || !timingSafeEqual(actual, pkg.integrity.digest)) {
+    throw new SecurityInstallError(`The tarball for ${pkg.name}@${pkg.version} failed its registry integrity check.`);
+  }
+}
+function safeTarRelative(entryPath, packageName) {
+  if (!entryPath || entryPath.includes("\\") || entryPath.startsWith("/") || /^[a-zA-Z]:/.test(entryPath)) {
+    throw new SecurityInstallError(`The npm tarball contains an unsafe path: ${entryPath || "(empty)"}`);
+  }
+  const parts = entryPath.split("/");
+  if (parts.at(-1) === "")
+    parts.pop();
+  const legacyTypesRoot = packageName.startsWith("@types/") ? packageName.slice("@types/".length) : null;
+  if (parts.some((part) => !part || part === "." || part === "..") || parts[0] !== "package" && parts[0] !== legacyTypesRoot) {
+    throw new SecurityInstallError(`The npm tarball contains an unsafe path: ${entryPath}`);
+  }
+  const relative = parts.slice(1).join("/");
+  if (!relative)
+    return { relative, key: "" };
+  assertWindowsSafeRelativePath(relative);
+  if (relative.normalize("NFKC").split("/").some((part) => part.toLowerCase() === "node_modules")) {
+    throw new SecurityInstallError(`The npm tarball contains bundled node_modules (${entryPath}); bundled dependencies are not accepted.`);
+  }
+  return { relative, key: windowsPathKey(relative) };
+}
+async function extractTarball(ctx, archivePath, packageDir, packageName) {
+  const { extract } = await import("tar");
+  let rejected = null;
+  const seen = new Set;
+  const metadataTypes = new Set([
+    "GlobalExtendedHeader",
+    "ExtendedHeader",
+    "NextFileHasLongLinkpath",
+    "NextFileHasLongPath",
+    "OldGnuLongPath",
+    "OldExtendedHeader"
+  ]);
+  await mkdir2(packageDir, { recursive: true });
+  const unpack = extract({
+    cwd: packageDir,
+    strip: 1,
+    strict: true,
+    preservePaths: false,
+    preserveOwner: false,
+    noMtime: true,
+    chmod: false,
+    maxDepth: ctx.limits.dependencyDepth * 4,
+    filter: (entryPath, rawEntry) => {
+      if (rejected)
+        return false;
+      const entry = rawEntry;
+      if (metadataTypes.has(entry.type))
+        return true;
+      if (entry.type === "Link" || entry.type === "SymbolicLink") {
+        rejected = new SecurityInstallError(`The npm tarball contains an unsafe link: ${entryPath}`);
+        return false;
+      }
+      if (entry.type !== "File" && entry.type !== "OldFile" && entry.type !== "Directory") {
+        rejected = new SecurityInstallError(`The npm tarball contains unsupported entry type ${entry.type}: ${entryPath}`);
+        return false;
+      }
+      try {
+        const { relative, key } = safeTarRelative(entryPath, packageName);
+        if (!relative) {
+          if (entry.type === "Directory")
+            return true;
+          throw new SecurityInstallError(`The npm tarball uses package/ as a file.`);
+        }
+        if (seen.has(key)) {
+          throw new SecurityInstallError(`The npm tarball has a Windows-colliding path: ${entryPath}`);
+        }
+        seen.add(key);
+        ctx.totalFiles++;
+        if (ctx.totalFiles > ctx.limits.totalFiles) {
+          throw new SecurityInstallError(`Plugin graph exceeds ${ctx.limits.totalFiles} files.`);
+        }
+        if (entry.type !== "Directory") {
+          if (!Number.isSafeInteger(entry.size) || entry.size < 0 || entry.size > ctx.limits.packageFileBytes) {
+            throw new SecurityInstallError(`Package file exceeds the ${mb(ctx.limits.packageFileBytes)} limit: ${entryPath}`);
+          }
+        }
+        return true;
+      } catch (error) {
+        rejected = error instanceof Error ? error : new SecurityInstallError(String(error));
+        return false;
+      }
+    }
+  });
+  const limiter = new Transform({
+    transform(chunk, _encoding, callback) {
+      ctx.totalUnpackedBytes += chunk.length;
+      if (ctx.totalUnpackedBytes > ctx.limits.totalUnpackedBytes) {
+        callback(new SecurityInstallError(`Plugin graph expands beyond the ${mb(ctx.limits.totalUnpackedBytes)} limit.`));
+      } else
+        callback(null, chunk);
+    }
+  });
+  try {
+    await pipeline(createReadStream(archivePath), createGunzip(), limiter, unpack);
+  } catch (error) {
+    if (rejected)
+      throw rejected;
+    if (error instanceof SecurityInstallError)
+      throw error;
+    throw new SecurityInstallError(`The npm tarball could not be safely extracted (${error instanceof Error ? error.message : String(error)}).`, { cause: error });
+  }
+  if (rejected)
+    throw rejected;
+}
+async function readInstalledManifest(packageDir, selected) {
+  const packageJsonPath = path2.join(packageDir, "package.json");
+  let manifest = null;
+  try {
+    const info = await lstat(packageJsonPath);
+    if (!info.isFile() || info.isSymbolicLink())
+      throw new Error("not a regular file");
+    manifest = object(JSON.parse(await readFile3(packageJsonPath, "utf8")));
+  } catch (error) {
+    throw new SecurityInstallError(`Downloaded ${selected.name}@${selected.version} has no valid package.json (${error instanceof Error ? error.message : String(error)}).`);
+  }
+  if (manifest?.name !== selected.name || manifest.version !== selected.version) {
+    throw new SecurityInstallError(`Downloaded ${String(manifest?.name)}@${String(manifest?.version)} instead of ${selected.name}@${selected.version}.`);
+  }
+  return manifest;
+}
+function platformAllowed(rule, current) {
+  let values;
+  if (typeof rule === "string") {
+    values = [rule];
+  } else if (Array.isArray(rule) && rule.every((item) => typeof item === "string")) {
+    values = rule;
+  } else {
+    return true;
+  }
+  if (values.length === 0)
+    return true;
+  if (values.length === 1 && values[0] === "any")
+    return true;
+  if (values.includes(`!${current}`))
+    return false;
+  const positives = values.filter((value) => !value.startsWith("!"));
+  return positives.length === 0 || positives.includes(current);
+}
+function relativePackagePath(parentPackagePath, name) {
+  const segments = name.split("/");
+  return parentPackagePath ? `${parentPackagePath}/node_modules/${segments.join("/")}` : `node_modules/${segments.join("/")}`;
+}
+async function installPackage(ctx, name, selector, parentPackagePath, ancestors, depth, optional) {
+  const recordStart = ctx.records.length;
+  const warningsBefore = new Set(ctx.warnings);
+  const discardOptionalSubtree = () => {
+    ctx.records.splice(recordStart);
+    ctx.warnings = warningsBefore;
+  };
+  if (depth > ctx.limits.dependencyDepth) {
+    throw new SecurityInstallError(`Dependency graph exceeds depth ${ctx.limits.dependencyDepth}.`);
+  }
+  let selected;
+  try {
+    selected = await selectPackage(ctx, name, selector);
+  } catch (error) {
+    if (optional && isOptionalAvailabilityError(error)) {
+      discardOptionalSubtree();
+      return { skipped: error instanceof Error ? error.message : String(error) };
+    }
+    throw error;
+  }
+  const ancestor = ancestors.find((candidate) => candidate.name === name && (candidate.version === selected.version || (selector ? satisfies(candidate.version, selector) : false)));
+  if (ancestor)
+    return { path: ancestor.path };
+  if (ctx.records.length >= ctx.limits.totalPackages) {
+    throw new SecurityInstallError(`Dependency graph exceeds ${ctx.limits.totalPackages} packages.`);
+  }
+  const relativePath = relativePackagePath(parentPackagePath, name);
+  const packageDir = path2.join(ctx.stageRoot, ...relativePath.split("/"));
+  const archivePath = path2.join(ctx.downloadsDir, `${ctx.archiveCounter++}.tgz`);
+  try {
+    await mkdir2(path2.dirname(packageDir), { recursive: true });
+    await downloadTarball(ctx, selected, archivePath);
+    await extractTarball(ctx, archivePath, packageDir, selected.name);
+    const manifest = await readInstalledManifest(packageDir, selected);
+    if (!platformAllowed(manifest.os, process.platform) || !platformAllowed(manifest.cpu, process.arch)) {
+      const reason = `${name}@${selected.version} does not support ${process.platform}/${process.arch}`;
+      if (optional) {
+        await rm2(packageDir, { recursive: true, force: true });
+        return { skipped: reason };
+      }
+      throw new PackageUnavailableError(reason);
+    }
+    if (parentPackagePath === null) {
+      try {
+        await resolvePackageEntry(packageDir, manifest);
+      } catch (cause) {
+        throw new SecurityInstallError(`${name}@${selected.version} has no JavaScript plugin entry.`, { cause });
+      }
+    }
+    const record = {
+      path: relativePath,
+      name,
+      version: selected.version,
+      packageDir,
+      manifest
+    };
+    ctx.records.push(record);
+    if (selected.integrity.legacySha1) {
+      ctx.warnings.add(`${name}@${selected.version} is an old npm release with only SHA-1 registry integrity. It was accepted for compatibility.`);
+    }
+    const dependencies = stringMap(manifest.dependencies);
+    const optionalDependencies = stringMap(manifest.optionalDependencies);
+    for (const optionalName of Object.keys(optionalDependencies))
+      delete dependencies[optionalName];
+    const peerDependencies = stringMap(manifest.peerDependencies);
+    const peerMeta = object(manifest.peerDependenciesMeta) ?? {};
+    for (const existing of [...Object.keys(dependencies), ...Object.keys(optionalDependencies)]) {
+      delete peerDependencies[existing];
+    }
+    const nextAncestors = [...ancestors, record];
+    const requiredEntries = [
+      ...Object.entries(dependencies).map(([dependency, range]) => ({ dependency, range, kind: "required" })),
+      ...Object.entries(peerDependencies).filter(([dependency]) => object(peerMeta[dependency])?.optional !== true).map(([dependency, range]) => ({ dependency, range, kind: "peer" }))
+    ].sort((a, b) => a.dependency.localeCompare(b.dependency));
+    for (const { dependency, range } of requiredEntries) {
+      const child = await installPackage(ctx, dependency, range, relativePath, nextAncestors, depth + 1, false);
+      if (!child.path)
+        throw new Error(`Required dependency ${dependency} was unexpectedly skipped.`);
+    }
+    const optionalEntries = Object.entries(optionalDependencies).sort(([a], [b]) => a.localeCompare(b));
+    for (const [dependency, range] of optionalEntries) {
+      await installPackage(ctx, dependency, range, relativePath, nextAncestors, depth + 1, true);
+    }
+    return { path: relativePath };
+  } catch (error) {
+    await rm2(packageDir, { recursive: true, force: true });
+    if (optional && isOptionalAvailabilityError(error)) {
+      discardOptionalSubtree();
+      return { skipped: error instanceof Error ? error.message : String(error) };
+    }
+    throw error;
+  } finally {
+    await rm2(archivePath, { force: true });
+  }
+}
+async function ensureDirectory(pathname) {
+  try {
+    const info = await lstat(pathname);
+    if (info.isSymbolicLink() || !info.isDirectory()) {
+      throw new Error(`Plugin install path is not a normal directory: ${pathname}`);
+    }
+    return false;
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+    await mkdir2(pathname);
+    return true;
+  }
+}
+async function removeEmptyDirs(dirs) {
+  for (const dir of [...dirs].reverse()) {
+    try {
+      await rmdir(dir);
+    } catch {
+      return;
+    }
+  }
+}
+async function prepareVendorParent(projectDir, name) {
+  const plugins = path2.join(projectDir, PLUGINS_DIR);
+  const npm = path2.join(plugins, VENDORED_NPM_DIR);
+  const packageParent = path2.dirname(vendoredNpmPluginRoot(projectDir, name, "0.0.0"));
+  await mkdir2(projectDir, { recursive: true });
+  const createdDirs = [];
+  try {
+    for (const dir of [plugins, npm, packageParent]) {
+      if (await ensureDirectory(dir))
+        createdDirs.push(dir);
+    }
+    const [realNpm, realPackageParent] = await Promise.all([
+      realpath(npm),
+      realpath(packageParent)
+    ]);
+    if (!isContained(projectDir, realNpm) || !isContained(projectDir, realPackageParent)) {
+      throw new Error("Plugin install path resolves outside the book folder.");
+    }
+    return { npmRoot: realNpm, createdDirs };
+  } catch (error) {
+    await removeEmptyDirs(createdDirs);
+    throw error;
+  }
+}
+async function installNpmPlugin(projectDirInput, packageSpec, options = {}) {
+  const requestedProjectDir = path2.resolve(projectDirInput);
+  await mkdir2(requestedProjectDir, { recursive: true });
+  const projectDir = await realpath(requestedProjectDir);
+  const requested = parseNpmPluginSpec(packageSpec);
+  const { npmRoot, createdDirs } = await prepareVendorParent(projectDir, requested.name);
+  const container = await mkdtemp(path2.join(npmRoot, ".install-"));
+  const stageRoot = path2.join(container, "root");
+  const downloadsDir = path2.join(container, "downloads");
+  await Promise.all([mkdir2(stageRoot), mkdir2(downloadsDir)]);
+  const ctx = {
+    fetch: options.fetch ?? globalThis.fetch,
+    signal: options.signal,
+    limits: mergeLimits(options.limits),
+    stageRoot,
+    downloadsDir,
+    packuments: new Map,
+    records: [],
+    warnings: new Set,
+    totalNetworkBytes: 0,
+    totalUnpackedBytes: 0,
+    totalFiles: 0,
+    archiveCounter: 0
+  };
+  let finalRoot = "";
+  let backupRoot = null;
+  let published = false;
+  try {
+    const rootResult = await installPackage(ctx, requested.name, requested.selector, null, [], 0, false);
+    if (!rootResult.path)
+      throw new Error("Root plugin package was unexpectedly skipped.");
+    const rootRecord = ctx.records.find((record) => record.path === rootResult.path);
+    if (!rootRecord)
+      throw new Error("Root plugin package is missing from the dependency graph.");
+    finalRoot = vendoredNpmPluginRoot(projectDir, rootRecord.name, rootRecord.version);
+    const realFinalParent = await realpath(path2.dirname(finalRoot));
+    if (!isContained(projectDir, realFinalParent)) {
+      throw new Error("Plugin install destination resolves outside the book folder.");
+    }
+    try {
+      await lstat(finalRoot);
+      backupRoot = `${finalRoot}.backup-${randomUUID2()}`;
+      await rename2(finalRoot, backupRoot);
+    } catch (error) {
+      if (error.code !== "ENOENT")
+        throw error;
+    }
+    try {
+      await rename2(stageRoot, finalRoot);
+    } catch (error) {
+      if (backupRoot) {
+        try {
+          await rename2(backupRoot, finalRoot);
+        } catch (restoreError) {
+          throw new Error(`Could not publish the new plugin tree or restore the previous tree: ${restoreError instanceof Error ? restoreError.message : String(restoreError)}`, { cause: error });
+        }
+      }
+      throw error;
+    }
+    published = true;
+    return {
+      name: rootRecord.name,
+      version: rootRecord.version,
+      installRoot: finalRoot,
+      backupRoot,
+      createdDirs,
+      warnings: [...ctx.warnings]
+    };
+  } finally {
+    await rm2(container, { recursive: true, force: true }).catch(() => {});
+    if (!published)
+      await removeEmptyDirs(createdDirs);
+  }
+}
+async function finalizeNpmPluginInstall(installed) {
+  if (installed.backupRoot) {
+    await rm2(installed.backupRoot, { recursive: true, force: true });
+  }
+}
+async function rollbackNpmPluginInstall(installed) {
+  await rm2(installed.installRoot, { recursive: true, force: true });
+  if (installed.backupRoot)
+    await rename2(installed.backupRoot, installed.installRoot);
+  else
+    await removeEmptyDirs(installed.createdDirs);
+}
+
+// src/lib/extension-manager.ts
+import { gt as semverGt, rcompare as semverRcompare } from "semver";
+
+// src/lib/project-gitignore.ts
+import { readFile as readFile4, writeFile } from "node:fs/promises";
+import path3 from "node:path";
+import ignore from "ignore";
+function ignoreStatus(gitignore, entry) {
+  const matcher = ignore().add(gitignore);
+  const dir = matcher.test(entry);
+  const file = matcher.test(`${entry}probe`);
+  if (file.ignored)
+    return "ignored";
+  return dir.unignored || file.unignored ? "negated" : "open";
+}
+var PROJECT_GITIGNORE_ENTRIES = ["dist/", "plugins/npm/"];
+async function ensureProjectGitignore(projectDir) {
+  const gitignorePath = path3.join(projectDir, ".gitignore");
+  let existing = null;
+  try {
+    existing = await readFile4(gitignorePath, "utf8");
+  } catch {}
+  const missing = [];
+  const negated = [];
+  for (const entry of PROJECT_GITIGNORE_ENTRIES) {
+    const status = ignoreStatus(existing ?? "", entry);
+    if (status === "open")
+      missing.push(entry);
+    else if (status === "negated")
+      negated.push(entry);
+  }
+  if (missing.length > 0) {
+    const lead = existing !== null && existing.length > 0 && !existing.endsWith(`
+`) ? `
+` : "";
+    await writeFile(gitignorePath, `${existing ?? ""}${lead}${missing.join(`
+`)}
+`, "utf8");
+  }
+  return { negated };
+}
+
+// src/lib/extension-manager.ts
+var EXTENSIONS_DIR = "extensions";
+var RECOMMENDED_EXTENSIONS = [
+  {
+    use: "markdown-it-mark",
+    label: "Highlight",
+    description: "Highlight text by wrapping it in `==double equals==`."
+  },
+  {
+    use: "markdown-it-sub",
+    label: "Subscript",
+    description: "Lower text below the line, like the 2 in `H~2~O`."
+  },
+  {
+    use: "markdown-it-sup",
+    label: "Superscript",
+    description: "Raise text above the line, like the th in `29^th^`."
+  },
+  {
+    use: "markdown-it-abbr",
+    label: "Abbreviations",
+    description: "Explain an abbreviation when readers hover over it. Define it once, like `*[GPS]: Global Positioning System`."
+  },
+  {
+    use: "gutterpress-gfm-alerts",
+    label: "Callouts",
+    description: "Turn a quote into a boxed note: start it with `> [!NOTE]` (or `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`)."
+  }
+];
+var BUILT_IN_STYLE_SET_IDS = ["clean-book", "zine", "technical-doc"];
+var mutationQueues = new Map;
+function projectKey(projectDir) {
+  const resolved = path4.resolve(projectDir);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function withMutationLock(projectDir, mutation) {
+  const key = projectKey(projectDir);
+  const previous = mutationQueues.get(key) ?? Promise.resolve();
+  const run = previous.then(mutation, mutation);
+  const tail = run.then(() => {
+    return;
+  }, () => {
+    return;
+  });
+  mutationQueues.set(key, tail);
+  tail.then(() => {
+    if (mutationQueues.get(key) === tail)
+      mutationQueues.delete(key);
+  });
+  return run;
+}
+function entryUse(item) {
+  if (isScalar(item))
+    return typeof item.value === "string" ? item.value.trim() : null;
+  if (isMap(item)) {
+    const u = item.get("use");
+    return typeof u === "string" ? u.trim() : null;
+  }
+  return null;
+}
+function rawEntry(item) {
+  const use = entryUse(item);
+  if (!use)
+    return null;
+  if (!isMap(item))
+    return { use, enabled: true };
+  const x = item.get("export");
+  return {
+    use,
+    ...typeof x === "string" && x.trim() ? { export: x.trim() } : {},
+    enabled: item.get("enabled") !== false
+  };
+}
+function sameExtension(a, b) {
+  if (a.trim() === b.trim())
+    return true;
+  let pa;
+  let pb;
+  try {
+    pa = parseExtensionSpecifier(a);
+    pb = parseExtensionSpecifier(b);
+  } catch {
+    return false;
+  }
+  return pa.kind === "npm" && pb.kind === "npm" && pa.name === pb.name;
+}
+function indexOfUse(seq, use) {
+  const items = seq.items;
+  const exact = items.findIndex((item) => entryUse(item) === use.trim());
+  if (exact >= 0)
+    return exact;
+  return items.findIndex((item) => {
+    const u = entryUse(item);
+    return !!u && sameExtension(u, use);
+  });
+}
+function manifestPathFor(projectDir, abs) {
+  const rel = path4.relative(path4.resolve(projectDir), abs).split(path4.sep).join("/");
+  if (rel === "") {
+    throw new Error("An extension cannot be the book folder itself.");
+  }
+  if (isPathSpecifier(rel))
+    return rel;
+  return `./${rel}`;
+}
+var NO_CARRIES = {
+  markdown: false,
+  styles: false,
+  snippets: false,
+  components: false,
+  publish: false
+};
+async function describeFolder(dir, base, fallbackLabel, labelFrom = prettify) {
+  const meta = await readExtensionMeta(dir);
+  const styles = extensionStyleList(meta);
+  return {
+    ...base,
+    label: meta.name?.trim() ? labelFrom(meta.name.trim()) : fallbackLabel,
+    ...meta.description?.trim() ? { description: meta.description.trim() } : {},
+    ...meta.author?.trim() ? { author: meta.author.trim() } : {},
+    ...meta.preview !== undefined ? { preview: meta.preview } : {},
+    ...meta.tokensFile?.trim() ? { tokensFile: meta.tokensFile.trim() } : {},
+    ...styles.length > 0 ? { styles } : {},
+    carries: extensionCarries(meta),
+    dir
+  };
+}
+async function describeEntry(projectDir, raw) {
+  const warnings = [];
+  let parsed = null;
+  try {
+    parsed = parseExtensionSpecifier(raw.use);
+  } catch (error) {
+    warnings.push(error instanceof Error ? error.message : String(error));
+  }
+  const common = {
+    use: raw.use,
+    enabled: raw.enabled,
+    ...raw.export ? { export: raw.export } : {}
+  };
+  const withWarnings = (entry) => warnings.length > 0 ? { ...entry, warnings: [...entry.warnings ?? [], ...warnings] } : entry;
+  if (!parsed) {
+    return withWarnings({ ...common, kind: "npm", name: raw.use, label: raw.use, carries: NO_CARRIES });
+  }
+  if (parsed.kind === "bundled") {
+    const bundledName = parsed.name;
+    const rec = RECOMMENDED_EXTENSIONS.find((r) => r.use === bundledName);
+    return withWarnings({
+      ...common,
+      kind: "bundled",
+      name: bundledName,
+      label: rec?.label ?? bundledName,
+      ...rec ? { description: rec.description } : {},
+      carries: { ...NO_CARRIES, markdown: true }
+    });
+  }
+  if (parsed.kind === "path") {
+    const abs = path4.resolve(projectDir, parsed.path);
+    const base2 = { ...common, kind: "path", name: parsed.path };
+    let info;
+    try {
+      info = await stat(abs);
+    } catch {
+      warnings.push(`Not found: ${abs}`);
+      return withWarnings({ ...base2, label: path4.basename(abs), carries: NO_CARRIES });
+    }
+    if (info.isDirectory()) {
+      return withWarnings(await describeFolder(abs, base2, prettify(path4.basename(abs))));
+    }
+    return withWarnings({
+      ...base2,
+      label: path4.basename(abs),
+      carries: { ...NO_CARRIES, markdown: true }
+    });
+  }
+  const base = {
+    ...common,
+    kind: "npm",
+    name: parsed.name,
+    ...parsed.version ? { version: parsed.version } : {}
+  };
+  if (!parsed.version) {
+    warnings.push(`Not pinned — run \`gutterpress ext add ${parsed.name}\` to install it and pin an exact version.`);
+    return withWarnings({ ...base, label: parsed.name, carries: { ...NO_CARRIES, markdown: true } });
+  }
+  let installRoot = null;
+  try {
+    installRoot = await resolveVendoredPluginInstallRoot(projectDir, parsed.name, parsed.version);
+  } catch (error) {
+    warnings.push(error instanceof Error ? error.message : String(error));
+  }
+  if (!installRoot) {
+    warnings.push(`Not installed — run \`gutterpress ext add ${raw.use}\`.`);
+    return withWarnings({ ...base, label: parsed.name, carries: { ...NO_CARRIES, markdown: true } });
+  }
+  const pkgDir = vendoredNpmPluginPackageDir(installRoot, parsed.name);
+  if (!existsSync3(path4.join(pkgDir, EXTENSION_MANIFEST_FILENAME))) {
+    return withWarnings({ ...base, label: parsed.name, carries: { ...NO_CARRIES, markdown: true } });
+  }
+  const described = await describeFolder(pkgDir, base, parsed.name, (name) => name);
+  return withWarnings({
+    ...described,
+    carries: { ...described.carries, markdown: !described.carries.publish }
+  });
+}
+async function listProjectExtensions(projectDir) {
+  const { doc } = await loadManifestDoc(projectDir);
+  const seq = doc.get("extensions", true);
+  if (!isSeq2(seq))
+    return [];
+  const out = [];
+  for (const item of seq.items) {
+    const raw = rawEntry(item);
+    if (!raw)
+      continue;
+    out.push(await describeEntry(projectDir, raw));
+  }
+  return out;
+}
+async function describeExtension(projectDir, use) {
+  return (await listProjectExtensions(projectDir)).find((e) => sameExtension(e.use, use)) ?? null;
+}
+function extensionConfigFor(entry) {
+  return {
+    use: entry.use,
+    ...entry.kind === "path" ? { path: entry.name } : { name: entry.name, ...entry.version ? { version: entry.version } : {} },
+    ...entry.export ? { export: entry.export } : {},
+    options: {}
+  };
+}
+async function setExtensionEnabled(projectDir, use, enabled) {
+  return withMutationLock(projectDir, async () => {
+    const { doc, file } = await loadManifestDoc(projectDir);
+    const seq = doc.get("extensions", true);
+    const idx = isSeq2(seq) ? indexOfUse(seq, use) : -1;
+    if (!isSeq2(seq) || idx < 0)
+      throw new Error(`Extension "${use}" is not in the manifest.`);
+    const item = seq.items[idx];
+    if (enabled) {
+      if (isMap(item)) {
+        item.delete("enabled");
+        if (item.items.length === 1 && typeof item.get("use") === "string") {
+          seq.items[idx] = new Scalar(item.get("use"));
+        }
+      }
+    } else if (isMap(item)) {
+      item.set("enabled", false);
+    } else {
+      const map = new YAMLMap(doc.schema);
+      map.set("use", entryUse(item));
+      map.set("enabled", false);
+      seq.items[idx] = map;
+    }
+    await writeManifestDoc(file, doc);
+  });
+}
+async function reorderExtensions(projectDir, order) {
+  return withMutationLock(projectDir, async () => {
+    const { doc, file } = await loadManifestDoc(projectDir);
+    const seq = doc.get("extensions", true);
+    if (!isSeq2(seq))
+      throw new Error(`No extensions are configured in ${path4.basename(file)}.`);
+    const items = seq.items;
+    const current = items.map((item) => entryUse(item));
+    const wanted = order.map((u) => u.trim());
+    const sameSet = current.length === wanted.length && [...current].sort().join(`
+`) === [...wanted].sort().join(`
+`);
+    if (!sameSet) {
+      throw new Error("The new order must list every configured extension exactly once — reload the list and try again.");
+    }
+    const remaining = [...items];
+    seq.items = wanted.map((u) => {
+      const i = remaining.findIndex((item) => entryUse(item) === u);
+      return remaining.splice(i, 1)[0];
+    });
+    await writeManifestDoc(file, doc);
+  });
+}
+async function removeExtension(projectDir, use) {
+  return withMutationLock(projectDir, async () => {
+    const { doc, file } = await loadManifestDoc(projectDir);
+    const seq = doc.get("extensions", true);
+    const idx = isSeq2(seq) ? indexOfUse(seq, use) : -1;
+    if (!isSeq2(seq) || idx < 0)
+      throw new Error(`Extension "${use}" is not in the manifest.`);
+    const written = entryUse(seq.items[idx]);
+    seq.items.splice(idx, 1);
+    if (seq.items.length === 0)
+      doc.delete("extensions");
+    await writeManifestDoc(file, doc);
+    let parsed = null;
+    try {
+      parsed = parseExtensionSpecifier(written);
+    } catch {
+      return;
+    }
+    if (parsed.kind === "npm" && parsed.version) {
+      const root = vendoredNpmPluginRoot(projectDir, parsed.name, parsed.version);
+      await rm3(root, { recursive: true, force: true });
+      await removeEmptyDirs([path4.dirname(root)]);
+    }
+  });
+}
+async function upsertEntry(projectDir, use, exportName) {
+  const { doc, file } = await loadManifestDoc(projectDir);
+  const seq = ensureSeq(doc, "extensions");
+  const idx = indexOfUse(seq, use);
+  if (idx >= 0) {
+    const item = seq.items[idx];
+    if (isMap(item)) {
+      item.set("use", use);
+      if (exportName)
+        item.set("export", exportName);
+      else
+        item.delete("export");
+      if (item.items.length === 1)
+        seq.items[idx] = new Scalar(use);
+    } else if (exportName) {
+      const map = new YAMLMap(doc.schema);
+      map.set("use", use);
+      map.set("export", exportName);
+      seq.items[idx] = map;
+    } else {
+      seq.items[idx] = new Scalar(use);
+    }
+  } else if (exportName) {
+    const map = new YAMLMap(doc.schema);
+    map.set("use", use);
+    map.set("export", exportName);
+    seq.add(map);
+  } else {
+    seq.add(new Scalar(use));
+  }
+  await writeManifestDoc(file, doc);
+}
+async function addPathExtension(projectDir, abs, exportName) {
+  try {
+    await stat(abs);
+  } catch {
+    throw new Error(`Extension not found: ${abs}`);
+  }
+  const use = manifestPathFor(projectDir, abs);
+  await loadPlugin(extensionConfigFor({ use, kind: "path", name: use, export: exportName }), projectDir);
+  await upsertEntry(projectDir, use, exportName);
+  return await describeExtension(projectDir, use);
+}
+async function addExtension(projectDir, specifier, options = {}) {
+  return withMutationLock(projectDir, () => addExtensionUnlocked(projectDir, specifier, options));
+}
+async function addExtensionUnlocked(projectDir, specifier, options) {
+  const input = specifier.trim();
+  const exportName = options.exportName?.trim() || undefined;
+  if (path4.isAbsolute(input))
+    return addPathExtension(projectDir, input, exportName);
+  const parsed = parseExtensionSpecifier(input);
+  if (parsed.kind === "path") {
+    return addPathExtension(projectDir, path4.resolve(projectDir, parsed.path), exportName);
+  }
+  if (parsed.kind === "bundled") {
+    if (exportName)
+      throw new Error(`Bundled extension "${parsed.name}" does not take a named export.`);
+    await upsertEntry(projectDir, parsed.name);
+    return await describeExtension(projectDir, parsed.name);
+  }
+  const existing = await describeExtension(projectDir, parsed.name);
+  const chosenExport = exportName ?? existing?.export;
+  const { name, version, use, warnings } = await vendorNpmExtension(projectDir, input, chosenExport, options, (use2) => upsertEntry(projectDir, use2, chosenExport));
+  warnings.push(...await pruneStaleVersions(projectDir, name, [version, ...await pinnedVersionsOf(projectDir, name)]));
+  const entry = await describeExtension(projectDir, use);
+  return warnings.length > 0 ? { ...entry, warnings: [...entry.warnings ?? [], ...warnings] } : entry;
+}
+function restoreNpmExtension(projectDir, name, version, exportName, options = {}) {
+  return withMutationLock(projectDir, async () => {
+    if (!await vendoredCopyNeedsInstall(projectDir, name, version))
+      return [];
+    const restored = await vendorNpmExtension(projectDir, `${name}@${version}`, exportName, options, async () => {});
+    return [...restored.warnings, ...await pruneStaleVersions(projectDir, name, [version, ...options.keepVersions ?? []])];
+  });
+}
+async function vendoredCopyNeedsInstall(projectDir, name, version) {
+  try {
+    const installRoot = await resolveVendoredPluginInstallRoot(projectDir, name, version);
+    if (!installRoot)
+      return true;
+    await resolvePackageEntry(vendoredNpmPluginPackageDir(installRoot, name));
+    return false;
+  } catch {
+    return true;
+  }
+}
+async function vendorNpmExtension(projectDir, input, exportName, options, commit) {
+  const installed = await installNpmPlugin(projectDir, input, options);
+  const use = pinnedNpmSpecifier(installed.name, installed.version);
+  try {
+    await loadPlugin(extensionConfigFor({
+      use,
+      kind: "npm",
+      name: installed.name,
+      version: installed.version,
+      export: exportName
+    }), projectDir);
+    await options.__testFailBeforeManifestCommit?.();
+    await commit(use);
+  } catch (cause) {
+    try {
+      await rollbackNpmPluginInstall(installed);
+    } catch (rollbackError) {
+      throw new Error(`Extension install failed and its previous vendor tree could not be restored: ` + `${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`, { cause });
+    }
+    throw new Error(`Downloaded ${use}, but it is not a loadable markdown-it plugin: ` + `${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+  }
+  const warnings = [...installed.warnings];
+  await finalizeNpmPluginInstall(installed).catch((error) => {
+    warnings.push(`The extension was installed, but an old backup could not be removed: ` + `${error instanceof Error ? error.message : String(error)}`);
+  });
+  try {
+    const { negated } = await ensureProjectGitignore(projectDir);
+    if (negated.includes("plugins/npm/")) {
+      warnings.push("Your .gitignore re-includes plugins/npm/, so downloaded extensions will be committed with " + "your book. They shouldn't be: the manifest pins each version and a build downloads a " + "missing copy again.");
+    }
+  } catch (error) {
+    warnings.push(`The extension was installed, but .gitignore could not be updated to keep it out of version history: ` + `${error instanceof Error ? error.message : String(error)}`);
+  }
+  return { name: installed.name, version: installed.version, use, warnings };
+}
+async function pinnedVersionsOf(projectDir, name) {
+  const { doc } = await loadManifestDoc(projectDir);
+  const seq = doc.get("extensions", true);
+  if (!isSeq2(seq))
+    return [];
+  const versions = [];
+  for (const item of seq.items) {
+    const raw = rawEntry(item);
+    if (!raw?.enabled)
+      continue;
+    try {
+      const parsed = parseExtensionSpecifier(raw.use);
+      if (parsed.kind === "npm" && parsed.name === name && parsed.version)
+        versions.push(parsed.version);
+    } catch {}
+  }
+  return versions;
+}
+async function pruneStaleVersions(projectDir, name, keep) {
+  const parent = path4.dirname(vendoredNpmPluginRoot(projectDir, name, "0.0.0"));
+  try {
+    for (const entry of await readdir(parent, { withFileTypes: true })) {
+      if (!entry.isDirectory())
+        continue;
+      let version;
+      try {
+        version = decodeURIComponent(entry.name);
+      } catch {
+        continue;
+      }
+      if (!isExactNpmVersion(version) || keep.includes(version))
+        continue;
+      await rm3(path4.join(parent, entry.name), { recursive: true, force: true });
+    }
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return [];
+    return [
+      `The extension was installed, but a previous version's downloaded copy could not be removed: ` + `${error instanceof Error ? error.message : String(error)}`
+    ];
+  }
+  return [];
+}
+var LATEST_LOOKUP_TIMEOUT_MS = 30000;
+var MAX_PACKUMENT_BYTES = 15 * 1024 * 1024;
+async function fetchNpmVersions(name, options) {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  return withFetchTimeout({
+    timeoutMs: LATEST_LOOKUP_TIMEOUT_MS,
+    signal: options.signal,
+    timeoutMessage: `Looking up ${name} on npm timed out. Check your connection and try again.`,
+    offlineMessage: (cause) => `Looking up ${name} on npm failed (${cause instanceof Error ? cause.message : String(cause)}).`
+  }, async (signal) => {
+    const response = await fetchImpl(`${npmRegistryUrl()}/${encodeURIComponent(name)}`, {
+      signal,
+      redirect: "error",
+      headers: { accept: "application/vnd.npm.install-v1+json" }
+    });
+    if (response.status === 404)
+      throw new FriendlyHttpError(`npm package "${name}" was not found.`);
+    if (!response.ok)
+      throw new FriendlyHttpError(`Looking up ${name} on npm failed (HTTP ${response.status}).`);
+    const bytes = await response.arrayBuffer();
+    if (bytes.byteLength > MAX_PACKUMENT_BYTES) {
+      throw new FriendlyHttpError(`npm metadata for "${name}" is too large to read.`);
+    }
+    try {
+      const packument = JSON.parse(Buffer.from(bytes).toString("utf8"));
+      return {
+        latest: packument["dist-tags"]?.latest,
+        versions: Object.keys(packument.versions ?? {}).filter(isExactNpmVersion)
+      };
+    } catch {
+      throw new FriendlyHttpError(`npm metadata for "${name}" is not valid JSON.`);
+    }
+  });
+}
+async function latestNpmVersion(name, options) {
+  const { latest, versions } = await fetchNpmVersions(name, options);
+  if (options.includePrerelease) {
+    const newest = versions.sort(semverRcompare)[0];
+    if (newest)
+      return newest;
+  }
+  if (typeof latest !== "string" || !isExactNpmVersion(latest)) {
+    throw new FriendlyHttpError(`npm metadata for "${name}" has no latest version.`);
+  }
+  return latest;
+}
+async function listNpmVersions(name, options = {}) {
+  return (await fetchNpmVersions(name, options)).versions.sort(semverRcompare);
+}
+async function checkExtensionUpdates(projectDir, options = {}) {
+  const entries = await listProjectExtensions(projectDir);
+  const pinned = entries.filter((e) => e.kind === "npm" && e.version);
+  return Promise.all(pinned.map(async (e) => {
+    const current = e.version;
+    const latest = await latestNpmVersion(e.name, options);
+    return { use: e.use, name: e.name, current, latest, outdated: semverGt(latest, current) };
+  }));
+}
+async function updateExtensions(projectDir, options = {}) {
+  let checks = await checkExtensionUpdates(projectDir, options);
+  if (options.only) {
+    checks = checks.filter((c) => c.name === options.only);
+    if (checks.length === 0) {
+      throw new Error(`"${options.only}" is not a pinned npm extension of this book.`);
+    }
+  }
+  const updated = [];
+  for (const check of checks) {
+    if (!check.outdated)
+      continue;
+    await addExtension(projectDir, pinnedNpmSpecifier(check.name, check.latest), {
+      fetch: options.fetch,
+      signal: options.signal,
+      limits: options.limits
+    });
+    updated.push({ name: check.name, from: check.current, to: check.latest });
+  }
+  return updated;
+}
+async function listBuiltInStyleSets() {
+  const assets = await getAssetsDir();
+  const out = [];
+  for (const id of BUILT_IN_STYLE_SET_IDS) {
+    const meta = await readExtensionMeta(path4.join(assets, "themes", id));
+    out.push({
+      id,
+      name: prettify(meta.name?.trim() || id),
+      description: meta.description?.trim() || ""
+    });
+  }
+  return out;
+}
+async function uniqueExtensionId(projectDir, base) {
+  const slug = slugify(base) || "extension";
+  let candidate = slug;
+  for (let n = 2;existsSync3(path4.join(projectDir, EXTENSIONS_DIR, candidate)); n++) {
+    candidate = `${slug}-${n}`;
+  }
+  return candidate;
+}
+async function addBuiltInStyleSet(projectDir, id) {
+  if (!BUILT_IN_STYLE_SET_IDS.includes(id)) {
+    throw new Error(`Unknown built-in look "${id}" (one of: ${BUILT_IN_STYLE_SET_IDS.join(", ")}).`);
+  }
+  return withMutationLock(projectDir, async () => {
+    const dest = path4.join(projectDir, EXTENSIONS_DIR, id);
+    if (!existsSync3(dest)) {
+      const src = path4.join(await getAssetsDir(), "themes", id);
+      await mkdir3(path4.dirname(dest), { recursive: true });
+      await cp(src, dest, { recursive: true });
+    }
+    return addExtensionUnlocked(projectDir, `./${EXTENSIONS_DIR}/${id}`, {});
+  });
+}
+async function validateProjectExtensions(projectDir) {
+  const out = [];
+  for (const entry of await listProjectExtensions(projectDir)) {
+    if (!entry.enabled) {
+      out.push({ use: entry.use, kind: entry.kind, enabled: false, ok: true });
+      continue;
+    }
+    try {
+      await loadPlugin(extensionConfigFor(entry), projectDir);
+      out.push({ use: entry.use, kind: entry.kind, enabled: true, ok: true });
+    } catch (e) {
+      out.push({
+        use: entry.use,
+        kind: entry.kind,
+        enabled: true,
+        ok: false,
+        error: e instanceof Error ? e.message : String(e)
+      });
+    }
+  }
+  return out;
+}
+async function readExtensionCss(projectDir, use) {
+  const entry = await describeExtension(projectDir, use);
+  if (!entry)
+    throw new Error(`Extension "${use}" is not in the manifest.`);
+  if (!entry.dir)
+    throw new Error(`Extension "${use}" has no stylesheets to preview.`);
+  const meta = await readExtensionMeta(entry.dir);
+  const sheets = resolveExtension(entry.dir, meta, `Extension "${use}"`).styles ?? [];
+  if (sheets.length === 0)
+    throw new Error(`Extension "${use}" declares no stylesheets.`);
+  const parts = [];
+  for (const sheet of sheets)
+    parts.push(await readFile5(sheet, "utf8"));
+  return parts.join(`
+
+`);
+}
+
+// src/lib/extension-restore.ts
+var OFFLINE_REASON = "you appear to be offline (npm can't be reached)";
+function pinnedEntries(manifest) {
+  const found = new Map;
+  for (const entry of Array.isArray(manifest.extensions) ? manifest.extensions : []) {
+    const object2 = typeof entry === "object" && entry !== null ? entry : null;
+    const use = typeof entry === "string" ? entry : object2?.use;
+    if (typeof use !== "string" || object2?.enabled === false)
+      continue;
+    let parsed;
+    try {
+      parsed = parseExtensionSpecifier(use);
+    } catch {
+      continue;
+    }
+    if (parsed.kind !== "npm" || !parsed.version || !isExactNpmVersion(parsed.version))
+      continue;
+    const spec = `${parsed.name}@${parsed.version}`;
+    if (found.has(spec))
+      continue;
+    found.set(spec, {
+      name: parsed.name,
+      version: parsed.version,
+      ...typeof object2?.export === "string" && object2.export ? { export: object2.export } : {}
+    });
+  }
+  return [...found.values()];
+}
+async function restoreAll(projectDir, manifestFile, pins, options) {
+  const result = { manifestFile, installed: [], failed: [], warnings: [], offline: false };
+  const missing = [];
+  for (const pin of pins)
+    if (await vendoredCopyNeedsInstall(projectDir, pin.name, pin.version))
+      missing.push(pin);
+  if (missing.length === 0)
+    return result;
+  const report = options.onProgress ?? (() => {});
+  const specs = missing.map((pin) => `${pin.name}@${pin.version}`);
+  report({ type: "start", specs });
+  for (const [index, pin] of missing.entries()) {
+    const spec = specs[index];
+    const step = { type: "package", spec, index, total: missing.length };
+    if (result.offline) {
+      result.failed.push({ use: spec, message: OFFLINE_REASON });
+      report({ ...step, state: "failed", message: OFFLINE_REASON });
+      continue;
+    }
+    report({ ...step, state: "downloading" });
+    try {
+      result.warnings.push(...await restoreNpmExtension(projectDir, pin.name, pin.version, pin.export, {
+        ...options,
+        keepVersions: pins.filter((other) => other.name === pin.name).map((other) => other.version)
+      }));
+      result.installed.push(spec);
+      report({ ...step, state: "done" });
+    } catch (error) {
+      if (error instanceof FetchUnavailableError)
+        result.offline = true;
+      const message = result.offline ? OFFLINE_REASON : error instanceof Error ? error.message : String(error);
+      result.failed.push({ use: spec, message });
+      report({ ...step, state: "failed", message });
+    }
+  }
+  report({ type: "end", installed: result.installed, failed: result.failed });
+  return result;
+}
+var inFlight = new Map;
+async function restorePinnedExtensions(projectDir, options = {}) {
+  let loaded;
+  try {
+    loaded = await loadManifestWithPath(options.manifestPath ?? projectDir);
+  } catch {
+    return { manifestFile: null, installed: [], failed: [], warnings: [], offline: false };
+  }
+  const { manifest, manifestDir, manifestPath } = loaded;
+  const pins = pinnedEntries(manifest);
+  if (manifestPath === null || pins.length === 0) {
+    return { manifestFile: manifestPath && path5.basename(manifestPath), installed: [], failed: [], warnings: [], offline: false };
+  }
+  const key = projectKey(manifestDir);
+  const running = inFlight.get(key);
+  if (running)
+    return running;
+  const run = restoreAll(manifestDir, path5.basename(manifestPath), pins, options).finally(() => {
+    inFlight.delete(key);
+  });
+  inFlight.set(key, run);
+  return run;
+}
+function restoreFailureMessage(failure, manifestFile) {
+  return `Could not download ${failure.use} (pinned in ${manifestFile ?? "the manifest"}): ${failure.message.replace(/[.\s]+$/, "")}. ` + `Check your internet connection and try again, or install it yourself with \`gutterpress ext add ${failure.use}\`.`;
+}
+function restoreOfflineMessage(failed, manifestFile) {
+  const list = failed.map((f) => f.use).join(", ");
+  return `You appear to be offline, and this book's extensions are not installed yet: ${list} ` + `(pinned in ${manifestFile ?? "the manifest"}). Connect to the internet and try again to install them; ` + `once installed, they work offline.`;
+}
+async function restoreForCommand(dir, options) {
+  const result = await restorePinnedExtensions(dir, { manifestPath: options.manifestPath });
+  const file = result.manifestFile ?? "the manifest";
+  for (const spec of result.installed)
+    console.error(`Downloaded ${spec} (pinned in ${file})`);
+  for (const warning of result.warnings)
+    log.warn(warning);
+  const offline = result.failed.filter((f) => result.offline && f.message === OFFLINE_REASON);
+  const problems = [
+    ...result.failed.filter((f) => !offline.includes(f)).map((f) => restoreFailureMessage(f, result.manifestFile)),
+    ...offline.length > 0 ? [restoreOfflineMessage(offline, result.manifestFile)] : []
+  ];
+  if (problems.length === 0)
+    return;
+  if (options.failFast)
+    throw new BuildError(problems.join(`
+`), EXIT_CODES.PIPELINE);
+  for (const problem of problems)
+    log.warn(problem);
+}
+
+export { BUNDLED_EXTENSIONS, isBundledExtension, isPathSpecifier, parseExtensionSpecifier, DEBOUNCE, UsageError, resolvePort, PRESET_IDS, PRESETS, TARGETS, TARGET_IDS, publishTargetFor, resolveTargets, applyDefaultPdfStrictChecks, MANIFEST_FILENAMES, hasProjectManifest, loadManifest, loadManifestWithPath, resolveConfig, resolveConfigForTarget, FriendlyHttpError, withFetchTimeout, loadManifestDoc, writeManifestDoc, ensureSeq, scalarString, DEFAULT_NPM_REGISTRY, npmRegistryUrl, ensureProjectGitignore, EXTENSIONS_DIR, RECOMMENDED_EXTENSIONS, BUILT_IN_STYLE_SET_IDS, sameExtension, listProjectExtensions, describeExtension, extensionConfigFor, setExtensionEnabled, reorderExtensions, removeExtension, addExtension, listNpmVersions, checkExtensionUpdates, updateExtensions, listBuiltInStyleSets, uniqueExtensionId, addBuiltInStyleSet, validateProjectExtensions, readExtensionCss, restorePinnedExtensions, restoreFailureMessage, restoreOfflineMessage, restoreForCommand };