gutterpress 0.10.0-alpha.4 → 0.10.0

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

@@ -10,6 +10,56 @@ export default function plugin(md: any, pluginOptions?: {}): void;
  * on its own page instead of resolving against the document canvas and
  * painting on the last page of the book.
  *
+ * `min-height: var(--gp-content-h)` is the other half of that contract: a
+ * page root that only shrink-wraps its text is a containing block whose
+ * `bottom` edge is the end of the PROSE, so `.gp-pin .gp-bottom` (and every
+ * hand-written `position: absolute; bottom: 0`) lands under the last
+ * paragraph instead of at the page foot. Paged.js used to supply this height
+ * for free — `.pagedjs_pagebox > .pagedjs_area > .pagedjs_page_content > div
+ * { height: inherit; }` stretched the page root to the page area — and
+ * deleting the polyfill (native-only migration, Phase 6) silently took
+ * page-boundary pinning with it. Both renderers now publish the page
+ * CONTENT height as `--gp-content-h` for the page context the element is in
+ * (the viewer on each `.gp-strip`; the compiler on `:root` plus every
+ * `page:` assignment selector), and custom properties inherit, so this one
+ * rule reaches a page root at any wrapper depth. Undefined var (plain
+ * markdown-it use, no engine) falls back to `1px`, which the cushion below
+ * takes back to zero — the rule is inert outside the pipeline, leaving the
+ * page root shrink-wrapped exactly as it is today.
+ *
+ * It is `min-height`, not `height`: a `.page` whose content runs past one
+ * sheet must still fragment normally. The whole rule is `:where()`, so an
+ * author who wants any of it back sets their own value at any specificity.
+ *
+ * `box-sizing` and `display` are what make a page-sized min-height safe, and
+ * both were found by MEASURING a real book (docs/fixtures/css-authoring-spike)
+ * print one extra sheet without them:
+ *
+ *   - `border-box`, because a page root with padding (that fixture's cover
+ *     has `padding-top: 2.5in`) would otherwise be one content box PLUS its
+ *     padding tall, which is one sheet plus 2.5in — the overflow lands on a
+ *     spurious blank sheet.
+ *   - `flow-root`, because a child margin collapsing THROUGH the root's edge
+ *     survives the forced break and eats into the new sheet: that fixture's
+ *     last page opens with an `<h2>` whose 22.4px margin-top pushed a
+ *     719px-tall root down 22.4px on a 720px sheet, spilling it. A page root
+ *     is a page; containing its children's margins is what a page does. The
+ *     viewer already forces `flow-root` on displaced page roots for exactly
+ *     this reason (`stabilizeFullHeightPageRoots`, fragment.ts) — declaring
+ *     it once in core means both renderers start from the same box. Zero
+ *     specificity, so an authored `display: flex`/`grid` page root still
+ *     wins, which is the case that function's comment warns about.
+ *
+ * The `- 1px` is the fragmentation cushion, and it is load-bearing. A box
+ * whose bottom edge lands EXACTLY on the fragmentainer's edge costs an empty
+ * fragment: MEASURED (Chromium 148, 384x480px sheet, 24px margins, one
+ * short page root) `min-height: 432px` prints 2 sheets with the second
+ * blank while `431px` prints 1 — and the viewer's multicol strip does the
+ * same, which is how it first showed up (an 8pp preview of a 7pp book on
+ * the gp-image-positioning fixture). One px at 96dpi is 0.75pt: it moves a
+ * pinned foot up by less than a point and absorbs sub-pixel rounding in the
+ * published value. Do not "clean it up" — the sheet it costs is silent.
+ *
  * The break/orphan rules below (`break-after` on headings, image sizing,
  * first-child glue) are all `:where()` so they carry zero specificity —
  * author CSS at any specificity wins outright, reusing this same
@@ -29,4 +79,4 @@ export default function plugin(md: any, pluginOptions?: {}): void;
  * `text-align: center` still centers it — `display: block` would not).
  *
  */
