gutterpress 0.11.17 → 0.11.18-alpha.10

package/dist/{index-vmcfahe2.js → index-jt552wtf.js}

@@ -148,22 +148,22 @@ import { fileURLToPath } from "node:url";
 var favicon_default = "./favicon-272ga6y0.ico";
 
 // src/assets/manifest.schema.json
-var manifest_schema_default = "./manifest.schema-gh0jjve9.json";
+var manifest_schema_default = "./manifest.schema-5pzhscqh.json";
 
 // src/assets/preview/scripts/preview-interface.js
-var preview_interface_default = "./preview-interface-c44qk17f.js";
+var preview_interface_default = "./preview-interface-2n1d9pbf.js";
 
 // src/assets/preview/scripts/preview-bridge.js
-var preview_bridge_default = "./preview-bridge-8jhd1wpb.js";
+var preview_bridge_default = "./preview-bridge-evecsh4w.js";
 
 // src/assets/preview/scripts/preview-shell.js
-var preview_shell_default = "./preview-shell-xwn84kqr.js";
+var preview_shell_default = "./preview-shell-hyp7g158.js";
 
 // profiles/CGATS21_CRPC1.icc
 var CGATS21_CRPC1_default = "./CGATS21_CRPC1-g0e3k7kr.icc";
 
 // src/assets/engine/gutterpress-viewer.js
-var gutterpress_viewer_default = "./gutterpress-viewer-ez7k4ha7.js";
+var gutterpress_viewer_default = "./gutterpress-viewer-k4mpqjh0.js";
 
 // src/assets/engine/gutterpress-agent.js
 var gutterpress_agent_default = "./gutterpress-agent-cazqstr1.js";

package/dist/{index-09h3n36d.js → index-n8vs6pss.js}

@@ -19,7 +19,7 @@ import {
   stringValueAt,
   toFolioPage,
   wantsRecto
-} from "./index-vmcfahe2.js";
+} from "./index-jt552wtf.js";
 import {
   launchChromium
 } from "./index-rzm1phg0.js";
