gutterpress 0.10.11 → 0.11.0

package/dist/{cli-hz44te1m.js → cli-xa9y4np2.js}

@@ -13,12 +13,12 @@ import {
   stampCreator,
   stripAnnotations,
   warn
-} from "./cli-36r50yr3.js";
+} from "./cli-r0ycvdr9.js";
 import {
   DEBOUNCE,
   UsageError,
   resolvePort
-} from "./cli-gxq7yz5f.js";
+} from "./cli-9a60c9wn.js";
 import {
   MARGIN_BOX_IGNORED_PROPERTIES,
   RENDER_TIMEOUT_MS,
@@ -28,7 +28,7 @@ import {
   getAssetsDir,
   getBrowser,
   prewarmBrowser
-} from "./cli-k8f9eb12.js";
+} from "./cli-sekhwex4.js";
 import {
   INSTALL_HINTS,
   execCapture,
@@ -5165,14 +5165,30 @@ function applyPlugins(md, plugins) {
     }
   }
 }
-function collectPluginCss(plugins) {
-  return plugins.map((p) => p.css).filter((css) => typeof css === "string" && css.length > 0).join(`
-
-`);
-}
 function collectPluginStylePaths(plugins) {
   return plugins.flatMap((p) => p.styles ?? []);
 }
+function collectPluginStyleGroups(plugins) {
+  const taken = new Set;
+  const groups = [];
+  for (const p of plugins) {
+    const paths = p.styles ?? [];
+    const css = typeof p.css === "string" && p.css.length > 0 ? p.css : undefined;
+    if (paths.length === 0 && !css)
+      continue;
+    const base = `ext.${layerSlug(p.name)}`;
+    let layer = base;
+    for (let n = 2;taken.has(layer); n++)
+      layer = `${base}-${n}`;
+    taken.add(layer);
+    groups.push({ name: p.name, layer, paths, ...css ? { css } : {} });
+  }
+  return groups;
+}
+function layerSlug(name) {
+  const slug = name.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  return /^[a-z]/.test(slug) ? slug : `x${slug}`;
+}
 
 // src/lib/markdown/plugins.ts
 import { createHash as createHash3 } from "node:crypto";
@@ -6085,12 +6101,12 @@ async function loadPlugins(configs, baseDir, onError) {
 }
 async function loadPluginsWithCss(configs, baseDir, onError) {
   if (!configs || configs.length === 0) {
-    return { plugins: undefined, pluginCss: "", pluginStylePaths: [] };
+    return { plugins: undefined, pluginStyles: [], pluginStylePaths: [] };
   }
   const plugins = await loadPlugins(configs, baseDir, onError);
   return {
     plugins,
-    pluginCss: collectPluginCss(plugins),
+    pluginStyles: collectPluginStyleGroups(plugins),
     pluginStylePaths: collectPluginStylePaths(plugins)
   };
 }
@@ -7635,7 +7651,7 @@ ${MARKER_CSS.trim()}
 @layer gp.vocab {
 ${GUTTERPRESS_CSS.trim()}
 }`,
-    pluginCss ? `/* user plugin css */
+    pluginCss ? `/* extension css */
 ${pluginCss.trim()}` : null,
     projectCss ? `/* project css */
 ${projectCss.trim()}` : null