-export const MARKER_CSS: "\n/* The UA default of 8px body margin is a screen affordance with no meaning\n   in paged media, and engines disagree about it: a polyfill that treats the\n   page div as the page box drops it, native print keeps it. Left in place it\n   insets EVERY page's content by 8px per side, and -- measured, 300dpi,\n   6x4in sheet -- it is what stops a full-width block from reaching the\n   paper: it lands at 0.080..5.917in of a 6in sheet instead of\n   0.000..6.000in, because width:100% resolves against the BODY content box,\n   not the page's. Zeroing it here (first in the cascade) makes the two\n   agree. Authors who want a body margin still just declare one. */\nbody { margin: 0; }\n\n.gp-page-break { break-before: page; }\n.page { break-before: page; }\n.spread { break-before: page; }\n:where(.page, .spread) { position: relative; }\n.gp-column-break { break-after: column; height: 0; font-size: 0; line-height: 0; visibility: hidden; }\n\n:where(h1,h2,h3,h4,h5,h6) { break-after: avoid; }\n:where(img, svg, video) { max-width: 100%; }\n:where(p > img:only-child, figure > img) { width: fit-content; max-width: 100%; height: auto; vertical-align: bottom; }\n:where(.section, figure) > :where(:first-child) { break-before: avoid; }\n\n";
+export const MARKER_CSS: "\n/* The UA default of 8px body margin is a screen affordance with no meaning\n   in paged media, and engines disagree about it: a polyfill that treats the\n   page div as the page box drops it, native print keeps it. Left in place it\n   insets EVERY page's content by 8px per side, and -- measured, 300dpi,\n   6x4in sheet -- it is what stops a full-width block from reaching the\n   paper: it lands at 0.080..5.917in of a 6in sheet instead of\n   0.000..6.000in, because width:100% resolves against the BODY content box,\n   not the page's. Zeroing it here (first in the cascade) makes the two\n   agree. Authors who want a body margin still just declare one. */\nbody { margin: 0; }\n\n.gp-page-break { break-before: page; }\n.page { break-before: page; }\n.spread { break-before: page; }\n:where(.page, .spread) { position: relative; display: flow-root; box-sizing: border-box; min-height: calc(var(--gp-content-h, 1px) - 1px); }\n.gp-column-break { break-after: column; height: 0; font-size: 0; line-height: 0; visibility: hidden; }\n\n:where(h1,h2,h3,h4,h5,h6) { break-after: avoid; }\n:where(img, svg, video) { max-width: 100%; }\n:where(p > img:only-child, figure > img) { width: fit-content; max-width: 100%; height: auto; vertical-align: bottom; }\n:where(.section, figure) > :where(:first-child) { break-before: avoid; }\n\n";

package/dist/{lint-xjwm5ep8.js → lint-p2sw53d9.js}

@@ -1,16 +1,16 @@
 import {
   MANIFEST_FILENAMES,
   runLint
-} from "./cli-n25qycwz.js";
+} from "./cli-eq5naw4m.js";
 import {
   log
-} from "./cli-ra0ed2xt.js";
+} from "./cli-cqtggsng.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-0r0tq16s.js";
-import"./cli-hp9r2pzt.js";
+} from "./cli-149edp6b.js";
+import"./cli-zfcryxg8.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/{new-kwdwpf0j.js → new-hvq0x91q.js}

@@ -5,16 +5,16 @@ import {
   TARGETS,
   TARGET_IDS,
   scaffoldProject
-} from "./cli-n25qycwz.js";
+} from "./cli-eq5naw4m.js";
 import {
   resolveGhostscript
-} from "./cli-ra0ed2xt.js";
+} from "./cli-cqtggsng.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-0r0tq16s.js";
-import"./cli-hp9r2pzt.js";
+} from "./cli-149edp6b.js";
+import"./cli-zfcryxg8.js";
 import {
   isToolAvailable
 } from "./cli-c41yr7he.js";

package/dist/{plugin-rg4tnn96.js → plugin-pssmk0dx.js}

@@ -1,14 +1,14 @@
 import {
   addNpmPlugin,
   parseNpmPluginSpec
-} from "./cli-n25qycwz.js";
-import"./cli-ra0ed2xt.js";
+} from "./cli-eq5naw4m.js";
+import"./cli-cqtggsng.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-0r0tq16s.js";
-import"./cli-hp9r2pzt.js";
+} from "./cli-149edp6b.js";
+import"./cli-zfcryxg8.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/{preflight-3127y25z.js → preflight-4j00yd0g.js}