@@ -724,7 +724,8 @@ var BUILD_DIAGNOSTIC_CODES = [
   "engine.content.overheight",
   "engine.image.low-dpi",
   "engine.flush.margin-box",
-  "engine.page-background.unreferenced"
+  "engine.page-background.unreferenced",
+  "engine.hyphenation.unsupported"
 ];
 async function build(opts) {
   const log = opts.onProgress ?? (() => {});
@@ -1333,6 +1334,54 @@ ${mapCss}`;
       if (multicol.length)
         log(`audit: ${multicol.length} fragmenting multicol warning(s)`);
     }
+    {
+      const missing = JSON.parse(await page.evaluate(`(() => {
+          const words = new Map();
+          const styled = new Map();
+          const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+          for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+            const found = n.data.match(/\\p{L}{7,}/gu);
+            const el = n.parentElement;
+            if (!found || !el) continue;
+            if (!styled.has(el)) styled.set(el, getComputedStyle(el).hyphens === "auto");
+            if (!styled.get(el)) continue;
+            const host = el.closest("[lang]");
+            const lang = host ? host.getAttribute("lang") : null;
+            if (!words.has(lang)) words.set(lang, new Set());
+            const set = words.get(lang);
+            for (const w of found) if (set.size < 200) set.add(w);
+          }
+          if (!words.size) return "[]";
+          const box = document.createElement("div");
+          box.style.cssText = "position:absolute;left:-10000px;top:0;visibility:hidden";
+          const probes = [];
+          for (const [lang, set] of words) {
+            for (const w of [...set].sort((a, b) => b.length - a.length).slice(0, 8)) {
+              const pair = ["auto", "manual"].map((h) => {
+                const d = document.createElement("div");
+                if (lang !== null) d.setAttribute("lang", lang);
+                d.style.cssText = "width:1px;font:16px/16px serif;word-break:normal;overflow-wrap:normal;hyphens:" + h;
+                d.textContent = w;
+                box.appendChild(d);
+                return d;
+              });
+              probes.push({ lang, pair });
+            }
+          }
+          document.body.appendChild(box);
+          const hyphenates = new Set();
+          for (const { lang, pair } of probes)
+            if (pair[0].offsetHeight > pair[1].offsetHeight) hyphenates.add(lang);
+          box.remove();
+          const ua = navigator.userAgent;
+          const browser = (/Electron\\/[\\d.]+/.exec(ua) || /(?:HeadlessChrome|Chrome)\\/[\\d.]+/.exec(ua) || [ua])[0];
+          return JSON.stringify([...words.keys()].filter((l) => !hyphenates.has(l)).map((lang) => ({ lang, browser })));
+        })()`));
+      for (const { lang, browser: browser2 } of missing)
+        diagnose("engine.hyphenation.unsupported", `Your stylesheets set hyphens: auto, but the browser making this PDF (${browser2}) has no hyphenation dictionary for ${lang ? `"${lang}"` : "the document's language"}, so no word is hyphenated automatically and lines (and pages) break differently than in a browser that has one. Build in a browser that hyphenates, such as Chrome (which the gutterpress CLI uses), or add soft hyphens (&shy;) where a word may break.`);
+      if (missing.length)
+        log(`audit: hyphenation unavailable for ${missing.length} language(s)`);
+    }
     if (bytes === undefined) {
       prints++;
       bytes = await printPdf(page);

package/dist/index.js

@@ -38,6 +38,7 @@ import {
   autoSyncDelayMs,
   checkCss,
   checkExtensionUpdates,
+  checkRemoteUpdates,
   checkToolAvailability,
   cloneRepository,
   connectGenericHost,
@@ -153,14 +154,14 @@ import {
   testRemoteAccess,
   updateExtensions,
   validateProjectExtensions
-} from "./index-3k3fyrec.js";
+} from "./index-cf1kanp0.js";
 import"./index-ht1bcqdd.js";
 import {
   BUILD_DIAGNOSTIC_CODES
-} from "./index-09h3n36d.js";
+} from "./index-n8vs6pss.js";
 import {
   BuildError
-} from "./index-vmcfahe2.js";
+} from "./index-jt552wtf.js";
 import {
   DEFAULT_PRINT_OPTS,
   assertMilestone,
@@ -318,6 +319,7 @@ export {
   connectGenericHost,
   cloneRepository,
   checkToolAvailability,
+  checkRemoteUpdates,
   checkExtensionUpdates,
   checkCss,
   capabilitiesFor,

package/dist/lib/markdown/block-names.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `data-name` — a stable hook for targeting ONE block from a stylesheet.
+ *
+ * A book's markdown holds content and semantic markers; its look lives in the
+ * plugin's and the book's CSS. What CSS needs, to restyle a single block
+ * without a markdown edit, is something on that block to select by. Class
+ * names are shared by every instance, an `id` is something the author must
+ * type, and position selectors break on any insertion. So every block this
+ * pipeline can name gets a `data-name`:
+ *
+ *   [data-name="sporos"] { break-inside: avoid; }
+ *   img[data-name="founder-house"] { float: right; width: 40%; }
+ *
+ * Plain HTML: a `data-*` attribute is standard, selected with the standard
+ * attribute selector, and nothing here is a behaviour a future browser
+ * feature would replace. The viewer never reads it; it exists for the
+ * author's CSS.
+ *
+ * WHAT GETS A NAME
+ *
+ *   Marker-opened blocks (`.chapter`, `.spread`, `.page`, `.section`, every
+ *   declared marker, `@columns` included, their variants too) take, in order:
+ *     1. the marker's explicit `name=` (core already emits it as `data-name`);
+ *     2. its `label=`, slugged;
+ *     3. the slug of the block's OWN first heading: the first heading whose
+ *        innermost marker block is this one, so a `@page` that holds a
+ *        `@section` does not borrow the section's title and the two never
+ *        share a name;
+ *     4. nothing. A block with no explicit name, label or own heading stays
+ *        unnamed rather than getting a position-based name that moves when
+ *        a block is inserted.
+ *   Headings take an explicit `{name=…}`, else the slug of their own text.
+ *   Images take an explicit `{name=…}`, else the slug of the file's basename
+ *   without its extension (see {@link nameFromSrc}, applied in images.ts).
+ *
+ * SLUGS: lower-case, accents folded to ASCII, apostrophes (' and ’) dropped,
+ * every run of other characters becomes one `-`, trimmed. `slug.ts`'s `slugify` plus a few letters NFKD
+ * does not decompose.
+ *
+ * COLLISIONS. Names are unique within one source file, because a file is
+ * rendered on its own (a book is the concatenation of its files):
+ *   - blocks share ONE namespace, so `[data-name="x"]` is exactly one block
+ *     in a file whatever its kind; headings have their own namespace, so a
+ *     section and its title can both be `sporos`. Pair the attribute with an
+ *     element (`h3[data-name="sporos"]`) or a class to say which;
+ *   - a later duplicate gets `-2`, `-3`, … in document order. Explicit names
+ *     are authored and never rewritten; they are reserved first, so a
+ *     derived name steps around them;
+ *   - images are NOT numbered: two images from the same file share a name,
+ *     which is usually what a book wants.
+ * A book that needs a name unique across files scopes the selector by chapter
+ * (`#ch-06 [data-name="x"]`) or types `name=`.
+ *
+ * CONTINUATIONS. A `gp-continued` section (made by `@continue`) is the SAME
+ * block, so it keeps its original's `data-name` and carries the
+ * `gp-continued` class; `:not(.gp-continued)` picks the first piece. It does
+ * NOT repeat the `id` (an id names one element; see markers.js).
+ *
+ * NO `id`s ARE ADDED. Ids feed `target-counter()` and links; inventing them
+ * would change what a document links to.
+ *
+ * Runs last among the built-in core rules and before any loaded plugin's own
+ * rules, so it sees `markdown-it-attrs`' result and a plugin sees the names.
+ */
+import type MarkdownIt from "markdown-it";
+import type Token from "markdown-it/lib/token.mjs";
+/** The `data-name` slug of `text`: `""` when nothing usable is left. */
+export declare function nameSlug(text: string): string;
+/**
+ * The image name for `src`: its file's basename without extension, slugged.
+ * `images/chapter-00/Founder%20House.png?v=2` is `founder-house`. A `data:`
+ * URI has no file name, so it has none.
+ */
+export declare function nameFromSrc(src: string): string;
+/**
+ * The author's explicit name on a token: `data-name`, or the `name` a
+ * `{name=…}` brace leaves behind (not a valid attribute on these elements, so
+ * it is moved to `data-name`). `""` when there is none.
+ */
+export declare function takeExplicitName(token: Token): string;
+/** Register the rule. Called by `createMarkdownRenderer` right after the marker plugin. */
+export declare function gpBlockNames(md: MarkdownIt): void;

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