@@ -7669,16 +7685,34 @@ async function resolveActiveMarkdownFiles(inputDir, configuredFiles) {
 async function renderChapters(inputDir, opts = {}) {
   const styles = await resolveActiveStyles(inputDir, opts.styles);
   const inlined = await inlineStyles(inputDir, styles);
-  const pluginInlined = await inlineStyles(inputDir, opts.pluginStylePaths ?? []);
-  const styleWarnings = [...pluginInlined.warnings, ...inlined.warnings];
+  const blocks = [];
+  const layers = [];
+  const styleWarnings = [];
+  const cssAssetCopies = [];
+  for (const group of opts.pluginStyles ?? []) {
+    const groupInlined = await inlineStyles(inputDir, group.paths);
+    styleWarnings.push(...groupInlined.warnings);
+    cssAssetCopies.push(...groupInlined.copies);
+    const css = [groupInlined.css, group.css].filter((s) => !!s && s.trim().length > 0).join(`
+
+`);
+    if (!css)
+      continue;
+    layers.push(group.layer);
+    blocks.push(`/* ${group.name} */
+@layer ${group.layer} {
+${css.trim()}
+}`);
+  }
+  styleWarnings.push(...inlined.warnings);
   if (styleWarnings.length > 0)
     opts.onStyleWarnings?.(styleWarnings);
-  const cssAssetCopies = [...pluginInlined.copies, ...inlined.copies];
+  cssAssetCopies.push(...inlined.copies);
   if (cssAssetCopies.length > 0)
     opts.onCssAssets?.(cssAssetCopies);
-  const pluginCss = [pluginInlined.css, opts.pluginCss].filter((s) => !!s && s.trim().length > 0).join(`
+  const pluginCss = blocks.length > 0 ? [`@layer ${layers.join(", ")};`, ...blocks].join(`
 
-`);
+`) : "";
   const files = await resolveActiveMarkdownFiles(inputDir, opts.files);
   if (files.length === 0) {
     throw new Error(`No markdown files found in ${inputDir}`);
@@ -7687,7 +7721,7 @@ async function renderChapters(inputDir, opts = {}) {
     files,
     readText: (relPath) => readFile19(join2(inputDir, canonicalChapterId(relPath)), "utf-8"),
     projectCss: inlined.css,
-    preloadImages: [...pluginInlined.copies.map((c) => c.to), ...inlined.copies.map((c) => c.to)],
+    preloadImages: cssAssetCopies.map((c) => c.to),
     title: opts.title,
     plugins: opts.plugins,
     pluginCss,
@@ -7704,8 +7738,7 @@ async function renderChaptersToFile(inputDir, outDir, opts = {}) {
     styles: opts.styles,
     files: opts.files,
     plugins: opts.plugins,
-    pluginCss: opts.pluginCss,
-    pluginStylePaths: opts.pluginStylePaths,
+    pluginStyles: opts.pluginStyles,
     onChapterWarnings: opts.onChapterWarnings,
     onImageRefs: opts.onImageRefs,
     onCssAssets: opts.onCssAssets,
@@ -8581,7 +8614,7 @@ async function renderBook(ctx) {
   } else {
     log.info("Using all .md files in alphabetical order");
   }
-  const { plugins, pluginCss, pluginStylePaths } = await loadBuildPlugins(ctx);
+  const { plugins, pluginStyles } = await loadBuildPlugins(ctx);
   const imageRefs = [];
   const cssAssets = [];
   const htmlFile = await renderChaptersToFile(renderDir, workDir, {
@@ -8589,8 +8622,7 @@ async function renderBook(ctx) {
     styles: config.styles,
     files: config.source.files,
     plugins,
-    pluginCss,
-    pluginStylePaths,
+    pluginStyles,
     onChapterWarnings: (file, warnings) => {
       for (const w of warnings) {
         const key = layoutWarningKey(path9.resolve(renderDir, file), w.line, w.message);
@@ -8736,7 +8768,7 @@ class PdfOutput {
       const rawPdf = pdfxMode ? path9.join(stage, "raw.pdf") : path9.resolve(pdfFile);
       await fsp2.mkdir(path9.dirname(path9.resolve(pdfFile)), { recursive: true });
       log.info("Rendering HTML to PDF via the Gutterpress engine (native Chromium pagination)");
-      const { buildNativePdf } = await import("./engine-qtmvaqt7.js");
+      const { buildNativePdf } = await import("./engine-cbc17ne4.js");
       const engineDiagnostics = await buildNativePdf(htmlFile, rawPdf, {
         title: config.title,
         author: config.authors.length > 0 ? config.authors.join(", ") : undefined,
@@ -8902,14 +8934,13 @@ function incrementalPreviewEnabled() {
   return process.env.GUTTERPRESS_PREVIEW_INCREMENTAL !== "0";
 }
 async function renderPreviewBook(inputPath, config, opts) {
-  const { plugins, pluginCss, pluginStylePaths } = await loadPluginsWithCss(config.extensions, inputPath, (ref, err) => warn(`Skipping plugin "${ref}" in preview — ${err.message}`));
+  const { plugins, pluginStyles } = await loadPluginsWithCss(config.extensions, inputPath, (ref, err) => warn(`Skipping plugin "${ref}" in preview — ${err.message}`));
   return renderChapters(inputPath, {
     title: config.title ?? "Document",
     styles: config.styles,
     files: opts.files,
     plugins,
-    pluginCss,
-    pluginStylePaths,
+    pluginStyles,
     wrapChapters: opts.wrapChapters,
     annotateSourceChapters: true,
     ...opts.onCssAssets ? { onCssAssets: opts.onCssAssets } : {},
@@ -10153,11 +10184,10 @@ async function startPreviewServer(options) {
   };
 }
 
-// src/lib/extension-manager.ts
-import { cp as cp2, mkdir as mkdir7, readFile as readFile26, rm as rm4, stat as stat5 } from "node:fs/promises";
-import { existsSync as existsSync11 } from "node:fs";
-import path16 from "node:path";
-import { isSeq as isSeq2, isMap, isScalar, YAMLMap, Scalar } from "yaml";
+// src/lib/project-scaffold.ts
+import { access, copyFile, cp as cp2, mkdir as mkdir6, readdir as readdir5, readFile as readFile25, stat as stat5, writeFile as writeFile6 } from "node:fs/promises";
+import { constants as FS, existsSync as existsSync11 } from "node:fs";
+import path15 from "node:path";
 
 // src/lib/manifest-doc.ts
 import { existsSync as existsSync10 } from "node:fs";
@@ -10212,1518 +10242,1509 @@ function ensureSeq(doc, key) {
   return seq;
 }
 
-// src/lib/npm-plugin-installer.ts
-import { createHash as createHash7, randomUUID as randomUUID3, timingSafeEqual } from "node:crypto";
-import { createReadStream as createReadStream2 } from "node:fs";
-import {
-  lstat as lstat2,
-  mkdir as mkdir6,
-  mkdtemp as mkdtemp2,
-  open as open2,
-  readFile as readFile25,
-  realpath as realpath2,
-  rename as rename2,
-  rm as rm3
-} from "node:fs/promises";
-import path15 from "node:path";
-import { Transform } from "node:stream";
-import { pipeline } from "node:stream/promises";
-import { createGunzip } from "node:zlib";
-import { maxSatisfying, satisfies as satisfies2, validRange as validRange2 } from "semver";
-
-// src/lib/fetch-timeout.ts
-class FetchPassthroughError extends Error {
-}
-
-class FriendlyHttpError extends FetchPassthroughError {
+// src/lib/project-scaffold.ts
+function starterOverridesCss() {
+  return `/**
+ * Your book's own styles.
+ *
+ * This file loads AFTER every extension, so any rule you add here overrides
+ * a look's defaults. A new book has no look until you add one:
+ *   gutterpress ext add clean-book <book> --look   (a built-in look)
+ *   gutterpress ext add <package> <book>           (a look from npm)
+ * A book has one look at a time; adding another turns the current one off.
+ */
+`;
 }
 
-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 });
+class CreateProjectErrorImpl extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "CreateProjectError";
+    this.code = code;
   }
 }
-
-// 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 slugifyProjectName(name) {
+  return slugify(name);
 }
-function isOptionalAvailabilityError(error2) {
-  return error2 instanceof PackageUnavailableError || error2 instanceof FriendlyHttpError || error2 instanceof FetchUnavailableError;
+function escapeYamlScalar(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
 }
-function object3(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+var DEFAULT_AUTHOR = "Anonymous";
+function isPositivePoints(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0;
 }
-function stringMap2(value) {
-  const map = object3(value);
-  if (!map)
-    return {};
-  const result = {};
-  for (const [name, selector] of Object.entries(map)) {
-    if (typeof selector === "string" && selector.trim())
-      result[name] = selector.trim();
+function requirePreset(preset, customPage) {
+  if (!preset || !PRESET_IDS.includes(preset)) {
+    const got = preset ? ` (got "${preset}")` : "";
+    throw new CreateProjectErrorImpl("preset-required", `A preset is required to create a book${got}. Choose one of: ${PRESET_IDS.join(", ")}.`);
   }
-  return result;
-}
-function mb(bytes) {
-  return `${Math.ceil(bytes / 1024 / 1024)}MB`;
-}
-function isContained2(root, candidate) {
-  const relative2 = path15.relative(root, candidate);
-  return relative2 === "" || !relative2.startsWith("..") && !path15.isAbsolute(relative2);
-}
-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}`);
+  if (preset === "custom") {
+    const missing = [];
+    if (!customPage || !isPositivePoints(customPage.width))
+      missing.push("page width");
+    if (!customPage || !isPositivePoints(customPage.height))
+      missing.push("page height");
+    if (missing.length > 0) {
+      throw new CreateProjectErrorImpl("custom-page-required", `The custom preset needs a trim size: ${missing.join(" and ")} in points ` + `(72pt = 1in — e.g. US Letter is 612 x 792).`);
     }
+  } else if (customPage && (!isPositivePoints(customPage.width) || !isPositivePoints(customPage.height))) {
+    throw new CreateProjectErrorImpl("custom-page-required", "Page overrides need a positive width and height in points (72pt = 1in).");
   }
-  return limits;
+  if (customPage?.tolerance !== undefined && !isPositivePoints(customPage.tolerance)) {
+    throw new CreateProjectErrorImpl("custom-page-required", "Page tolerance must be a positive number of points.");
+  }
+  return preset;
 }
-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)}).`);
+function resolveScaffoldTargets(requested, preset) {
+  const ids = requested ?? [...PRESETS[preset].defaultTargets];
+  const unknown = ids.filter((id) => !TARGETS[id]);
+  if (unknown.length > 0) {
+    throw new CreateProjectErrorImpl("invalid-targets", `Unknown publish target${unknown.length > 1 ? "s" : ""} "${unknown.join('", "')}". ` + `Known targets: ${TARGET_IDS.join(", ")}.`);
   }
-  if (Number.isFinite(declared) && declared > ctx.limits.totalNetworkBytes - ctx.totalNetworkBytes) {
-    throw new SecurityInstallError(totalLimitMessage);
+  return [...new Set(ids)];
+}
+async function scaffoldProject(options) {
+  const name = (options.name ?? "").trim();
+  if (!name) {
+    throw new CreateProjectErrorImpl("invalid-name", "A project name is required.");
+  }
+  const slug = slugifyProjectName(name);
+  const folderName = (options.folderName ?? slug).trim();
+  if (!folderName || folderName !== slugifyProjectName(folderName)) {
+    throw new CreateProjectErrorImpl("invalid-name", `Could not derive a valid folder name from "${name}".`);
+  }
+  const parentDir = options.parentDir;
+  if (!parentDir || !path15.isAbsolute(parentDir)) {
+    throw new CreateProjectErrorImpl("parent-not-writable", "The save location must be an absolute path.");
   }
-  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)}).`);
+    await access(parentDir, FS.W_OK);
+  } catch {
+    throw new CreateProjectErrorImpl("parent-not-writable", `The chosen save location can't be written to: ${parentDir}`);
+  }
+  const projectDir = path15.join(parentDir, folderName);
+  let targetExists = true;
+  try {
+    await access(projectDir, FS.F_OK);
+  } catch {
+    targetExists = false;
+  }
+  if (targetExists) {
+    throw new CreateProjectErrorImpl("target-exists", `A folder named "${folderName}" already exists here. Choose a different name or location.`);
+  }
+  const template = options.template ?? "book";
+  const customTemplateDir = options.templateDir;
+  const preset = customTemplateDir && options.preset === undefined ? undefined : requirePreset(options.preset, options.customPage);
+  const targets = preset ? resolveScaffoldTargets(options.targets, preset) : undefined;
+  try {
+    await mkdir6(projectDir, { recursive: true });
+    if (customTemplateDir) {
+      const entries = await readdir5(customTemplateDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name === ".gutterpress-template.json")
+          continue;
+        await cp2(path15.join(customTemplateDir, entry.name), path15.join(projectDir, entry.name), { recursive: true });
       }
-      if (ctx.totalNetworkBytes + value.length > ctx.limits.totalNetworkBytes) {
-        await reader.cancel("total size limit exceeded").catch(() => {});
-        throw new SecurityInstallError(totalLimitMessage);
+      await mkdir6(path15.join(projectDir, "assets"), { recursive: true });
+    } else {
+      const tplManifest = await getAssetPath(`templates/${template}/manifest.yaml`);
+      const tplChapter = await getAssetPath(`templates/${template}/chapter-01.md`);
+      await mkdir6(path15.join(projectDir, "assets"), { recursive: true });
+      await copyFile(tplManifest, path15.join(projectDir, MANIFEST_FILENAMES[0]));
+      await copyFile(tplChapter, path15.join(projectDir, "chapter-01.md"));
+      await mkdir6(path15.join(projectDir, "styles"), { recursive: true });
+      await writeFile6(path15.join(projectDir, "styles", "book.css"), starterOverridesCss(), "utf8");
+    }
+  } catch (e) {
+    throw new CreateProjectErrorImpl("scaffold-io", `Could not create the project files: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  try {
+    await ensureGitignoreHasDist(projectDir);
+  } catch (e) {
+    throw new CreateProjectErrorImpl("scaffold-io", `Could not write .gitignore: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  const manifestPath = MANIFEST_FILENAMES.map((name2) => path15.join(projectDir, name2)).find(existsSync11) ?? path15.join(projectDir, MANIFEST_FILENAMES[0]);
+  const author = (options.author ?? "").trim() || DEFAULT_AUTHOR;
+  const substitutions = {
+    "{{TITLE}}": escapeYamlScalar(name),
+    "{{AUTHOR}}": escapeYamlScalar(author)
+  };
+  let openFile = path15.join(projectDir, "chapter-01.md");
+  try {
+    await fillTemplateFile(manifestPath, substitutions);
+    if (preset) {
+      const { doc, file } = await loadManifestDoc(projectDir);
+      doc.set("preset", preset);
+      doc.set("targets", doc.createNode(targets ?? []));
+      if (options.customPage) {
+        const page = {
+          width: options.customPage.width,
+          height: options.customPage.height
+        };
+        if (options.customPage.tolerance !== undefined) {
+          page.tolerance = options.customPage.tolerance;
+        }
+        doc.set("page", doc.createNode(page));
       }
-      ctx.totalNetworkBytes += value.length;
-      await onChunk(value);
+      await writeManifestDoc(file, doc);
     }
-  } finally {
-    reader.releaseLock();
+    const firstSource = await firstSourceFile(manifestPath);
+    if (firstSource)
+      openFile = path15.join(projectDir, firstSource);
+    await fillTemplateFile(openFile, { "{{TITLE}}": name }).catch(() => {});
+  } catch (e) {
+    throw new CreateProjectErrorImpl("scaffold-io", `Could not finalise the project files: ${e instanceof Error ? e.message : String(e)}`);
   }
-  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.`, (chunk2) => {
-      chunks.push(chunk2);
-    });
-    const bytes = new Uint8Array(size);
-    let offset = 0;
-    for (const chunk2 of chunks) {
-      bytes.set(chunk2, offset);
-      offset += chunk2.length;
-    }
-    let metadata = null;
+  const requested = options.versionHistory ?? "local-git";
+  let versionHistory = "none";
+  let versionHistoryError;
+  if (requested === "local-git") {
     try {
-      metadata = object3(JSON.parse(new TextDecoder().decode(bytes)));
-    } catch {}
-    if (!metadata || metadata.name !== name) {
-      throw new FriendlyHttpError(`npm returned invalid metadata for "${name}".`);
+      const { providerFor } = await import("./source-provider-51g6mt6y.js");
+      const provider = providerFor({ type: "local-folder", path: projectDir });
+      await provider.initVersionHistory({
+        projectDir,
+        authorName: options.author?.trim() || undefined,
+        initialMessage: "Created project"
+      });
+      versionHistory = "local-git";
+    } catch (e) {
+      versionHistory = "none";
+      const { findEnclosingRepoDir } = await import("./project-source-ekcyp63q.js");
+      const enclosingRepoDir = await findEnclosingRepoDir(projectDir);
+      versionHistoryError = enclosingRepoDir ? `This book was added to ${path15.basename(enclosingRepoDir)}'s shared version history; save a snapshot to record it.` : e instanceof Error ? e.message : String(e);
     }
-    return metadata;
-  }).catch((error2) => {
-    ctx.packuments.delete(name);
-    throw error2;
-  });
-  ctx.packuments.set(name, pending);
-  return pending;
+  }
+  const result = {
+    projectDir,
+    manifestPath,
+    openFile,
+    versionHistory
+  };
+  if (versionHistoryError !== undefined) {
+    result.versionHistoryError = versionHistoryError;
+  }
+  return result;
 }
-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 };
-    }
+async function ensureGitignoreHasDist(projectDir) {
+  const gitignorePath = path15.join(projectDir, ".gitignore");
+  let existing = null;
+  try {
+    existing = await readFile25(gitignorePath, "utf8");
+  } catch {}
+  if (existing === null) {
+    await writeFile6(gitignorePath, `dist/
+`, "utf8");
+    return;
   }
-  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
-    };
+  const alreadyIgnoresDist = existing.split(`
+`).some((line) => /^\/?dist\/?$/.test(line.trim()));
+  if (alreadyIgnoresDist)
+    return;
+  const needsLeadingNewline = existing.length > 0 && !existing.endsWith(`
+`);
+  await writeFile6(gitignorePath, existing + (needsLeadingNewline ? `
+` : "") + `dist/
+`, "utf8");
+}
+async function firstSourceFile(manifestPath) {
+  let text;
+  try {
+    text = await readFile25(manifestPath, "utf8");
+  } catch {
+    return;
   }
-  if (integrity) {
-    throw new SecurityInstallError("The npm registry supplied integrity data, but no supported SHA-256-or-stronger hash.");
+  const filesIdx = text.search(/^\s*files:\s*$/m);
+  if (filesIdx === -1)
+    return;
+  const rest = text.slice(filesIdx);
+  const m = rest.match(/^\s*-\s*"?([^"\n]+?)"?\s*$/m);
+  return m ? m[1].trim() : undefined;
+}
+async function fillTemplateFile(filePath, substitutions) {
+  let text = await readFile25(filePath, "utf8");
+  for (const [token, value] of Object.entries(substitutions)) {
+    text = text.split(token).join(value);
   }
-  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
-    };
+  await writeFile6(filePath, text, "utf8");
+}
+
+// src/lib/extension-scaffold.ts
+import { access as access2, mkdir as mkdir7, readFile as readFile26, writeFile as writeFile7 } from "node:fs/promises";
+import { constants as FS2 } from "node:fs";
+import path16 from "node:path";
+var EXTENSION_KINDS = ["plugin", "theme"];
+var RESERVED_PREFIX = "gp-";
+var TEMPLATE_FILES = {
+  plugin: [
+    ["package.json", "package.json"],
+    ["README.md", "README.md"],
+    ["plugin.js.tpl", "plugin.js"],
+    ["styles/plugin.css", "styles/plugin.css"],
+    ["snippets/term-box.md", "snippets/term-box.md"],
+    ["test/fixture.md", "test/fixture.md"],
+    ["test/expected.html", "test/expected.html"],
+    ["test/plugin.test.js.tpl", "test/plugin.test.js"]
+  ],
+  theme: [
+    ["package.json", "package.json"],
+    ["README.md", "README.md"],
+    ["components.yaml", "components.yaml"],
+    ["snippets/callout.md", "snippets/callout.md"],
+    ["styles/tokens.css", "styles/tokens.css"],
+    ["styles/base.css", "styles/base.css"],
+    ["styles/components.css", "styles/components.css"],
+    ["styles/page-templates.css", "styles/page-templates.css"],
+    ["styles/page-rules.css", "styles/page-rules.css"],
+    ["styles/book.css", "styles/book.css"]
+  ]
+};
+var OPEN_FILE = {
+  plugin: "plugin.js",
+  theme: "styles/tokens.css"
+};
+var DEFAULT_DESCRIPTION = {
+  plugin: "A Gutterpress plugin.",
+  theme: "A Gutterpress theme."
+};
+var DEFAULT_AUTHOR2 = "Anonymous";
+
+class ExtensionScaffoldError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "CreateProjectError";
+    this.code = code;
   }
-  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);
+function resolveExtensionPrefix(slug, requested) {
+  const raw = (requested ?? `${slug}-`).trim();
+  const prefix = raw.endsWith("-") ? raw : `${raw}-`;
+  if (!/^[a-z][a-z0-9-]*-$/.test(prefix)) {
+    throw new ExtensionScaffoldError("invalid-name", `"${raw}" is not a usable prefix. Use lower-case letters, digits and hyphens, ` + `starting with a letter — for example "${slug}-" or "fn-".`);
+  }
+  if (prefix === RESERVED_PREFIX) {
+    throw new ExtensionScaffoldError("invalid-name", `"${RESERVED_PREFIX}" is reserved for Gutterpress core's own classes and custom ` + `properties. Taking it would silently override them — choose your own prefix.`);
+  }
+  return prefix;
 }
-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.`);
+function identifierFor(slug) {
+  const camel = slug.replace(/-([a-z0-9])/g, (_m, c) => c.toUpperCase());
+  return /^[0-9]/.test(camel) ? `_${camel}` : camel;
+}
+function escapeJsonScalar(value) {
+  return JSON.stringify(value).slice(1, -1);
+}
+async function scaffoldExtension(options) {
+  const kind = options.kind;
+  if (kind !== "plugin" && kind !== "theme") {
+    throw new ExtensionScaffoldError("invalid-name", `Unknown extension kind "${String(kind)}". Choose one of: ${EXTENSION_KINDS.join(", ")}.`);
   }
-  const metadata = await fetchPackument(ctx, name);
-  const versions = object3(metadata.versions);
-  const tags = object3(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 (object3(versions[selector])) {
-    version = selector;
-  } else if (typeof tags[selector] === "string") {
-    version = tags[selector];
-  } else if (validRange2(selector)) {
-    version = maxSatisfying(Object.keys(versions), selector) ?? undefined;
+  const name = (options.name ?? "").trim();
+  if (!name) {
+    throw new ExtensionScaffoldError("invalid-name", "A name is required.");
   }
-  if (!version || !isExactNpmVersion(version)) {
-    throw new PackageUnavailableError(`No exact npm version of "${name}" satisfies "${selector ?? "latest"}".`);
+  const slug = (options.folderName ?? slugify(name)).trim();
+  if (!slug || slug !== slugify(slug)) {
+    throw new ExtensionScaffoldError("invalid-name", `Could not derive a valid folder name from "${name}".`);
   }
-  const selected = object3(versions[version]);
-  if (!selected || selected.name !== name || selected.version !== version) {
-    throw new SecurityInstallError(`npm metadata identity failed for "${name}@${version}".`);
+  const prefix = resolveExtensionPrefix(slug, options.prefix);
+  const parentDir = options.parentDir;
+  if (!parentDir || !path16.isAbsolute(parentDir)) {
+    throw new ExtensionScaffoldError("parent-not-writable", "The save location must be an absolute path.");
   }
-  const dist = object3(selected.dist);
-  if (!dist || typeof dist.tarball !== "string") {
-    throw new PackageUnavailableError(`npm metadata for "${name}@${version}" has no tarball.`);
+  try {
+    await access2(parentDir, FS2.W_OK);
+  } catch {
+    throw new ExtensionScaffoldError("parent-not-writable", `The chosen save location can't be written to: ${parentDir}`);
   }
-  let tarball;
+  const extensionDir = path16.join(parentDir, slug);
+  let targetExists = true;
   try {
-    tarball = new URL(dist.tarball);
+    await access2(extensionDir, FS2.F_OK);
   } catch {
-    throw new SecurityInstallError(`npm returned an invalid tarball URL for "${name}@${version}".`);
+    targetExists = false;
   }
-  if (tarball.origin !== new URL(npmRegistryUrl()).origin || tarball.username || tarball.password) {
-    throw new SecurityInstallError(`npm returned an unexpected tarball host for "${name}@${version}".`);
+  if (targetExists) {
+    throw new ExtensionScaffoldError("target-exists", `A folder named "${slug}" already exists here. Choose a different name or location.`);
   }
-  return { name, version, tarball: tarball.href, integrity: parseIntegrity(dist) };
-}
-async function downloadTarball(ctx, pkg, archivePath) {
-  const file = await open2(archivePath, "wx");
-  const hash = createHash7(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 (chunk2) => {
-        hash.update(chunk2);
-        try {
-          await file.write(chunk2);
-        } 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 relative2 = parts.slice(1).join("/");
-  if (!relative2)
-    return { relative: relative2, key: "" };
-  assertWindowsSafeRelativePath(relative2);
-  if (relative2.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: relative2, key: windowsPathKey(relative2) };
-}
-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 mkdir6(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: relative2, key } = safeTarRelative(entryPath, packageName);
-        if (!relative2) {
-          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 (error2) {
-        rejected = error2 instanceof Error ? error2 : new SecurityInstallError(String(error2));
-        return false;
-      }
-    }
-  });
-  const limiter = new Transform({
-    transform(chunk2, _encoding, callback) {
-      ctx.totalUnpackedBytes += chunk2.length;
-      if (ctx.totalUnpackedBytes > ctx.limits.totalUnpackedBytes) {
-        callback(new SecurityInstallError(`Plugin graph expands beyond the ${mb(ctx.limits.totalUnpackedBytes)} limit.`));
-      } else
-        callback(null, chunk2);
-    }
-  });
-  try {
-    await pipeline(createReadStream2(archivePath), createGunzip(), limiter, unpack);
-  } catch (error2) {
-    if (rejected)
-      throw rejected;
-    if (error2 instanceof SecurityInstallError)
-      throw error2;
-    throw new SecurityInstallError(`The npm tarball could not be safely extracted (${error2 instanceof Error ? error2.message : String(error2)}).`, { cause: error2 });
-  }
-  if (rejected)
-    throw rejected;
-}
-async function readInstalledManifest(packageDir, selected) {
-  const packageJsonPath = path15.join(packageDir, "package.json");
-  let manifest = null;
-  try {
-    const info2 = await lstat2(packageJsonPath);
-    if (!info2.isFile() || info2.isSymbolicLink())
-      throw new Error("not a regular file");
-    manifest = object3(JSON.parse(await readFile25(packageJsonPath, "utf8")));
-  } catch (error2) {
-    throw new SecurityInstallError(`Downloaded ${selected.name}@${selected.version} has no valid package.json (${error2 instanceof Error ? error2.message : String(error2)}).`);
-  }
-  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;
-}
-async function optionalPackageEntry(packageDir, manifest, condition) {
-  try {
-    return await resolvePackageEntry(packageDir, manifest, condition);
-  } catch (error2) {
-    if (error2 instanceof Error && error2.message.includes("no contained JavaScript entry point")) {
-      return;
-    }
-    throw error2;
-  }
-}
-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 skippedStart = ctx.skipped.length;
-  const warningsBefore = new Set(ctx.warnings);
-  const discardOptionalSubtree = () => {
-    ctx.records.splice(recordStart);
-    ctx.skipped.splice(skippedStart);
-    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 (error2) {
-    if (optional && isOptionalAvailabilityError(error2)) {
-      discardOptionalSubtree();
-      return { skipped: error2 instanceof Error ? error2.message : String(error2) };
-    }
-    throw error2;
-  }
-  const ancestor = ancestors.find((candidate) => candidate.name === name && (candidate.version === selected.version || (selector ? satisfies2(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 = path15.join(ctx.stageRoot, ...relativePath.split("/"));
-  const archivePath = path15.join(ctx.downloadsDir, `${ctx.archiveCounter++}.tgz`);
-  try {
-    await mkdir6(path15.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 rm3(packageDir, { recursive: true, force: true });
-        return { skipped: reason };
-      }
-      throw new PackageUnavailableError(reason);
-    }
-    const importEntry = await optionalPackageEntry(packageDir, manifest, "import");
-    const requireEntry = await optionalPackageEntry(packageDir, manifest, "require");
-    if (parentPackagePath === null && !importEntry && !requireEntry) {
-      throw new SecurityInstallError(`${name}@${selected.version} has no JavaScript plugin entry.`);
-    }
-    const record = {
-      path: relativePath,
-      name,
-      version: selected.version,
-      tarball: selected.tarball,
-      integrity: selected.integrity.label,
-      legacySha1: selected.integrity.legacySha1,
-      ...importEntry ? { entry: `${relativePath}/${importEntry}` } : {},
-      ...requireEntry ? { requireEntry: `${relativePath}/${requireEntry}` } : {},
-      dependencies: {},
-      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 and recorded as legacy SHA-1 in the vendor receipt.`);
-    }
-    const dependencies = stringMap2(manifest.dependencies);
-    const optionalDependencies = stringMap2(manifest.optionalDependencies);
-    for (const optionalName of Object.keys(optionalDependencies))
-      delete dependencies[optionalName];
-    const peerDependencies = stringMap2(manifest.peerDependencies);
-    const peerMeta = object3(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]) => object3(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.`);
-      record.dependencies[dependency] = child.path;
-    }
-    const optionalEntries = Object.entries(optionalDependencies).sort(([a], [b]) => a.localeCompare(b));
-    for (const [dependency, range] of optionalEntries) {
-      const child = await installPackage(ctx, dependency, range, relativePath, nextAncestors, depth + 1, true);
-      if (child.path)
-        record.dependencies[dependency] = child.path;
-      else if (child.skipped) {
-        ctx.skipped.push({ from: relativePath, name: dependency, selector: range, kind: "optional", reason: child.skipped });
-      }
-    }
-    for (const [dependency, range] of Object.entries(peerDependencies)) {
-      if (object3(peerMeta[dependency])?.optional === true) {
-        ctx.skipped.push({
-          from: relativePath,
-          name: dependency,
-          selector: range,
-          kind: "optional-peer",
-          reason: "Optional peer dependencies are not auto-installed."
-        });
-      }
-    }
-    return { path: relativePath };
-  } catch (error2) {
-    await rm3(packageDir, { recursive: true, force: true });
-    if (optional && isOptionalAvailabilityError(error2)) {
-      discardOptionalSubtree();
-      return { skipped: error2 instanceof Error ? error2.message : String(error2) };
-    }
-    throw error2;
-  } finally {
-    await rm3(archivePath, { force: true });
-  }
-}
-async function ensureDirectory(pathname) {
+  const author = (options.author ?? "").trim() || DEFAULT_AUTHOR2;
+  const description = (options.description ?? "").trim() || DEFAULT_DESCRIPTION[kind];
+  const plain = {
+    "{{NAME}}": name,
+    "{{SLUG}}": slug,
+    "{{PREFIX}}": prefix,
+    "{{AUTHOR}}": author,
+    "{{DESCRIPTION}}": description,
+    "{{IDENT}}": identifierFor(slug)
+  };
+  const jsonSafe = Object.fromEntries(Object.entries(plain).map(([token, value]) => [token, escapeJsonScalar(value)]));
+  const entries = TEMPLATE_FILES[kind];
+  const written = [];
   try {
-    const info2 = await lstat2(pathname);
-    if (info2.isSymbolicLink() || !info2.isDirectory()) {
-      throw new Error(`Plugin install path is not a normal directory: ${pathname}`);
+    await mkdir7(extensionDir, { recursive: true });
+    for (const [assetName, relDest] of entries) {
+      const src = await getAssetPath(`extension-templates/${kind}/${assetName}`);
+      const dest = path16.join(extensionDir, relDest);
+      await mkdir7(path16.dirname(dest), { recursive: true });
+      const text = await readFile26(src, "utf8");
+      const table = relDest.endsWith(".json") ? jsonSafe : plain;
+      await writeFile7(dest, substitute(text, table), "utf8");
+      written.push(relDest);
     }
-  } catch (error2) {
-    if (error2.code !== "ENOENT")
-      throw error2;
-    await mkdir6(pathname);
+  } catch (e) {
+    throw new ExtensionScaffoldError("scaffold-io", `Could not create the ${kind} files: ${e instanceof Error ? e.message : String(e)}`);
   }
+  return {
+    extensionDir,
+    manifestPath: path16.join(extensionDir, "package.json"),
+    kind,
+    slug,
+    prefix,
+    openFile: path16.join(extensionDir, OPEN_FILE[kind]),
+    files: written
+  };
 }
-async function prepareVendorParent(projectDir, name) {
-  const plugins = path15.join(projectDir, PLUGINS_DIR);
-  const npm = path15.join(plugins, VENDORED_NPM_DIR);
-  const packageParent = path15.dirname(vendoredNpmPluginRoot(projectDir, name, "0.0.0"));
-  await mkdir6(projectDir, { recursive: true });
-  await ensureDirectory(plugins);
-  await ensureDirectory(npm);
-  await ensureDirectory(packageParent);
-  const [realNpm, realPackageParent] = await Promise.all([
-    realpath2(npm),
-    realpath2(packageParent)
-  ]);
-  if (!isContained2(projectDir, realNpm) || !isContained2(projectDir, realPackageParent)) {
-    throw new Error("Plugin install path resolves outside the project.");
+function substitute(text, table) {
+  let out = text;
+  for (const [token, value] of Object.entries(table)) {
+    out = out.split(token).join(value);
   }
-  return realNpm;
+  return out;
 }
-function publicReceipt(record) {
+
+// src/lib/project-templates.ts
+import { isMap, isScalar, isSeq as isSeq2, parseDocument as parseDocument2 } from "yaml";
+var BUILT_IN_TEMPLATE_IDS = [
+  "book",
+  "zine",
+  "technical"
+];
+var SKIP_ENTRIES = new Set([
+  ".git",
+  "node_modules",
+  "out",
+  "dist",
+  "build",
+  ".gutterpress",
+  ".DS_Store"
+]);
+
+// src/lib/extension-manager.ts
+import { cp as cp3, mkdir as mkdir9, readFile as readFile28, rm as rm4, stat as stat6 } from "node:fs/promises";
+import { existsSync as existsSync12 } from "node:fs";
+import path18 from "node:path";
+import { isSeq as isSeq3, isMap as isMap2, isScalar as isScalar2, YAMLMap, Scalar } from "yaml";
+
+// src/lib/npm-plugin-installer.ts
+import { createHash as createHash7, randomUUID as randomUUID3, timingSafeEqual } from "node:crypto";
+import { createReadStream as createReadStream2 } from "node:fs";
+import {
+  lstat as lstat2,
+  mkdir as mkdir8,
+  mkdtemp as mkdtemp2,
+  open as open2,
+  readFile as readFile27,
+  realpath as realpath2,
+  rename as rename2,
+  rm as rm3
+} from "node:fs/promises";
+import path17 from "node:path";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+import { maxSatisfying, satisfies as satisfies2, validRange as validRange2 } from "semver";
+
+// 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 {
-    path: record.path,
-    name: record.name,
-    version: record.version,
-    tarball: record.tarball,
-    integrity: record.integrity,
-    legacySha1: record.legacySha1,
-    ...record.entry ? { entry: record.entry } : {},
-    ...record.requireEntry ? { requireEntry: record.requireEntry } : {},
-    dependencies: record.dependencies
+    signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+    timeout
   };
 }
-async function installNpmPlugin(projectDirInput, packageSpec, options = {}) {
-  const requestedProjectDir = path15.resolve(projectDirInput);
-  await mkdir6(requestedProjectDir, { recursive: true });
-  const projectDir = await realpath2(requestedProjectDir);
-  const requested = parseNpmPluginSpec(packageSpec);
-  const npmRoot = await prepareVendorParent(projectDir, requested.name);
-  const container = await mkdtemp2(path15.join(npmRoot, ".install-"));
-  const stageRoot = path15.join(container, "root");
-  const downloadsDir = path15.join(container, "downloads");
-  await Promise.all([mkdir6(stageRoot), mkdir6(downloadsDir)]);
-  const ctx = {
-    fetch: options.fetch ?? globalThis.fetch,
-    signal: options.signal,
-    limits: mergeLimits(options.limits),
-    stageRoot,
-    downloadsDir,
-    packuments: new Map,
-    records: [],
-    skipped: [],
-    warnings: new Set,
-    totalNetworkBytes: 0,
-    totalUnpackedBytes: 0,
-    totalFiles: 0,
-    archiveCounter: 0
-  };
-  let finalRoot = "";
-  let backupRoot = null;
+async function withFetchTimeout(options, run) {
+  const composed = composeSignal(options.signal, options.timeoutMs);
   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.");
-    const importEntry = rootRecord.entry ?? rootRecord.requireEntry;
-    if (!importEntry)
-      throw new Error("Root plugin package has no recorded JavaScript entry.");
-    const importFormat = packageEntryFormat(rootRecord.manifest, importEntry);
-    const entry = importFormat === "commonjs" ? rootRecord.requireEntry ?? importEntry : importEntry;
-    const format = packageEntryFormat(rootRecord.manifest, entry);
-    const tree = await computeVendorTreeDigest(stageRoot);
-    const receipt = {
-      schemaVersion: VENDOR_RECEIPT_VERSION,
-      root: {
-        name: rootRecord.name,
-        version: rootRecord.version,
-        packagePath: rootRecord.path,
-        entry,
-        format
-      },
-      packages: ctx.records.map(publicReceipt).sort((a, b) => a.path.localeCompare(b.path)),
-      skipped: ctx.skipped,
-      tree: { algorithm: "sha256", ...tree }
-    };
-    const receiptFile = await open2(path15.join(stageRoot, VENDOR_RECEIPT_FILE), "wx");
-    try {
-      await receiptFile.writeFile(`${JSON.stringify(receipt, null, 2)}
-`, "utf8");
-      await receiptFile.sync();
-    } finally {
-      await receiptFile.close();
+    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/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(error2) {
+  return error2 instanceof PackageUnavailableError || error2 instanceof FriendlyHttpError || error2 instanceof FetchUnavailableError;
+}
+function object3(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function stringMap2(value) {
+  const map = object3(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 isContained2(root, candidate) {
+  const relative2 = path17.relative(root, candidate);
+  return relative2 === "" || !relative2.startsWith("..") && !path17.isAbsolute(relative2);
+}
+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);
     }
-    finalRoot = vendoredNpmPluginRoot(projectDir, rootRecord.name, rootRecord.version);
-    const realFinalParent = await realpath2(path15.dirname(finalRoot));
-    if (!isContained2(projectDir, realFinalParent)) {
-      throw new Error("Plugin install destination resolves outside the project.");
+  } 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.`);
     }
-    try {
-      await lstat2(finalRoot);
-      backupRoot = `${finalRoot}.backup-${randomUUID3()}`;
-      await rename2(finalRoot, backupRoot);
-    } catch (error2) {
-      if (error2.code !== "ENOENT")
-        throw error2;
+    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.`, (chunk2) => {
+      chunks.push(chunk2);
+    });
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk2 of chunks) {
+      bytes.set(chunk2, offset);
+      offset += chunk2.length;
     }
+    let metadata = null;
     try {
-      await rename2(stageRoot, finalRoot);
-    } catch (error2) {
-      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: error2 });
-        }
-      }
-      throw error2;
+      metadata = object3(JSON.parse(new TextDecoder().decode(bytes)));
+    } catch {}
+    if (!metadata || metadata.name !== name) {
+      throw new FriendlyHttpError(`npm returned invalid metadata for "${name}".`);
+    }
+    return metadata;
+  }).catch((error2) => {
+    ctx.packuments.delete(name);
+    throw error2;
+  });
+  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 {
-      name: rootRecord.name,
-      version: rootRecord.version,
-      installRoot: finalRoot,
-      backupRoot,
-      warnings: [...ctx.warnings]
+      algorithm: "sha1",
+      digest: Buffer.from(sha1[2], "base64"),
+      label: `sha1-${sha1[2]}`,
+      legacySha1: true
     };