@@ -2,16 +2,16 @@ import {
   executeValidation,
   publishTargetFor,
   reportMissingTools
-} from "./cli-n25qycwz.js";
+} from "./cli-eq5naw4m.js";
 import {
   log
-} from "./cli-ra0ed2xt.js";
+} from "./cli-cqtggsng.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-0r0tq16s.js";
-import"./cli-hp9r2pzt.js";
+} from "./cli-149edp6b.js";
+import"./cli-zfcryxg8.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/{preview-ncgfhqmw.js → preview-d4s6gk6p.js}

@@ -1,15 +1,15 @@
 import {
   previewArgs
-} from "./cli-revgt4pr.js";
+} from "./cli-yzf38679.js";
 import {
   openPath,
   runBuild,
   splitOutPath,
   startPreviewServer
-} from "./cli-n25qycwz.js";
+} from "./cli-eq5naw4m.js";
 import {
   log
-} from "./cli-ra0ed2xt.js";
+} from "./cli-cqtggsng.js";
 import {
   UsageError,
   parseEngine,
@@ -18,8 +18,8 @@ import {
   rejectExtraPositionals,
   rejectUnknownFlags,
   resolvePort
-} from "./cli-0r0tq16s.js";
-import"./cli-hp9r2pzt.js";
+} from "./cli-149edp6b.js";
+import"./cli-zfcryxg8.js";
 import"./cli-c41yr7he.js";
 import {
   BuildError
@@ -82,6 +82,7 @@ var preview_default = defineCommand({
         skipLint: !!args["skip-lint"],
         skipPreValidate: !!args["skip-pre-validate"],
         skipPostValidate: !!args["skip-post-validate"],
+        allowShrink: !!args["allow-shrink"],
         engine,
         rawArgs: args
       });

package/dist/{preview-interface-435cczt5.js → preview-interface-0ssk8bmm.js}

@@ -331,6 +331,125 @@
     return null;
   }
 