@@ -89,8 +89,9 @@ export interface GutterpressMarkerLabel {
  *
  * The close token has no meta. A `section: true` marker produces the core
  * `layout_section_open` / `layout_section_close` pair instead; its open token
- * carries `{ line, component, kind, variant, attrs }` (plus `continued: true`
- * on a `@continue` reopening) and a plain `@section`'s carries only `{ line }`.
+ * carries `{ line, component, kind, variant, attrs }` and a plain `@section`'s
+ * carries only `{ line }`; a `@continue` reopening of either adds
+ * `continued: true`.
  *
  * See `markers.js`'s header comment for a worked example and
  * `buildDeclaredMarkerRegistry` for the full validation/resolution contract

package/dist/lib/markdown/table-align.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Table column alignment as `data-align`, not an inline style.
+ *
+ * markdown-it writes `|:--|--:|` as `style="text-align:left"` on every cell.
+ * An inline style beats every stylesheet, so a book could never restyle a
+ * column without `!important`. The same fact as a plain attribute,
+ * `data-align="left|center|right"`, is applied by {@link TABLE_ALIGN_CSS} and
+ * loses to the book's own rules.
+ *
+ * Only markdown-it's own exact `text-align:` value is converted. An author's
+ * own `{style=…}` on a cell is left untouched.
+ */
+import type MarkdownIt from "markdown-it";
+export declare function gpTableAlign(md: MarkdownIt): void;
+/**
+ * The rules that apply `data-align`. `assemble.ts` injects them UNLAYERED,
+ * just before the book's own stylesheets, and with the natural specificity of
+ * an element plus an attribute (0,1,1). That puts them where the inline style
+ * they replace sat against the two things that used to lose to it:
+ *
+ *   - a plugin's default (`th { text-align: left }`, always in a cascade
+ *     layer): unlayered beats layered, so a markdown `:-:` still wins;
+ *   - a book's generic element rule (`th { text-align: left }`, specificity
+ *     0,0,1): the attribute selector outranks it, so the same book prints the
+ *     same. Measured on the user guide and the design guide, whose `th` rule
+ *     centred headers only until a layered version of these rules let it win.
+ *
+ * Unlike an inline style they can be overridden without `!important`: any
+ * book rule at least as specific that comes later wins, e.g.
+ * `td[data-align="right"] { text-align: center }` or `.stats td { … }`.
+ */
+export declare const TABLE_ALIGN_CSS = "\nth[data-align=\"left\"], td[data-align=\"left\"] { text-align: left; }\nth[data-align=\"center\"], td[data-align=\"center\"] { text-align: center; }\nth[data-align=\"right\"], td[data-align=\"right\"] { text-align: right; }\n";

package/dist/lib/presets.d.ts

@@ -21,6 +21,17 @@ export interface VendorPreset extends Omit<ResolvedConfig, "title" | "authors" |
 /** The built-in preset ids, in the order pickers should offer them. */
 export declare const PRESET_IDS: readonly ["dtrpg", "book", "custom"];
 export type PresetId = (typeof PRESET_IDS)[number];
+/**
+ * DriveThruRPG print-on-demand interior. Where each value comes from:
+ *
+ *  SPEC = DriveThru Partners, "Quick Specifications for Print Books"
+ *         (help.drivethrupartners.com/hc/en-us/articles/12780800178583)
+ *  GUIDE = third-party DriveThruRPG layout guides (consistent with SPEC's
+ *         bleed rule; not stated by DriveThru itself)
+ *  CONVENTION = Gutterpress's own choice or a value DERIVED from a spec
+ *         requirement (e.g. PDF/X-1a forbids transparency) — NOT a DriveThru
+ *         requirement in its own right.
+ */
 export declare const DTRPG_PRESET: VendorPreset;
 /**
  * A neutral, vendor-agnostic default for authors who aren't targeting a

package/dist/lib/printsafe.d.ts

@@ -2,6 +2,7 @@ export declare const ruleRemoteUrls = "printsafe/no-remote-urls";
 export declare const ruleRiskyProps = "printsafe/no-risky-print-effects";
 export declare const ruleSyntax = "printsafe/syntax-error";
 export declare const rulePageContainment = "printsafe/page-containment";
+export declare const rulePreviewCannotFollow = "printsafe/preview-cannot-follow";
 export interface PrintSafeWarning {
     rule: string;
     severity: "error" | "warning";

package/dist/lib/remote-auth/sync.d.ts

@@ -61,3 +61,24 @@ export declare function refreshRemoteCopies(options: {
     refreshed: boolean;
     reason?: "no-remote" | "auth" | "offline";
 }>;
+/**
+ * Has the book's branch moved online since this copy last heard from it?
+ * Reads only the server's advertised refs (`listServerRefs`: no objects
+ * downloaded, no history walked, nothing written), so it is cheap enough to
+ * poll and safe on a dirty tree. The branch's online tip is compared with the
+ * remote-tracking ref (the last tip this copy fetched or pushed) and with the
+ * local tip: if it matches neither, someone else sent changes the author has
+ * not got. A local copy ahead of the remote is not "updates available".
+ *
+ * Best-effort like refreshRemoteCopies: it never throws; it reports why it
+ * could not tell.
+ */
+export declare function checkRemoteUpdates(options: {
+    projectDir: string;
+    credential?: HostCredential;
+    tokenStore?: TokenStore;
+    httpClient?: typeof defaultGitHttp;
+}): Promise<{
+    available: boolean;
+    reason?: "no-remote" | "auth" | "offline";
+}>;

package/dist/lib/unknown-classes.d.ts

@@ -0,0 +1,12 @@
+import type Token from "markdown-it/lib/token.mjs";
+/** One class as the markdown uses it: where it first appears, and how often. */
+export interface ClassUse {
+    line: number;
+    count: number;
+}
+/** The author-written classes the tokens carry (`gp-*` and pipeline-emitted ones left out), keyed by class. */
+export declare function classesInTokens(tokens: readonly Token[]): Map<string, ClassUse>;
+/** Add every class a selector in `css` names to `into`. Unparseable CSS contributes what a text scan finds. */
+export declare function addCssClasses(css: string, into: Set<string>): void;
+/** The known class `cls` is most likely a typo of, or null: one edit for short names, two for longer ones. */
+export declare function nearestKnownClass(cls: string, known: ReadonlySet<string>): string | null;

package/dist/{manifest.schema-gh0jjve9.json → manifest.schema-5pzhscqh.json}

@@ -200,6 +200,12 @@
           "description": "Allowed deviation, in points, between the expected and the actual page size.",
           "default": 0.5,
           "minimum": 0
+        },
+        "bleed": {
+          "type": "number",
+          "description": "A bleed, in points, that the page width x height ALREADY CONTAINS on the top, bottom and OUTER edges (none on the binding edge) — how DriveThruRPG's interior file is cut (8.625 x 11.25in for an 8.5 x 11in book). Preview overlay only: it tells the margin & bleed overlay where the trim is and changes nothing in the PDF. CSS `@page { bleed }` wins when the stylesheet declares one. Preset default: dtrpg 9 (0.125in); book and custom none.",
+          "minimum": 0,
+          "examples": [9]
         }
       }
     },