-  } finally {
-    await rm3(container, { recursive: true, force: true }).catch(() => {});
   }
-}
-async function finalizeNpmPluginInstall(installed) {
-  if (installed.backupRoot) {
-    await rm3(installed.backupRoot, { recursive: true, force: 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.");
 }
-async function rollbackNpmPluginInstall(installed) {
-  await rm3(installed.installRoot, { recursive: true, force: true });
-  if (installed.backupRoot)
-    await rename2(installed.backupRoot, installed.installRoot);
+function unsupportedSelector(selector) {
+  return /^(?:file:|git\+|https?:|ssh:|github:|workspace:|link:|npm:)/i.test(selector);
 }
-
-// src/lib/extension-manager.ts
-var EXTENSIONS_DIR = "extensions";
-var RECOMMENDED_EXTENSIONS = [
-  {
-    use: "markdown-it-mark",
-    label: "Highlight",
-    description: "Highlighted text with `==marked==` -> `<mark>`."
-  },
-  {
-    use: "markdown-it-sub",
-    label: "Subscript",
-    description: "Subscript text with `H~2~O`."
-  },
-  {
-    use: "markdown-it-sup",
-    label: "Superscript",
-    description: "Superscript text with `29^th^`."
-  },
-  {
-    use: "markdown-it-abbr",
-    label: "Abbreviations",
-    description: "Define `*[HTML]: Hyper Text...` and get `<abbr>` tooltips."
-  },
-  {
-    use: "gutterpress-gfm-alerts",
-    label: "Callouts",
-    description: "GitHub-style `> [!NOTE]` alert boxes (Note/Tip/Important/Warning/Caution)."
+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.`);
   }
-];
-var BUILT_IN_STYLE_SET_IDS = ["clean-book", "zine", "technical-doc"];
-var mutationQueues = new Map;
-function withMutationLock(projectDir, mutation) {
-  const resolved = path16.resolve(projectDir);
-  const key = process.platform === "win32" ? resolved.toLowerCase() : resolved;
-  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;
+  const metadata = await fetchPackument(ctx, name);
+  const versions = object3(metadata.versions);
+  const tags = object3(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 (object3(versions[selector])) {
+    version = selector;
+  } else if (typeof tags[selector] === "string") {
+    version = tags[selector];
+  } else if (validRange2(selector)) {
+    version = maxSatisfying(Object.keys(versions), selector) ?? undefined;
   }
-  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;
+  if (!version || !isExactNpmVersion(version)) {
+    throw new PackageUnavailableError(`No exact npm version of "${name}" satisfies "${selector ?? "latest"}".`);
+  }
+  const selected = object3(versions[version]);
+  if (!selected || selected.name !== name || selected.version !== version) {
+    throw new SecurityInstallError(`npm metadata identity failed for "${name}@${version}".`);
+  }
+  const dist = object3(selected.dist);
+  if (!dist || typeof dist.tarball !== "string") {
+    throw new PackageUnavailableError(`npm metadata for "${name}@${version}" has no tarball.`);
+  }
+  let tarball;
   try {
-    pa = parseExtensionSpecifier(a);
-    pb = parseExtensionSpecifier(b);
+    tarball = new URL(dist.tarball);
   } catch {
-    return false;
+    throw new SecurityInstallError(`npm returned an invalid tarball URL for "${name}@${version}".`);
   }
-  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 = path16.relative(path16.resolve(projectDir), abs).split(path16.sep).join("/");
-  if (rel === "") {
-    throw new Error("An extension cannot be the project folder itself.");
+  if (tarball.origin !== new URL(npmRegistryUrl()).origin || tarball.username || tarball.password) {
+    throw new SecurityInstallError(`npm returned an unexpected tarball host for "${name}@${version}".`);
   }
-  if (isPathSpecifier(rel))
-    return rel;
-  return `./${rel}`;
-}
-var NO_CARRIES = {
-  markdown: false,
-  styles: false,
-  snippets: false,
-  components: 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
-  };
+  return { name, version, tarball: tarball.href, integrity: parseIntegrity(dist) };
 }
-async function describeEntry(projectDir, raw) {
-  const warnings = [];
-  let parsed = null;
+async function downloadTarball(ctx, pkg, archivePath) {
+  const file = await open2(archivePath, "wx");
+  const hash = createHash7(pkg.integrity.algorithm);
   try {
-    parsed = parseExtensionSpecifier(raw.use);
-  } catch (error2) {
-    warnings.push(error2 instanceof Error ? error2.message : String(error2));
+    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 (chunk2) => {
+        hash.update(chunk2);
+        try {
+          await file.write(chunk2);
+        } catch (cause) {
+          throw new SecurityInstallError(`Could not store ${pkg.name}@${pkg.version} while downloading.`, { cause });
+        }
+      });
+    });
+  } finally {
+    await file.close();
   }
-  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 });
+  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.`);
   }
-  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 }
-    });
+}
+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)"}`);
   }
