gutterpress 0.11.21 → 0.11.22-alpha.2

package/dist/index-r7jcsk6h.js

@@ -0,0 +1,200 @@
+// src/lib/plugin-vendor.ts
+import { lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { exports as resolveExports } from "resolve.exports";
+var PLUGINS_DIR = "plugins";
+var VENDORED_NPM_DIR = "npm";
+var NPM_SEGMENT = /^[a-z0-9][a-z0-9._~-]*$/;
+var EXACT_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+var WINDOWS_RESERVED = /^(con|prn|aux|nul|clock\$|conin\$|conout\$|com[1-9¹²³]|lpt[1-9¹²³])(?:\..*)?$/i;
+function isValidNpmPackageName(name) {
+  if (!name || name.length > 214 || name !== name.toLowerCase())
+    return false;
+  if (name.startsWith("@")) {
+    const parts = name.slice(1).split("/");
+    return parts.length === 2 && parts.every((part) => NPM_SEGMENT.test(part));
+  }
+  return !name.includes("/") && NPM_SEGMENT.test(name);
+}
+function parseNpmPluginSpec(input) {
+  const spec = input.trim();
+  if (!spec)
+    throw new Error("An npm package name is required.");
+  let name = spec;
+  let selector;
+  if (spec.startsWith("@")) {
+    const slash = spec.indexOf("/");
+    const versionAt = spec.lastIndexOf("@");
+    if (slash > 1 && versionAt > slash) {
+      name = spec.slice(0, versionAt);
+      selector = spec.slice(versionAt + 1);
+    }
+  } else {
+    const versionAt = spec.lastIndexOf("@");
+    if (versionAt > 0) {
+      name = spec.slice(0, versionAt);
+      selector = spec.slice(versionAt + 1);
+    }
+  }
+  if (!isValidNpmPackageName(name)) {
+    throw new Error(`"${name}" is not a valid npm package name. Use a name like ` + "markdown-it-highlightjs or @scope/markdown-it-plugin.");
+  }
+  if (selector !== undefined && !selector) {
+    throw new Error(`The package spec "${spec}" is missing a selector after @.`);
+  }
+  return selector === undefined ? { name } : { name, selector };
+}
+function isExactNpmVersion(version) {
+  return EXACT_VERSION.test(version);
+}
+function encodePathPart(value) {
+  return encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function vendoredNpmPluginRoot(projectDir, name, version) {
+  return path.join(projectDir, PLUGINS_DIR, VENDORED_NPM_DIR, encodePathPart(name), encodePathPart(version));
+}
+function vendoredNpmPluginPackageDir(installRoot, name) {
+  return path.join(installRoot, "node_modules", ...name.split("/"));
+}
+function toPosixPath(value) {
+  return value.split(path.sep).join("/");
+}
+function assertWindowsSafeRelativePath(relative) {
+  if (!relative || relative.includes("\\") || relative.startsWith("/") || /^[a-zA-Z]:/.test(relative)) {
+    throw new Error(`Unsafe package path: ${relative || "(empty)"}`);
+  }
+  const normalized = relative.normalize("NFKC");
+  const parts = normalized.split("/");
+  if (parts.some((part) => !part || part === "." || part === "..")) {
+    throw new Error(`Unsafe package path: ${relative}`);
+  }
+  for (const part of parts) {
+    if (part.length > 255 || /[\u0000-\u001f<>:"|?*]/.test(part) || part.endsWith(".") || part.endsWith(" ") || WINDOWS_RESERVED.test(part)) {
+      throw new Error(`Package path is invalid on Windows: ${relative}`);
+    }
+  }
+}
+function windowsPathKey(relative) {
+  return relative.normalize("NFKC").toLowerCase();
+}
+function isContained(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+async function readPackageJson(packageDir) {
+  const packageJsonPath = path.join(packageDir, "package.json");
+  const info = await lstat(packageJsonPath);
+  if (!info.isFile() || info.isSymbolicLink()) {
+    throw new Error(`Package metadata is not a regular file: ${packageJsonPath}`);
+  }
+  const parsed = object(JSON.parse(await readFile(packageJsonPath, "utf8")));
+  if (!parsed)
+    throw new Error(`Package metadata is not an object: ${packageJsonPath}`);
+  return parsed;
+}
+function packageResolutionTargets(manifest, subpath, condition) {
+  if (manifest.exports !== undefined) {
+    try {
+      const targets2 = resolveExports(manifest, subpath ? `./${subpath}` : ".", { require: condition === "require" }) ?? [];
+      return targets2.map((target) => ({ target, exact: true }));
+    } catch {
+      return [];
+    }
+  }
+  if (subpath)
+    return [{ target: subpath, exact: false }];
+  const targets = [
+    ...condition === "import" && typeof manifest.module === "string" ? [manifest.module] : [],
+    ...typeof manifest.main === "string" ? [manifest.main] : [],
+    "index.mjs",
+    "index.js",
+    "index.cjs"
+  ];
+  return [...new Set(targets)].map((target) => ({ target, exact: false }));
+}
+function safePackageTarget(target) {
+  if (!target || target.includes("\\") || target.includes("*") || target.includes("?") || target.includes("#")) {
+    return null;
+  }
+  const relative = target.startsWith("./") ? target.slice(2) : target;
+  if (!relative || path.isAbsolute(relative))
+    return null;
+  assertWindowsSafeRelativePath(relative);
+  if (relative.normalize("NFKC").split("/").some((part) => part.toLowerCase() === "node_modules")) {
+    return null;
+  }
+  return relative;
+}
+async function resolveEntryCandidate(packageDir, resolution) {
+  const relative = safePackageTarget(resolution.target);
+  if (!relative)
+    return null;
+  const base = path.resolve(packageDir, ...relative.split("/"));
+  if (!isContained(packageDir, base))
+    return null;
+  const candidates = resolution.exact ? [base] : [
+    base,
+    `${base}.mjs`,
+    `${base}.js`,
+    `${base}.cjs`,
+    `${base}.json`,
+    path.join(base, "index.mjs"),
+    path.join(base, "index.js"),
+    path.join(base, "index.cjs"),
+    path.join(base, "index.json")
+  ];
+  for (const candidate of candidates) {
+    try {
+      const info = await lstat(candidate);
+      if (!info.isFile() || info.isSymbolicLink())
+        continue;
+      const extension = path.extname(candidate);
+      if (extension && ![".js", ".mjs", ".cjs", ".json"].includes(extension))
+        continue;
+      const [realRoot, realCandidate] = await Promise.all([realpath(packageDir), realpath(candidate)]);
+      if (!isContained(realRoot, realCandidate))
+        continue;
+      return toPosixPath(path.relative(packageDir, realCandidate));
+    } catch {}
+  }
+  return null;
+}
+async function resolvePackageEntry(packageDir, packageJson) {
+  const manifest = packageJson ?? await readPackageJson(packageDir);
+  for (const condition of ["import", "require"]) {
+    for (const target of packageResolutionTargets(manifest, "", condition)) {
+      const resolved = await resolveEntryCandidate(packageDir, target);
+      if (resolved)
+        return resolved;
+    }
+  }
+  throw new Error("Package has no contained JavaScript entry point.");
+}
+async function resolveVendoredPluginInstallRoot(projectDir, expectedName, expectedVersion) {
+  const requestedProjectRoot = path.resolve(projectDir);
+  const requestedInstallRoot = vendoredNpmPluginRoot(requestedProjectRoot, expectedName, expectedVersion);
+  let installInfo;
+  try {
+    installInfo = await lstat(requestedInstallRoot);
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return null;
+    throw error;
+  }
+  if (!installInfo.isDirectory() || installInfo.isSymbolicLink()) {
+    throw new Error("Vendor install root is not a normal directory.");
+  }
+  const [realProjectRoot, installRoot] = await Promise.all([
+    realpath(requestedProjectRoot),
+    realpath(requestedInstallRoot)
+  ]);
+  if (!isContained(realProjectRoot, installRoot)) {
+    throw new Error("Vendor install root resolves outside the book folder.");
+  }
+  return installRoot;
+}
+
+export { PLUGINS_DIR, VENDORED_NPM_DIR, isValidNpmPackageName, parseNpmPluginSpec, isExactNpmVersion, vendoredNpmPluginRoot, vendoredNpmPluginPackageDir, toPosixPath, assertWindowsSafeRelativePath, windowsPathKey, packageResolutionTargets, safePackageTarget, resolvePackageEntry, resolveVendoredPluginInstallRoot };

package/dist/index.js

@@ -4,58 +4,42 @@ import {
   AUTO_SYNC_MAX_MINUTES,
   AUTO_SYNC_MIN_MINUTES,
   AUTO_SYNC_PUSH_INTERVAL_MINUTES,
-  BUILT_IN_STYLE_SET_IDS,
   BUILT_IN_TEMPLATE_IDS,
-  BUNDLED_EXTENSIONS,
-  DEFAULT_NPM_REGISTRY,
-  EXTENSIONS_DIR,
   EXTENSION_KINDS,
-  EXTENSION_MANIFEST_FILENAME,
   FileTokenStore,
   GDRIVE_HOST,
   GITHUB_HOST,
   GOOGLE_NOT_CONFIGURED_MESSAGE,
   GitHubAuthProvider,
   GoogleAuthProvider,
-  MANIFEST_FILENAMES,
   MAX_SEARCH_BYTES,
-  PRESETS,
-  PRESET_IDS,
   PublishSelectionsStore,
-  RECOMMENDED_EXTENSIONS,
   REPAIR_SNAPSHOT_MESSAGE,
   RESERVED_PREFIX,
   SEARCH_KEYWORDS,
   SNIPPETS_DIR,
   SYNC_SNAPSHOT_MESSAGE,
-  TARGETS,
-  TARGET_IDS,
-  addBuiltInStyleSet,
-  addExtension,
+  VERSION_CHANGES_SHOWN,
   adoptFolder,
-  assertExtensionContained,
   autoSnapshotDelayMs,
   autoSyncDelayMs,
   checkCss,
-  checkExtensionUpdates,
   checkRemoteUpdates,
   checkToolAvailability,
   cloneRepository,
+  compareVersionFile,
   connectGenericHost,
   connectGoogleDrive,
   connectPublishProvider,
   defaultConfigDir,
   deleteSnippet,
-  describeExtension,
+  describeVersions,
   diagnoseProjectRemote,
   disconnectPublishCredential,
-  ensureProjectGitignore,
   escapeYamlScalar,
   executeAndReport,
   executeValidation,
-  extensionCarries,
-  extensionEntry,
-  extensionStyleList,
+  exportVersionTree,
   extractUrlCredential,
   extractVariables,
   forgeKindForHost,
@@ -63,18 +47,15 @@ import {
   getCheckById,
   getChecks,
   getSystemDiagnostics,
-  hasProjectManifest,
   importExtensionFromFile,
   importExtensionFromUrl,
   importTemplateFromFolder,
   inspectImage,
-  isBundledExtension,
   isGitInternalPath,
-  isPathSpecifier,
   isSshRemoteUrl,
   isValidRepositoryName,
   knownForgeTokenUrl,
-  listBuiltInStyleSets,
+  listBookPublishProviders,
   listBuiltInTemplates,
   listCustomTemplates,
   listGitHubBranches,
@@ -82,49 +63,34 @@ import {
   listLocationVariants,
   listMarkerComponents,
   listMergedSnippets,
-  listNpmVersions,
-  listProjectExtensions,
+  listOnlineVersions,
   listProjectStyles,
   listPublishAccounts,
   listPublishProviders,
   listRepoBooks,
   listSnippets,
-  loadManifest,
-  loadManifestWithPath,
-  log,
-  npmRegistryUrl,
   openPath,
-  parseExtensionSpecifier,
   parseRemoteOrigin,
-  pathEscapesFolder,
   pkceChallengeFromVerifier,
   publishConnectionStatus,
   publishCredentialKey,
   publishProviderFor,
-  publishTargetFor,
-  readExtensionCss,
-  readExtensionMeta,
   readManifestFields,
   readPageSetup,
   readPublishSettings,
   refreshRemoteCopies,
-  removeExtension,
-  reorderExtensions,
   repairOnlineBackup,
   reportMissingTools,
   requireGoogleClientCredentials,
   resolveActiveStyles,
   resolveCheckSelectors,
-  resolveConfig,
-  resolveExtension,
   resolveExtensionPrefix,
   resolveGitHubClientId,
   resolveGoogleClientId,
   resolveGoogleClientSecret,
   resolvePublishFormat,
+  resolvePublishProvider,
   resolvePublishRequest,
-  restoreFailureMessage,
-  restorePinnedExtensions,
   revokeGoogleCredential,
   ruleRemoteUrls,
   ruleRiskyProps,
@@ -132,7 +98,6 @@ import {
   runBuild,
   runChecks,
   runPublish,
-  sameExtension,
   sanitizeCloneFolderName,
   saveProjectAsTemplate,
   saveSnippet,
@@ -141,7 +106,6 @@ import {
   scorchedEarth,
   searchNpmExtensions,
   setActiveStyles,
-  setExtensionEnabled,
   setManifestFields,
   setPageSetup,
   setPublishProviderConfig,
@@ -151,18 +115,66 @@ import {
   startPreviewServer,
   substituteVariables,
   syncProject,
-  testRemoteAccess,
+  testRemoteAccess
+} from "./index-3wcr69ba.js";
+import {
+  BUILT_IN_STYLE_SET_IDS,
+  BUNDLED_EXTENSIONS,
+  DEFAULT_NPM_REGISTRY,
+  EXTENSIONS_DIR,
+  MANIFEST_FILENAMES,
+  PRESETS,
+  PRESET_IDS,
+  RECOMMENDED_EXTENSIONS,
+  TARGETS,
+  TARGET_IDS,
+  addBuiltInStyleSet,
+  addExtension,
+  checkExtensionUpdates,
+  describeExtension,
+  ensureProjectGitignore,
+  hasProjectManifest,
+  isBundledExtension,
+  isPathSpecifier,
+  listBuiltInStyleSets,
+  listNpmVersions,
+  listProjectExtensions,
+  loadManifest,
+  loadManifestWithPath,
+  npmRegistryUrl,
+  parseExtensionSpecifier,
+  publishTargetFor,
+  readExtensionCss,
+  removeExtension,
+  reorderExtensions,
+  resolveConfig,
+  restoreFailureMessage,
+  restorePinnedExtensions,
+  sameExtension,
+  setExtensionEnabled,
   updateExtensions,
   validateProjectExtensions
-} from "./index-mr7zs8mv.js";
+} from "./index-ew7cyk7c.js";
+import {
+  EXTENSION_MANIFEST_FILENAME,
+  assertExtensionContained,
+  extensionCarries,
+  extensionEntry,
+  extensionStyleList,
+  log,
+  pathEscapesFolder,
+  readExtensionMeta,
+  resolveExtension
+} from "./index-kx03e4m4.js";
 import"./index-ht1bcqdd.js";
 import {
   BUILD_DIAGNOSTIC_CODES
-} from "./index-t7r8g75c.js";
+} from "./index-2d8j0enc.js";
+import"./index-apc8w9w8.js";
 import {
   BuildError
-} from "./index-mr72vt8n.js";
-import"./index-sth219v1.js";
+} from "./index-jsz0s3dy.js";
+import"./index-2ppw6q9v.js";
 import {
   DEFAULT_PRINT_OPTS,
   assertMilestone,
@@ -171,7 +183,6 @@ import {
 import {
   AUTO_SNAPSHOT_MESSAGE,
   HISTORY_PAGE_LIMIT,
-  PLUGINS_DIR,
   RESTORE_BACKUP_MESSAGE,
   SWITCH_BRANCH_SNAPSHOT_MESSAGE,
   countUnversionedChanges,
@@ -182,7 +193,10 @@ import {
   restoreVersionWithBackup,
   switchBranch,
   whenGitIdle
-} from "./index-qf7y4d85.js";
+} from "./index-93pqkvty.js";
+import {
+  PLUGINS_DIR
+} from "./index-r7jcsk6h.js";
 import {
   capabilitiesFor,
   detectProjectSource,
@@ -227,6 +241,7 @@ export {
   restorePinnedExtensions,
   restoreFailureMessage,
   resolvePublishRequest,
+  resolvePublishProvider,
   resolvePublishFormat,
   resolveLogger,
   resolveGoogleClientSecret,
@@ -271,6 +286,7 @@ export {
   listPublishAccounts,
   listProjectStyles,
   listProjectExtensions,
+  listOnlineVersions,
   listNpmVersions,
   listMergedSnippets,
   listMarkerComponents,
@@ -281,6 +297,7 @@ export {
   listCustomTemplates,
   listBuiltInTemplates,
   listBuiltInStyleSets,
+  listBookPublishProviders,
   knownForgeTokenUrl,
   isValidRepositoryName,
   isSshRemoteUrl,
@@ -304,6 +321,7 @@ export {
   extensionStyleList,
   extensionEntry,
   extensionCarries,
+  exportVersionTree,
   executeValidation,
   executeAndReport,
   escapeYamlScalar,
@@ -311,6 +329,7 @@ export {
   disconnectPublishCredential,
   diagnoseProjectRemote,
   detectProjectSource,
+  describeVersions,
   describeExtension,
   deleteSnippet,
   defaultConfigDir,
@@ -318,6 +337,7 @@ export {
   connectPublishProvider,
   connectGoogleDrive,
   connectGenericHost,
+  compareVersionFile,
   cloneRepository,
   checkToolAvailability,
   checkRemoteUpdates,
@@ -331,6 +351,7 @@ export {
   adoptFolder,
   addExtension,
   addBuiltInStyleSet,
+  VERSION_CHANGES_SHOWN,
   TARGET_IDS,
   TARGETS,
   SYNC_SNAPSHOT_MESSAGE,

package/dist/lib/extension-manifest.d.ts

@@ -70,6 +70,15 @@ export interface ExtensionMetadata {
      * does the merge.
      */
     snippets?: string;
+    /**
+     * `gutterpress.publish: true` — EXPERIMENTAL (#381): the package is a
+     * publishing plugin. Its entry (npm `main`/`exports`, or a folder's `main`)
+     * exports a named `publish` function and contributes NO markdown-it plugin,
+     * so the markdown loader skips it without importing it. A boolean, not a
+     * path: it lets core recognise a publisher from package.json alone, without
+     * executing its code. Anything other than literal `true` reads as absent.
+     */
+    publish?: boolean;
     /**
      * npm `engines.gutterpress` — the Gutterpress versions the extension works
      * with, as a semver range (e.g. `">=0.11.20-alpha.3"`). Checked when the
@@ -98,7 +107,8 @@ export declare function extensionStyleList(meta: ExtensionMetadata): string[];
  * The markdown-it entry of a FOLDER extension: an explicit
  * `gutterpress.markdown` when the package's `main` is not the plugin,
  * otherwise npm's own `main`. `undefined` for a folder that carries no
- * markdown behaviour at all (a look).
+ * markdown behaviour at all (a look, or a publishing plugin — whose `main` is
+ * its publish module, not a markdown-it plugin).
  */
 export declare function extensionEntry(meta: ExtensionMetadata): string | undefined;
 /** What an extension declares, by field — the desktop's one-list filter. */
@@ -107,8 +117,19 @@ export interface ExtensionCarries {
     styles: boolean;
     snippets: boolean;
     components: boolean;
+    /** A publishing plugin (experimental, #381). */
+    publish: boolean;
 }
 export declare function extensionCarries(meta: ExtensionMetadata): ExtensionCarries;
+/**
+ * A publishing plugin (experimental, #381) is a publisher and nothing else:
+ * its entry is never imported while a book renders, so a markdown entry,
+ * styles, components or snippets it also declared would either load (a
+ * folder) or be dropped without a word (a vendored copy). One rule, checked
+ * here, keeps both load paths and the publish path agreeing. Not a listing
+ * guard — `readExtensionMeta` stays tolerant.
+ */
+export declare function assertPublishOnly(meta: ExtensionMetadata, ref: string): void;
 /**
  * True when a declared relative path escapes its own folder (absolute, or a
  * `..` segment) — the traversal shape every containment check in this

package/dist/lib/markdown/assemble.d.ts

@@ -132,8 +132,9 @@ export interface AssembleBookHtmlOptions {
      * preset id and printer spec — written as `<meta name="gp-print-area">`
      * (engine/shared/print-area.ts) into EVERY assembled book, preview, build
      * and publish alike: the preview's print overlays judge the ink against it,
-     * and both engines place pinned art on its art-safe line. Metadata only:
-     * nothing renders from it but what reads it.
+     * and both engines place pinned art on its art-safe line. Metadata only,
+     * with one exception: its `width` x `height` is also the page size the book
+     * prints at when no stylesheet sets one — see {@link defaultPageSizeCss}.
      */
     printArea?: PrintAreaSource;
     plugins?: LoadedPlugin[];

package/dist/lib/markdown/plugins.d.ts

@@ -1,4 +1,5 @@
 import type { ResolvedExtensionConfig } from "../../schema/manifest.types";
+import type { PublishPluginFunction } from "../publish/types";
 import type { LoadedPlugin } from "./renderer";
 export type { GutterpressComponent, GutterpressComponentBlock, GutterpressComponentProblem, GutterpressMarkerDeclaration, GutterpressMarkerLabel, GutterpressMarkerTable, GutterpressPlugin, GutterpressPluginMetadata, GutterpressPluginExport, LoadedPlugin, } from "./renderer";
 export { applyPlugins, collectPluginCss, collectPluginStylePaths, collectPluginStyleGroups } from "./renderer";
@@ -7,6 +8,25 @@ import { type PluginStyleGroup } from "./renderer";
 /** Test-only: reset the path-plugin cache between test cases. */
 export declare function __resetPathPluginCacheForTests(): void;
 export declare function loadPlugin(config: ResolvedExtensionConfig, baseDir: string): Promise<LoadedPlugin>;
+/** Where a publishing plugin's package sits, as discovery found it. */
+export interface PublishPluginLocation {
+    /** The package folder: a `path:` folder, or the vendored copy's package dir. */
+    dir: string;
+    /** The vendored install root of an npm entry; `null` for a folder. */
+    installRoot: string | null;
+    /** The manifest spelling, for messages. */
+    ref: string;
+}
+/**
+ * EXPERIMENTAL (#381): import a publishing plugin's entry and return its
+ * named `publish` export. Only the publish path calls this — never a build or
+ * preview (see the skip in {@link loadPlugin}). The package is the one
+ * discovery located, so there is no second lookup and no fall-through to a
+ * same-named package elsewhere: a vendored copy loads through
+ * {@link importVendoredEntry}, a folder's `main` through the mtime cache, so
+ * the long-lived desktop host sees edits.
+ */
+export declare function loadPublishFunction({ dir, installRoot, ref }: PublishPluginLocation): Promise<PublishPluginFunction>;
 /**
  * Load all plugins from the resolved configuration.
  *

package/dist/lib/markdown/two-versions.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `two_versions` — renders a passage the converge merge left with TWO
+ * versions as two labelled boxes instead of broken markdown.
+ *
+ * After a sync that found a passage edited both here and online, the file
+ * holds both versions inside the marker family `two-versions-markers.ts`
+ * spells out. Those lines are valid markdown — `=======` is a setext
+ * underline, `>>>>>>>` seven nested blockquotes — so until this rule the
+ * preview showed the author's paragraph as a chapter-sized heading, listed
+ * `<<<<<<< your version` in the outline, and gave no way to read either
+ * version as it would print. The `source.sync.merge-markers` check still
+ * reports every block as an error, so a build never ships one; this rule
+ * only decides what the LIVE PREVIEW shows while the author chooses.
+ *
+ * The output is plain HTML + CSS: a `div.gp-two-versions` holding two
+ * `div.gp-version`s (`-yours`, `-online`), each labelled through
+ * `data-label` and each parsed as ordinary block markdown, so a heading or
+ * a list inside a version renders as one. No viewer or print code reads
+ * these classes; `TWO_VERSIONS_CSS` is the whole styling. Matching is as
+ * exact as the check's: the three fixed lines, at the start of a line, in
+ * order; anything else (a bare `=======`, a half-deleted family) is left
+ * to markdown as before.
+ */
+import type MarkdownIt from "markdown-it";
+/** The styling for the block above — injected by assemble.ts with MARKER_CSS. */
+export declare const TWO_VERSIONS_CSS = "\n.gp-two-versions {\n  margin: 1em 0;\n  border: 2px dashed #b7791f;\n  border-radius: 6px;\n  break-inside: avoid;\n}\n.gp-two-versions > .gp-version {\n  padding: 0.5em 0.9em;\n}\n.gp-two-versions > .gp-version + .gp-version {\n  border-top: 2px dashed #b7791f;\n}\n.gp-two-versions > .gp-version > .gp-version-text {\n  margin: 0;\n  white-space: pre-wrap;\n  overflow-wrap: anywhere;\n  font-size: 0.85em;\n}\n.gp-two-versions > .gp-version::before {\n  content: attr(data-label);\n  display: block;\n  margin-bottom: 0.35em;\n  font-family: system-ui, sans-serif;\n  font-size: 0.7em;\n  font-weight: 700;\n  letter-spacing: 0.06em;\n  text-transform: uppercase;\n  color: #b7791f;\n}\n";
+/**
+ * markdown-it plugin. Before `html_block` so the `<` opener is ours first;
+ * listed as a paragraph terminator so a block that starts right under a
+ * line of prose (as the merge writes it) still opens.
+ */
+export default function gpTwoVersions(md: MarkdownIt): void;

package/dist/lib/page-size.d.ts

@@ -1,5 +1,7 @@
 import type { Document } from "yaml";
 import { type PresetId } from "./presets.ts";
+import { formatPageSize, isPositivePoints } from "../engine/shared/print-area.ts";
+export { formatPageSize, isPositivePoints };
 /** Page bounds written to the manifest's `page:` block (points; 72pt = 1in). */
 export interface CustomPageOptions {
     /** Trim width in points (72pt = 1in). */
@@ -28,12 +30,11 @@ export interface PageSetup {
     bounds: (PageSizePoints & {
         tolerance: number;
     }) | null;
-    /** What the book's stylesheets print at, or null when no plain `@page` sets a size. */
+    /** What the book's stylesheets print at, or null when no plain `@page` sets a size (the book then prints at `bounds`). */
     css: (PageSizePoints & {
         file: string;
     }) | null;
 }
-export declare function isPositivePoints(value: unknown): value is number;
 /**
  * Write the manifest's `page:` bounds. `tolerance` defaults to whatever the
  * block already carries, so re-sizing a book never silently resets a
@@ -43,8 +44,6 @@ export declare function isPositivePoints(value: unknown): value is number;
 export declare function writePageBounds(doc: Document, page: CustomPageOptions): void;
 /** The size (points) a choice means: `custom` brings its own, the others are the preset's. */
 export declare function pageSizeForChoice(choice: PageSizeChoice): PageSizePoints;
-/** The `size` value written for a page: `8.5in 11in`, `595pt 842pt`. */
-export declare function formatPageSize(page: PageSizePoints): string;
 /** The size the LAST plain `@page { size }` in the stylesheet sets (cascade: last wins), or null. */
 export declare function readPageSizeFromCss(css: string): PageSizePoints | null;
 /**

package/dist/lib/pdf-inspect.d.ts

@@ -122,6 +122,18 @@ export interface ImageRef {
      */
     x: number;
     y: number;
+    /**
+     * The drawn rect in points, y up from the sheet's bottom: the unit square
+     * under the CTM as its axis-aligned bounds, so it holds for an image drawn
+     * flipped or rotated where `x`/`y`/`placedW`/`placedH` do not. The
+     * `pdf.print.safe-margins` check judges it against the art rule.
+     */
+    bounds: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
     /** 1-based page number. */
     page: number;
 }

package/dist/lib/project-scaffold.d.ts

@@ -64,9 +64,9 @@ export interface CreateProjectOptions {
     /**
      * Page geometry written into the generated manifest (points; 72pt = 1in).
      * REQUIRED when `preset` is `"custom"` (it has no built-in trim); allowed
-     * with any preset to override its trim. These are the validation bounds
-     * the built PDF is checked against — the actual trim comes from the
-     * stylesheet's `@page` rule, and the two should match.
+     * with any preset to override its trim. This is the size the book prints
+     * at, unless a stylesheet sets its own plain `@page { size }` (#415), and
+     * the size the built PDF is checked against — so the two should match.
      */
     customPage?: CustomPageOptions;
     /** Version-history mode for the new project. Defaults to `"local-git"`. */