gutterpress 0.11.23-beta.1 → 0.11.23-beta.3

package/dist/index.js

@@ -6,6 +6,7 @@ import {
   AUTO_SYNC_PUSH_INTERVAL_MINUTES,
   BUILT_IN_TEMPLATE_IDS,
   EXTENSION_KINDS,
+  EXTENSION_KIND_ALIASES,
   FileTokenStore,
   GDRIVE_HOST,
   GITHUB_HOST,
@@ -42,6 +43,7 @@ import {
   executeAndReport,
   executeValidation,
   exportVersionTree,
+  extensionKindFor,
   extractUrlCredential,
   extractVariables,
   forgeKindForHost,
@@ -122,14 +124,16 @@ import {
   substituteVariables,
   syncProject,
   testRemoteAccess
-} from "./index-c6y0p7jy.js";
+} from "./index-z6vzj3s5.js";
 import {
+  BUILT_IN_LOOKS,
   DEFAULT_NPM_REGISTRY,
   MANIFEST_FILENAMES,
   PRESETS,
   PRESET_IDS,
   TARGETS,
   TARGET_IDS,
+  addBuiltInStyleSet,
   addExtension,
   checkExtensionUpdates,
   describeExtension,
@@ -152,9 +156,10 @@ import {
   setExtensionEnabled,
   updateExtensions,
   validateProjectExtensions
-} from "./index-rj5vrhz6.js";
+} from "./index-fntpr44x.js";
 import {
   BUNDLED_EXTENSIONS,
+  BUNDLED_EXTENSION_DETAILS,
   EXTENSION_MANIFEST_FILENAME,
   assertExtensionContained,
   bundledExtension,
@@ -169,12 +174,12 @@ import {
   pathEscapesFolder,
   readExtensionMeta,
   resolveExtension
-} from "./index-a4j3xcfp.js";
+} from "./index-67g8f7r4.js";
 import"./index-ht1bcqdd.js";
 import {
   BUILD_DIAGNOSTIC_CODES
-} from "./index-fk2kpf2t.js";
-import"./index-798jt0qc.js";
+} from "./index-santcs4q.js";
+import"./index-d9w3r89w.js";
 import {
   BuildError
 } from "./index-tayzfr9c.js";