-  if (parsed.kind === "path") {
-    const abs = path16.resolve(projectDir, parsed.path);
-    const base2 = { ...common, kind: "path", name: parsed.path };
-    let info2;
-    try {
-      info2 = await stat5(abs);
-    } catch {
-      warnings.push(`Not found: ${abs}`);
-      return withWarnings({ ...base2, label: path16.basename(abs), carries: NO_CARRIES });
+  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 relative2 = parts.slice(1).join("/");
+  if (!relative2)
+    return { relative: relative2, key: "" };
+  assertWindowsSafeRelativePath(relative2);
+  if (relative2.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: relative2, key: windowsPathKey(relative2) };
+}
+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 mkdir8(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: relative2, key } = safeTarRelative(entryPath, packageName);
+        if (!relative2) {
+          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 (error2) {
+        rejected = error2 instanceof Error ? error2 : new SecurityInstallError(String(error2));
+        return false;
+      }
     }
-    if (info2.isDirectory()) {
-      return withWarnings(await describeFolder(abs, base2, prettify(path16.basename(abs))));
+  });
+  const limiter = new Transform({
+    transform(chunk2, _encoding, callback) {
+      ctx.totalUnpackedBytes += chunk2.length;
+      if (ctx.totalUnpackedBytes > ctx.limits.totalUnpackedBytes) {
+        callback(new SecurityInstallError(`Plugin graph expands beyond the ${mb(ctx.limits.totalUnpackedBytes)} limit.`));
+      } else
+        callback(null, chunk2);
     }
-    return withWarnings({
-      ...base2,
-      label: path16.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 } });
+  });
+  try {
+    await pipeline(createReadStream2(archivePath), createGunzip(), limiter, unpack);
+  } catch (error2) {
+    if (rejected)
+      throw rejected;
+    if (error2 instanceof SecurityInstallError)
+      throw error2;
+    throw new SecurityInstallError(`The npm tarball could not be safely extracted (${error2 instanceof Error ? error2.message : String(error2)}).`, { cause: error2 });
   }
