gutterpress 0.10.9 → 0.10.10-alpha.2

package/dist/{index-zwcv1njy.js → index-5dgxeevv.js}

@@ -631,14 +631,11 @@ var manifest_default3 = "./manifest-n1gh3qw5.yaml";
 // src/assets/templates/technical/chapter-01.md
 var chapter_01_default3 = "./chapter-01-6fn9pvd0.md";
 
-// src/assets/extension-templates/plugin/gutterpress.json
-var gutterpress_default = "./gutterpress-m98e2w2d.json";
-
 // src/assets/extension-templates/plugin/package.json
-var package_default = "./package-rm9d2tht.json";
+var package_default = "./package-9rv69pxm.json";
 
 // src/assets/extension-templates/plugin/README.md
-var README_default = "./README-jntqyj1z.md";
+var README_default = "./README-3zk4tgnj.md";
 
 // src/assets/extension-templates/plugin/plugin.js.tpl
 var plugin_js_default = "./plugin.js-aszz0zgh.tpl";
@@ -656,22 +653,22 @@ var fixture_default = "./fixture-2qnyqgb5.md";
 var expected_default = "./expected-ycmacem8.html";
 
 // src/assets/extension-templates/plugin/test/plugin.test.js.tpl
-var plugin_test_js_default = "./plugin.test.js-npnfhyca.tpl";
+var plugin_test_js_default = "./plugin.test.js-k2r87k04.tpl";
 
-// src/assets/extension-templates/theme/gutterpress.json
-var gutterpress_default2 = "./gutterpress-x2ycdsb8.json";
+// src/assets/extension-templates/theme/package.json
+var package_default2 = "./package-aenwjew3.json";
 
 // src/assets/extension-templates/theme/README.md
-var README_default2 = "./README-6c7fda1s.md";
+var README_default2 = "./README-7x5akcns.md";
 
 // src/assets/extension-templates/theme/components.yaml
-var components_default = "./components-0mmswvvm.yaml";
+var components_default = "./components-dhgv2sm7.yaml";
 
 // src/assets/extension-templates/theme/snippets/callout.md
 var callout_default = "./callout-hv56m16h.md";
 
 // src/assets/extension-templates/theme/styles/tokens.css
-var tokens_default = "./tokens-e4xk3x4v.css";
+var tokens_default = "./tokens-2sracx1w.css";
 
 // src/assets/extension-templates/theme/styles/base.css
 var base_default = "./base-ypqh9n7f.css";
@@ -691,20 +688,20 @@ var book_default = "./book-ted3tzrp.css";
 // src/assets/themes/clean-book/theme.css
 var theme_default = "./theme-j2bagrfx.css";
 
-// src/assets/themes/clean-book/theme.json
-var theme_default2 = "./theme-vktedy8q.json";
+// src/assets/themes/clean-book/package.json
+var package_default3 = "./package-97gm31sg.json";
 
 // src/assets/themes/zine/theme.css
-var theme_default3 = "./theme-h5recz6c.css";
+var theme_default2 = "./theme-h5recz6c.css";
 
-// src/assets/themes/zine/theme.json
-var theme_default4 = "./theme-etj4gxck.json";
+// src/assets/themes/zine/package.json
+var package_default4 = "./package-gag6ykwn.json";
 
 // src/assets/themes/technical-doc/theme.css
-var theme_default5 = "./theme-nn6d53zy.css";
+var theme_default3 = "./theme-nn6d53zy.css";
 
-// src/assets/themes/technical-doc/theme.json
-var theme_default6 = "./theme-s2rg7xe7.json";
+// src/assets/themes/technical-doc/package.json
+var package_default5 = "./package-nrhkwf2m.json";
 
 // src/lib/embedded-assets.ts
 var __libdir = dirname(fileURLToPath(import.meta.url));