+  // Full hit stack at a point, top-most first. Degrades to the single
+  // elementFromPoint() hit on hosts without elementsFromPoint().
+  function elementStackAtPoint(x, y) {
+    try {
+      if (typeof document.elementsFromPoint === 'function') {
+        var els = document.elementsFromPoint(x, y);
+        if (els && els.length) return Array.prototype.slice.call(els);
+      }
+    } catch (_e) { /* fall through to the single-element path */ }
+    var el = elementAtPoint(x, y);
+    return el ? [el] : [];
+  }
+
+  // Computed z-index as a number; NaN for 'auto'/unset/unsupported hosts
+  // (NaN < 0 is false, so those never qualify as behind-layered below).
+  function zIndexOf(el) {
+    try {
+      if (typeof window.getComputedStyle === 'function') {
+        return parseFloat(window.getComputedStyle(el).zIndex);
+      }
+    } catch (_e) { /* unsupported host */ }
+    return NaN;
+  }
+
+  // Why elementsFromPoint (plural) exists here: a `.gp-behind` image — the
+  // image-properties "Layer" facet sets `z-index: -1` to paint a pinned
+  // plate UNDER the page's own text (gutterpress-css.ts's depth ladder) —
+  // hit-tests beneath the covering paragraph boxes and the annotated
+  // `.page`/`.section` containers too, so document.elementFromPoint() can
+  // NEVER return it. Every right-click used to resolve the covering element
+  // instead, leaving the image's context menu unreachable at EVERY point.
+  // Probe the full hit stack for the first (= top-most in paint order, so
+  // the upper of two overlapping plates wins) image layered at negative z.
+  // ONLY negative-z images qualify: a normally-layered image that merely
+  // overlaps other content is already reachable at its uncovered points,
+  // and stealing the covering content's right-clicks would invert the bug.
+  // Computed style, not a `gp-behind` class test, mirrors the build-time
+  // engine.layer.trapped audit — book CSS can layer an image behind with a
+  // bare `z-index: -1` of its own.
+  function behindImageInStack(stack) {
+    for (var i = 0; i < stack.length; i++) {
+      var el = stack[i];
+      if (el.tagName && el.tagName.toLowerCase() === 'img' && zIndexOf(el) < 0) return el;
+    }
+    return null;
+  }
+
+  // The .gp-sheet whose box contains a viewport point, or null. The sheet
+  // chrome lives in the hit-transparent .gp-layer (viewer.css), so it can
+  // never appear in the hit stack — this is a geometric scan of the cached
+  // page list (refreshPages), not a DOM hit test.
+  function sheetAtPoint(x, y) {
+    if (pages.length === 0) refreshPages();
+    for (var i = 0; i < pages.length; i++) {
+      var r = pages[i].getBoundingClientRect();
+      if (x >= r.left && x <= r.right && y >= r.top && y <= r.bottom) return pages[i];
+    }
+    return null;
+  }
+
+  // The annotated .page/.spread wrapper that OWNS a sheet: greatest
+  // client-rect intersection with the sheet's box — the same rect-vs-sheet
+  // resolution nativeRectsFor() uses. Null when the page has no author
+  // @page/@spread wrapper (plain flowed content) — callers then keep the
+  // plain hit result.
+  function pageMarkerElForSheet(sheet) {
+    var sheetRect = sheet.getBoundingClientRect();
+    var candidates = document.querySelectorAll('.page[data-source-range], .spread[data-source-range]');
+    var best = null;
+    var bestArea = 0;
+    for (var i = 0; i < candidates.length; i++) {
+      var rects = rectsOf(candidates[i]);
+      for (var j = 0; j < rects.length; j++) {
+        var r = rects[j];
+        var width = Math.min(r.right, sheetRect.right) - Math.max(r.left, sheetRect.left);
+        var height = Math.min(r.bottom, sheetRect.bottom) - Math.max(r.top, sheetRect.top);
+        var area = width > 0 && height > 0 ? width * height : 0;
+        if (area > bestArea) {
+          bestArea = area;
+          best = candidates[i];
+        }
+      }
+    }
+    return best;
+  }
+
+  // The element getContextTargetAt() resolves the payload from. `topmostOnly`
+  // (the keyboard path) skips the behind-image probe: its anchor is a
+  // SYNTHETIC block-center point (keyboardAnchorPoint()), not a user-aimed
+  // pointer position — probing beneath it would hijack every keyboard menu
+  // on a page with a background plate.
+  function contextPointEl(x, y, topmostOnly) {
+    var stack = elementStackAtPoint(x, y);
+    var topEl = stack.length ? stack[0] : null;
+    if (topmostOnly || !topEl || !topEl.closest) return topEl;
+    // The user aimed at visible interactive content — a directly-hit image
+    // (an <img> only ever matches closest('img') as itself: images have no
+    // descendants) or a link's own text — never probe beneath those.
+    if (topEl.closest('img') || topEl.closest('a')) return topEl;
+    // Margin-box furniture (running headers, page numbers) keeps its native
+    // context menu even when a full-bleed plate runs beneath it — the
+    // contextmenu listener's kind==='none' contract below.
+    if (topEl.closest('.gp-marginbox')) return topEl;
+    var behind = behindImageInStack(stack);
+    if (behind) return behind;
+    // Margin band (protocol v7): the point sits in a page's margin — outside
+    // every author box, so nothing annotated is under it (the sheet chrome
+    // and the run/strip boxes are hit-transparent viewer chrome). When the
+    // point still lies inside a .gp-sheet, resolve to the annotated
+    // .page/.spread that owns that sheet, so right-clicking anywhere on the
+    // paper reaches the @page marker, not just the content box.
+    if (!resolveAnnotatedBlock(topEl)) {
+      var sheet = sheetAtPoint(x, y);
+      var owner = sheet ? pageMarkerElForSheet(sheet) : null;
+      if (owner) return owner;
+    }
+    return topEl;
+  }
+
   function elementOf(node) {
     if (!node) return null;
     return node.nodeType === 1 ? node : (node.parentElement || null);
@@ -454,6 +573,21 @@
 
     var block = resolveAnnotatedBlock(pointEl);
 
+    // Secondary page-marker target (protocol v7): resolveAnnotatedBlock()
+    // returns the INNERMOST annotated block, so inside a @section the
+    // enclosing @page marker never wins the primary slot. Surface the
+    // enclosing .page/.spread/.chapter wrapper's own marker line as a
+    // secondary field — the same always-populated pattern image/link/
+    // selection use — so the menu can offer "Edit page marker…" when it
+    // differs from the primary target.
+    var pageMarkerEl = pointEl && pointEl.closest ? pointEl.closest('.page, .spread, .chapter') : null;
+    var pageMarkerRange = pageMarkerEl ? sourceRangeOf(pageMarkerEl) : null;
+    var pageMarker = pageMarkerRange ? {
+      chapter: chapterOf(pageMarkerEl),
+      range: pageMarkerRange,
+      blockTag: pageMarkerEl.tagName ? pageMarkerEl.tagName.toLowerCase() : null
+    } : null;
+
     var kind;
     if (selection) kind = 'selection';
     else if (image) kind = 'image';
@@ -471,7 +605,8 @@
       rect: plainRect(block || pointEl),
       image: image,
       link: link,
-      selection: selection
+      selection: selection,
+      pageMarker: pageMarker
     };
   }
 