@@ -199,10 +204,11 @@ import {
   revisionNameFrom,
   switchBranch,
   whenGitIdle
-} from "./index-cw03e9p4.js";
+} from "./index-kw4tbthz.js";
 import {
-  EXTENSIONS_DIR
-} from "./index-5x42amh8.js";
+  EXTENSIONS_DIR,
+  PLUGINS_DIR
+} from "./index-g3te5ey1.js";
 import {
   capabilitiesFor,
   detectProjectSource,
@@ -327,7 +333,22 @@ function insertDeclaration(root, name, value) {
   root.raws.after = `
 `;
 }
+function assertDeclarationValue(name, value) {
+  let single = false;
+  try {
+    const nodes = postcss.parse(`:root{${name}:${value}}`).nodes;
+    const rule = nodes[0];
+    single = nodes.length === 1 && rule?.type === "rule" && rule.nodes.length === 1 && rule.nodes[0].type === "decl";
+  } catch {
+    single = false;
+  }
+  if (!single)
+    throw new Error(`"${value}" can't be saved as ${name}: it is not one CSS value.`);
+}
 function applyTokenUpdates(sheets, target, updates) {
+  for (const { name, value } of updates)
+    if (value !== null)
+      assertDeclarationValue(name, value);
   const roots = sheets.map((css) => postcss.parse(css));
   const changed = new Set;
   for (const { name, value } of updates) {
@@ -550,6 +571,7 @@ export {
   extractVariables,
   extractUrlCredential,
   extensionStyleList,
+  extensionKindFor,
   extensionEntry,
   extensionCarries,
   exportVersionTree,
@@ -585,6 +607,7 @@ export {
   assertExtensionContained,
   adoptFolder,
   addExtension,
+  addBuiltInStyleSet,
   VERSION_CHANGES_SHOWN,
   TARGET_IDS,
   TARGETS,
@@ -598,6 +621,7 @@ export {
   PublishSelectionsStore,
   PRESET_IDS,
   PRESETS,
+  PLUGINS_DIR,
   MAX_SEARCH_BYTES,
   MANIFEST_FILENAMES,
   HISTORY_PAGE_LIMIT,
@@ -608,13 +632,16 @@ export {
   GDRIVE_HOST,
   FileTokenStore,
   EXTENSION_MANIFEST_FILENAME,
+  EXTENSION_KIND_ALIASES,
   EXTENSION_KINDS,
   EXTENSIONS_DIR,
   DEFAULT_PRINT_OPTS,
   DEFAULT_NPM_REGISTRY,
   BuildError,
+  BUNDLED_EXTENSION_DETAILS,
   BUNDLED_EXTENSIONS,
   BUILT_IN_TEMPLATE_IDS,
+  BUILT_IN_LOOKS,
   BUILD_DIAGNOSTIC_CODES,
   AUTO_SYNC_PUSH_INTERVAL_MINUTES,
   AUTO_SYNC_MIN_MINUTES,

package/dist/lib/check-options.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The options a check takes in its `checks:` entry (#443, #483): the numbers
+ * and the list it measures against. The preset and the publish target set
+ * them; a book overrides one in the same entry that sets the check's level.
+ *
+ *   checks:
+ *     pdf.print.ink-coverage: { maxTac: 300 }
+ *     pdf.print.image-resolution: { level: error, minImageResolution: 200 }
+ *
+ * Each option lands at ONE place in the resolved config, `at`, which is what
+ * the check reads (and, for `maxTac`, what the PDF/X conversion holds the ink
+ * to). `at` is also how a 0.11.22 manifest spelled the option
+ * (`ink.maxTac`, `validate.pdf.minImageResolution`, `page.tolerance`), so
+ * manifest-old-spellings.ts translates the old keys from this same table.
+ *
+ * No filesystem or check-registry imports: manifest.ts resolves with it, and
+ * the Book setup writers use {@link setCheckOption}.
+ */
+import { type Document } from "yaml";
+import type { CheckLevelInput, ResolvedConfig } from "../schema/manifest.types";
+/** What an option's value is: points/bytes/DPI/a count, a `{ min, max }` range, or a list of file patterns. */
+type OptionKind = "number" | "range" | "patterns";
+interface CheckOption {
+    /** Where the value lands in the resolved config, and the 0.11.22 manifest spelling. */
+    at: string;
+    kind: OptionKind;
+}
+/** Check id -> option name -> where it lands. */
+export declare const CHECK_OPTIONS: Readonly<Record<string, Readonly<Record<string, CheckOption>>>>;
+/** The check id and option name a 0.11.22 spelling (`ink.maxTac`) moved to, if it is one. */
+export declare function optionForOldSpelling(at: string): {
+    id: string;
+    option: string;
+} | undefined;
+/** A `checks:` level as a manifest may write it: `off`, `on`, `info`, `warn` (`warning`), `error`, or a boolean. */
+export declare function isCheckLevelInput(value: unknown): value is CheckLevelInput;
+/**
+ * A 0.11.22 threshold (`validate.heuristics.maxDecorativeLayers`) read as
+ * the option it became, or undefined when the key was never a threshold.
+ * 0.11.22 passed any value through, and a check given one it could not use
+ * measured nothing, so a value the option cannot take is NOT an error here:
+ * `mustBe` says what it should have been and the caller reports it and
+ * ignores it, and a book that built in 0.11.22 still builds. A range keeps
+ * whichever of `min` and `max` are numbers, as 0.11.22's merge did.
+ */
+export declare function readOldThreshold(at: string, value: unknown): {
+    id: string;
+    option: string;
+    value?: unknown;
+    mustBe?: string;
+} | undefined;
+/**
+ * Read the options of one `checks:` entry (every key but `level`). A key the
+ * check does not take is a usage error naming the ones it does, so a typo
+ * never silently keeps the preset's number. A `null` value is left unset.
+ */
+export declare function readCheckOptions(id: string, entry: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Write read options into a resolved config, over the preset's and the
+ * target's values. A range merges key by key, so `{ max: 4000 }` keeps the
+ * preset's `min`; a list replaces the preset's whole.
+ */
+export declare function applyCheckOptions(config: ResolvedConfig, options: Record<string, Record<string, unknown>>): void;
+/**
+ * Set one option in a manifest Document, keeping the entry's level: a bare
+ * level (`warn`) becomes `{ level: warn, <option>: value }`. Used where Book
+ * setup and `gutterpress new` write a check's option.
+ */
+export declare function setCheckOption(doc: Document, id: string, option: string, value: unknown): void;
+export {};

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

@@ -4,7 +4,7 @@ import type { ResolvedExtensionConfig } from "../schema/manifest.types.ts";
 /** The folder (relative to the project root) a book's extensions live under:
  *  vendored npm copies in `extensions/npm/`, zip and URL imports beside them
  *  (extension-import.ts). Path entries elsewhere are never moved. */
-export { EXTENSIONS_DIR } from "./plugin-vendor.ts";
+export { EXTENSIONS_DIR, PLUGINS_DIR } from "./plugin-vendor.ts";
 /** How an `extensions:` entry resolves — the form of its specifier decides. */
 export type ExtensionSourceKind = "bundled" | "path" | "npm";
 /** One configured extension, as surfaced to the CLI and the desktop. */
@@ -194,6 +194,21 @@ export interface BundledExtensionInfo {
 }
 /** The bundled extensions, in table order. */
 export declare function listBundledExtensions(): BundledExtensionInfo[];
+/** The built-in looks' names (the bundled extensions that carry a stylesheet), in table order. */
+export declare const BUILT_IN_LOOKS: readonly string[];
+/**
+ * Make an editable copy of a built-in look (0.11.22's, restored in #482): its
+ * stylesheet and a package.json land in `extensions/<id>/`, the author's own
+ * files from then on, and the book lists the copy as `./extensions/<id>` — a
+ * plain path extension, loaded and built like any folder the author owns.
+ *
+ * A book that lists the built-in by name gets the copy in that entry's place
+ * (on or off as it was), so the look is not listed twice and the cascade
+ * order holds; otherwise the copy is added at the end. Idempotent: a folder
+ * already there is kept as it is — the author's edits survive — and only
+ * (re-)referenced.
+ */
+export declare function addBuiltInStyleSet(projectDir: string, id: string): Promise<ProjectExtensionEntry>;
 /** A folder name under `extensions/` not yet taken: `<slug>`, `<slug>-2`, … */
 export declare function uniqueExtensionId(projectDir: string, base: string): Promise<string>;
 /**

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

@@ -2,6 +2,19 @@
 export type ExtensionKind = "plugin" | "look";
 /** The kinds `--kind` accepts, for CLI help text and pickers. */
 export declare const EXTENSION_KINDS: readonly ["plugin", "look"];
+/**
+ * Older names for a kind, read wherever a kind is given (`scaffoldExtension`,
+ * `gutterpress new --kind`) and never offered: 0.11.22 called a look a
+ * `theme` (#483). Kept apart from {@link EXTENSION_KINDS} so help text and
+ * pickers keep showing one word per kind.
+ */
+export declare const EXTENSION_KIND_ALIASES: {
+    readonly theme: "look";
+};
+/** An older name {@link EXTENSION_KIND_ALIASES} reads. */
+export type ExtensionKindAlias = keyof typeof EXTENSION_KIND_ALIASES;
+/** The kind a word names — a kind, or an older name for one — or undefined. */
+export declare function extensionKindFor(word: string): ExtensionKind | undefined;
 /**
  * The class/property prefix a scaffolded extension is FORBIDDEN to take.
  * `gp-` is Gutterpress core's own vocabulary (CLAUDE.md §6); an extension
@@ -13,8 +26,8 @@ export declare const RESERVED_PREFIX = "gp-";
 export interface ScaffoldExtensionOptions {
     /** Human-friendly package name, e.g. "Field Notes". Required. */
     name: string;
-    /** Which starter to create. Required. */
-    kind: ExtensionKind;
+    /** Which starter to create. Required. `theme` (0.11.22's word) makes a look. */
+    kind: ExtensionKind | ExtensionKindAlias;
     /** Absolute path to the PARENT directory the folder is created in. */
     parentDir: string;
     /** Folder name under `parentDir`. Defaults to a slug of `name`. */

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

@@ -20,7 +20,14 @@ export interface BundledExtension {
     /** A look's stylesheet. Absent for a markdown feature. */
     css?: string;
 }
-export declare const BUNDLED_EXTENSIONS: readonly BundledExtension[];
+export declare const BUNDLED_EXTENSION_DETAILS: readonly BundledExtension[];
+/**
+ * The bundled names, in table order: the shape this export had in 0.11.22,
+ * so `BUNDLED_EXTENSIONS.includes(name)` still answers "is this bundled?".
+ * Each one's label, description and stylesheet are in
+ * {@link BUNDLED_EXTENSION_DETAILS}.
+ */
+export declare const BUNDLED_EXTENSIONS: readonly string[];
 export declare function bundledExtension(name: string): BundledExtension | undefined;
 export declare function isBundledExtension(name: string): boolean;
 /** `./x`, `../x`, `/x`, or a Windows drive path (`C:\x`). Nothing else is a path. */

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

@@ -17,7 +17,9 @@ export interface ProjectConfigFields {
  * Only the keys present in `updates` are written; everything else is left
  * untouched (so unrelated comments + sections survive). `sourceFiles: null`
  * deletes the `chapters` entry (back to "all chapter files"). Either way an
- * older book's `source.files` is taken out, so the list has one spelling.
+ * older book's `source.files` is taken out, so the list has one spelling, and
+ * the thresholds it spells the 0.11.22 way are written as their checks'
+ * options (`rewriteOldThresholds`).
  */
 export declare function setManifestFields(projectDir: string, updates: ProjectConfigFields): Promise<ProjectConfigFields>;
 /**

package/dist/lib/manifest-old-spellings.d.ts

@@ -2,8 +2,10 @@
  * The manifest spellings 0.11.23 replaced, read for this release only so a
  * book written for 0.11.22 still builds. Every old key found is translated
  * to its new spelling (or dropped, when nothing replaces it) and named in ONE
- * notice. Delete this module, and its call in `loadManifestWithPath`, in the
- * release after 0.11.23.
+ * notice. Book setup writes the new spelling of a threshold when it saves
+ * (`rewriteOldThresholds`). Delete this module, its call in
+ * `loadManifestWithPath` and the two calls of `rewriteOldThresholds`
+ * (manifest-config.ts, page-size.ts) in the release after 0.11.23.
  *
  *   source.files                     -> chapters
  *   validate.checks, lint.rules      -> checks (off | on | info | warn | error)
@@ -14,17 +16,27 @@
  *   validate.pdf.requireBookmarks,
  *   validate.pdf.requireTocLinks,
  *   validate.pdf.requireBleed,
- *   validate.pdf.forbidTransparency  -> the matching check, on or off
+ *   validate.pdf.forbidTransparency  -> the matching check, on or off; a level
+ *                                       the same book set for it is kept
+ *   ink.*, page.tolerance and the
+ *   validate.assets / pdf /
+ *   heuristics thresholds            -> an option of their check:
+ *                                       checks: { <id>: { <option>: value } }
+ *                                       (lib/check-options.ts)
  *   validate.source.<tool>: <path>   -> dropped: the config file is found by
  *                                       its usual name in the book's folder
  *                                       or a folder above it
- *   ink.*, page.tolerance,
- *   validate thresholds,
- *   validate.enabled, lint.configPath,
- *   and the keys
- *   0.11.22 already ignored           -> dropped: the preset and the publish
- *                                       target set the thresholds
+ *   validate.enabled, lint.configPath
+ *   and the keys 0.11.22 already
+ *   ignored                          -> dropped
+ *
+ * Nothing read from an old spelling can stop a book from building: 0.11.22
+ * passed any value through, so a threshold, a severity or a rule level it
+ * could not have used (`maxDecorativeLayers: many`, `severity: critical`) is
+ * named in the notice and ignored. The new spelling, written directly, is
+ * checked strictly (`resolveConfig`).
  */
+import { type Document } from "yaml";
 import type { CheckLevelInput, GutterpressManifest } from "../schema/manifest.types";
 type OldCheckEntry = boolean | {
     enabled?: boolean;
@@ -61,4 +73,15 @@ export interface OldSpellings {
  * removed before 0.11.23 with an actionable error.
  */
 export declare function readOldSpellings(raw: GutterpressManifest & OldSpellings): GutterpressManifest;
+/**
+ * Book setup's save: move every 0.11.22 threshold key in a manifest Document
+ * (`ink.maxTac`, `validate.pdf.minImageResolution`, `page.tolerance`, …) to
+ * its check's option, the way `setManifestFields` moves `source.files` to
+ * `chapters`. An option the new spelling already sets keeps its value; a
+ * block left empty goes. A value the option cannot take stays where it is,
+ * as written: moved, the new spelling's strict check would stop the book
+ * from building, and left, it is named and ignored at load. Every other key
+ * stays as written.
+ */
+export declare function rewriteOldThresholds(doc: Document): void;
 export {};

package/dist/lib/markdown/gutterpress-css.d.ts

@@ -151,7 +151,7 @@
  * carrying gp-left could start shifting; that is standards-tracking per
  * CLAUDE.md ("Chrome wins once it ships"), not a bug in the author's book.
  */
-export declare const GUTTERPRESS_CSS = "\n/* gp-* author image/block vocabulary. One vocabulary, gp-* only \u2014 the\n   pre-vocabulary utility names (.center/.float-left/.float-right/\n   .full-width/.full-bleed) were REMOVED when gp-* shipped; books rename\n   the classes in their markdown (see the migration note). Source ORDER is\n   the contract \u2014 see the doctrine comment above. */\n\n/* flow positions */\n.gp-left {\n  float: left;\n  margin: 0 var(--gp-gap, 1em) var(--gp-gap, 1em) 0;\n  max-width: 50%;\n}\n.gp-right {\n  float: right;\n  margin: 0 0 var(--gp-gap, 1em) var(--gp-gap, 1em);\n  max-width: 50%;\n}\n.gp-center {\n  display: block;\n  float: none;\n  margin-left: auto;\n  margin-right: auto;\n  max-width: 100%;\n}\n.gp-full {\n  display: block;\n  float: none;\n  width: 100%;\n  max-width: 100%;\n}\n@page gp-full-bleed { margin-left: 0; margin-right: 0; }\n.gp-bleed {\n  display: block;\n  float: none;\n  break-before: page;\n  page: gp-full-bleed;\n  max-width: none;\n  width: 100%;\n  margin-left: 0;\n  margin-right: 0;\n}\n\n/* sizes \u2014 AFTER the flow positions so max-width:100% lifts the floats' 50%\n   cap at equal specificity */\n.gp-size-10 { width: 10%; max-width: 100%; }\n.gp-size-20 { width: 20%; max-width: 100%; }\n.gp-size-30 { width: 30%; max-width: 100%; }\n.gp-size-40 { width: 40%; max-width: 100%; }\n.gp-size-50 { width: 50%; max-width: 100%; }\n.gp-size-60 { width: 60%; max-width: 100%; }\n.gp-size-70 { width: 70%; max-width: 100%; }\n.gp-size-80 { width: 80%; max-width: 100%; }\n.gp-size-90 { width: 90%; max-width: 100%; }\n\n/* float clearance presets \u2014 consumed by var(--gp-gap) in the float rules\n   above and by .gp-shape's shape-margin below; --gp-gap itself is\n   author-settable CSS */\n.gp-tight { --gp-gap: 0.5em; }\n.gp-loose { --gp-gap: 2em; }\n\n/* column runs \u2014 plain CSS Multi-column, emitted by the core @columns marker\n   (markers.js): @columns [1-5] ... @end-columns is the ONE way to lay\n   content out in columns, and @column-break moves to the next column.\n   The classes below are the CSS that marker emits, not author vocabulary.\n\n   Permanent vocabulary, not a shim: Chromium implements multicol natively\n   and these rules are the standard properties verbatim, so there is no\n   spec gap here to remove later. Deliberately minimal \u2014 column-fill is\n   NOT set (the CSS initial balance applies).\n   Themes style a run through two tokens instead of writing column rules:\n     --gp-column-gap   default 1.5em\n     --gp-column-rule  default none (any column-rule shorthand value)\n   Both hooks sit at zero specificity (:where), so any author rule wins.\n   .gp-columns is two columns on its own; a count class (bare @columns\n   emits gp-columns-2) wins because it comes later at the same specificity. */\n:where(.gp-columns, .gp-columns-1, .gp-columns-2, .gp-columns-3, .gp-columns-4, .gp-columns-5) {\n  column-gap: var(--gp-column-gap, 1.5em);\n  column-rule: var(--gp-column-rule, none);\n}\n.gp-columns { columns: 2; }\n.gp-columns-1 { columns: 1; }\n.gp-columns-2 { columns: 2; }\n.gp-columns-3 { columns: 3; }\n.gp-columns-4 { columns: 4; }\n.gp-columns-5 { columns: 5; }\n\n/* fragmentation controls \u2014 generic pagination utilities for any element,\n   independent of the column vocabulary above (a book reached for\n   these just as often outside a multicol run: keeping a card whole,\n   forcing a section to start a fresh page). Standard properties only \u2014\n   this project is Chromium-only (CLAUDE.md), so there are no legacy\n   page-break-* twins to also emit. One name each. */\n.gp-no-break { break-inside: avoid; }\n.gp-break-before { break-before: page; }\n\n/* shape wrap \u2014 text follows the image's alpha silhouette instead of its\n   rectangular box. shape-outside only applies to floats, so this is inert\n   without .gp-left/.gp-right (and under .gp-pin, which un-floats). The\n   shape URL cannot be written in CSS (url() contexts can't read attr()),\n   so the image renderer rule (images.ts) mirrors the src into an inline\n   --gp-shape:url(...) custom property whenever it sees this class --\n   authors only ever type the class. threshold 0.2 ignores near-transparent\n   anti-aliasing halos; shape-margin shares the float-gap vocabulary. */\nimg.gp-shape {\n  shape-outside: var(--gp-shape);\n  shape-image-threshold: 0.2;\n  shape-margin: var(--gp-gap, 1em);\n}\n\n/* pin \u2014 within the nearest positioned ancestor (.page/.spread, rule above).\n   The four insets are the pin box: 0 (the text block's edge) unless an\n   engine set --gp-pin-<edge> on the page root for an edge a pin uses (the\n   art-safe line). Non-auto insets and the explicit centers are\n   load-bearing; see doctrine comment. */\n.gp-pin {\n  position: absolute;\n  top: var(--gp-pin-top, 0px);\n  right: var(--gp-pin-right, 0px);\n  bottom: var(--gp-pin-bottom, 0px);\n  left: var(--gp-pin-left, 0px);\n  align-self: center;\n  justify-self: center;\n  margin: 0;\n  max-width: 100%;\n}\n\n/* pin edge modifiers \u2014 AFTER .gp-pin to beat its center defaults;\n   justify-self is inert on in-flow floats, so gp-left/gp-right safely do\n   double duty as flow float + pin edge */\n.gp-top { align-self: start; }\n.gp-bottom { align-self: end; }\n.gp-left { justify-self: start; }\n.gp-right { justify-self: end; }\n\n/* the escape hatch \u2014 the paper's edge, past the printer's safe area: the\n   pin box loses its art-safe insets. Set on the pin itself, so it beats the\n   values the page root hands down. */\n.gp-pin.gp-flush {\n  --gp-pin-top: 0px;\n  --gp-pin-right: 0px;\n  --gp-pin-bottom: 0px;\n  --gp-pin-left: 0px;\n}\n\n/* wrapper-margin neutralization (same pattern and rationale as the\n   .gp-bleed paragraph-margin note in the doctrine comment; for pin, the\n   emptied paragraph would otherwise leave a phantom margin gap in flow) */\n:where(p:has(> img.gp-bleed:only-child)) { margin: 0; }\n:where(p:has(> img.gp-pin:only-child)) { margin: 0; }\n\n/* depth \u2014 a named ladder for z-index, so books stop hand-tuning bare\n   integers. A real book measured 21 z-index declarations using only four\n   distinct values (-1, 0, 1, 2), each written literally at its use site.\n   The custom properties are the author-settable surface (a book needing a\n   deeper stack raises them once); the classes are the shorthand.\n\n   NOT named \"layer\": CSS Paged Media 3 \u00A73.1 already defines \"page layers\"\n   (page background, canvas, borders, contents, margin boxes) and those are\n   parts of the PAGE BOX, not a z-ladder for content. Reusing the word for a\n   different concept would collide with the spec vocabulary this project\n   tracks. The pin EDGE modifiers already own .gp-top/.gp-bottom, so the\n   ladder avoids those words too.\n\n   .gp-behind is the one that earns its place: it puts a pinned image UNDER\n   the page's text, which is otherwise impossible to express without a bare\n   negative z-index. \"Above\" needs no class \u2014 an out-of-flow pin already\n   paints above in-flow content.\n\n   Two things silently defeat .gp-behind, neither visible at the use site:\n     - a stacking context on the .page/.spread ancestor (z-index, isolation,\n       opacity, filter, transform on it traps the negative layer inside).\n       Core keeps .page/.spread at 'position: relative; z-index: auto'\n       precisely so they are not stacking contexts.\n     - a clipping ancestor (overflow other than visible) \u2014 but only where\n       the art actually overhangs that ancestor's clip box on a clipped\n       axis: the overhang is cut off, the same mechanism that clips a\n       .gp-bleed plate back to the wrapper's width. Clipping never reorders\n       layers \u2014 within-bounds art under a clipping .page prints whole and\n       still behind (measured; see the build audit's comment in\n       engine/compiler/build.ts), and a static wrapper's overflow never\n       binds an abspos .gp-pin at all.\n   The build-time engine.layer.trapped audit reports both against the live\n   ancestor chain. printsafe/page-containment is only an early source hint for\n   declarations written directly on .page/.spread. */\n:root {\n  --gp-z-behind: -1;\n  --gp-z-base: 0;\n  --gp-z-raised: 1;\n  --gp-z-front: 2;\n}\n.gp-behind { z-index: var(--gp-z-behind); }\n.gp-base   { z-index: var(--gp-z-base); }\n.gp-raised { z-index: var(--gp-z-raised); }\n.gp-front  { z-index: var(--gp-z-front); }\n\n/* GFM-style alert/callout boxes (#237) \u2014 the DOM gfm-alerts.ts emits from\n   \"> [!TYPE]\" blockquote syntax when a project opts into the bundled\n   gutterpress-gfm-alerts feature (BUILTIN_OPTIONAL_PLUGINS, renderer.ts).\n   The plugin is optional and inert by default; these rules are equally\n   inert wherever the classes never appear, exactly like every other\n   utility above, so shipping them costs nothing to a book that has not\n   turned the feature on.\n\n   This is authored-COMPONENT vocabulary, not the @marker structural family\n   (markers.js/MARKER_CSS) \u2014 CLAUDE.md \u00A76 splits the two core CSS blocks by\n   ROLE, and an author-facing box an author invokes via inline syntax is the\n   same role as every other gp-* utility here, not page/chapter/section DOM.\n\n   Deliberately minimal (CLAUDE.md \"thin over capable\" / the issue's own\n   \"a rule and a label\"): a left border plus a bold label, :where()'d to\n   zero specificity so a theme's own (unlayered) rule for any of these\n   classes wins outright regardless of selector weight \u2014 see the\n   cascade-layers note atop this file. Five semantic accent colors (the same\n   NOTE/TIP/IMPORTANT/WARNING/CAUTION hues GitHub's own alerts use \u2014 a\n   long-established, non-proprietary convention, not DC branding) are\n   exposed as :root custom properties, the same author-settable-surface\n   pattern as the --gp-z-* ladder above: a book retints every alert of one\n   type by overriding a single property, no specificity fight required.\n   --gp-alert-color cascades from the type modifier down to .gp-alert-title\n   through ordinary CSS inheritance (the title is always a DOM descendant of\n   the box), so it is set in exactly five places, not ten. */\n:root {\n  --gp-alert-note-color: #0969da;\n  --gp-alert-tip-color: #1a7f37;\n  --gp-alert-important-color: #8250df;\n  --gp-alert-warning-color: #9a6700;\n  --gp-alert-caution-color: #cf222e;\n}\n:where(.gp-alert) {\n  margin: 1em 0;\n  padding: 0.5em 1em;\n  border-left: 0.25em solid var(--gp-alert-color, currentColor);\n}\n:where(.gp-alert-title) {\n  margin: 0 0 0.5em;\n  font-weight: bold;\n  color: var(--gp-alert-color, inherit);\n}\n:where(.gp-alert-note)      { --gp-alert-color: var(--gp-alert-note-color); }\n:where(.gp-alert-tip)       { --gp-alert-color: var(--gp-alert-tip-color); }\n:where(.gp-alert-important) { --gp-alert-color: var(--gp-alert-important-color); }\n:where(.gp-alert-warning)   { --gp-alert-color: var(--gp-alert-warning-color); }\n:where(.gp-alert-caution)   { --gp-alert-color: var(--gp-alert-caution-color); }\n\n/* Math (the bundled gutterpress-math feature, math.ts): MathJax's own rules\n   for the <mjx-container> SVG output it emits, from its SVG output jax's\n   stylesheet, less the ones for its interactive menu and tooltips. Inert in\n   a book without formulas. */\nmjx-container[jax=\"SVG\"] { direction: ltr; }\nmjx-container[jax=\"SVG\"] > svg { overflow: visible; min-height: 1px; min-width: 1px; }\nmjx-container[jax=\"SVG\"] > svg a { fill: blue; stroke: blue; }\nmjx-container[jax=\"SVG\"][display=\"true\"] { display: block; text-align: center; margin: 1em 0; }\nmjx-container[jax=\"SVG\"][display=\"true\"][width=\"full\"] { display: flex; }\nmjx-container[jax=\"SVG\"][justify=\"left\"] { text-align: left; }\nmjx-container[jax=\"SVG\"][justify=\"right\"] { text-align: right; }\nmjx-container[jax=\"SVG\"] path[data-c], mjx-container[jax=\"SVG\"] use[data-c] { stroke-width: 3; }\nmjx-assistive-mml {\n  position: absolute !important;\n  top: 0px; left: 0px;\n  clip: rect(1px, 1px, 1px, 1px);\n  padding: 1px 0px 0px 0px !important;\n  border: 0px !important;\n  display: block !important;\n  width: auto !important;\n  overflow: hidden !important;\n  user-select: none;\n}\nmjx-assistive-mml[display=\"block\"] { width: 100% !important; }\ng[data-mml-node=\"merror\"] > g { fill: red; stroke: red; }\ng[data-mml-node=\"merror\"] > rect[data-background] { fill: yellow; stroke: none; }\ng[data-mml-node=\"mtable\"] > line[data-line], svg[data-table] > g > line[data-line] { stroke-width: 70px; fill: none; }\ng[data-mml-node=\"mtable\"] > rect[data-frame], svg[data-table] > g > rect[data-frame] { stroke-width: 70px; fill: none; }\ng[data-mml-node=\"mtable\"] > .mjx-dashed, svg[data-table] > g > .mjx-dashed { stroke-dasharray: 140; }\ng[data-mml-node=\"mtable\"] > .mjx-dotted, svg[data-table] > g > .mjx-dotted { stroke-linecap: round; stroke-dasharray: 0,140; }\ng[data-mml-node=\"mtable\"] > g > svg { overflow: visible; }\n";
+export declare const GUTTERPRESS_CSS = "\n/* gp-* author image/block vocabulary. One vocabulary, gp-* only \u2014 the\n   pre-vocabulary utility names (.center/.float-left/.float-right/\n   .full-width/.full-bleed) were REMOVED when gp-* shipped; books rename\n   the classes in their markdown (see the migration note). Source ORDER is\n   the contract \u2014 see the doctrine comment above. */\n\n/* flow positions */\n.gp-left {\n  float: left;\n  margin: 0 var(--gp-gap, 1em) var(--gp-gap, 1em) 0;\n  max-width: 50%;\n}\n.gp-right {\n  float: right;\n  margin: 0 0 var(--gp-gap, 1em) var(--gp-gap, 1em);\n  max-width: 50%;\n}\n.gp-center {\n  display: block;\n  float: none;\n  margin-left: auto;\n  margin-right: auto;\n  max-width: 100%;\n}\n.gp-full {\n  display: block;\n  float: none;\n  width: 100%;\n  max-width: 100%;\n}\n@page gp-full-bleed { margin-left: 0; margin-right: 0; }\n.gp-bleed {\n  display: block;\n  float: none;\n  break-before: page;\n  page: gp-full-bleed;\n  max-width: none;\n  width: 100%;\n  margin-left: 0;\n  margin-right: 0;\n}\n\n/* sizes \u2014 AFTER the flow positions so max-width:100% lifts the floats' 50%\n   cap at equal specificity */\n.gp-size-10 { width: 10%; max-width: 100%; }\n.gp-size-20 { width: 20%; max-width: 100%; }\n.gp-size-30 { width: 30%; max-width: 100%; }\n.gp-size-40 { width: 40%; max-width: 100%; }\n.gp-size-50 { width: 50%; max-width: 100%; }\n.gp-size-60 { width: 60%; max-width: 100%; }\n.gp-size-70 { width: 70%; max-width: 100%; }\n.gp-size-80 { width: 80%; max-width: 100%; }\n.gp-size-90 { width: 90%; max-width: 100%; }\n\n/* float clearance presets \u2014 consumed by var(--gp-gap) in the float rules\n   above and by .gp-shape's shape-margin below; --gp-gap itself is\n   author-settable CSS */\n.gp-tight { --gp-gap: 0.5em; }\n.gp-loose { --gp-gap: 2em; }\n\n/* column runs \u2014 plain CSS Multi-column, emitted by the core @columns marker\n   (markers.js): @columns [1-5] ... @end-columns is the ONE way to lay\n   content out in columns, and @column-break moves to the next column.\n   The classes below are the CSS that marker emits, not author vocabulary.\n\n   Permanent vocabulary, not a shim: Chromium implements multicol natively\n   and these rules are the standard properties verbatim, so there is no\n   spec gap here to remove later. Deliberately minimal \u2014 column-fill is\n   NOT set (the CSS initial balance applies).\n   Themes style a run through two tokens instead of writing column rules:\n     --gp-column-gap   default 1.5em\n     --gp-column-rule  default none (any column-rule shorthand value)\n   Both hooks sit at zero specificity (:where), so any author rule wins.\n   .gp-columns is two columns on its own; a count class (bare @columns\n   emits gp-columns-2) wins because it comes later at the same specificity. */\n:where(.gp-columns, .gp-columns-1, .gp-columns-2, .gp-columns-3, .gp-columns-4, .gp-columns-5) {\n  column-gap: var(--gp-column-gap, 1.5em);\n  column-rule: var(--gp-column-rule, none);\n}\n.gp-columns { columns: 2; }\n.gp-columns-1 { columns: 1; }\n.gp-columns-2 { columns: 2; }\n.gp-columns-3 { columns: 3; }\n.gp-columns-4 { columns: 4; }\n.gp-columns-5 { columns: 5; }\n\n/* fragmentation controls \u2014 generic pagination utilities for any element,\n   independent of the column vocabulary above (a book reached for\n   these just as often outside a multicol run: keeping a card whole,\n   forcing a section to start a fresh page). Standard properties only \u2014\n   this project is Chromium-only (CLAUDE.md), so there are no legacy\n   page-break-* twins to also emit. One name each. */\n.gp-no-break { break-inside: avoid; }\n.gp-break-before { break-before: page; }\n\n/* shape wrap \u2014 text follows the image's alpha silhouette instead of its\n   rectangular box. shape-outside only applies to floats, so this is inert\n   without .gp-left/.gp-right (and under .gp-pin, which un-floats). The\n   shape URL cannot be written in CSS (url() contexts can't read attr()),\n   so the image renderer rule (images.ts) mirrors the src into an inline\n   --gp-shape:url(...) custom property whenever it sees this class --\n   authors only ever type the class. threshold 0.2 ignores near-transparent\n   anti-aliasing halos; shape-margin shares the float-gap vocabulary. */\nimg.gp-shape {\n  shape-outside: var(--gp-shape);\n  shape-image-threshold: 0.2;\n  shape-margin: var(--gp-gap, 1em);\n}\n\n/* pin \u2014 within the nearest positioned ancestor (.page/.spread, rule above).\n   The four insets are the pin box: 0 (the text block's edge) unless an\n   engine set --gp-pin-<edge> on the page root for an edge a pin uses (the\n   art-safe line). Non-auto insets and the explicit centers are\n   load-bearing; see doctrine comment. */\n.gp-pin {\n  position: absolute;\n  top: var(--gp-pin-top, 0px);\n  right: var(--gp-pin-right, 0px);\n  bottom: var(--gp-pin-bottom, 0px);\n  left: var(--gp-pin-left, 0px);\n  align-self: center;\n  justify-self: center;\n  margin: 0;\n  max-width: 100%;\n}\n\n/* pin edge modifiers \u2014 AFTER .gp-pin to beat its center defaults;\n   justify-self is inert on in-flow floats, so gp-left/gp-right safely do\n   double duty as flow float + pin edge */\n.gp-top { align-self: start; }\n.gp-bottom { align-self: end; }\n.gp-left { justify-self: start; }\n.gp-right { justify-self: end; }\n\n/* the escape hatch \u2014 the paper's edge, past the printer's safe area: the\n   pin box loses its art-safe insets. Set on the pin itself, so it beats the\n   values the page root hands down. */\n.gp-pin.gp-flush {\n  --gp-pin-top: 0px;\n  --gp-pin-right: 0px;\n  --gp-pin-bottom: 0px;\n  --gp-pin-left: 0px;\n}\n\n/* wrapper-margin neutralization (same pattern and rationale as the\n   .gp-bleed paragraph-margin note in the doctrine comment; for pin, the\n   emptied paragraph would otherwise leave a phantom margin gap in flow) */\n:where(p:has(> img.gp-bleed:only-child)) { margin: 0; }\n:where(p:has(> img.gp-pin:only-child)) { margin: 0; }\n\n/* depth \u2014 a named ladder for z-index, so books stop hand-tuning bare\n   integers. A real book measured 21 z-index declarations using only four\n   distinct values (-1, 0, 1, 2), each written literally at its use site.\n   The custom properties are the author-settable surface (a book needing a\n   deeper stack raises them once); the classes are the shorthand.\n\n   NOT named \"layer\": CSS Paged Media 3 \u00A73.1 already defines \"page layers\"\n   (page background, canvas, borders, contents, margin boxes) and those are\n   parts of the PAGE BOX, not a z-ladder for content. Reusing the word for a\n   different concept would collide with the spec vocabulary this project\n   tracks. The pin EDGE modifiers already own .gp-top/.gp-bottom, so the\n   ladder avoids those words too.\n\n   .gp-behind is the one that earns its place: it puts a pinned image UNDER\n   the page's text, which is otherwise impossible to express without a bare\n   negative z-index. \"Above\" needs no class \u2014 an out-of-flow pin already\n   paints above in-flow content.\n\n   Two things silently defeat .gp-behind, neither visible at the use site:\n     - a stacking context on the .page/.spread ancestor (z-index, isolation,\n       opacity, filter, transform on it traps the negative layer inside).\n       Core keeps .page/.spread at 'position: relative; z-index: auto'\n       precisely so they are not stacking contexts.\n     - a clipping ancestor (overflow other than visible) \u2014 but only where\n       the art actually overhangs that ancestor's clip box on a clipped\n       axis: the overhang is cut off, the same mechanism that clips a\n       .gp-bleed plate back to the wrapper's width. Clipping never reorders\n       layers \u2014 within-bounds art under a clipping .page prints whole and\n       still behind (measured; see the build audit's comment in\n       engine/compiler/build.ts), and a static wrapper's overflow never\n       binds an abspos .gp-pin at all.\n   The build-time engine.layer.trapped audit reports both against the live\n   ancestor chain. printsafe/page-containment is only an early source hint for\n   declarations written directly on .page/.spread. */\n:root {\n  --gp-z-behind: -1;\n  --gp-z-base: 0;\n  --gp-z-raised: 1;\n  --gp-z-front: 2;\n}\n.gp-behind { z-index: var(--gp-z-behind); }\n.gp-base   { z-index: var(--gp-z-base); }\n.gp-raised { z-index: var(--gp-z-raised); }\n.gp-front  { z-index: var(--gp-z-front); }\n\n/* GFM-style alert/callout boxes (#237) \u2014 the DOM gfm-alerts.ts emits from\n   \"> [!TYPE]\" blockquote syntax when a project opts into the bundled\n   gutterpress-gfm-alerts feature (BUILTIN_OPTIONAL_PLUGINS, renderer.ts).\n   The plugin is optional and inert by default; these rules are equally\n   inert wherever the classes never appear, exactly like every other\n   utility above, so shipping them costs nothing to a book that has not\n   turned the feature on.\n\n   This is authored-COMPONENT vocabulary, not the @marker structural family\n   (markers.js/MARKER_CSS) \u2014 CLAUDE.md \u00A76 splits the two core CSS blocks by\n   ROLE, and an author-facing box an author invokes via inline syntax is the\n   same role as every other gp-* utility here, not page/chapter/section DOM.\n\n   Deliberately minimal (CLAUDE.md \"thin over capable\" / the issue's own\n   \"a rule and a label\"): a left border plus a bold label, :where()'d to\n   zero specificity so a theme's own (unlayered) rule for any of these\n   classes wins outright regardless of selector weight \u2014 see the\n   cascade-layers note atop this file. Five semantic accent colors (the same\n   NOTE/TIP/IMPORTANT/WARNING/CAUTION hues GitHub's own alerts use \u2014 a\n   long-established, non-proprietary convention, not DC branding) are\n   exposed as :root custom properties, the same author-settable-surface\n   pattern as the --gp-z-* ladder above: a book retints every alert of one\n   type by overriding a single property, no specificity fight required.\n   --gp-alert-color cascades from the type modifier down to .gp-alert-title\n   through ordinary CSS inheritance (the title is always a DOM descendant of\n   the box), so it is set in exactly five places, not ten. */\n:root {\n  --gp-alert-note-color: #0969da;\n  --gp-alert-tip-color: #1a7f37;\n  --gp-alert-important-color: #8250df;\n  --gp-alert-warning-color: #9a6700;\n  --gp-alert-caution-color: #cf222e;\n}\n:where(.gp-alert) {\n  margin: 1em 0;\n  padding: 0.5em 1em;\n  border-left: 0.25em solid var(--gp-alert-color, currentColor);\n}\n:where(.gp-alert-title) {\n  margin: 0 0 0.5em;\n  font-weight: bold;\n  color: var(--gp-alert-color, inherit);\n}\n:where(.gp-alert-note)      { --gp-alert-color: var(--gp-alert-note-color); }\n:where(.gp-alert-tip)       { --gp-alert-color: var(--gp-alert-tip-color); }\n:where(.gp-alert-important) { --gp-alert-color: var(--gp-alert-important-color); }\n:where(.gp-alert-warning)   { --gp-alert-color: var(--gp-alert-warning-color); }\n:where(.gp-alert-caution)   { --gp-alert-color: var(--gp-alert-caution-color); }\n\n/* Math (the bundled gutterpress-math feature, math.ts): MathJax's own rules\n   for the <mjx-container> SVG output it emits, from its SVG output jax's\n   stylesheet, less the ones for its interactive menu and tooltips, plus one\n   bound of ours on the hidden MathML copy (#469, below). Inert in a book\n   without formulas. */\nmjx-container[jax=\"SVG\"] { direction: ltr; }\nmjx-container[jax=\"SVG\"] > svg { overflow: visible; min-height: 1px; min-width: 1px; }\nmjx-container[jax=\"SVG\"] > svg a { fill: blue; stroke: blue; }\nmjx-container[jax=\"SVG\"][display=\"true\"] { display: block; text-align: center; margin: 1em 0; }\nmjx-container[jax=\"SVG\"][display=\"true\"][width=\"full\"] { display: flex; }\nmjx-container[jax=\"SVG\"][justify=\"left\"] { text-align: left; }\nmjx-container[jax=\"SVG\"][justify=\"right\"] { text-align: right; }\nmjx-container[jax=\"SVG\"] path[data-c], mjx-container[jax=\"SVG\"] use[data-c] { stroke-width: 3; }\nmjx-assistive-mml {\n  position: absolute !important;\n  top: 0px; left: 0px;\n  clip: rect(1px, 1px, 1px, 1px);\n  padding: 1px 0px 0px 0px !important;\n  border: 0px !important;\n  display: block !important;\n  width: auto !important;\n  /* Ours (#469). The browser lays the copy out in whatever math font it has,\n     so it can be wider than the formula's SVG; ending a line, it crossed the\n     column edge and Chromium shrank the whole print to fit. MathJax makes the\n     container position: relative with the copy at its top left, so 100% is\n     the formula's width. Clip and overflow still hide the copy and its MathML\n     still reaches screen readers; only its box changes. Not the 1px\n     visually-hidden box MathJax 2 used: its docs note VoiceOver on iOS could\n     not reach a formula by touch in it. */\n  max-width: 100% !important;\n  overflow: hidden !important;\n  user-select: none;\n}\nmjx-assistive-mml[display=\"block\"] { width: 100% !important; }\ng[data-mml-node=\"merror\"] > g { fill: red; stroke: red; }\ng[data-mml-node=\"merror\"] > rect[data-background] { fill: yellow; stroke: none; }\ng[data-mml-node=\"mtable\"] > line[data-line], svg[data-table] > g > line[data-line] { stroke-width: 70px; fill: none; }\ng[data-mml-node=\"mtable\"] > rect[data-frame], svg[data-table] > g > rect[data-frame] { stroke-width: 70px; fill: none; }\ng[data-mml-node=\"mtable\"] > .mjx-dashed, svg[data-table] > g > .mjx-dashed { stroke-dasharray: 140; }\ng[data-mml-node=\"mtable\"] > .mjx-dotted, svg[data-table] > g > .mjx-dotted { stroke-linecap: round; stroke-dasharray: 0,140; }\ng[data-mml-node=\"mtable\"] > g > svg { overflow: visible; }\n";
 /**
  * GP_CLASSES — every class an author may legitimately write with a `gp-`
  * prefix: the `.gp-*` selectors in `GUTTERPRESS_CSS` above, the two

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

@@ -5,7 +5,7 @@ import type MarkdownIt from "markdown-it";
  *
  * Bundled, OPT-IN markdown feature (`gutterpress-math` in
  * `BUILTIN_OPTIONAL_PLUGINS`, renderer.ts; "Math" in
- * `BUNDLED_EXTENSIONS`, extension-specifier.ts), exactly like the Callouts
+ * `BUNDLED_EXTENSION_DETAILS`, extension-specifier.ts), exactly like the Callouts
  * feature: a book that never lists it renders `$` as the character it is.
  *
  * WHY SVG. Each formula is written as a drawing of its own glyphs, so the

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

@@ -9,4 +9,5 @@ import type MarkdownIt from "markdown-it";
  */
 export declare const QUOTES: Record<string, string | string[]>;
 export declare function quotesFor(language?: string): string | string[];
+/** Replaces markdown-it's `replacements` rule, at its place in the core chain. */
 export declare function gpTypography(md: MarkdownIt): void;

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

@@ -10,6 +10,8 @@ export interface CustomPageOptions {
     width: number;
     /** Trim height in points (72pt = 1in). */
     height: number;
+    /** How far (pt) the built PDF may differ from it, written as the page-size check's option. Default: the preset's 0.5. */
+    tolerance?: number;
 }
 /** A page size in points. */
 export interface PageSizePoints {
@@ -50,9 +52,10 @@ export interface PageSetup {
     presetSizeOverridden: boolean;
 }
 /**
- * Write the manifest's `page:` bounds. A `tolerance` an older book carries
- * goes (the preset sets it); the block's other keys stay as written; a
- * `page:` that is not a map is replaced.
+ * Write the manifest's `page:` bounds, and a `tolerance` given with them as
+ * the page-size check's option (one already recorded stays when none is
+ * given). The block's other keys stay as written; a `page:` that is not a
+ * map is replaced.
  */
 export declare function writePageBounds(doc: Document, page: CustomPageOptions): void;
 /** Remove the bounds a preset owns and nothing else; a `page:` left empty goes too. */
@@ -67,6 +70,8 @@ export declare function numberAt(doc: Document, keyPath: string[]): number | und
 export declare function pageSizeForChoice(choice: PageSizeChoice): PageSizePoints;
 /** Read a book's page geometry back from its manifest (and, for margins it does not set, its stylesheets). */
 export declare function readPageSetup(projectDir: string): Promise<PageSetup>;
+/** @deprecated 0.11.22's call shape: pass `{ size: { preset, page } }`. */
+export declare function setPageSetup(projectDir: string, choice: PageSizeChoice): Promise<PageSetup>;
 /**
  * Change a book's page geometry in the manifest. The size mirrors what the
  * wizard records — `dtrpg` / `book` carry their own bounds (the `page:` block's
@@ -74,6 +79,9 @@ export declare function readPageSetup(projectDir: string): Promise<PageSetup>;
  * other keys stay), `custom` records the typed trim. The margins go to
  * `page.margin`, validated against the size being written, else the recorded
  * one; `margins: null` removes `page.margin`. Nothing is written unless the
- * whole change validates.
+ * whole change validates. A 0.11.22 caller's `{ preset, page? }` (a size
+ * choice, before margins joined it) is read as `{ size: { preset, page } }`.
+ * The thresholds a 0.11.22 manifest spells the old way are written the new
+ * way (`rewriteOldThresholds`).
  */
 export declare function setPageSetup(projectDir: string, change: PageSetupChange): Promise<PageSetup>;

package/dist/lib/plugin-vendor.d.ts

@@ -1,5 +1,11 @@
 /** Project-relative folder every extension a book carries lives under: vendored npm copies in `npm/`, imports beside them. */
 export declare const EXTENSIONS_DIR = "extensions";
+/**
+ * @deprecated 0.11.22's name for the folder vendored npm extensions go in;
+ * the same folder as {@link EXTENSIONS_DIR}, kept so a caller of the lib keeps
+ * working. Books vendored before 0.11.23 keep theirs in {@link LEGACY_PLUGINS_DIR}.
+ */
+export declare const PLUGINS_DIR = "extensions";
 /** Where books vendored before 0.11.23 keep their npm copies. Read, never written. */
 export declare const LEGACY_PLUGINS_DIR = "plugins";
 export declare const VENDORED_NPM_DIR = "npm";

package/dist/lib/presets.d.ts

@@ -7,8 +7,8 @@ import type { ResolvedConfig } from "../schema/manifest.types";
  *
  * Geometry, build and print values are overridable from the manifest, leaf
  * by leaf (resolveConfig's mergeShape; precedence cli > manifest > target >
- * preset). The check thresholds (`ink`, `validate`) are the preset's and the
- * target's alone; a book changes a check's level in `checks:`.
+ * preset). The check thresholds (`ink`, `validate`, `page.tolerance`) are
+ * overridden in the check's own `checks:` entry (lib/check-options.ts).
  */
 export interface VendorPreset extends Omit<ResolvedConfig, "title" | "authors" | "language" | "preset" | "targets" | "page"> {
     /** This preset's id: what the manifest's `preset:` names and a resolved config reports. */

package/dist/lib/root-tokens.d.ts

@@ -71,6 +71,7 @@ export declare function rootTokens(css: string): RootToken[];
  * added to `sheets[target]`. A null value removes the token from every
  * sheet, so what the looks set shows through. Returns the sheets' new text;
  * a sheet nothing changed comes back as it was given. Throws postcss's
- * `CssSyntaxError` for a sheet it cannot parse.
+ * `CssSyntaxError` for a sheet it cannot parse, and refuses the whole batch,
+ * writing nothing, when a value is not one declaration's value.
  */
 export declare function applyTokenUpdates(sheets: readonly string[], target: number, updates: readonly TokenUpdate[]): string[];

package/dist/lib/source-provider.d.ts

@@ -1,3 +1,4 @@
+import { type ReadCommitResult } from "isomorphic-git";
 import type { ProjectCapabilities, ProjectSource } from "./project-source.ts";
 /**
  * isomorphic-git object cache scoped to ONE operation and released with it.
@@ -182,6 +183,32 @@ export declare function hasPendingChanges(dir: string, cache?: GitCache): Promis
  * as dirty (the WORKDIR-vs-STAGE-only check silently drops it).
  */
 export declare function hasUncommittedChanges(dir: string, cache?: GitCache): Promise<boolean>;
+/**
+ * A walk back through a repo's history in the order `git.log` lists it (the
+ * newest commit time first), visiting each commit once (#472). `git.log` has
+ * no visited set: after a merge it lists a commit again, with everything older,
+ * and the repeats used up a page. Starting the next page's log at the last id
+ * also dropped the side of a merge that id does not descend from. Shared with
+ * the online-only versions (`commitsAhead`, #477), which walks two tips at once.
+ */
+export interface HistoryWalk {
+    /** Commits read but not listed yet, sorted so the newest is last. */
+    tips: ReadCommitResult[];
+    /** Every commit ever put in `tips`. */
+    queued: Set<string>;
+    /** `.git/shallow`: commits whose parents a shallow clone does not have. */
+    shallow: Set<string>;
+    /** Commits read ahead (see {@link nextInHistory}), not queued yet. */
+    readAhead: Map<string, ReadCommitResult>;
+}
+/** A walk back from `heads` (the history of each of them, together). */
+export declare function startHistoryWalk(dir: string, cache: GitCache, heads: string[]): Promise<HistoryWalk>;
+/**
+ * The walk's next commit, newest first; undefined once the history is done.
+ * `needed` is how many more commits the page needs, to bound a read-ahead
+ * (none for 1: a caller that cannot tell how far it will go reads one by one).
+ */
+export declare function nextInHistory(dir: string, walk: HistoryWalk, cache: GitCache, needed: number): Promise<ReadCommitResult | undefined>;
 /**
  * Lock-free snapshot of the full working tree (stage everything + commit).
  *

package/dist/lib/style-resolver.d.ts

@@ -14,7 +14,8 @@ export declare function relDisplay(projectDir: string, absPath: string): string;
  * BOTH the renderer (to `<link>` them) and the editor (to edit them), so they
  * can never disagree. Returns project-relative paths:
  *   1. the manifest `styles:` list, if it has any entries; else
- *   2. `styles/book.css`, when the project has it; else
+ *   2. the first conventional stylesheet the project actually has
+ *      (`FALLBACK_PRIORITY`); else
  *   3. the first discovered `.css` anywhere we scan (deterministic); else
  *   4. `[]` — the project has no stylesheet (an honest empty, never a phantom
  *      link to a missing file).

package/dist/lib/version-changes.d.ts

@@ -22,6 +22,12 @@ export interface VersionEntry extends SnapshotEntry {
     /** True = online too; false = on this computer only; null = no online copy to compare with. */
     backedUp: boolean | null;
 }
+/** A version in the online copy that this computer has not got, with the files it changed. */
+export interface OnlineVersionEntry extends VersionEntry {
+    changes: VersionFileChange[];
+    /** Changed files beyond the ones listed. */
+    moreChanges: number;
+}
 /** How many changed files a version card lists before "and N more". */
 export declare const VERSION_CHANGES_SHOWN = 8;
 /** The size hint for a text file that changed between two versions. */
@@ -45,15 +51,25 @@ export declare function listVersionChanges(projectDir: string, oid: string): Pro
 export declare function describeVersions(projectDir: string, entries: SnapshotEntry[]): Promise<VersionEntry[]>;
 /**
  * The commits reachable from `fromOid` that `baseOid`'s history does not
- * have, newest first, down to (not including) their merge base. None when
- * the two share no history.
+ * have (`git rev-list fromOid ^baseOid`), each once, newest first in the
+ * order Version history lists versions, up to `limit`. None when the two
+ * share no history: that is another book's online copy, which Sync refuses.
+ *
+ * One walk back from both tips, newest commit time first (#477). What
+ * `baseOid` reaches is marked, and a marked commit marks its parents, even
+ * ones already walked: a commit both tips reach is never listed, by whatever
+ * path `fromOid` reaches it (a criss-cross merge has two merge bases). The
+ * walk goes on while an unmarked commit is queued, so a version dated before
+ * the commits it builds on (a collaborator's clock behind) is still found;
+ * then until every marked commit queued is {@link CLOCK_SKEW_SECONDS} older
+ * than the oldest version listed.
  */
-export declare function commitsAhead(dir: string, fromOid: string, baseOid: string, cache?: object, limit?: number): Promise<SnapshotEntry[]>;
+export declare function commitsAhead(dir: string, fromOid: string, baseOid: string, cache?: Record<string, unknown>, limit?: number): Promise<SnapshotEntry[]>;
 /**
  * What is online that this computer has not got: fetch the book's branch
  * (remote-tracking ref only — no merge, no checkout, safe on a dirty tree)
- * and describe the commits above the merge base. Quiet on every failure,
- * reporting why, like `checkRemoteUpdates`.
+ * and describe the commits this computer has not got, each with the files it
+ * changed. Quiet on every failure, reporting why, like `checkRemoteUpdates`.
  */
 export declare function listOnlineVersions(options: {
     projectDir: string;
@@ -61,7 +77,7 @@ export declare function listOnlineVersions(options: {
     tokenStore?: TokenStore;
     httpClient?: typeof defaultGitHttp;
 }): Promise<{
-    entries: VersionEntry[];
+    entries: OnlineVersionEntry[];
     reason?: "no-remote" | "auth" | "offline";
 }>;
 /**