-  let installRoot = null;
+  if (rejected)
+    throw rejected;
+}
+async function readInstalledManifest(packageDir, selected) {
+  const packageJsonPath = path17.join(packageDir, "package.json");
+  let manifest = null;
   try {
-    installRoot = await resolveVendoredPluginInstallRoot(projectDir, parsed.name, parsed.version);
+    const info2 = await lstat2(packageJsonPath);
+    if (!info2.isFile() || info2.isSymbolicLink())
+      throw new Error("not a regular file");
+    manifest = object3(JSON.parse(await readFile27(packageJsonPath, "utf8")));
   } catch (error2) {
-    warnings.push(error2 instanceof Error ? error2.message : String(error2));
+    throw new SecurityInstallError(`Downloaded ${selected.name}@${selected.version} has no valid package.json (${error2 instanceof Error ? error2.message : String(error2)}).`);
   }
-  if (!installRoot) {
-    warnings.push(`Not installed — run \`gutterpress ext add ${raw.use}\`.`);
-    return withWarnings({ ...base, label: parsed.name, carries: { ...NO_CARRIES, markdown: true } });
+  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}.`);
   }
-  const pkgDir = vendoredNpmPluginPackageDir(installRoot, parsed.name);
-  if (!existsSync11(path16.join(pkgDir, EXTENSION_MANIFEST_FILENAME))) {
-    return withWarnings({ ...base, label: parsed.name, carries: { ...NO_CARRIES, markdown: true } });
+  return manifest;
+}
+async function optionalPackageEntry(packageDir, manifest, condition) {
+  try {
+    return await resolvePackageEntry(packageDir, manifest, condition);
+  } catch (error2) {
+    if (error2 instanceof Error && error2.message.includes("no contained JavaScript entry point")) {
+      return;
+    }
+    throw error2;
   }
-  const described = await describeFolder(pkgDir, base, parsed.name, (name) => name);
-  return withWarnings({
-    ...described,
-    carries: { ...described.carries, markdown: true }
-  });
 }
-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));
+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;
   }
-  return out;
+  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);
 }
-async function describeExtension(projectDir, use) {
-  return (await listProjectExtensions(projectDir)).find((e) => sameExtension(e.use, use)) ?? null;
+function relativePackagePath(parentPackagePath, name) {
+  const segments = name.split("/");
+  return parentPackagePath ? `${parentPackagePath}/node_modules/${segments.join("/")}` : `node_modules/${segments.join("/")}`;
 }
-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 installPackage(ctx, name, selector, parentPackagePath, ancestors, depth, optional) {
+  const recordStart = ctx.records.length;
+  const skippedStart = ctx.skipped.length;
+  const warningsBefore = new Set(ctx.warnings);
+  const discardOptionalSubtree = () => {
+    ctx.records.splice(recordStart);
+    ctx.skipped.splice(skippedStart);
+    ctx.warnings = warningsBefore;
   };
-}
-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"));
-        }
+  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 (error2) {
+    if (optional && isOptionalAvailabilityError(error2)) {
+      discardOptionalSubtree();
+      return { skipped: error2 instanceof Error ? error2.message : String(error2) };
+    }
+    throw error2;
+  }
+  const ancestor = ancestors.find((candidate) => candidate.name === name && (candidate.version === selected.version || (selector ? satisfies2(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 = path17.join(ctx.stageRoot, ...relativePath.split("/"));
+  const archivePath = path17.join(ctx.downloadsDir, `${ctx.archiveCounter++}.tgz`);
+  try {
+    await mkdir8(path17.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 rm3(packageDir, { recursive: true, force: true });
+        return { skipped: reason };
       }
-    } 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;
+      throw new PackageUnavailableError(reason);
     }
-    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;
+    const importEntry = await optionalPackageEntry(packageDir, manifest, "import");
+    const requireEntry = await optionalPackageEntry(packageDir, manifest, "require");
+    if (parentPackagePath === null && !importEntry && !requireEntry) {
+      throw new SecurityInstallError(`${name}@${selected.version} has no JavaScript plugin entry.`);
     }
-    if (parsed.kind === "npm" && parsed.version) {
-      await rm4(vendoredNpmPluginRoot(projectDir, parsed.name, parsed.version), {
-        recursive: true,
-        force: true
-      });
-      clearVendoredPluginResolver(projectDir, parsed.name, parsed.version);
+    const record = {
+      path: relativePath,
+      name,
+      version: selected.version,
+      tarball: selected.tarball,
+      integrity: selected.integrity.label,
+      legacySha1: selected.integrity.legacySha1,
+      ...importEntry ? { entry: `${relativePath}/${importEntry}` } : {},
+      ...requireEntry ? { requireEntry: `${relativePath}/${requireEntry}` } : {},
+      dependencies: {},
+      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 and recorded as legacy SHA-1 in the vendor receipt.`);
     }
-  });
-}
-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);
+    const dependencies = stringMap2(manifest.dependencies);
+    const optionalDependencies = stringMap2(manifest.optionalDependencies);
+    for (const optionalName of Object.keys(optionalDependencies))
+      delete dependencies[optionalName];
+    const peerDependencies = stringMap2(manifest.peerDependencies);
+    const peerMeta = object3(manifest.peerDependenciesMeta) ?? {};
+    for (const existing of [...Object.keys(dependencies), ...Object.keys(optionalDependencies)]) {
+      delete peerDependencies[existing];
     }