@@ -609,8 +744,10 @@
         // `setSpread()` does the real relayout: `column-wrap: wrap` wraps each
         // chapter's columns into a 2-column grid so content, not just sheet
         // chrome, actually moves into pairs — see fragment.ts's
-        // `applySpreadMode`. No-ops to single-row on a browser without the
-        // capability (Firefox/Safari as of this writing).
+        // `applySpreadMode`, which no-ops to single-row where CSS
+        // `column-wrap`/`column-height` are unavailable (Chromium < 145).
+        // The guard below is a LIB-version check, not a browser one: a
+        // hot-updated shell may be paired with an older bundled viewer.
         if (window.Gutterpress && typeof window.Gutterpress.setSpread === 'function') {
           window.Gutterpress.setSpread(currentViewMode !== 'single');
         }
@@ -660,13 +797,21 @@
     // v6 (WORK PACKAGE B item 2): getRectsFor()/setEditMask() dropped the
     // {ref} form entirely — {chapter, range} is the only target shape now
     // (the native viewer never mints a ref — it never clones).
-    getProtocolVersion: function () { return 6; },
+    // v7: getContextTargetAt() gained the `pageMarker` secondary field (the
+    // enclosing .page/.spread/.chapter marker) and the margin-band fallback
+    // (a point inside a .gp-sheet but outside every author box resolves to
+    // the sheet's owning .page/.spread). An older SPA simply ignores the
+    // extra field; a newer SPA feature-detects by the field's presence.
+    getProtocolVersion: function () { return 7; },
 
     // Resolve the annotated element/selection at a viewport point (protocol
     // v4). Pure read; see buildContextTarget() above for the full contract.
+    // Point resolution prefers a behind-layered (negative z-index) image the
+    // top-most hit covers — see contextPointEl(); `spec.topmostOnly` opts a
+    // synthetic-anchor caller (the keyboard listener) out of that probe.
     getContextTargetAt: function (spec) {
       spec = spec || {};
-      return buildContextTarget(elementAtPoint(spec.x, spec.y));
+      return buildContextTarget(contextPointEl(spec.x, spec.y, spec.topmostOnly));
     },
 
     // All fragment rects for one logical block (protocol v6, §5.3), targeted
@@ -976,7 +1121,9 @@
       var isMenuKey = e.key === 'ContextMenu';
       if (!isShiftF10 && !isMenuKey) return;
       var anchor = keyboardAnchorPoint();
-      var detail = api.getContextTargetAt({ x: anchor.x, y: anchor.y });
+      // topmostOnly: the anchor is a synthetic block-center point, so the
+      // behind-image probe must not run — see contextPointEl().
+      var detail = api.getContextTargetAt({ x: anchor.x, y: anchor.y, topmostOnly: true });
       detail.x = anchor.x;
       detail.y = anchor.y;
       detail.via = 'keyboard';

package/dist/{publish-pr0rwh6p.js → publish-tkc26en7.js}

@@ -7,17 +7,17 @@ import {
   publishCredentialKey,
   publishProviderFor,
   runPublish
-} from "./cli-n25qycwz.js";
+} from "./cli-eq5naw4m.js";
 import {
   FileTokenStore,
   log
-} from "./cli-ra0ed2xt.js";
+} from "./cli-cqtggsng.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-0r0tq16s.js";
-import"./cli-hp9r2pzt.js";
+} from "./cli-149edp6b.js";
+import"./cli-zfcryxg8.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/render.js

@@ -172,6 +172,9 @@ function warn(env, line, type, message, marker) {
     env.layoutWarnings = [];
   env.layoutWarnings.push({ line, type, message, marker });
 }