@@ -237,7 +243,7 @@
         },
         "rules": {
           "type": "object",
-          "description": "Per-rule level overrides, keyed by rule id: a printsafe rule (printsafe/no-risky-print-effects, printsafe/page-containment, printsafe/no-remote-urls) or a check id such as source.accessibility.heading-order. \"off\" silences the rule; \"warn\" / \"error\" set its severity. An id that matches no rule is ignored. To silence one site instead, put a `gutterpress-disable-next-line <rule-id> -- reason` comment (CSS `/* */` or markdown `<!-- -->`) on the line above it.",
+          "description": "Per-rule level overrides, keyed by rule id: a printsafe rule (printsafe/no-risky-print-effects, printsafe/page-containment, printsafe/preview-cannot-follow, printsafe/no-remote-urls) or a check id such as source.accessibility.heading-order. \"off\" silences the rule; \"warn\" / \"error\" set its severity. An id that matches no rule is ignored. To silence one site instead, put a `gutterpress-disable-next-line <rule-id> -- reason` comment (CSS `/* */` or markdown `<!-- -->`) on the line above it.",
           "additionalProperties": { "enum": ["off", "warn", "error"] },
           "examples": [{ "printsafe/no-risky-print-effects": "off" }]
         }

package/dist/{new-a9m2jwyy.js → new-pbd5zrds.js}

