gutterpress 0.10.5 → 0.10.6-beta.2

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   UsageError,
   package_default,
   rejectUnknownFlags
-} from "./cli-v031r2h6.js";
+} from "./cli-980t4qp9.js";
 import {
   EXIT_CODES
 } from "./cli-46ycxe6r.js";
@@ -18,16 +18,16 @@ import {
 import { defineCommand, parseArgs, runMain } from "citty";
 import { statSync } from "node:fs";
 var SUBCOMMANDS = {
-  new: () => import("./new-yf8emyp3.js").then((m) => m.default),
-  preview: () => import("./preview-g2f5982y.js").then((m) => m.default),
-  build: () => import("./build-79dv44cn.js").then((m) => m.default),
-  publish: () => import("./publish-6vt6yqm4.js").then((m) => m.default),
-  lint: () => import("./lint-wweg6pf0.js").then((m) => m.default),
-  validate: () => import("./validate-vjwgxswp.js").then((m) => m.default),
-  audit: () => import("./audit-ax5ps29k.js").then((m) => m.default),
-  preflight: () => import("./preflight-d34pzgr6.js").then((m) => m.default),
-  doctor: () => import("./doctor-qejmbv32.js").then((m) => m.default),
-  plugin: () => import("./plugin-dj6crat4.js").then((m) => m.default)
+  new: () => import("./new-cgnm1vz6.js").then((m) => m.default),
+  preview: () => import("./preview-670h69jp.js").then((m) => m.default),
+  build: () => import("./build-by1rwswq.js").then((m) => m.default),
+  publish: () => import("./publish-zw39dmgm.js").then((m) => m.default),
+  lint: () => import("./lint-p5m5gn2f.js").then((m) => m.default),
+  validate: () => import("./validate-2fnfyyx8.js").then((m) => m.default),
+  audit: () => import("./audit-gwhqj45v.js").then((m) => m.default),
+  preflight: () => import("./preflight-gypyj54v.js").then((m) => m.default),
+  doctor: () => import("./doctor-gxetpd6x.js").then((m) => m.default),
+  plugin: () => import("./plugin-2zwx1tex.js").then((m) => m.default)
 };
 var VERSION = package_default.version;
 var main = defineCommand({
@@ -52,7 +52,7 @@ async function preflightRequiredInvocations(rawArgs) {
   const [command, ...commandArgs] = rawArgs;
   try {
     if (command === "new") {
-      const { newArgs } = await import("./new-yf8emyp3.js");
+      const { newArgs } = await import("./new-cgnm1vz6.js");
       rejectUnknownFlags(commandArgs, newArgs, "new");
       const parsed2 = parseArgs(commandArgs, {
         ...newArgs,
@@ -64,7 +64,7 @@ async function preflightRequiredInvocations(rawArgs) {
       return;
     }
     if (command === "preflight") {
-      const { preflightArgs } = await import("./preflight-d34pzgr6.js");
+      const { preflightArgs } = await import("./preflight-gypyj54v.js");
       rejectUnknownFlags(commandArgs, preflightArgs, "preflight");
       const parsed2 = parseArgs(commandArgs, {
         ...preflightArgs,
@@ -88,7 +88,7 @@ async function preflightRequiredInvocations(rawArgs) {
     if (subcommand !== "add") {
       throw new UsageError(`gutterpress plugin: unknown command "${subcommand}"`);
     }
-    const { pluginAddArgs } = await import("./plugin-dj6crat4.js");
+    const { pluginAddArgs } = await import("./plugin-2zwx1tex.js");
     rejectUnknownFlags(subcommandArgs, pluginAddArgs, "plugin add");
     const parsed = parseArgs(subcommandArgs, {
       ...pluginAddArgs,

package/dist/{doctor-qejmbv32.js → doctor-gxetpd6x.js}

@@ -1,12 +1,12 @@
 import {
   getSystemDiagnostics,
   log
-} from "./cli-5pq315qe.js";
+} from "./cli-vntks53w.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-v031r2h6.js";
+} from "./cli-980t4qp9.js";
 import"./cli-c41yr7he.js";
 import"./cli-46ycxe6r.js";
 import"./cli-37x76zdn.js";

package/dist/{engine-mtyjc4v6.js → engine-4ctgbwj5.js}

@@ -1,6 +1,6 @@
 import {
   build
-} from "./index-ja0p4w5f.js";
+} from "./index-eyzv51dw.js";
 import {
   BuildError,
   RENDER_TIMEOUT_MS,

package/dist/{engine-fwe8djyn.js → engine-bhhcne06.js}

@@ -4,7 +4,7 @@ import {
   build,
   connectChromium,
   getBrowser
-} from "./cli-0t4zfevc.js";
+} from "./cli-bwbs3qm4.js";
 import"./cli-c41yr7he.js";
 import {
   BuildError

package/dist/{index-ya1yw5me.js → index-dxvn0dr9.js}

@@ -1186,6 +1186,8 @@ body { margin: 0; }
 :where(h1,h2,h3,h4,h5,h6) { break-after: avoid; }
 :where(img, svg, video) { max-width: 100%; }
 :where(p > img:only-child, figure > img) { width: fit-content; max-width: 100%; height: auto; vertical-align: bottom; }
+:where(p) > :where(img:not([class])) { max-height: calc(var(--gp-content-h) - 4px); object-fit: contain; }
+:where(figure) { break-inside: avoid; }
 :where(.section, figure) > :where(:first-child) { break-before: avoid; }
 
 `;
@@ -1264,6 +1266,32 @@ 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); }
 
+/* the per-shape decisions the paragraph above deliberately leaves to the
+   author, named instead of left as raw CSS every book was reinventing
+   (2026-09-01 CSS architecture review, findings C1/C7 — CLAUDE.md §0:
+   "behavior broadly useful to non-technical authors belongs in core").
+   Permanent vocabulary, standard properties verbatim — same rationale as
+   the column/grid runs above. One name each, no aliases:
+     .gp-columns-all       column-span: all      a heading or block that
+                                                  spans every column in the
+                                                  run it sits inside.
+     .gp-columns-flow      column-fill: auto     a run that FRAGMENTS across
+                                                  pages — every page's
+                                                  columns fill instead of
+                                                  only the last one
+                                                  balancing (the dead-column
+                                                  collapse the build's
+                                                  engine.multicol.dead-column
+                                                  warning names this fix
+                                                  for).
+     .gp-columns-balanced  column-fill: balance  a run that fits on ONE
+                                                  page (the CSS initial
+                                                  value — ragged columns
+                                                  would be wrong here). */
+.gp-columns-all { column-span: all; }
+.gp-columns-flow { column-fill: auto; }
+.gp-columns-balanced { column-fill: balance; }
+
 /* 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
@@ -1284,6 +1312,15 @@ var GUTTERPRESS_CSS = `
 .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); }
 
+/* fragmentation controls — generic pagination utilities for any element,
+   independent of the column/grid vocabulary above (a book reached for
+   these just as often outside a multicol run: keeping a card whole,
+   forcing a section to start a fresh page). Standard properties only —
+   this project is Chromium-only (CLAUDE.md), so there are no legacy
+   page-break-* twins to also emit. One name each. */
+.gp-no-break { break-inside: avoid; }
+.gp-break-before { break-before: page; }
+
 /* 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
@@ -1368,6 +1405,39 @@ img.gp-shape {
 .gp-raised { z-index: var(--gp-z-raised); }
 .gp-front  { z-index: var(--gp-z-front); }
 `;
+var GP_CLASSES = new Set([
+  "gp-left",
+  "gp-right",
+  "gp-center",
+  "gp-full",
+  "gp-bleed",
+  "gp-small",
+  "gp-medium",
+  "gp-large",
+  "gp-tight",
+  "gp-loose",
+  "gp-columns-2",
+  "gp-columns-3",
+  "gp-columns-all",
+  "gp-columns-flow",
+  "gp-columns-balanced",
+  "gp-no-break",
+  "gp-break-before",
+  "gp-grid-2",
+  "gp-grid-3",
+  "gp-shape",
+  "gp-pin",
+  "gp-top",
+  "gp-bottom",
+  "gp-behind",
+  "gp-base",
+  "gp-raised",
+  "gp-front",
+  "gp-page-break",
+  "gp-column-break",
+  "gp-continued",
+  "gp-flush"
+]);
 
 // src/lib/markdown/renderer.ts
 import MarkdownIt from "markdown-it";
@@ -1444,12 +1514,70 @@ function warn3(env, line, type, message, marker) {
     env.layoutWarnings = [];
   env.layoutWarnings.push({ line, type, message, marker });
 }
+function editDistance2(a, b) {
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1;i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1;j <= b.length; j++) {
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = cur;
+  }
+  return prev[b.length];
+}
+function nearestGpClass(cls) {
+  const threshold = Math.max(2, Math.floor(cls.length / 3));
+  let best = null;
+  let bestDistance = Infinity;
+  for (const known of GP_CLASSES) {
+    const d = editDistance2(cls, known);
+    if (d < bestDistance) {
+      bestDistance = d;
+      best = known;
+    }
+  }
+  return best !== null && bestDistance > 0 && bestDistance <= threshold ? best : null;
+}
+function hasPinClass(token) {
+  const cls = token.attrGet && token.attrGet("class");
+  return typeof cls === "string" && cls.split(/\s+/).includes("gp-pin");
+}
+function elementNameFor(token) {
+  switch (token.type) {
+    case "layout_chapter_open":
+      return "@chapter";
+    case "layout_spread_open":
+      return "@spread";
+    case "layout_page_open":
+      return "@page";
+    case "layout_section_open":
+      return "@section";
+    case "image":
+      return "an image";
+    case "heading_open":
+      return "a heading";
+    case "paragraph_open":
+      return "a paragraph";
+    case "link_open":
+      return "a link";
+    default:
+      return token.tag ? `a <${token.tag}>` : "an element";
+  }
+}
+function checkUnknownGpClasses(token, env, line) {
+  const cls = token.attrGet && token.attrGet("class");
+  if (typeof cls !== "string" || !cls)
+    return;
+  for (const c of cls.split(/\s+/)) {
+    if (!c.startsWith("gp-") || GP_CLASSES.has(c))
+      continue;
+    const suggestion = nearestGpClass(c);
+    const base = `Unknown class "${c}" on ${elementNameFor(token)}.`;
+    warn3(env, line, "unknown_gp_class", suggestion ? `${base} Did you mean "${suggestion}"?` : base);
+  }
+}
 function gpPinScope(md) {
   const PIN_OUTSIDE_PAGE_MSG = "A .gp-pin element is not inside any @page or @spread, so it is pinned to the whole document instead of the page it sits on — it can print on a completely different sheet. Move it inside an @page or @spread block, or remove .gp-pin.";
-  function hasPinClass(token) {
-    const cls = token.attrGet && token.attrGet("class");
-    return typeof cls === "string" && cls.split(/\s+/).includes("gp-pin");
-  }
   md.core.ruler.push("gp_pin_scope_check", function(state) {
     let depth = 0;
     for (const token of state.tokens) {
@@ -1468,6 +1596,13 @@ function gpPinScope(md) {
           warn3(state.env, (token.map?.[0] ?? 0) + 1, "pin_outside_page", PIN_OUTSIDE_PAGE_MSG);
         }
       }
+      const line = (token.map?.[0] ?? 0) + 1;
+      checkUnknownGpClasses(token, state.env, line);
+      if (token.type === "inline" && token.children) {
+        for (const child of token.children) {
+          checkUnknownGpClasses(child, state.env, line);
+        }
+      }
     }
   });
 }
@@ -1991,10 +2126,15 @@ ${rendered}
     opts.onImageRefs([...imageRefs]);
   }
   const inlineCss = [
+    "@layer gp.marker, gp.vocab;",
     `/* gutterpress markers */
-${MARKER_CSS.trim()}`,
+@layer gp.marker {
+${MARKER_CSS.trim()}
+}`,
     `/* gutterpress */
-${GUTTERPRESS_CSS.trim()}`,
+@layer gp.vocab {
+${GUTTERPRESS_CSS.trim()}
+}`,
     pluginCss ? `/* user plugin css */
 ${pluginCss.trim()}` : null,
     projectCss ? `/* project css */
@@ -3978,7 +4118,7 @@ import git from "isomorphic-git";
 // package.json
 var package_default = {
   name: "gutterpress",
-  version: "0.10.5",
+  version: "0.10.6-beta.2",
   description: "Markdown-to-PDF converter for professional print layout using a native Chromium print engine and Ghostscript.",
   author: "itlackey",
   license: "MPL-2.0",
@@ -4839,26 +4979,33 @@ function getTextPass(doc) {
     p = (async () => {
       const textByPage = [];
       const positions = [];
+      const runsByPage = [];
       for (let i = 1;i <= doc.numPages; i++) {
         try {
           const page = await doc.getPage(i);
           const tc = await page.getTextContent();
           let pageText = "";
+          const runs = [];
           for (const item of tc.items) {
             const it = item;
             if (typeof it.str !== "string")
               continue;
             pageText += it.str;
             if (it.transform && it.str.trim().length > 0) {
-              positions.push({ x: it.transform[4], y: it.transform[5] });
+              const x = it.transform[4];
+              const y = it.transform[5];
+              positions.push({ x, y });
+              runs.push({ s: it.str, x, y, w: it.width ?? 0, h: it.height ?? 0 });
             }
           }
           textByPage.push(pageText);
+          runsByPage.push(runs);
         } catch {
           textByPage.push("");
+          runsByPage.push([]);
         }
       }
-      return { textByPage, positions };
+      return { textByPage, positions, runsByPage };
     })();
     textCache.set(doc, p);
   }
@@ -4922,6 +5069,8 @@ function getOpPass(doc) {
               name,
               placedW: Math.hypot(ctm[0], ctm[1]),
               placedH: Math.hypot(ctm[2], ctm[3]),
+              x: ctm[4],
+              y: ctm[5],
               page: i
             });
           } else if (fn === OPS.setFont) {
@@ -6195,7 +6344,7 @@ import { readFile as readFile17 } from "node:fs/promises";
 var check22 = {
   id: "source.markdown.layout-markers",
   name: "Layout Markers",
-  description: "Reports @page/@section/@chapter marker arguments Gutterpress could not understand",
+  description: "Reports @page/@section/@chapter marker arguments Gutterpress could not understand, plus any unknown gp-* class",
   category: "source",
   phase: "pre-build",
   async run(ctx) {
@@ -8032,7 +8181,7 @@ class PdfOutput {
       const rawPdf = pdfxMode ? path8.join(stage, "raw.pdf") : path8.resolve(pdfFile);
       await fsp2.mkdir(path8.dirname(path8.resolve(pdfFile)), { recursive: true });
       log.info("Rendering HTML to PDF via the Gutterpress engine (native Chromium pagination)");
-      const { buildNativePdf } = await import("./engine-mtyjc4v6.js");
+      const { buildNativePdf } = await import("./engine-4ctgbwj5.js");
       const engineDiagnostics = await buildNativePdf(htmlFile, rawPdf, {
         title: config.title,
         author: config.authors.length > 0 ? config.authors.join(", ") : undefined,

package/dist/{index-ja0p4w5f.js → index-eyzv51dw.js}

@@ -1989,7 +1989,7 @@ ${mapCss}`;
       if (pageBackgrounds.length)
         log(`audit: ${pageBackgrounds.length} unreferenced @page background image(s)`);
       for (const d of multicol)
-        diagnose("engine.multicol.dead-column", `${d} runs over more than one page in columns, and only the last page's columns get balanced — earlier pages are left with an empty column. Add column-fill: auto to ${d}.`);
+        diagnose("engine.multicol.dead-column", `${d} runs over more than one page in columns, and only the last page's columns get balanced — earlier pages are left with an empty column. Add .gp-columns-flow to ${d} (column-fill: auto) so every page's columns fill.`);
       if (multicol.length)
         log(`audit: ${multicol.length} fragmenting multicol warning(s)`);
     }

package/dist/index.js

@@ -124,10 +124,10 @@ import {
   syncProject,
   testRemoteAccess,
   validateProjectPlugins
-} from "./index-ya1yw5me.js";
+} from "./index-dxvn0dr9.js";
 import {
   BUILD_DIAGNOSTIC_CODES
-} from "./index-ja0p4w5f.js";
+} from "./index-eyzv51dw.js";
 import {
   BuildError,
   DEFAULT_PRINT_OPTS,

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

@@ -8,7 +8,9 @@ export type ReadText = (relPath: string) => Promise<string>;
  * `type`s (`ambiguous_marker_token`, `unrecognized_marker_token`,
  * `extra_bare_marker_token`, `unknown_marker`, `nested_spread`,
  * `continue_without_section`, `spread_without_pages`, `spread_eof_close`,
- * `page_outside_spread`, `pin_outside_page`).
+ * `page_outside_spread`, `pin_outside_page`, `unknown_gp_class` — the last
+ * emitted by `gp-pin-scope.js`'s `gp_pin_scope_check`, same as
+ * `pin_outside_page`, see #226).
  *
  * `section_without_page` and `implicit_page` were REMOVED 2026-08-12: a
  * @section with no open @page is valid authoring (audited, 17/17 false

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

@@ -7,10 +7,13 @@
  * classes authors apply to content. Keeping the two core blocks separate makes
  * that ownership boundary explicit without implying an external plugin.
  *
- * Injected by assemble.ts immediately AFTER `MARKER_CSS` and BEFORE user plugin
- * and project CSS, so the cascade order is: marker layout primitives ->
- * Gutterpress vocabulary -> plugin CSS -> the author's stylesheets last. An
- * author overriding a `gp-*` class at equal specificity still wins.
+ * Injected by assemble.ts inside `@layer gp.vocab` (#227), immediately after
+ * MARKER_CSS's own `@layer gp.marker`, and before user plugin CSS and the
+ * author's project stylesheets — both of which stay UNLAYERED. Per the CSS
+ * Cascade Layers spec, unlayered CSS always beats layered CSS regardless of
+ * selector specificity, so a plugin or project rule targeting a `gp-*` class
+ * now wins UNCONDITIONALLY, not merely at equal specificity — see
+ * assemble.ts's cascade-order comment for the full layer list.
  *
  * Also ships the author-facing `gp-*` image/block vocabulary (CLAUDE.md §0 —
  * a behavior broadly useful to non-technical authors belongs in core, not a
@@ -133,4 +136,27 @@
  * 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-small { width: 25%; max-width: 100%; }\n.gp-medium { width: 50%; max-width: 100%; }\n.gp-large { width: 75%; 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, exposed as author vocabulary so\n   \"put this in two columns\" does not require borrowing a styled container\n   from the book's own component layer. That borrowing is what this exists\n   to prevent: a book whose theme paints .section chrome by default gives\n   every author who opens a section just to start a column run a panel they\n   did not ask for, and the book then needs a reset rule to take it back.\n   With a neutral primitive the author opts into columns and nothing else.\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, because the correct value depends on whether the run fragments\n   across pages (auto packs each page's columns; the CSS initial balance is\n   right for a run that fits on one page) and only the author knows which.\n   --gp-column-gap is author-settable. */\n.gp-columns-2 { columns: 2; column-gap: var(--gp-column-gap, 1.5em); }\n.gp-columns-3 { columns: 3; column-gap: var(--gp-column-gap, 1.5em); }\n\n/* grid runs \u2014 the SLOTTED counterpart to the column runs above. Grid places\n   each child into the next cell, across then down (deterministic slots: card\n   layouts, stat blocks, image-plus-caption pairs); columns FLOW one text run\n   down then across. Same neutral-primitive rationale as .gp-columns-*, and\n   permanent vocabulary for the same reason: standard CSS Grid verbatim, no\n   spec gap to remove later. MEASURED (Chromium 151, gp-grid evidence pack):\n   grid rows fragment across sheets with EXACT print/viewer parity \u2014 2- and\n   3-col, unequal item heights, mid-row cuts, multi-sheet overflow,\n   break-inside:avoid, gap geometry \u2014 so a grid taller than the page is safe,\n   no fit-one-page constraint. Two things to know, not fix:\n     - on a min-height page root (MARKER_CSS), default align-content\n       stretches rows apart to fill the page \u2014 identically in both engines.\n       Authors wanting packed rows set align-content: start.\n     - a @page-break / @column-break marker DIRECTLY inside a grid container\n       becomes a grid item and corrupts placement (the one measured parity\n       break); markers.js diagnoses it (break_inside_grid).\n   --gp-grid-gap is author-settable. */\n.gp-grid-2 { display: grid; grid-template-columns: repeat(2, 1fr); gap: var(--gp-grid-gap, 1.5em); }\n.gp-grid-3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--gp-grid-gap, 1.5em); }\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   inset:0 and the explicit centers are load-bearing; see doctrine comment. */\n.gp-pin {\n  position: absolute;\n  inset: 0;\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/* 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";
+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-small { width: 25%; max-width: 100%; }\n.gp-medium { width: 50%; max-width: 100%; }\n.gp-large { width: 75%; 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, exposed as author vocabulary so\n   \"put this in two columns\" does not require borrowing a styled container\n   from the book's own component layer. That borrowing is what this exists\n   to prevent: a book whose theme paints .section chrome by default gives\n   every author who opens a section just to start a column run a panel they\n   did not ask for, and the book then needs a reset rule to take it back.\n   With a neutral primitive the author opts into columns and nothing else.\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, because the correct value depends on whether the run fragments\n   across pages (auto packs each page's columns; the CSS initial balance is\n   right for a run that fits on one page) and only the author knows which.\n   --gp-column-gap is author-settable. */\n.gp-columns-2 { columns: 2; column-gap: var(--gp-column-gap, 1.5em); }\n.gp-columns-3 { columns: 3; column-gap: var(--gp-column-gap, 1.5em); }\n\n/* the per-shape decisions the paragraph above deliberately leaves to the\n   author, named instead of left as raw CSS every book was reinventing\n   (2026-09-01 CSS architecture review, findings C1/C7 \u2014 CLAUDE.md \u00A70:\n   \"behavior broadly useful to non-technical authors belongs in core\").\n   Permanent vocabulary, standard properties verbatim \u2014 same rationale as\n   the column/grid runs above. One name each, no aliases:\n     .gp-columns-all       column-span: all      a heading or block that\n                                                  spans every column in the\n                                                  run it sits inside.\n     .gp-columns-flow      column-fill: auto     a run that FRAGMENTS across\n                                                  pages \u2014 every page's\n                                                  columns fill instead of\n                                                  only the last one\n                                                  balancing (the dead-column\n                                                  collapse the build's\n                                                  engine.multicol.dead-column\n                                                  warning names this fix\n                                                  for).\n     .gp-columns-balanced  column-fill: balance  a run that fits on ONE\n                                                  page (the CSS initial\n                                                  value \u2014 ragged columns\n                                                  would be wrong here). */\n.gp-columns-all { column-span: all; }\n.gp-columns-flow { column-fill: auto; }\n.gp-columns-balanced { column-fill: balance; }\n\n/* grid runs \u2014 the SLOTTED counterpart to the column runs above. Grid places\n   each child into the next cell, across then down (deterministic slots: card\n   layouts, stat blocks, image-plus-caption pairs); columns FLOW one text run\n   down then across. Same neutral-primitive rationale as .gp-columns-*, and\n   permanent vocabulary for the same reason: standard CSS Grid verbatim, no\n   spec gap to remove later. MEASURED (Chromium 151, gp-grid evidence pack):\n   grid rows fragment across sheets with EXACT print/viewer parity \u2014 2- and\n   3-col, unequal item heights, mid-row cuts, multi-sheet overflow,\n   break-inside:avoid, gap geometry \u2014 so a grid taller than the page is safe,\n   no fit-one-page constraint. Two things to know, not fix:\n     - on a min-height page root (MARKER_CSS), default align-content\n       stretches rows apart to fill the page \u2014 identically in both engines.\n       Authors wanting packed rows set align-content: start.\n     - a @page-break / @column-break marker DIRECTLY inside a grid container\n       becomes a grid item and corrupts placement (the one measured parity\n       break); markers.js diagnoses it (break_inside_grid).\n   --gp-grid-gap is author-settable. */\n.gp-grid-2 { display: grid; grid-template-columns: repeat(2, 1fr); gap: var(--gp-grid-gap, 1.5em); }\n.gp-grid-3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--gp-grid-gap, 1.5em); }\n\n/* fragmentation controls \u2014 generic pagination utilities for any element,\n   independent of the column/grid 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   inset:0 and the explicit centers are load-bearing; see doctrine comment. */\n.gp-pin {\n  position: absolute;\n  inset: 0;\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/* 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";
+/**
+ * GP_CLASSES — every class an author may legitimately write with a `gp-`
+ * prefix: the `.gp-*` selectors in `GUTTERPRESS_CSS` above, the two
+ * structural classes `markers.js`'s `MARKER_CSS` styles (`gp-page-break`,
+ * `gp-column-break`), and two classes the marker plugin EMITS but that carry
+ * no CSS rule of their own — `gp-continued` (a `@continue`d section's marker,
+ * for author/theme styling — see markers.js's header) and `gp-flush` (a
+ * `.gp-pin` edge modifier implemented in the engine's layout code, not CSS —
+ * see the `.gp-flush` doctrine note above).
+ *
+ * This is the vocabulary `gp-pin-scope.js`'s `unknown_gp_class` diagnostic
+ * (#226) checks every author-facing class against: any `gp-`-prefixed class
+ * NOT in this set is either a typo or forgotten vocabulary, and is worth a
+ * warning either way — key on `gp-` only; `.dc-*`, `.fg-*`, and unprefixed
+ * classes are none of core's business.
+ *
+ * `gutterpress-css.test.ts` asserts this set and the `.gp-*` selectors
+ * textually present in `GUTTERPRESS_CSS` + `MARKER_CSS` agree (modulo the two
+ * marker-only exceptions above), so the two cannot silently drift apart —
+ * whoever adds a class to one CSS block and forgets this list finds out from
+ * a failing test, not from a future bug report.
+ */
+export declare const GP_CLASSES: ReadonlySet<string>;

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

@@ -2,8 +2,21 @@ export default function plugin(md: any, pluginOptions?: {}): void;
 /**
  * The minimal CSS the DOM this module emits requires. Author utility
  * vocabulary lives in gutterpress-css.ts — see the ownership note above.
- * Consumers should inject this into <head> after their user stylesheets so
- * the layout contract (page/section/column breaks) wins at equal specificity.
+ *
+ * The real contract (#227; a prior version of this paragraph said the
+ * opposite and was stale — 2026-09-01 CSS architecture review, C4):
+ * consumers inject this FIRST, wrapped in `@layer gp.marker` (assemble.ts
+ * declares `@layer gp.marker, gp.vocab;` before both core blocks). Author
+ * CSS — plugin CSS, every project stylesheet, anything loaded via
+ * `engineStyles.native` — stays UNLAYERED, and per the CSS Cascade Layers
+ * spec unlayered CSS always wins over layered CSS regardless of selector
+ * specificity. That is what makes "author wins" true now, not injection
+ * order. The `:where()` wrapping on the break/orphan/sizing rules below is
+ * a NARROWER, still-necessary guarantee that survives the layer: it keeps
+ * this block from out-specificity-ing whatever ELSE an author writes
+ * (their own plain `.section { break-inside: ... }`, say) — a concern
+ * `@layer` doesn't touch, since two unlayered rules still settle by
+ * ordinary specificity between themselves.
  *
  * `.page`/`.spread` are given `position: relative` so they are the containing
  * block for any abspos descendant: a mispinned `bottom: 0` now fails LOCALLY
@@ -76,5 +89,68 @@ export default function plugin(md: any, pluginOptions?: {}): void;
  * bottom` collapses the line box onto the image, keeping the image inline (so
  * `text-align: center` still centers it — `display: block` would not).
  *
+ * #231 — two engine-generic print fixes adopted from a real book's own
+ * engine sheet (2026-09-01 CSS architecture review, finding C8), because
+ * both are written entirely in terms of core's own published contract and
+ * fix a failure every book with big art or a `<figure>` hits, not a
+ * DC-brand-specific one:
+ *
+ *   - A bare markdown placard (`![Alt](art.jpg)`, no class) taller than the
+ *     page content box is monolithic replaced content, and the fragmenter
+ *     SLICES it mid-image across the page break instead of moving it whole.
+ *     Capping a bare image to `--gp-content-h` (core's own published page
+ *     CONTENT height for the page context it is in — see the min-height
+ *     rule above) with `object-fit: contain` letterboxes it onto one page
+ *     instead. Scoped to `:not([class])` so it never touches a `.gp-full`,
+ *     `.gp-bleed`, or any other explicitly sized/classed image — an author
+ *     who already sized their own art has already made the call this rule
+ *     exists to make for the ones who haven't. `--gp-content-h` is
+ *     published by BOTH renderers (the compiler on `:root` plus every
+ *     `page:` assignment selector; the viewer on each `.gp-strip`), so this
+ *     rule cannot itself split preview from print.
+ *
+ *     MEASURED on the field guide (295pp, adopted verbatim from its own
+ *     native-furniture.css §9, which carried this exact rule for months):
+ *     chapter-01's rabbit placard paints 717.0pt tall on the default page
+ *     both before and after adoption (core's cap and the book's copy agree
+ *     bit-for-bit — the book's copy is now a harmless duplicate of core's,
+ *     not a competing rule). Chapter-03's full-sheet plate (an `@page` with
+ *     zero margins, so the content box IS the sheet) paints 621.0 x 804.0pt
+ *     inside its 621 x 810pt sheet both before and after — the OLD hand-
+ *     computed version of this rule (`calc(var(--page-height) - 0.5in -
+ *     0.75in - 4px)`, hard-coding the DEFAULT page's margins) over-capped
+ *     this named page's art to 553.5 x 717.0pt, a 1.3in band of bare wall
+ *     along its foot; reading the cap off `--gp-content-h` instead fixed
+ *     that BEFORE core ever adopted the rule, so adoption itself changes
+ *     nothing further. Total page count unchanged at 295pp — no
+ *     shrink-to-fit side effect from moving the rule into core.
+ *
+ *   - `figure { break-inside: avoid }` keeps in-flow art (anything an
+ *     author or a plugin wraps in a real `<figure>`) from being sliced
+ *     across a page break the same way a bare placard would be — the
+ *     `:where(p > img:only-child, figure > img)` sizing rule above already
+ *     assumes the figure survives as one piece; without this it did not.
+ *
+ * Design-for-deletion note (CLAUDE.md): neither rule is a Chromium-gap shim
+ * with a removal trigger — both are permanent, standards-verbatim defaults
+ * in the same category as the min-height/box-sizing/vertical-align rules
+ * above (real print-fragmentation behavior, not a spec feature Chrome has
+ * yet to ship). They stay `:where()` so an author's own sizing or
+ * break-inside rule, at ANY specificity, still wins outright.
+ *
+ * The companion "spanner + unbreakable box" glue pattern (`column-span: all`
+ * followed by a `break-inside: avoid` box, native-engine-styling-guide.md
+ * §5) was measured for this same adoption pass and DELIBERATELY NOT
+ * adopted: a `:where()`-zero-specificity override can never win against
+ * whatever real-specificity rule gave the box its `break-inside: avoid` in
+ * the first place (a synthetic 2-column fixture with the candidate
+ * `:where(.gp-columns-all) + :where(*) { break-inside: auto }` produced
+ * BYTE-IDENTICAL output to the same fixture without it, across every
+ * geometry swept), and the field guide's own native-furniture.css §13 shows
+ * a context-blind version of the same idea is actively wrong for at least
+ * one real, shipped case (a short, non-fragmenting instance that needed its
+ * `avoid` restored after a general fragmenting-context rule took it away).
+ * It stays an author remedy, named in the styling guide (`.gp-columns-all`).
+ *
  */
-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";
+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(p) > :where(img:not([class])) { max-height: calc(var(--gp-content-h) - 4px); object-fit: contain; }\n:where(figure) { break-inside: avoid; }\n:where(.section, figure) > :where(:first-child) { break-before: avoid; }\n\n";