@@ -725,7 +722,6 @@ var EMBEDDED_ASSETS = {
   "templates/zine/chapter-01.md": abs(filePath(chapter_01_default2)),
   "templates/technical/manifest.yaml": abs(filePath(manifest_default3)),
   "templates/technical/chapter-01.md": abs(filePath(chapter_01_default3)),
-  "extension-templates/plugin/gutterpress.json": abs(filePath(gutterpress_default)),
   "extension-templates/plugin/package.json": abs(filePath(package_default)),
   "extension-templates/plugin/README.md": abs(filePath(README_default)),
   "extension-templates/plugin/plugin.js.tpl": abs(filePath(plugin_js_default)),
@@ -734,7 +730,7 @@ var EMBEDDED_ASSETS = {
   "extension-templates/plugin/test/fixture.md": abs(filePath(fixture_default)),
   "extension-templates/plugin/test/expected.html": abs(filePath(expected_default)),
   "extension-templates/plugin/test/plugin.test.js.tpl": abs(filePath(plugin_test_js_default)),
-  "extension-templates/theme/gutterpress.json": abs(filePath(gutterpress_default2)),
+  "extension-templates/theme/package.json": abs(filePath(package_default2)),
   "extension-templates/theme/README.md": abs(filePath(README_default2)),
   "extension-templates/theme/components.yaml": abs(filePath(components_default)),
   "extension-templates/theme/snippets/callout.md": abs(filePath(callout_default)),
@@ -745,11 +741,11 @@ var EMBEDDED_ASSETS = {
   "extension-templates/theme/styles/page-rules.css": abs(filePath(page_rules_default)),
   "extension-templates/theme/styles/book.css": abs(filePath(book_default)),
   "themes/clean-book/theme.css": abs(filePath(theme_default)),
-  "themes/clean-book/theme.json": abs(filePath(theme_default2)),
-  "themes/zine/theme.css": abs(filePath(theme_default3)),
-  "themes/zine/theme.json": abs(filePath(theme_default4)),
-  "themes/technical-doc/theme.css": abs(filePath(theme_default5)),
-  "themes/technical-doc/theme.json": abs(filePath(theme_default6))
+  "themes/clean-book/package.json": abs(filePath(package_default3)),
+  "themes/zine/theme.css": abs(filePath(theme_default2)),
+  "themes/zine/package.json": abs(filePath(package_default4)),
+  "themes/technical-doc/theme.css": abs(filePath(theme_default3)),
+  "themes/technical-doc/package.json": abs(filePath(package_default5))
 };
 var extractPromise = null;
 async function extractAssets() {

package/dist/{index-dhgzkhs7.js → index-a0e2253t.js}

@@ -4,7 +4,7 @@ import {
   launchChromium,
   marginBoxAlign,
   marginBoxRectPt
-} from "./index-zwcv1njy.js";
+} from "./index-5dgxeevv.js";
 
 // src/engine/compiler/build.ts
 import { readFile } from "node:fs/promises";

package/dist/{index-dtrftayr.js → index-y01v2fe0.js}

@@ -508,5 +508,131 @@ async function restoreVersionWithBackup(options) {
     return { restoredId: id, backupId };
   });
 }