@@ -7,17 +7,17 @@ import {
   TARGET_IDS,
   scaffoldExtension,
   scaffoldProject
-} from "./cli-a4qtctrw.js";
+} from "./cli-gf1ywzeg.js";
 import {
   resolveGhostscript
-} from "./cli-zfgvssqz.js";
+} from "./cli-d0cq87s5.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-8nw6d915.js";
+} from "./cli-ytck518d.js";
 import"./cli-ht1bcqdd.js";
-import"./cli-ycbg7mxk.js";
+import"./cli-ptez7zcc.js";
 import {
   EXIT_CODES
 } from "./cli-46ycxe6r.js";

package/dist/{preflight-w3tnbtb8.js → preflight-vnkb8tj7.js}

@@ -2,17 +2,17 @@ import {
   executeValidation,
   publishTargetFor,
   reportMissingTools
-} from "./cli-a4qtctrw.js";
+} from "./cli-gf1ywzeg.js";
 import {
   log
-} from "./cli-zfgvssqz.js";
+} from "./cli-d0cq87s5.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-8nw6d915.js";
+} from "./cli-ytck518d.js";
 import"./cli-ht1bcqdd.js";
-import"./cli-ycbg7mxk.js";
+import"./cli-ptez7zcc.js";
 import {
   BuildError,
   EXIT_CODES

package/dist/preview/file-watcher.d.ts

@@ -22,7 +22,7 @@ import type { PrintPadding } from '../engine/shared/synthesis.ts';
  * no per-source wrappers or forced breaks are added, so preview pagination
  * never diverges from the PDF where a source file begins mid-page.
  */
-export declare function injectPreviewScripts(html: string): string;
+export declare function injectPreviewScripts(html: string, insetBleedPt?: number): string;
 /**
  * Generate HTML from markdown and write book.html to the temp directory.
  * The desktop's iframe loads `book.html` via a relative URL — same name in
@@ -45,6 +45,9 @@ export declare function generateAndWriteHtml(inputPath: string, tempDir: string,
     };
     extensions?: ResolvedExtensionConfig[];
     print?: PrintPadding;
+    page?: {
+        bleed?: number;
+    };
 }, cssAssets: Map<string, string>, imageRefs?: Set<string>): Promise<void>;
 /**
  * Chokidar 5's `ignored` matcher (regex or function) is tested against the

package/dist/{preview-bridge-8jhd1wpb.js → preview-bridge-evecsh4w.js}

@@ -14,7 +14,7 @@
 //
 // Commands map 1:1 to previewAPI methods: getTotalPages, getCurrentPage,
 // goToPage, firstPage, prevPage, nextPage, lastPage, setViewMode, setZoom,
-// toggleDebugMode. Plus a synthetic 'print' command that calls window.print().
+// toggleDebugMode, setMarginOverlay(on, {color, strength}). Plus a synthetic 'print' command that calls window.print().
 //
 // Additional messages:
 //   parent -> iframe: { type: 'gutterpress:inject-styles', id: <attr-name>, css: <string> }
@@ -82,6 +82,10 @@
   window.addEventListener('contextMenuRequested', function (e) {
     post({ type: 'gutterpress:event', name: 'contextMenuRequested', detail: e.detail });
   });
+  // Margin & bleed overlay result (protocol v9): {on, issues, intended, bleedPt}.
+  window.addEventListener('overlayChanged', function (e) {
+    post({ type: 'gutterpress:event', name: 'overlayChanged', detail: e.detail });
+  });
   // In-flow block editing (protocol v8). `Requested` is the double-click entry
   // point — the SPA answers it with a beginBlockEdit command. `Finished`
   // carries the edited text back for an end the AUTHOR initiated inside the

package/dist/{preview-7z8tt0b4.js → preview-g1hp0jt8.js}

@@ -7,10 +7,10 @@ import {
   runBuild,
   splitOutPath,
   startPreviewServer
-} from "./cli-a4qtctrw.js";
+} from "./cli-gf1ywzeg.js";
 import {
   log
-} from "./cli-zfgvssqz.js";
+} from "./cli-d0cq87s5.js";
 import {
   UsageError,
   parseFormat,
@@ -18,9 +18,9 @@ import {
   rejectExtraPositionals,
   rejectUnknownFlags,
   resolvePort
-} from "./cli-8nw6d915.js";
+} from "./cli-ytck518d.js";
 import"./cli-ht1bcqdd.js";
-import"./cli-ycbg7mxk.js";
+import"./cli-ptez7zcc.js";
 import {
   BuildError
 } from "./cli-46ycxe6r.js";

package/dist/{preview-interface-c44qk17f.js → preview-interface-2n1d9pbf.js}

@@ -1070,6 +1070,12 @@
       refreshPages();
       currentPage = detectVisiblePage();
       recordVisibleSource();
+      // A hot-reload swap makes this frame the active one AFTER its overlay was
+      // switched on (while hidden, where nothing is relayed): say so now.
+      var overlay = api.getMarginOverlay();
+      if (overlay && overlay.on) {
+        window.dispatchEvent(new CustomEvent('overlayChanged', { detail: overlay }));
+      }
       return api.notifyPageChange();
     },
 
@@ -1091,7 +1097,33 @@
     // floating edit panel this replaces. A v8 lib with a pre-v8 SPA loses the
     // "Edit this block" action and nothing else; a v8 SPA feature-detects on
     // the version before offering it.
-    getProtocolVersion: function () { return 8; },
+    // v9: ADDED setMarginOverlay()/toggleMarginOverlay()/getMarginOverlay() and
+    // the overlayChanged event (margin & bleed overlay, engine/viewer/
+    // overlay.ts). A v9 lib with a pre-v9 SPA simply never turns it on; a v9
+    // SPA feature-detects on the version before offering the toggle.
+    // (v9 is unreleased as of this writing, so setMarginOverlay's optional
+    // second argument — the look, below — is part of v9, not a bump.)
+    getProtocolVersion: function () { return 9; },
+
+    // Margin & bleed overlay. Viewer chrome only — it adds no box to the book
+    // and no attribute to its elements, so pagination is identical on or off.
+    // Returns the summary {on, issues, intended, bleedPt}, or null when the
+    // viewer predates it. `style` ({color: '#rrggbb', strength: 'subtle' |
+    // 'normal' | 'strong'}) is optional: it only sets the viewer's own
+    // `--gp-ov-*` tokens, and a call that carries it while the overlay is
+    // already on restyles without repainting.
+    setMarginOverlay: function (on, style) {
+      var d = window.Gutterpress && window.Gutterpress.decoration;
+      return d && typeof d.setOverlay === 'function' ? d.setOverlay(!!on, style) : null;
+    },
+    toggleMarginOverlay: function () {
+      var d = window.Gutterpress && window.Gutterpress.decoration;
+      return d && typeof d.setOverlay === 'function' ? d.setOverlay(document.body.dataset.overlay !== 'on') : null;
+    },
+    getMarginOverlay: function () {
+      var d = window.Gutterpress && window.Gutterpress.decoration;
+      return d && typeof d.overlay === 'function' ? d.overlay() : null;
+    },
 
     // Resolve the annotated element/selection at a viewport point (protocol
     // v4). Pure read; see buildContextTarget() above for the full contract.
@@ -1596,4 +1628,48 @@
   // The Gutterpress engine viewer dispatches this when its pagination
   // completes (engine/viewer/index.ts's mount()).
   window.addEventListener('gp:layout', onRenderingComplete);
+
+  // Margin & bleed overlay: relay the viewer's result as 'overlayChanged' (the
+  // bridge posts it to a host toolbar) and, where no host toolbar exists, give
+  // the standalone CLI preview its own switch: Alt+M, plus a small status pill.
+  // "Standalone" = the shell is top level (the CLI); under the desktop app the
+  // shell's parent is the app, which owns the toggle and the count.
+  var standalone = false;
+  try { standalone = window.parent === window || window.parent.parent === window.parent; } catch (_e) {}
+
+  function updateOverlayBadge(summary) {
+    var badge = document.getElementById('gp-ov-badge');
+    if (!standalone || !summary || !summary.on) {
+      if (badge) badge.remove();
+      return;
+    }
+    if (!badge) {
+      badge = document.createElement('div');
+      badge.id = 'gp-ov-badge';
+      badge.setAttribute('role', 'status');
+      badge.style.cssText = 'position:fixed;top:8px;right:8px;z-index:2147483000;pointer-events:none;' +
+        'background:rgba(20,20,24,.88);color:#fff;font:600 11px/1.4 ui-sans-serif,system-ui,sans-serif;' +
+        'padding:4px 10px;border-radius:999px;box-shadow:0 1px 6px rgba(0,0,0,.4)';
+      document.documentElement.appendChild(badge);
+    }
+    var parts = ['Margins & bleed'];
+    parts.push(summary.issues ? summary.issues + ' overflowing' : 'nothing overflows');
+    if (summary.intended) parts.push(summary.intended + ' placed on purpose');
+    if (summary.bleedInSheet) parts.push('bleed inside the page (print preset)');
+    if (!summary.bleedPt) parts.push('no bleed set \u2014 add @page { bleed: 0.125in } to see the bleed edge');
+    badge.textContent = parts.join(' \u00b7 ') + '  (Alt+M hides)';
+  }
+
+  window.addEventListener('gp:overlay', function (e) {
+    updateOverlayBadge(e.detail);
+    window.dispatchEvent(new CustomEvent('overlayChanged', { detail: e.detail }));
+  });
+
+  if (standalone) {
+    document.addEventListener('keydown', function (e) {
+      if (e.code !== 'KeyM' || !e.altKey || e.ctrlKey || e.metaKey || e.defaultPrevented) return;
+      e.preventDefault();
+      api.toggleMarginOverlay();
+    });
+  }
 })();

package/dist/{preview-shell-xwn84kqr.js → preview-shell-hyp7g158.js}

@@ -106,6 +106,15 @@
       else if (sourceBody.classList.contains('view-spread')) api.setViewMode('spread', true);
       else if (sourceBody.classList.contains('view-two-column')) api.setViewMode('two-column', true);
       if (sourceBody.classList.contains('debug')) api.toggleDebugMode();
+      // The margin & bleed overlay is a review aid the author switched on: a
+      // hot reload must not drop it.
+      // Its look (colour, strength) travels with it.
+      if (sourceBody.dataset.overlay === 'on' && api.setMarginOverlay) {
+        api.setMarginOverlay(true, {
+          color: sourceBody.style.getPropertyValue('--gp-ov-color').trim(),
+          strength: sourceBody.dataset.overlayStrength
+        });
+      }
     }
     var zoom = source.documentElement.style.getPropertyValue('--gutterpress-zoom');
     // Carry the fit flag too (setZoom's third argument clips sideways overflow).

package/dist/{publish-bbftdxh2.js → publish-vkbmf3tj.js}

@@ -11,18 +11,18 @@ import {
   publishProviderFor,
   resolvePublishFormat,
   runPublish
-} from "./cli-a4qtctrw.js";
+} from "./cli-gf1ywzeg.js";
 import {
   FileTokenStore,
   log
-} from "./cli-zfgvssqz.js";
+} from "./cli-d0cq87s5.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-8nw6d915.js";
+} from "./cli-ytck518d.js";
 import"./cli-ht1bcqdd.js";
-import"./cli-ycbg7mxk.js";
+import"./cli-ptez7zcc.js";
 import {
   EXIT_CODES
 } from "./cli-46ycxe6r.js";