-  } 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));
+    const nextAncestors = [...ancestors, record];
+    const requiredEntries = [
+      ...Object.entries(dependencies).map(([dependency, range]) => ({ dependency, range, kind: "required" })),
+      ...Object.entries(peerDependencies).filter(([dependency]) => object3(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.`);
+      record.dependencies[dependency] = child.path;
+    }
+    const optionalEntries = Object.entries(optionalDependencies).sort(([a], [b]) => a.localeCompare(b));
+    for (const [dependency, range] of optionalEntries) {
+      const child = await installPackage(ctx, dependency, range, relativePath, nextAncestors, depth + 1, true);
+      if (child.path)
+        record.dependencies[dependency] = child.path;
+      else if (child.skipped) {
+        ctx.skipped.push({ from: relativePath, name: dependency, selector: range, kind: "optional", reason: child.skipped });
+      }
+    }
+    for (const [dependency, range] of Object.entries(peerDependencies)) {
+      if (object3(peerMeta[dependency])?.optional === true) {
+        ctx.skipped.push({
+          from: relativePath,
+          name: dependency,
+          selector: range,
+          kind: "optional-peer",
+          reason: "Optional peer dependencies are not auto-installed."
+        });
+      }
+    }
+    return { path: relativePath };
+  } catch (error2) {
+    await rm3(packageDir, { recursive: true, force: true });
+    if (optional && isOptionalAvailabilityError(error2)) {
+      discardOptionalSubtree();
+      return { skipped: error2 instanceof Error ? error2.message : String(error2) };
+    }
+    throw error2;
+  } finally {
+    await rm3(archivePath, { force: true });
   }
-  await writeManifestDoc(file, doc);
 }
-async function addPathExtension(projectDir, abs, exportName) {
+async function ensureDirectory(pathname) {
   try {
-    await stat5(abs);
-  } catch {
-    throw new Error(`Extension not found: ${abs}`);
+    const info2 = await lstat2(pathname);
+    if (info2.isSymbolicLink() || !info2.isDirectory()) {
+      throw new Error(`Plugin install path is not a normal directory: ${pathname}`);
+    }
+  } catch (error2) {
+    if (error2.code !== "ENOENT")
+      throw error2;
+    await mkdir8(pathname);
   }
-  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 (path16.isAbsolute(input))
-    return addPathExtension(projectDir, input, exportName);
-  const parsed = parseExtensionSpecifier(input);
-  if (parsed.kind === "path") {
-    return addPathExtension(projectDir, path16.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);
+async function prepareVendorParent(projectDir, name) {
+  const plugins = path17.join(projectDir, PLUGINS_DIR);
+  const npm = path17.join(plugins, VENDORED_NPM_DIR);
+  const packageParent = path17.dirname(vendoredNpmPluginRoot(projectDir, name, "0.0.0"));
+  await mkdir8(projectDir, { recursive: true });
+  await ensureDirectory(plugins);
+  await ensureDirectory(npm);
+  await ensureDirectory(packageParent);
+  const [realNpm, realPackageParent] = await Promise.all([
+    realpath2(npm),
+    realpath2(packageParent)
+  ]);
+  if (!isContained2(projectDir, realNpm) || !isContained2(projectDir, realPackageParent)) {
+    throw new Error("Plugin install path resolves outside the project.");
   }
-  const existing = await describeExtension(projectDir, parsed.name);
-  const chosenExport = exportName ?? existing?.export;
-  const installed = await installNpmPlugin(projectDir, input, options);
-  const use = pinnedNpmSpecifier(installed.name, installed.version);
+  return realNpm;
+}
+function publicReceipt(record) {
+  return {
+    path: record.path,
+    name: record.name,
+    version: record.version,
+    tarball: record.tarball,
+    integrity: record.integrity,
+    legacySha1: record.legacySha1,
+    ...record.entry ? { entry: record.entry } : {},
+    ...record.requireEntry ? { requireEntry: record.requireEntry } : {},
+    dependencies: record.dependencies
+  };
+}
+async function installNpmPlugin(projectDirInput, packageSpec, options = {}) {
+  const requestedProjectDir = path17.resolve(projectDirInput);
+  await mkdir8(requestedProjectDir, { recursive: true });
+  const projectDir = await realpath2(requestedProjectDir);
+  const requested = parseNpmPluginSpec(packageSpec);
+  const npmRoot = await prepareVendorParent(projectDir, requested.name);
+  const container = await mkdtemp2(path17.join(npmRoot, ".install-"));
+  const stageRoot = path17.join(container, "root");
+  const downloadsDir = path17.join(container, "downloads");
+  await Promise.all([mkdir8(stageRoot), mkdir8(downloadsDir)]);
+  const ctx = {
+    fetch: options.fetch ?? globalThis.fetch,
+    signal: options.signal,
+    limits: mergeLimits(options.limits),
+    stageRoot,
+    downloadsDir,
+    packuments: new Map,
+    records: [],
+    skipped: [],
+    warnings: new Set,
+    totalNetworkBytes: 0,
+    totalUnpackedBytes: 0,
+    totalFiles: 0,
+    archiveCounter: 0
+  };
+  let finalRoot = "";
+  let backupRoot = null;
   try {
-    await loadPlugin(extensionConfigFor({
-      use,
-      kind: "npm",
-      name: installed.name,
-      version: installed.version,
-      export: chosenExport
-    }), projectDir);
-    await options.__testFailBeforeManifestCommit?.();
-    await upsertEntry(projectDir, use, chosenExport);
-  } catch (cause) {
+    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.");
+    const importEntry = rootRecord.entry ?? rootRecord.requireEntry;
+    if (!importEntry)
+      throw new Error("Root plugin package has no recorded JavaScript entry.");
+    const importFormat = packageEntryFormat(rootRecord.manifest, importEntry);
+    const entry = importFormat === "commonjs" ? rootRecord.requireEntry ?? importEntry : importEntry;
+    const format = packageEntryFormat(rootRecord.manifest, entry);
+    const tree = await computeVendorTreeDigest(stageRoot);
+    const receipt = {
+      schemaVersion: VENDOR_RECEIPT_VERSION,
+      root: {
+        name: rootRecord.name,
+        version: rootRecord.version,
+        packagePath: rootRecord.path,
+        entry,
+        format
+      },
+      packages: ctx.records.map(publicReceipt).sort((a, b) => a.path.localeCompare(b.path)),
+      skipped: ctx.skipped,
+      tree: { algorithm: "sha256", ...tree }
+    };
+    const receiptFile = await open2(path17.join(stageRoot, VENDOR_RECEIPT_FILE), "wx");
     try {
-      await rollbackNpmPluginInstall(installed);
-      clearVendoredPluginResolver(projectDir, installed.name, installed.version);
-    } 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 });
+      await receiptFile.writeFile(`${JSON.stringify(receipt, null, 2)}
+`, "utf8");
+      await receiptFile.sync();
+    } finally {
+      await receiptFile.close();
     }
-    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((error2) => {
-    warnings.push(`The extension was installed, but an old backup could not be removed: ` + `${error2 instanceof Error ? error2.message : String(error2)}`);
-  });
-  const entry = await describeExtension(projectDir, use);
-  return warnings.length > 0 ? { ...entry, warnings: [...entry.warnings ?? [], ...warnings] } : entry;
-}
-async function uniqueExtensionId(projectDir, base) {
-  const slug = slugify(base) || "extension";
-  let candidate = slug;
-  for (let n = 2;existsSync11(path16.join(projectDir, EXTENSIONS_DIR, candidate)); n++) {
-    candidate = `${slug}-${n}`;
+    finalRoot = vendoredNpmPluginRoot(projectDir, rootRecord.name, rootRecord.version);
+    const realFinalParent = await realpath2(path17.dirname(finalRoot));
+    if (!isContained2(projectDir, realFinalParent)) {
+      throw new Error("Plugin install destination resolves outside the project.");
+    }
+    try {
+      await lstat2(finalRoot);
+      backupRoot = `${finalRoot}.backup-${randomUUID3()}`;
+      await rename2(finalRoot, backupRoot);
+    } catch (error2) {
+      if (error2.code !== "ENOENT")
+        throw error2;
+    }
+    try {
+      await rename2(stageRoot, finalRoot);
+    } catch (error2) {
+      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: error2 });
+        }
+      }
+      throw error2;
+    }
+    return {
+      name: rootRecord.name,
+      version: rootRecord.version,
+      installRoot: finalRoot,
+      backupRoot,
+      warnings: [...ctx.warnings]
+    };
+  } finally {
+    await rm3(container, { recursive: true, force: true }).catch(() => {});
   }
-  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(", ")}).`);
+async function finalizeNpmPluginInstall(installed) {
+  if (installed.backupRoot) {
+    await rm3(installed.backupRoot, { recursive: true, force: true });
   }
-  return withMutationLock(projectDir, async () => {
-    const dest = path16.join(projectDir, EXTENSIONS_DIR, id);
-    if (!existsSync11(dest)) {
-      const src = path16.join(await getAssetsDir(), "themes", id);
-      await mkdir7(path16.dirname(dest), { recursive: true });
-      await cp2(src, dest, { recursive: true });
-    }
-    return addExtensionUnlocked(projectDir, `./${EXTENSIONS_DIR}/${id}`, {});
-  });
 }
-
-// src/lib/project-scaffold.ts
-import { access, copyFile, cp as cp3, mkdir as mkdir8, readdir as readdir5, readFile as readFile27, stat as stat6, writeFile as writeFile6 } from "node:fs/promises";
-import { constants as FS, existsSync as existsSync12 } from "node:fs";
-import path17 from "node:path";
-var STARTER_THEME_FOR_TEMPLATE = {
-  book: "clean-book",
-  zine: "zine",
-  technical: "technical-doc"
-};
-function starterOverridesCss(themeId) {
-  return `/**
- * Your book's own styles.
- *
- * Your book's look lives in ${EXTENSIONS_DIR}/${themeId}/theme.css — an
- * extension listed under \`extensions:\` in manifest.yaml. Add or swap looks
- * with \`gutterpress ext add\` (or the desktop's Look view) without losing
- * anything you write here. This file loads AFTER every extension, so any
- * rule you add below overrides the look's defaults.
- *
- * Most everyday adjustments (colors, fonts, margins, spacing) are already
- * exposed as CSS custom properties on the theme's :root — try those first.
- */
-`;
+async function rollbackNpmPluginInstall(installed) {
+  await rm3(installed.installRoot, { recursive: true, force: true });
+  if (installed.backupRoot)
+    await rename2(installed.backupRoot, installed.installRoot);
 }
 
-class CreateProjectErrorImpl extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "CreateProjectError";
-    this.code = code;
+// src/lib/extension-manager.ts
+var EXTENSIONS_DIR = "extensions";
+var RECOMMENDED_EXTENSIONS = [
+  {
+    use: "markdown-it-mark",
+    label: "Highlight",
+    description: "Highlighted text with `==marked==` -> `<mark>`."
+  },
+  {
+    use: "markdown-it-sub",
+    label: "Subscript",
+    description: "Subscript text with `H~2~O`."
+  },
+  {
+    use: "markdown-it-sup",
+    label: "Superscript",
+    description: "Superscript text with `29^th^`."
+  },
+  {
+    use: "markdown-it-abbr",
+    label: "Abbreviations",
+    description: "Define `*[HTML]: Hyper Text...` and get `<abbr>` tooltips."
+  },
+  {
+    use: "gutterpress-gfm-alerts",
+    label: "Callouts",
+    description: "GitHub-style `> [!NOTE]` alert boxes (Note/Tip/Important/Warning/Caution)."
   }
+];
+var BUILT_IN_STYLE_SET_IDS = ["clean-book", "zine", "technical-doc"];
+var mutationQueues = new Map;
+function withMutationLock(projectDir, mutation) {
+  const resolved = path18.resolve(projectDir);
+  const key = process.platform === "win32" ? resolved.toLowerCase() : resolved;
+  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 slugifyProjectName(name) {
-  return slugify(name);
-}
-function escapeYamlScalar(value) {
-  return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
-}
-var DEFAULT_AUTHOR = "Anonymous";
-function isPositivePoints(value) {
-  return typeof value === "number" && Number.isFinite(value) && value > 0;
-}
-function requirePreset(preset, customPage) {
-  if (!preset || !PRESET_IDS.includes(preset)) {
-    const got = preset ? ` (got "${preset}")` : "";
-    throw new CreateProjectErrorImpl("preset-required", `A preset is required to create a book${got}. Choose one of: ${PRESET_IDS.join(", ")}.`);
-  }
-  if (preset === "custom") {
-    const missing = [];
-    if (!customPage || !isPositivePoints(customPage.width))
-      missing.push("page width");
-    if (!customPage || !isPositivePoints(customPage.height))
-      missing.push("page height");
-    if (missing.length > 0) {
-      throw new CreateProjectErrorImpl("custom-page-required", `The custom preset needs a trim size: ${missing.join(" and ")} in points ` + `(72pt = 1in — e.g. US Letter is 612 x 792).`);
-    }
-  } else if (customPage && (!isPositivePoints(customPage.width) || !isPositivePoints(customPage.height))) {
-    throw new CreateProjectErrorImpl("custom-page-required", "Page overrides need a positive width and height in points (72pt = 1in).");
-  }
-  if (customPage?.tolerance !== undefined && !isPositivePoints(customPage.tolerance)) {
-    throw new CreateProjectErrorImpl("custom-page-required", "Page tolerance must be a positive number of points.");
+function entryUse(item) {
+  if (isScalar2(item))
+    return typeof item.value === "string" ? item.value.trim() : null;
+  if (isMap2(item)) {
+    const u = item.get("use");
+    return typeof u === "string" ? u.trim() : null;
   }
-  return preset;
+  return null;
 }
-function resolveScaffoldTargets(requested, preset) {
-  const ids = requested ?? [...PRESETS[preset].defaultTargets];
-  const unknown = ids.filter((id) => !TARGETS[id]);
-  if (unknown.length > 0) {
-    throw new CreateProjectErrorImpl("invalid-targets", `Unknown publish target${unknown.length > 1 ? "s" : ""} "${unknown.join('", "')}". ` + `Known targets: ${TARGET_IDS.join(", ")}.`);
-  }
-  return [...new Set(ids)];
+function rawEntry(item) {
+  const use = entryUse(item);
+  if (!use)
+    return null;
+  if (!isMap2(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
+  };
 }
-async function scaffoldProject(options) {
-  const name = (options.name ?? "").trim();
-  if (!name) {
-    throw new CreateProjectErrorImpl("invalid-name", "A project name is required.");
-  }
-  const slug = slugifyProjectName(name);
-  const folderName = (options.folderName ?? slug).trim();
-  if (!folderName || folderName !== slugifyProjectName(folderName)) {
-    throw new CreateProjectErrorImpl("invalid-name", `Could not derive a valid folder name from "${name}".`);
-  }
-  const parentDir = options.parentDir;
-  if (!parentDir || !path17.isAbsolute(parentDir)) {
-    throw new CreateProjectErrorImpl("parent-not-writable", "The save location must be an absolute path.");
-  }
-  try {
-    await access(parentDir, FS.W_OK);
-  } catch {
-    throw new CreateProjectErrorImpl("parent-not-writable", `The chosen save location can't be written to: ${parentDir}`);
-  }
-  const projectDir = path17.join(parentDir, folderName);
-  let targetExists = true;
+function sameExtension(a, b) {
+  if (a.trim() === b.trim())
+    return true;
+  let pa;
+  let pb;
   try {
-    await access(projectDir, FS.F_OK);
+    pa = parseExtensionSpecifier(a);
+    pb = parseExtensionSpecifier(b);
   } catch {
-    targetExists = false;
-  }
-  if (targetExists) {
-    throw new CreateProjectErrorImpl("target-exists", `A folder named "${folderName}" already exists here. Choose a different name or location.`);
+    return false;
   }
-  const template = options.template ?? "book";
-  const customTemplateDir = options.templateDir;
-  const starterThemeId = STARTER_THEME_FOR_TEMPLATE[template] ?? "clean-book";
-  const preset = customTemplateDir && options.preset === undefined ? undefined : requirePreset(options.preset, options.customPage);
-  const targets = preset ? resolveScaffoldTargets(options.targets, preset) : undefined;
-  try {
-    await mkdir8(projectDir, { recursive: true });
-    if (customTemplateDir) {
-      const entries = await readdir5(customTemplateDir, { withFileTypes: true });
-      for (const entry of entries) {
-        if (entry.name === ".gutterpress-template.json")
-          continue;
-        await cp3(path17.join(customTemplateDir, entry.name), path17.join(projectDir, entry.name), { recursive: true });
-      }
-      await mkdir8(path17.join(projectDir, "assets"), { recursive: true });
-    } else {
-      const tplManifest = await getAssetPath(`templates/${template}/manifest.yaml`);
-      const tplChapter = await getAssetPath(`templates/${template}/chapter-01.md`);
-      await mkdir8(path17.join(projectDir, "assets"), { recursive: true });
-      await copyFile(tplManifest, path17.join(projectDir, MANIFEST_FILENAMES[0]));
-      await copyFile(tplChapter, path17.join(projectDir, "chapter-01.md"));
-      await mkdir8(path17.join(projectDir, "styles"), { recursive: true });
-      await writeFile6(path17.join(projectDir, "styles", "book.css"), starterOverridesCss(starterThemeId), "utf8");
-    }
-  } catch (e) {
-    throw new CreateProjectErrorImpl("scaffold-io", `Could not create the project files: ${e instanceof Error ? e.message : String(e)}`);
+  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 = path18.relative(path18.resolve(projectDir), abs).split(path18.sep).join("/");
+  if (rel === "") {
+    throw new Error("An extension cannot be the project folder itself.");
   }
+  if (isPathSpecifier(rel))
+    return rel;
+  return `./${rel}`;
+}
+var NO_CARRIES = {
+  markdown: false,
+  styles: false,
+  snippets: false,
+  components: 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 {
-    await ensureGitignoreHasDist(projectDir);
-  } catch (e) {
-    throw new CreateProjectErrorImpl("scaffold-io", `Could not write .gitignore: ${e instanceof Error ? e.message : String(e)}`);
+    parsed = parseExtensionSpecifier(raw.use);
+  } catch (error2) {
+    warnings.push(error2 instanceof Error ? error2.message : String(error2));
   }
-  const manifestPath = MANIFEST_FILENAMES.map((name2) => path17.join(projectDir, name2)).find(existsSync12) ?? path17.join(projectDir, MANIFEST_FILENAMES[0]);
-  const author = (options.author ?? "").trim() || DEFAULT_AUTHOR;
-  const substitutions = {
-    "{{TITLE}}": escapeYamlScalar(name),
-    "{{AUTHOR}}": escapeYamlScalar(author)
+  const common = {
+    use: raw.use,
+    enabled: raw.enabled,
+    ...raw.export ? { export: raw.export } : {}
   };
-  let openFile = path17.join(projectDir, "chapter-01.md");
-  try {
-    await fillTemplateFile(manifestPath, substitutions);
-    if (!customTemplateDir) {
-      await addBuiltInStyleSet(projectDir, starterThemeId);
-    }
-    if (preset) {
-      const { doc, file } = await loadManifestDoc(projectDir);
-      doc.set("preset", preset);
-      doc.set("targets", doc.createNode(targets ?? []));
-      if (options.customPage) {
-        const page = {
-          width: options.customPage.width,
-          height: options.customPage.height
-        };
-        if (options.customPage.tolerance !== undefined) {
-          page.tolerance = options.customPage.tolerance;
-        }
-        doc.set("page", doc.createNode(page));
-      }
-      await writeManifestDoc(file, doc);
-    }
-    const firstSource = await firstSourceFile(manifestPath);
-    if (firstSource)
-      openFile = path17.join(projectDir, firstSource);
-    await fillTemplateFile(openFile, { "{{TITLE}}": name }).catch(() => {});
-  } catch (e) {
-    throw new CreateProjectErrorImpl("scaffold-io", `Could not finalise the project files: ${e instanceof Error ? e.message : String(e)}`);
+  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 });
   }
-  const requested = options.versionHistory ?? "local-git";
-  let versionHistory = "none";
-  let versionHistoryError;
-  if (requested === "local-git") {
+  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 = path18.resolve(projectDir, parsed.path);
+    const base2 = { ...common, kind: "path", name: parsed.path };
+    let info2;
     try {
-      const { providerFor } = await import("./source-provider-51g6mt6y.js");
-      const provider = providerFor({ type: "local-folder", path: projectDir });
-      await provider.initVersionHistory({
-        projectDir,
-        authorName: options.author?.trim() || undefined,
-        initialMessage: "Created project"
-      });
-      versionHistory = "local-git";
-    } catch (e) {
-      versionHistory = "none";
-      const { findEnclosingRepoDir } = await import("./project-source-ekcyp63q.js");
-      const enclosingRepoDir = await findEnclosingRepoDir(projectDir);
-      versionHistoryError = enclosingRepoDir ? `This book was added to ${path17.basename(enclosingRepoDir)}'s shared version history; save a snapshot to record it.` : e instanceof Error ? e.message : String(e);
+      info2 = await stat6(abs);
+    } catch {
+      warnings.push(`Not found: ${abs}`);
+      return withWarnings({ ...base2, label: path18.basename(abs), carries: NO_CARRIES });
+    }
+    if (info2.isDirectory()) {
+      return withWarnings(await describeFolder(abs, base2, prettify(path18.basename(abs))));
     }
+    return withWarnings({
+      ...base2,
+      label: path18.basename(abs),
+      carries: { ...NO_CARRIES, markdown: true }
+    });
   }
-  const result = {
-    projectDir,
-    manifestPath,
-    openFile,
-    versionHistory
+  const base = {
+    ...common,
+    kind: "npm",
+    name: parsed.name,
+    ...parsed.version ? { version: parsed.version } : {}
   };
-  if (versionHistoryError !== undefined) {
-    result.versionHistoryError = versionHistoryError;
-  }
-  return result;
-}
-async function ensureGitignoreHasDist(projectDir) {
-  const gitignorePath = path17.join(projectDir, ".gitignore");
-  let existing = null;
-  try {
-    existing = await readFile27(gitignorePath, "utf8");
-  } catch {}
-  if (existing === null) {
-    await writeFile6(gitignorePath, `dist/
-`, "utf8");
-    return;
+  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 } });
   }
-  const alreadyIgnoresDist = existing.split(`
-`).some((line) => /^\/?dist\/?$/.test(line.trim()));
-  if (alreadyIgnoresDist)
-    return;
-  const needsLeadingNewline = existing.length > 0 && !existing.endsWith(`
-`);
-  await writeFile6(gitignorePath, existing + (needsLeadingNewline ? `
-` : "") + `dist/
-`, "utf8");
-}
-async function firstSourceFile(manifestPath) {
-  let text;
+  let installRoot = null;
   try {
-    text = await readFile27(manifestPath, "utf8");
-  } catch {
-    return;
-  }
-  const filesIdx = text.search(/^\s*files:\s*$/m);
-  if (filesIdx === -1)
-    return;
-  const rest = text.slice(filesIdx);
-  const m = rest.match(/^\s*-\s*"?([^"\n]+?)"?\s*$/m);
-  return m ? m[1].trim() : undefined;
-}
-async function fillTemplateFile(filePath, substitutions) {
-  let text = await readFile27(filePath, "utf8");
-  for (const [token, value] of Object.entries(substitutions)) {
-    text = text.split(token).join(value);
+    installRoot = await resolveVendoredPluginInstallRoot(projectDir, parsed.name, parsed.version);
+  } catch (error2) {
+    warnings.push(error2 instanceof Error ? error2.message : String(error2));
   }
-  await writeFile6(filePath, text, "utf8");
-}
-
-// src/lib/extension-scaffold.ts
-import { access as access2, mkdir as mkdir9, readFile as readFile28, writeFile as writeFile7 } from "node:fs/promises";
-import { constants as FS2 } from "node:fs";
-import path18 from "node:path";
-var EXTENSION_KINDS = ["plugin", "theme"];
-var RESERVED_PREFIX = "gp-";
-var TEMPLATE_FILES = {
-  plugin: [
-    ["package.json", "package.json"],
-    ["README.md", "README.md"],
-    ["plugin.js.tpl", "plugin.js"],
-    ["styles/plugin.css", "styles/plugin.css"],
-    ["snippets/term-box.md", "snippets/term-box.md"],
-    ["test/fixture.md", "test/fixture.md"],
-    ["test/expected.html", "test/expected.html"],
-    ["test/plugin.test.js.tpl", "test/plugin.test.js"]
-  ],
-  theme: [
-    ["package.json", "package.json"],
-    ["README.md", "README.md"],
-    ["components.yaml", "components.yaml"],
-    ["snippets/callout.md", "snippets/callout.md"],
-    ["styles/tokens.css", "styles/tokens.css"],
-    ["styles/base.css", "styles/base.css"],
-    ["styles/components.css", "styles/components.css"],
-    ["styles/page-templates.css", "styles/page-templates.css"],
-    ["styles/page-rules.css", "styles/page-rules.css"],
-    ["styles/book.css", "styles/book.css"]
-  ]
-};
-var OPEN_FILE = {
-  plugin: "plugin.js",
-  theme: "styles/tokens.css"
-};
-var DEFAULT_DESCRIPTION = {
-  plugin: "A Gutterpress plugin.",
-  theme: "A Gutterpress theme."
-};
-var DEFAULT_AUTHOR2 = "Anonymous";
-
-class ExtensionScaffoldError extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "CreateProjectError";
-    this.code = code;
+  if (!installRoot) {
+    warnings.push(`Not installed — run \`gutterpress ext add ${raw.use}\`.`);
+    return withWarnings({ ...base, label: parsed.name, carries: { ...NO_CARRIES, markdown: true } });
   }
-}
-function resolveExtensionPrefix(slug, requested) {
-  const raw = (requested ?? `${slug}-`).trim();
-  const prefix = raw.endsWith("-") ? raw : `${raw}-`;
-  if (!/^[a-z][a-z0-9-]*-$/.test(prefix)) {
-    throw new ExtensionScaffoldError("invalid-name", `"${raw}" is not a usable prefix. Use lower-case letters, digits and hyphens, ` + `starting with a letter — for example "${slug}-" or "fn-".`);
+  const pkgDir = vendoredNpmPluginPackageDir(installRoot, parsed.name);
+  if (!existsSync12(path18.join(pkgDir, EXTENSION_MANIFEST_FILENAME))) {
+    return withWarnings({ ...base, label: parsed.name, carries: { ...NO_CARRIES, markdown: true } });
   }
-  if (prefix === RESERVED_PREFIX) {
-    throw new ExtensionScaffoldError("invalid-name", `"${RESERVED_PREFIX}" is reserved for Gutterpress core's own classes and custom ` + `properties. Taking it would silently override them — choose your own prefix.`);
+  const described = await describeFolder(pkgDir, base, parsed.name, (name) => name);
+  return withWarnings({
+    ...described,
+    carries: { ...described.carries, markdown: true }
+  });
+}
+async function listProjectExtensions(projectDir) {
+  const { doc } = await loadManifestDoc(projectDir);
+  const seq = doc.get("extensions", true);
+  if (!isSeq3(seq))
+    return [];
+  const out = [];
+  for (const item of seq.items) {
+    const raw = rawEntry(item);
+    if (!raw)
+      continue;
+    out.push(await describeEntry(projectDir, raw));
   }
-  return prefix;
+  return out;
 }
-function identifierFor(slug) {
-  const camel = slug.replace(/-([a-z0-9])/g, (_m, c) => c.toUpperCase());
-  return /^[0-9]/.test(camel) ? `_${camel}` : camel;
+async function describeExtension(projectDir, use) {
+  return (await listProjectExtensions(projectDir)).find((e) => sameExtension(e.use, use)) ?? null;
 }
-function escapeJsonScalar(value) {
-  return JSON.stringify(value).slice(1, -1);
+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 scaffoldExtension(options) {
-  const kind = options.kind;
-  if (kind !== "plugin" && kind !== "theme") {
-    throw new ExtensionScaffoldError("invalid-name", `Unknown extension kind "${String(kind)}". Choose one of: ${EXTENSION_KINDS.join(", ")}.`);
-  }
-  const name = (options.name ?? "").trim();
-  if (!name) {
-    throw new ExtensionScaffoldError("invalid-name", "A name is required.");
-  }
-  const slug = (options.folderName ?? slugify(name)).trim();
-  if (!slug || slug !== slugify(slug)) {
-    throw new ExtensionScaffoldError("invalid-name", `Could not derive a valid folder name from "${name}".`);
-  }
-  const prefix = resolveExtensionPrefix(slug, options.prefix);
-  const parentDir = options.parentDir;
-  if (!parentDir || !path18.isAbsolute(parentDir)) {
-    throw new ExtensionScaffoldError("parent-not-writable", "The save location must be an absolute path.");
+async function setExtensionEnabled(projectDir, use, enabled) {
+  return withMutationLock(projectDir, async () => {
+    const { doc, file } = await loadManifestDoc(projectDir);
+    const seq = doc.get("extensions", true);
+    const idx = isSeq3(seq) ? indexOfUse(seq, use) : -1;
+    if (!isSeq3(seq) || idx < 0)
+      throw new Error(`Extension "${use}" is not in the manifest.`);
+    const item = seq.items[idx];
+    if (enabled) {
+      if (isMap2(item)) {
+        item.delete("enabled");
+        if (item.items.length === 1 && typeof item.get("use") === "string") {
+          seq.items[idx] = new Scalar(item.get("use"));
+        }
+      }
+    } else if (isMap2(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 removeExtension(projectDir, use) {
+  return withMutationLock(projectDir, async () => {
+    const { doc, file } = await loadManifestDoc(projectDir);
+    const seq = doc.get("extensions", true);
+    const idx = isSeq3(seq) ? indexOfUse(seq, use) : -1;
+    if (!isSeq3(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) {
+      await rm4(vendoredNpmPluginRoot(projectDir, parsed.name, parsed.version), {
+        recursive: true,
+        force: true
+      });
+      clearVendoredPluginResolver(projectDir, parsed.name, parsed.version);
+    }
+  });
+}
+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 (isMap2(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 access2(parentDir, FS2.W_OK);
+    await stat6(abs);
   } catch {
-    throw new ExtensionScaffoldError("parent-not-writable", `The chosen save location can't be written to: ${parentDir}`);
+    throw new Error(`Extension not found: ${abs}`);
   }
-  const extensionDir = path18.join(parentDir, slug);
-  let targetExists = true;
-  try {
-    await access2(extensionDir, FS2.F_OK);
-  } catch {
-    targetExists = false;
+  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 (path18.isAbsolute(input))
+    return addPathExtension(projectDir, input, exportName);
+  const parsed = parseExtensionSpecifier(input);
+  if (parsed.kind === "path") {
+    return addPathExtension(projectDir, path18.resolve(projectDir, parsed.path), exportName);
   }
-  if (targetExists) {
-    throw new ExtensionScaffoldError("target-exists", `A folder named "${slug}" already exists here. Choose a different name or location.`);
+  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 author = (options.author ?? "").trim() || DEFAULT_AUTHOR2;
-  const description = (options.description ?? "").trim() || DEFAULT_DESCRIPTION[kind];
-  const plain = {
-    "{{NAME}}": name,
-    "{{SLUG}}": slug,
-    "{{PREFIX}}": prefix,
-    "{{AUTHOR}}": author,
-    "{{DESCRIPTION}}": description,
-    "{{IDENT}}": identifierFor(slug)
-  };
-  const jsonSafe = Object.fromEntries(Object.entries(plain).map(([token, value]) => [token, escapeJsonScalar(value)]));
-  const entries = TEMPLATE_FILES[kind];
-  const written = [];
+  const existing = await describeExtension(projectDir, parsed.name);
+  const chosenExport = exportName ?? existing?.export;
+  const installed = await installNpmPlugin(projectDir, input, options);
+  const use = pinnedNpmSpecifier(installed.name, installed.version);
   try {
-    await mkdir9(extensionDir, { recursive: true });
-    for (const [assetName, relDest] of entries) {
-      const src = await getAssetPath(`extension-templates/${kind}/${assetName}`);
-      const dest = path18.join(extensionDir, relDest);
-      await mkdir9(path18.dirname(dest), { recursive: true });
-      const text = await readFile28(src, "utf8");
-      const table = relDest.endsWith(".json") ? jsonSafe : plain;
-      await writeFile7(dest, substitute(text, table), "utf8");
-      written.push(relDest);
+    await loadPlugin(extensionConfigFor({
+      use,
+      kind: "npm",
+      name: installed.name,
+      version: installed.version,
+      export: chosenExport
+    }), projectDir);
+    await options.__testFailBeforeManifestCommit?.();
+    await upsertEntry(projectDir, use, chosenExport);
+  } catch (cause) {
+    try {
+      await rollbackNpmPluginInstall(installed);
+      clearVendoredPluginResolver(projectDir, installed.name, installed.version);
+    } 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 });
     }
-  } catch (e) {
-    throw new ExtensionScaffoldError("scaffold-io", `Could not create the ${kind} files: ${e instanceof Error ? e.message : String(e)}`);
+    throw new Error(`Downloaded ${use}, but it is not a loadable markdown-it plugin: ` + `${cause instanceof Error ? cause.message : String(cause)}`, { cause });
   }
-  return {
-    extensionDir,
-    manifestPath: path18.join(extensionDir, "package.json"),
-    kind,
-    slug,
-    prefix,
-    openFile: path18.join(extensionDir, OPEN_FILE[kind]),
-    files: written
-  };
+  const warnings = [...installed.warnings];
+  await finalizeNpmPluginInstall(installed).catch((error2) => {
+    warnings.push(`The extension was installed, but an old backup could not be removed: ` + `${error2 instanceof Error ? error2.message : String(error2)}`);
+  });
+  const entry = await describeExtension(projectDir, use);
+  return warnings.length > 0 ? { ...entry, warnings: [...entry.warnings ?? [], ...warnings] } : entry;
 }
-function substitute(text, table) {
-  let out = text;
-  for (const [token, value] of Object.entries(table)) {
-    out = out.split(token).join(value);
+async function uniqueExtensionId(projectDir, base) {
+  const slug = slugify(base) || "extension";
+  let candidate = slug;
+  for (let n = 2;existsSync12(path18.join(projectDir, EXTENSIONS_DIR, candidate)); n++) {
+    candidate = `${slug}-${n}`;
   }
-  return out;
+  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 = path18.join(projectDir, EXTENSIONS_DIR, id);
+    if (!existsSync12(dest)) {
+      const src = path18.join(await getAssetsDir(), "themes", id);
+      await mkdir9(path18.dirname(dest), { recursive: true });
+      await cp3(src, dest, { recursive: true });
+    }
+    return addExtensionUnlocked(projectDir, `./${EXTENSIONS_DIR}/${id}`, {});
+  });
 }
-
-// src/lib/project-templates.ts
-import { isMap as isMap2, isScalar as isScalar2, isSeq as isSeq3, parseDocument as parseDocument2 } from "yaml";
-var BUILT_IN_TEMPLATE_IDS = [
-  "book",
-  "zine",
-  "technical"
-];
-var SKIP_ENTRIES = new Set([
-  ".git",
-  "node_modules",
-  "out",
-  "dist",
-  "build",
-  ".gutterpress",
-  ".DS_Store"
-]);
 
 // src/lib/extension-import.ts
 import { existsSync as existsSync13 } from "node:fs";
@@ -14242,4 +14263,4 @@ async function runLint(opts = {}) {
   }
   return { ok: true, riskyCount, containmentCount, filesLinted: linted };
 }
-export { isPathSpecifier, parseExtensionSpecifier, PRESET_IDS, PRESETS, TARGETS, TARGET_IDS, publishTargetFor, MANIFEST_FILENAMES, loadManifestWithPath, reportMissingTools, executeValidation, executeAndReport, splitOutPath, runBuild, openPath, startPreviewServer, BUILT_IN_STYLE_SET_IDS, listProjectExtensions, setExtensionEnabled, removeExtension, addExtension, addBuiltInStyleSet, scaffoldProject, EXTENSION_KINDS, scaffoldExtension, BUILT_IN_TEMPLATE_IDS, importExtensionFromFile, importExtensionFromUrl, searchNpmExtensions, publishCredentialKey, publishConnectionStatus, listPublishAccounts, connectGoogleDrive, listPublishProviders, publishProviderFor, resolvePublishFormat, runPublish, connectPublishProvider, disconnectPublishCredential, runLint };
+export { isPathSpecifier, parseExtensionSpecifier, PRESET_IDS, PRESETS, TARGETS, TARGET_IDS, publishTargetFor, MANIFEST_FILENAMES, loadManifestWithPath, reportMissingTools, executeValidation, executeAndReport, splitOutPath, runBuild, openPath, startPreviewServer, scaffoldProject, EXTENSION_KINDS, scaffoldExtension, BUILT_IN_TEMPLATE_IDS, BUILT_IN_STYLE_SET_IDS, listProjectExtensions, setExtensionEnabled, removeExtension, addExtension, addBuiltInStyleSet, importExtensionFromFile, importExtensionFromUrl, searchNpmExtensions, publishCredentialKey, publishConnectionStatus, listPublishAccounts, connectGoogleDrive, listPublishProviders, publishProviderFor, resolvePublishFormat, runPublish, connectPublishProvider, disconnectPublishCredential, runLint };