+var SWITCH_BRANCH_SNAPSHOT_MESSAGE = "Saved before switching copy";
+async function listLocalBranches(dir) {
+  const source = await detectProjectSource(dir);
+  if (source.type !== "local-git-folder")
+    return null;
+  const repoDir = gitScopeFor(source);
+  const [local, current, remotes] = await Promise.all([
+    git.listBranches({ fs: gitFs, dir: repoDir }),
+    git.currentBranch({ fs: gitFs, dir: repoDir, fullname: false }).catch(() => {
+      return;
+    }),
+    git.listRemotes({ fs: gitFs, dir: repoDir }).catch(() => [])
+  ]);
+  const localNames = new Set(local);
+  const remoteOnly = new Set;
+  for (const { remote } of remotes) {
+    const names = await git.listBranches({ fs: gitFs, dir: repoDir, remote }).catch(() => []);
+    for (const name of names) {
+      if (name === "HEAD")
+        continue;
+      if (!localNames.has(name))
+        remoteOnly.add(name);
+    }
+  }
+  return {
+    current: current ?? null,
+    branches: [...localNames, ...remoteOnly].sort(),
+    remoteOnly: [...remoteOnly].sort()
+  };
+}
+async function resolveCopy(repoDir, branch) {
+  const local = await git.resolveRef({ fs: gitFs, dir: repoDir, ref: `refs/heads/${branch}` }).catch(() => {
+    return;
+  });
+  if (local)
+    return { oid: local };
+  const remotes = await git.listRemotes({ fs: gitFs, dir: repoDir }).catch(() => []);
+  for (const { remote } of remotes) {
+    const oid = await git.resolveRef({ fs: gitFs, dir: repoDir, ref: `refs/remotes/${remote}/${branch}` }).catch(() => {
+      return;
+    });
+    if (oid)
+      return { oid, remote };
+  }
+  throw new Error(`Couldn't find a copy named "${branch}" — it may have been renamed or deleted.`);
+}
+function isCheckoutConflictError(e) {
+  return e?.code === "CheckoutConflictError";
+}
+async function diffCommitPaths(dir, fromOid, toOid, cache) {
+  const changed = [];
+  await git.walk({
+    fs: gitFs,
+    dir,
+    cache,
+    trees: [git.TREE({ ref: fromOid }), git.TREE({ ref: toOid })],
+    map: async (filepath, [from, to]) => {
+      if (filepath === ".")
+        return;
+      const [fType, tType] = await Promise.all([
+        from ? from.type() : Promise.resolve(undefined),
+        to ? to.type() : Promise.resolve(undefined)
+      ]);
+      if (fType === "tree" || tType === "tree")
+        return;
+      if (!fType && !tType)
+        return;
+      if (!fType || !tType) {
+        changed.push(filepath);
+        return;
+      }
+      const [fOid, tOid] = await Promise.all([from.oid(), to.oid()]);
+      if (fOid !== tOid)
+        changed.push(filepath);
+    }
+  });
+  return changed;
+}
+async function switchBranch(options) {
+  const { projectDir, branch, authorName, authorEmail } = options;
+  const source = await detectProjectSource(projectDir);
+  if (source.type !== "local-git-folder") {
+    throw new Error("This project has no version history yet. Enable version history first.");
+  }
+  const repoDir = gitScopeFor(source);
+  return withRepoLock(repoDir, async () => {
+    const cache = {};
+    try {
+      await snapshotWorkingTreeUnlocked({
+        projectDir,
+        repoRoot: repoDir,
+        message: SWITCH_BRANCH_SNAPSHOT_MESSAGE,
+        authorName,
+        authorEmail,
+        cache
+      });
+    } catch (e) {
+      if (!isNoChangesError(e))
+        throw e;
+    }
+    const fromOid = await git.resolveRef({ fs: gitFs, dir: repoDir, ref: "HEAD" }).catch(() => {
+      return;
+    });
+    const { oid: toOid, remote } = await resolveCopy(repoDir, branch);
+    try {
+      await git.checkout({
+        fs: gitFs,
+        dir: repoDir,
+        cache,
+        ref: branch,
+        force: false,
+        ...remote ? { remote } : {}
+      });
+    } catch (e) {
+      if (isCheckoutConflictError(e)) {
+        throw new Error("Couldn't switch copies — some files changed on disk right as the switch " + "started. Try again.", { cause: e });
+      }
+      throw e;
+    }
+    const changedPaths = fromOid && fromOid !== toOid ? await diffCommitPaths(repoDir, fromOid, toOid, cache) : [];
+    return {
+      current: branch,
+      changedFiles: changedPaths.map((p) => path2.join(repoDir, p))
+    };
+  });
+}
 