+function proseEscapeHint(kind) {
+  return ` If this line is prose that happens to begin with "@${kind}" — a wrapped sentence, for` + ` instance — escape it as \\@${kind} or write it as \`@${kind}\` in backticks, and it stays text.`;
+}
 function addClasses(token, baseClass, extraClass) {
   const cls = [];
   if (baseClass)
@@ -233,14 +236,14 @@ function plugin(md, pluginOptions = {}) {
       const unknown = parsed.__unknownTokens;
       delete parsed.__unknownTokens;
       for (const t of unknown) {
-        warn(state.env, startLine + 1, "unrecognized_marker_token", `@${parsed.kind}: "${t}" is not something a marker understands, so it was kept verbatim as a class name. Write a class as .my-class (or {.my-class}), an id as #my-id, and anything else as key=value.`, parsed);
+        warn(state.env, startLine + 1, "unrecognized_marker_token", `@${parsed.kind}: "${t}" is not something a marker understands, so it was kept verbatim as a class name. Write a class as .my-class (or {.my-class}), an id as #my-id, and anything else as key=value.` + proseEscapeHint(parsed.kind), parsed);
       }
     }
     if (parsed.__extraBareTokens) {
       const { tokens, named } = parsed.__extraBareTokens;
       delete parsed.__extraBareTokens;
       const list = tokens.map((t) => `"${t}"`).join(", ");
-      warn(state.env, startLine + 1, "extra_bare_marker_token", named ? `@${parsed.kind}: only the first plain word (${list.split(", ")[0]}) is used as the name; the rest (${tokens.slice(1).map((t) => `"${t}"`).join(", ")}) became class names instead. Quote a name that contains spaces ("${tokens.join(" ")}"), or write classes as .${tokens.slice(1).join(" .")}.` : `@${parsed.kind}: ${list} are several plain words, but a marker has only one name slot — so NONE of them was used as the name and they all became class names instead. Quote a name that contains spaces ("${tokens.join(" ")}"), or write classes as .${tokens.join(" .")}.`, parsed);
+      warn(state.env, startLine + 1, "extra_bare_marker_token", named ? `@${parsed.kind}: only the first plain word (${list.split(", ")[0]}) is used as the name; the rest (${tokens.slice(1).map((t) => `"${t}"`).join(", ")}) became class names instead. Quote a name that contains spaces ("${tokens.join(" ")}"), or write classes as .${tokens.slice(1).join(" .")}.` : `@${parsed.kind}: ${list} are several plain words, but a marker has only one name slot — so NONE of them was used as the name and they all became class names instead. Quote a name that contains spaces ("${tokens.join(" ")}"), or write classes as .${tokens.join(" .")}.` + proseEscapeHint(parsed.kind), parsed);
     }
     state.line = startLine + 1;
     return true;
@@ -332,7 +335,12 @@ function plugin(md, pluginOptions = {}) {
       t.meta = { line: meta.__line };
       addClasses(t, "spread", meta.attrs && meta.attrs.class ? meta.attrs.class : "");
       attachDataAttrs(t, "spread", meta.name, meta.attrs || {});
-      stack.open({ kind: "spread", noPagesYet: true, sawAnyPage: false }, t);
+      stack.open({
+        kind: "spread",
+        classes: meta.attrs && meta.attrs.class || "",
+        noPagesYet: true,
+        sawAnyPage: false
+      }, t);
     }
     function openPage(meta) {
       const chapter = stack.get("chapter");
@@ -347,7 +355,7 @@ function plugin(md, pluginOptions = {}) {
       const label = chapter ? chapter.label : "";
       if (label)
         t.attrSet("data-chapter-label", label);
-      stack.open({ kind: "page" }, t);
+      stack.open({ kind: "page", classes: explicit }, t);
       if (label && !chapter.openerEmitted) {
         const opener = new state.Token("html_block", "", 0);
         opener.content = `<div class="chapter-opener" data-chapter-label="${escapeAttr(label)}">${escapeHtml(label)}</div>
@@ -370,13 +378,51 @@ function plugin(md, pluginOptions = {}) {
       t.meta = { hasColumnBreak: false, line: meta.__line };
       stack.open({
         kind: "section",
+        classes: meta.attrs && meta.attrs.class || "",
+        sawContent: false,
         meta: { name: meta.name || null, attrs: { ...meta.attrs || {} } },
         openToken: t
       }, t);
     }
+    function breakHost() {
+      return stack.get("section") || stack.get("page") || stack.get("spread");
+    }
+    function gridClassOf(frame) {
+      if (!frame || !frame.classes)
+        return null;
+      return frame.classes.split(/\s+/).find((c) => c.startsWith("gp-grid-")) || null;
+    }
+    function warnBreakInsideGrid(kind, line, meta) {
+      const host = breakHost();
+      const gridClass = gridClassOf(host);
+      if (!gridClass)
+        return;
+      warn(state.env, line, "break_inside_grid", `@${kind} inside a grid container: the enclosing @${host.kind} carries .${gridClass}, so this break's <div> becomes a grid ITEM — it takes a cell of its own, corrupts the grid's placement, and print and the live preview then disagree about which page the content after it lands on. Move the break outside the grid @${host.kind}, or remove it — grid rows already flow and fragment across pages on their own.`, meta);
+    }
+    function warnIfEmptyDecoratedSection(closingKind, closingLine) {
+      const sec = stack.get("section");
+      if (!sec || sec.sawContent)
+        return;
+      const attrs = sec.meta && sec.meta.attrs || {};
+      const decorations = [];
+      for (const c of (attrs.class || "").split(/\s+/).filter(Boolean))
+        decorations.push(`.${c}`);
+      for (const [k, v] of Object.entries(attrs)) {
+        if (k === "class")
+          continue;
+        decorations.push(k === "id" ? `#${v}` : `${k}=${v}`);
+      }
+      if (!decorations.length)
+        return;
+      const openLine = sec.openToken && sec.openToken.meta && Number.isFinite(sec.openToken.meta.line) ? sec.openToken.meta.line : closingLine;
+      warn(state.env, openLine, "empty_section", `This @section (${decorations.join(" ")}) was closed by the @${closingKind} on line ${closingLine} with no content between the two markers, so its styling applies to an empty element and nothing prints the layout it asked for. Delete one of the two markers, or move the content that belongs inside the section between them.`, null);
+    }
     for (let i = 0;i < state.tokens.length; i++) {
       const tok = state.tokens[i];
       if (tok.type !== "layout_marker") {
+        const openSectionFrame = stack.get("section");
+        if (openSectionFrame)
+          openSectionFrame.sawContent = true;
         out.push(tok);
         continue;
       }
@@ -402,6 +448,7 @@ function plugin(md, pluginOptions = {}) {
         continue;
       }
       if (kind === "section") {
+        warnIfEmptyDecoratedSection("section", line);
         stack.close("section");
         const spread = stack.get("spread");
         if (spread && spread.noPagesYet) {
@@ -430,6 +477,7 @@ function plugin(md, pluginOptions = {}) {
         continue;
       }
       if (kind === "page-break") {
+        warnBreakInsideGrid("page-break", line, meta);
         const t = new state.Token("layout_page_break", "div", 0);
         t.meta = { line };
         t.attrSet("class", "gp-page-break");
@@ -438,6 +486,7 @@ function plugin(md, pluginOptions = {}) {
         continue;
       }
       if (kind === "column-break") {
+        warnBreakInsideGrid("column-break", line, meta);
         const openSectionFrame = stack.get("section");
         if (openSectionFrame && openSectionFrame.openToken && !openSectionFrame.openToken.meta.hasColumnBreak) {
           const sectionCls = openSectionFrame.openToken.attrGet("class") || "";
@@ -453,6 +502,7 @@ function plugin(md, pluginOptions = {}) {
         continue;
       }
       if (kind === "end-section") {
+        warnIfEmptyDecoratedSection("end-section", line);
         stack.close("section");
         continue;
       }
@@ -540,7 +590,7 @@ body { margin: 0; }
 .gp-page-break { break-before: page; }
 .page { break-before: page; }
 .spread { break-before: page; }
-:where(.page, .spread) { position: relative; }
+:where(.page, .spread) { position: relative; display: flow-root; box-sizing: border-box; min-height: calc(var(--gp-content-h, 1px) - 1px); }
 .gp-column-break { break-after: column; height: 0; font-size: 0; line-height: 0; visibility: hidden; }
 
 :where(h1,h2,h3,h4,h5,h6) { break-after: avoid; }
@@ -624,6 +674,26 @@ var GUTTERPRESS_CSS = `
 .gp-columns-2 { columns: 2; column-gap: var(--gp-column-gap, 1.5em); }
 .gp-columns-3 { columns: 3; column-gap: var(--gp-column-gap, 1.5em); }
 
+/* grid runs — the SLOTTED counterpart to the column runs above. Grid places
+   each child into the next cell, across then down (deterministic slots: card
+   layouts, stat blocks, image-plus-caption pairs); columns FLOW one text run
+   down then across. Same neutral-primitive rationale as .gp-columns-*, and
+   permanent vocabulary for the same reason: standard CSS Grid verbatim, no
+   spec gap to remove later. MEASURED (Chromium 151, gp-grid evidence pack):
+   grid rows fragment across sheets with EXACT print/viewer parity — 2- and
+   3-col, unequal item heights, mid-row cuts, multi-sheet overflow,
+   break-inside:avoid, gap geometry — so a grid taller than the page is safe,
+   no fit-one-page constraint. Two things to know, not fix:
+     - on a min-height page root (MARKER_CSS), default align-content
+       stretches rows apart to fill the page — identically in both engines.
+       Authors wanting packed rows set align-content: start.
+     - a @page-break / @column-break marker DIRECTLY inside a grid container
+       becomes a grid item and corrupts placement (the one measured parity
+       break); markers.js diagnoses it (break_inside_grid).
+   --gp-grid-gap is author-settable. */
+.gp-grid-2 { display: grid; grid-template-columns: repeat(2, 1fr); gap: var(--gp-grid-gap, 1.5em); }
+.gp-grid-3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--gp-grid-gap, 1.5em); }
+
 /* shape wrap — text follows the image's alpha silhouette instead of its
    rectangular box. shape-outside only applies to floats, so this is inert
    without .gp-left/.gp-right (and under .gp-pin, which un-floats). The
@@ -686,8 +756,14 @@ img.gp-shape {
        opacity, filter, transform on it traps the negative layer inside).
        Core keeps .page/.spread at 'position: relative; z-index: auto'
        precisely so they are not stacking contexts.
-     - a clipping ancestor (overflow other than visible), the same mechanism
-       that clips a .gp-bleed plate back to the wrapper's width.
+     - a clipping ancestor (overflow other than visible) — but only where
+       the art actually overhangs that ancestor's clip box on a clipped
+       axis: the overhang is cut off, the same mechanism that clips a
+       .gp-bleed plate back to the wrapper's width. Clipping never reorders
+       layers — within-bounds art under a clipping .page prints whole and
+       still behind (measured; see the build audit's comment in
+       engine/compiler/build.ts), and a static wrapper's overflow never
+       binds an abspos .gp-pin at all.
    The build-time engine.layer.trapped audit reports both against the live
    ancestor chain. printsafe/page-containment is only an early source hint for
    declarations written directly on .page/.spread. */

package/dist/{repair-8270smfw.js → repair-2va4w12t.js}

@@ -5,17 +5,17 @@ import {
   isUnbornRepo,
   repairRepo,
   verifyRepoReadable
-} from "./cli-n25qycwz.js";
+} from "./cli-eq5naw4m.js";
 import {
   FileTokenStore,
   defaultConfigDir
-} from "./cli-ra0ed2xt.js";
+} from "./cli-cqtggsng.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-0r0tq16s.js";
-import"./cli-hp9r2pzt.js";
+} from "./cli-149edp6b.js";
+import"./cli-zfcryxg8.js";
 import"./cli-c41yr7he.js";
 import"./cli-46ycxe6r.js";
 import"./cli-k1065rkg.js";

package/dist/{validate-54e17rae.js → validate-w9vfefrw.js}

@@ -1,15 +1,15 @@
 import {
   executeAndReport
-} from "./cli-n25qycwz.js";
+} from "./cli-eq5naw4m.js";
 import {
   log
-} from "./cli-ra0ed2xt.js";
+} from "./cli-cqtggsng.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-0r0tq16s.js";
-import"./cli-hp9r2pzt.js";
+} from "./cli-149edp6b.js";
+import"./cli-zfcryxg8.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gutterpress",
-  "version": "0.10.0-alpha.4",
+  "version": "0.10.0",
   "description": "Markdown-to-PDF converter for professional print layout using a native Chromium print engine and Ghostscript.",
   "author": "itlackey",
   "license": "MPL-2.0",