-export { gitFs, resolveLogger, gitScopeFor, HISTORY_PAGE_LIMIT, withRepoLock, __repoLockQueueSizeForTests, resolveGitAuthor, listWorkdirChanges, stageChanges, hasPendingChanges, hasUncommittedChanges, snapshotWorkingTreeUnlocked, isNoChangesError, providerFor, gitDirFor, snapshotStagingMarkerPath, RESTORE_BACKUP_MESSAGE, AUTO_SNAPSHOT_MESSAGE, restoreVersionWithBackup };
+export { gitFs, resolveLogger, gitScopeFor, HISTORY_PAGE_LIMIT, withRepoLock, __repoLockQueueSizeForTests, resolveGitAuthor, listWorkdirChanges, stageChanges, hasPendingChanges, hasUncommittedChanges, snapshotWorkingTreeUnlocked, isNoChangesError, providerFor, gitDirFor, snapshotStagingMarkerPath, RESTORE_BACKUP_MESSAGE, AUTO_SNAPSHOT_MESSAGE, restoreVersionWithBackup, SWITCH_BRANCH_SNAPSHOT_MESSAGE, listLocalBranches, switchBranch };

package/dist/index.js

@@ -1,7 +1,5 @@
 import {
   AUTO_SNAPSHOT_DEFAULT_MINUTES,
-  AUTO_SNAPSHOT_MAX_MINUTES,
-  AUTO_SNAPSHOT_MIN_MINUTES,
   AUTO_SYNC_DEFAULT_MINUTES,
   AUTO_SYNC_MAX_MINUTES,
   AUTO_SYNC_MIN_MINUTES,
@@ -9,6 +7,7 @@ import {
   BUILT_IN_STYLE_SET_IDS,
   BUILT_IN_TEMPLATE_IDS,
   BUNDLED_EXTENSIONS,
+  DEFAULT_NPM_REGISTRY,
   EXTENSIONS_DIR,
   EXTENSION_KINDS,
   EXTENSION_MANIFEST_FILENAME,
@@ -18,14 +17,15 @@ import {
   GOOGLE_NOT_CONFIGURED_MESSAGE,
   GitHubAuthProvider,
   GoogleAuthProvider,
-  LEGACY_THEME_MANIFEST_FILENAME,
   MANIFEST_FILENAMES,
+  MAX_SEARCH_BYTES,
   PLUGINS_DIR,
   PRESETS,
   PRESET_IDS,
   PublishSelectionsStore,
   RECOMMENDED_EXTENSIONS,
   RESERVED_PREFIX,
+  SEARCH_KEYWORDS,
   SNIPPETS_DIR,
   SYNC_SNAPSHOT_MESSAGE,
   TARGETS,
@@ -51,8 +51,8 @@ import {
   executeAndReport,
   executeValidation,
   extensionCarries,
+  extensionEntry,
   extensionStyleList,
-  extensionStyleListWithDefault,
   extractUrlCredential,
   extractVariables,
   forgeKindForHost,
@@ -84,7 +84,9 @@ import {
   listSnippets,
   loadManifest,
   loadManifestWithPath,
+  loadPluginsWithCss,
   log,
+  npmRegistryUrl,
   openPath,
   parseExtensionSpecifier,
   parseRemoteOrigin,
@@ -115,12 +117,12 @@ import {
   resolvePublishFormat,
   resolvePublishRequest,
   revokeGoogleCredential,
+  rulePageContainment,
   ruleRemoteUrls,
   ruleRiskyProps,
   ruleSyntax,
   runBuild,
   runChecks,
-  runLint,
   runPublish,
   sameExtension,
   sanitizeCloneFolderName,
@@ -128,6 +130,7 @@ import {
   saveSnippet,
   scaffoldExtension,
   scaffoldProject,
+  searchNpmExtensions,
   setActiveStyles,
   setExtensionEnabled,
   setManifestFields,
@@ -139,24 +142,27 @@ import {
   syncProject,
   testRemoteAccess,
   validateProjectExtensions
-} from "./index-mey5vraz.js";
+} from "./index-1he93sjd.js";
 import {
   BUILD_DIAGNOSTIC_CODES
-} from "./index-dhgzkhs7.js";
+} from "./index-a0e2253t.js";
 import {
   BuildError,
   DEFAULT_PRINT_OPTS,
   readyProbeExpr
-} from "./index-zwcv1njy.js";
+} from "./index-5dgxeevv.js";
 import {
   AUTO_SNAPSHOT_MESSAGE,
   HISTORY_PAGE_LIMIT,
   RESTORE_BACKUP_MESSAGE,
+  SWITCH_BRANCH_SNAPSHOT_MESSAGE,
   isNoChangesError,
+  listLocalBranches,
   providerFor,
   resolveLogger,
-  restoreVersionWithBackup
-} from "./index-dtrftayr.js";
+  restoreVersionWithBackup,
+  switchBranch
+} from "./index-y01v2fe0.js";
 import {
   capabilitiesFor,
   detectProjectSource,
@@ -164,11 +170,88 @@ import {
   repoRootForSource,
   repoSubPath
 } from "./index-v5mp7a6q.js";
-import"./index-37x76zdn.js";
+import {
+  __require
+} from "./index-37x76zdn.js";
+// src/lib/lint-runner.ts
+import { resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+async function runLint(opts = {}) {
+  const { glob } = await import("glob");
+  const { manifest, manifestDir } = await loadManifestWithPath(opts.manifest, {
+    explicit: opts.manifest !== undefined
+  });
+  const resolved = resolveConfig({}, manifest);
+  let files;
+  if (opts.files) {
+    files = await glob([opts.files], { nodir: true, ignore: ["**/*.min.css"] });
+  } else {
+    const relStyles = await resolveActiveStyles(manifestDir, resolved.styles);
+    const projectFiles = relStyles.map((rel) => resolve(manifestDir, rel));
+    let pluginStylePaths = opts.pluginStylePaths;
+    if (pluginStylePaths === undefined) {
+      ({ pluginStylePaths } = await loadPluginsWithCss(resolved.extensions, manifestDir, (ref, err) => log.warn(`Skipping plugin "${ref}" for lint — ${err.message}`)));
+    }
+    files = [...projectFiles, ...pluginStylePaths].filter((f) => !f.endsWith(".min.css"));
+  }
+  if (files.length === 0) {
+    log.warn("No CSS files found to lint");
+    return { ok: true, riskyCount: 0, containmentCount: 0, filesLinted: 0 };
+  }
+  log.info(`Linting ${files.length} CSS file(s)`);
+  let errorCount = 0;
+  let riskyCount = 0;
+  let containmentCount = 0;
+  let linted = 0;
+  for (const file of files) {
+    let css;
+    try {
+      css = await readFile(file, "utf8");
+    } catch (err) {
+      log.error(`  ${file}`);
+      log.error(`    cannot read stylesheet: ${err instanceof Error ? err.message : String(err)}`);
+      errorCount++;
+      continue;
+    }
+    linted++;
+    const warnings = checkCss(css, file);
+    const errors = warnings.filter((w) => w.severity === "error");
+    const risky = warnings.filter((w) => w.rule === ruleRiskyProps);
+    const containment = warnings.filter((w) => w.rule === rulePageContainment);
+    riskyCount += risky.length;
+    containmentCount += containment.length;
+    if (errors.length > 0) {
+      log.error(`  ${file}`);
+      for (const w of errors) {
+        log.error(`    ${w.line}:${w.column}  ${w.message}  (${w.rule})`);
+      }
+      errorCount += errors.length;
+    }
+    const nonErrorWarnings = [...risky, ...containment].sort((a, b) => a.line - b.line);
+    if (nonErrorWarnings.length > 0) {
+      log.warn(`  ${file}`);
+      for (const w of nonErrorWarnings) {
+        log.warn(`    ${w.line}:${w.column}  ${w.message}  (${w.rule})`);
+      }
+    }
+  }
+  if (errorCount > 0) {
+    log.error("CSS lint errors found");
+    return { ok: false, riskyCount, containmentCount, filesLinted: linted };
+  }
+  const totalWarnings = riskyCount + containmentCount;
+  if (totalWarnings > 0) {
+    log.warn(`${totalWarnings} print-safety warning(s): ${riskyCount} risky effect(s), ${containmentCount} page-containment`);
+  } else {
+    log.success("CSS lint passed");
+  }
+  return { ok: true, riskyCount, containmentCount, filesLinted: linted };
+}
 export {
   validateProjectExtensions,
   testRemoteAccess,
   syncProject,
+  switchBranch,
   substituteVariables,
   startPreviewServer,
   splitOutPath,
@@ -177,6 +260,7 @@ export {
   setManifestFields,
   setExtensionEnabled,
   setActiveStyles,
+  searchNpmExtensions,
   scaffoldProject,
   scaffoldExtension,
   saveSnippet,
@@ -226,6 +310,7 @@ export {
   parseRemoteOrigin,
   parseExtensionSpecifier,
   openPath,
+  npmRegistryUrl,
   log,
   loadManifestWithPath,
   loadManifest,
@@ -236,6 +321,7 @@ export {
   listProjectStyles,
   listProjectExtensions,
   listMergedSnippets,
+  listLocalBranches,
   listGitHubRepositories,
   listGitHubBranches,
   listCustomTemplates,
@@ -260,8 +346,8 @@ export {
   findEnclosingRepoDir,
   extractVariables,
   extractUrlCredential,
-  extensionStyleListWithDefault,
   extensionStyleList,
+  extensionEntry,
   extensionCarries,
   executeValidation,
   executeAndReport,
@@ -288,7 +374,9 @@ export {
   TARGET_IDS,
   TARGETS,
   SYNC_SNAPSHOT_MESSAGE,
+  SWITCH_BRANCH_SNAPSHOT_MESSAGE,
   SNIPPETS_DIR,
+  SEARCH_KEYWORDS,
   RESTORE_BACKUP_MESSAGE,
   RESERVED_PREFIX,
   RECOMMENDED_EXTENSIONS,
@@ -296,8 +384,8 @@ export {
   PRESET_IDS,
   PRESETS,
   PLUGINS_DIR,
+  MAX_SEARCH_BYTES,
   MANIFEST_FILENAMES,
-  LEGACY_THEME_MANIFEST_FILENAME,
   HISTORY_PAGE_LIMIT,
   GoogleAuthProvider,
   GitHubAuthProvider,
@@ -309,6 +397,7 @@ export {
   EXTENSION_KINDS,
   EXTENSIONS_DIR,
   DEFAULT_PRINT_OPTS,
+  DEFAULT_NPM_REGISTRY,
   BuildError,
   BUNDLED_EXTENSIONS,
   BUILT_IN_TEMPLATE_IDS,
@@ -318,8 +407,6 @@ export {
   AUTO_SYNC_MIN_MINUTES,
   AUTO_SYNC_MAX_MINUTES,
   AUTO_SYNC_DEFAULT_MINUTES,
-  AUTO_SNAPSHOT_MIN_MINUTES,
   AUTO_SNAPSHOT_MESSAGE,
-  AUTO_SNAPSHOT_MAX_MINUTES,
   AUTO_SNAPSHOT_DEFAULT_MINUTES
 };

package/dist/lib/build-error.d.ts

@@ -9,11 +9,12 @@
  *                  failures (validate/preflight/audit findings, a build's
  *                  quality-gate rejection). The invocation itself was fine;
  *                  the content wasn't. Standalone `gutterpress lint` uses this
- *                  code for CSS lint failures too, but the `build` pipeline's
- *                  own CSS-lint gate is a documented historical exception
- *                  that exits 2 instead (see build-runner.ts's
- *                  runQualityGates) — not a bug, just an inconsistency kept
- *                  for back-compat.
+ *                  code for CSS lint failures too. `gutterpress build`'s CSS
+ *                  print-safety check (`source.stylelint`) now runs as one
+ *                  of pre-build validation's checks (#272 — one CSS gate,
+ *                  not two) and fails the build through this same code; the
+ *                  `build` pipeline's former separate CSS-lint gate, and its
+ *                  own exit code 2, are gone.
  *   2  USAGE     — the invocation itself was wrong: a bad flag, positional,
  *                  preset, or value. See {@link UsageError} in ./cli-args.ts.
  *   3  PIPELINE  — the build/render/export pipeline failed for a reason

package/dist/lib/build-preflight.d.ts

@@ -58,7 +58,17 @@ export declare function preflightBuildTools(format: BuildFormat, opts: {
  */
 export declare function verifyNativeChromiumMilestone(): Promise<void>;
 export interface Gates {
-    lint: boolean;
+    /**
+     * Disable the `source.stylelint` check (CSS print-safety: remote urls,
+     * risky print effects, page-containment) for this run, without touching
+     * `preValidate` itself (#272 — one CSS gate, not two: this used to be a
+     * whole second gate, `runLint`, that duplicated `source.stylelint`'s own
+     * `checkCss` pass one phase later). `true` when `--skip-lint` was passed or
+     * `config.lint.enabled === false`; consulted only when `preValidate` is
+     * also true — with `preValidate` off, no pre-build check (CSS included)
+     * runs at all, `--skip-lint` or not.
+     */
+    skipStylelint: boolean;
     preValidate: boolean;
     postValidate: boolean;
 }

package/dist/lib/build-runner.d.ts

@@ -20,6 +20,14 @@ export interface BuildRunnerOptions {
     iccPath?: string;
     manifestPath?: string;
     stripAnnotations?: boolean;
+    /**
+     * Skip the CSS print-safety check (#272 — one CSS gate, not two). This used
+     * to gate a separate `runLint` pass; it now disables just the
+     * `source.stylelint` check inside pre-build validation (see
+     * {@link computeGates}'s `skipStylelint`). Has no effect when
+     * `skipPreValidate` is also set — pre-build validation, CSS check
+     * included, does not run at all in that case.
+     */
     skipLint?: boolean;
     skipPreValidate?: boolean;
     skipPostValidate?: boolean;
@@ -54,10 +62,12 @@ export interface BuildRunnerOptions {
 export interface BuildRunnerResult {
     outDir: string;
     /**
-     * The published `book.html`, or `null` for a one-file delivery (`--out x.pdf`,
-     * a desktop export) where only the PDF is delivered and everything else is
-     * discarded with the work dir. Returning a work-dir path here would hand the
-     * caller a filename that is already deleted by the time they see it.
+     * The published `book.html`, or `null` when only the PDF is delivered and
+     * everything else is discarded with the work dir — a one-file delivery
+     * (`--out x.pdf`, a desktop export), or a `pdf`/`pdfx` build into a
+     * `--out <dir>` (#270, #271; see {@link PublishTarget}'s `directory` case).
+     * Returning a work-dir path here would hand the caller a filename that is
+     * already deleted by the time they see it.
      */
     htmlPath: string | null;
     pdfPath: string | null;
@@ -102,7 +112,15 @@ type PublishTarget =
     kind: "project";
     dir: string;
 }
-/** `--out <dir>`: the user's directory. Files are added; nothing is removed. */
+/**
+ * `--out <dir>`: the user's directory. Files are added; nothing is removed.
+ * An `html` build delivers its whole bundle (book.html + viewer, index.html,
+ * assets, fingerprint) here. A `pdf`/`pdfx` build delivers ONLY its own PDF
+ * — never book.html/index.html/assets — so building both formats into one
+ * shared directory (the documented `--out ./_site` sequence) cannot let the
+ * pdf build's staged, viewer-less, link-stripped `book.html` clobber the
+ * html build's published one (#270, #271).
+ */
  | {
     kind: "directory";
     dir: string;
@@ -161,10 +179,10 @@ export interface BuildContext {
     prevalidatedLayoutWarningKeys: Set<string>;
     /**
      * The build's ONE plugin load (#262). `null` until {@link loadBuildPlugins}
-     * runs; every stage that needs plugins (the lint gate and preValidate gate
-     * in {@link runQualityGates}, and {@link renderBook}) calls that function
-     * and gets the SAME resolved `{ plugins, pluginCss, pluginStylePaths }`
-     * back, whichever of them runs first.
+     * runs; every stage that needs plugins (the preValidate gate in
+     * {@link runQualityGates}, and {@link renderBook}) calls that function and
+     * gets the SAME resolved `{ plugins, pluginCss, pluginStylePaths }` back,
+     * whichever of them runs first.
      *
      * Before this, `runQualityGates`'s lint gate and `renderBook` each called
      * `loadPluginsWithCss` independently for the identical manifest. For an
@@ -192,13 +210,13 @@ export interface BuildContext {
 export declare function resolveBuildContext(opts: BuildRunnerOptions): Promise<BuildContext>;
 /**
  * Load every plugin the manifest configures, exactly once for the whole
- * build (#262). Memoized on `ctx.plugins`: the lint gate, the preValidate
- * gate (both in {@link runQualityGates}), and {@link renderBook} each call
- * this instead of `loadPluginsWithCss` directly, and only the first caller
- * does real work — the rest get the cached result back, however the gates
- * are configured and whichever stage happens to run first (a test calling
- * {@link renderBook} directly, without going through `runQualityGates`, gets
- * a fresh load here exactly as it would have before this existed).
+ * build (#262). Memoized on `ctx.plugins`: the preValidate gate (in
+ * {@link runQualityGates}) and {@link renderBook} each call this instead of
+ * `loadPluginsWithCss` directly, and only the first caller does real work —
+ * the other gets the cached result back, whichever stage happens to run
+ * first (a test calling {@link renderBook} directly, without going through
+ * `runQualityGates`, gets a fresh load here exactly as it would have before
+ * this existed).
  *
  * Fail-fast (no `onError`), matching `renderBook`'s pre-existing behavior:
  * a build/export must never silently omit author-configured formatting (see
@@ -241,6 +259,21 @@ export declare function renderBook(ctx: BuildContext): Promise<string>;
  * copy shipped in the binary. Throws BuildError(exitCode 2) if nothing resolves.
  */
 export declare function resolveIccProfile(icc: string, manifestDir: string, explicitIccPath: string | undefined): Promise<string>;
+/**
+ * Publish a completed work dir into a `--out <dir>` target: the pure copy
+ * decision behind {@link PublishTarget}'s `directory` case, pulled out of
+ * {@link publishBuild} so it is unit-testable without a full
+ * {@link BuildContext}.
+ *
+ * `html` delivers the whole bundle (book.html + viewer, index.html, assets,
+ * fingerprint) — files are added, never removed. `pdf`/`pdfx` delivers ONLY
+ * its own PDF: its staged `book.html` has no viewer script
+ * (`HtmlOutput.finish` never runs for these formats) and, since #263, no
+ * relative hrefs either, so copying the whole work dir would silently
+ * clobber an html build's published book.html/index.html/assets in the same
+ * `--out` directory (#270, #271).
+ */
+export declare function publishToDirectory(workDir: string, targetDir: string, format: BuildFormat, artifactName: string | null): Promise<void>;
 /**
  * Orchestrate a build: resolve the context, mkdir the output, preflight tools
  * (non-html), pre-warm the browser when this build will render in Chromium,