gp-dimm-city 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -7,6 +7,190 @@ cut a version that has no `## [X.Y.Z]` heading below.
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-10-07
+
+**Layout note for books upgrading from 1.0.x:** the page margins now follow
+DriveThruRPG's print specification (text at least 0.5in inside the trim),
+which takes 0.25in off every page and reflows the whole book. Build and
+review your book after upgrading; the Field Guide needed a short layout
+pass (see `dc-op-manual`, branch `design/plugin-updates`). DriveThruRPG
+books should also end with `@page .dc-printer-page` and set
+`print: signature: 4` in `manifest.yaml`.
+
+### Added
+
+- **`@page .dc-printer-page`**, a completely blank last page (no wall, no
+  footer). DriveThruRPG reserves a book's final page for printer
+  information: the interior must be one page short of its signature (4 for
+  US Letter) or end on a blank page. End the last chapter with this marker
+  and set `print: signature: 4` in the manifest — gutterpress pads with
+  blank pages to the next multiple of 4 — and the book always ends blank.
+  Verified in the Field Guide (228 content pages + 4 blank = 232).
+- **Variant Gallery** (design guide chapter 11): every element with more than
+  one variant, its variants on one stage — all ten skill trees (each
+  specialty's first learning path with one skill card, Field Guide content
+  excerpted), the skill-card switches (tier override, both highlight forms,
+  two columns, outcome table), every AP chip, the ten specialty intros and
+  cards, class tags, alerts, blocks, choice cards, and the flush, heading,
+  section, sidebar and image-float variants.
+- **The design guide lives here.** `design-guide/` is the Dimm City Design
+  Guide book, moved from `dimm-city/dc-op-manual`. Its manifest loads the
+  package from this checkout (`extensions: - ../`), so it documents and
+  renders the working copy: `npm run dev` previews it, `npm run build`
+  renders the PDF, and the test suite uses it as the fixture
+  (`test/design-guide.test.js`: every chapter renders clean, every macro and
+  alert type is demonstrated, and each chapter's HTML is snapshotted under
+  `test/__snapshots__/`). CI builds the PDF with the PR's plugin and CSS and
+  uploads it; the release workflow attaches it to the GitHub release; a
+  *Publish design guide* workflow deploys the HTML build to GitHub Pages.
+- **`@glossary` is demonstrated** in the component gallery, which used raw
+  HTML for the term-list specimen before.
+
+### Changed
+
+- **Page margins follow DriveThruRPG's print specification.** Its
+  [Quick Specifications for Print Books](https://help.drivethrupartners.com/hc/en-us/articles/12780800178583-Quick-Specifications-for-Print-Books)
+  require all text at least 0.5in inside the trim. The bleed (0.125in on
+  the three outside edges, none at the spine) and the outside and binding
+  margins already complied; the top did not (0.375in from the trim) and
+  neither did the footer chips (0.43in). Top margin 0.5in → 0.625in on the
+  sheet (0.5in from the trim); bottom 0.75in → 0.875in, as the new
+  `--bottom-margin` token, so the chips print 0.55in from the trim. The
+  "Citizen File" running head, which printed 0.1in from the trim, sits at
+  the foot of a 0.875in top margin. Footer chips re-homed by a `.gp-flush`
+  pin are top-aligned like native ones (gutterpress centres them, which put
+  them 0.24in from the trim). A card title too long for its card breaks
+  rather than running into the margin. **This reflows every book:** the
+  Field Guide goes from 221 to 238 pages and now has no text inside 0.5in
+  of the trim (it had 1,273 words on 204 pages); the design guide goes from
+  126 to 131.
+- **Design guide: explainer pages print plain, specimens sit on the wall.**
+  Part 1 pages (and the Part 2 overview) are `@page .dg-doc`, a named page
+  with a white background and neutral headings, tables and contents, so guide
+  text can't be mistaken for a component. Each rendered result is wrapped in
+  a framed `.dg-stage` that carries the brick wall; whole-page specimens and
+  the Part 2 example pages keep the full brick page. Chapter ledes, the
+  contents lists, and the explainer notes and column panels that used
+  package components are now plain guide markup. All of this lives in
+  `design-guide/` (markdown and `styles/guide.css`); the package is unchanged.
+- **Design guide: print-design review pass.** Readability and finish fixes
+  from a review against the print-quality rubrics, all in `design-guide/`:
+  - Code boxes are set in IBM Plex Mono (OFL, bundled in
+    `design-guide/fonts/ibm-plex-mono/`), 9pt on 1.4 leading, without the
+    doubled blank lines; fences of 20+ lines may split across pages.
+  - Guide text is capped at a 5.1in measure (about 65–70 characters) on 1.4
+    leading; tables are 10pt and may run across pages.
+  - Chapters open with a "Chapter N" label; H1 26pt, H3 13pt. Doc pages
+    carry a plain running foot (folio and chapter title); the contents list
+    has page numbers; Part 2 has a title page and E.1–E.6 chapter badges.
+  - YOU WRITE / RESULT labels are 8pt; YOU WRITE is cream on blood (7.7:1).
+  - Specimen stages stay whole unless marked `dg-tall`; prose specimens sit
+    on paper (`dg-on-paper`); two Do/Don't pairs (flavor in bold italic,
+    body text on bare wall).
+  - Typeface specimens for lixdu, Titillium Web and Tomorrow; palette
+    swatches are 1in and each carries a CMYK build from the CGATS21_CRPC1
+    profile (the hand-entered four-row CMYK table is replaced).
+  - Fixed: the type-scale table listed H1–H4 at stale sizes; the guide's
+    inline-code style leaked into the Part 2 examples (invisible text on a
+    dark callout), and its `hr` rule replaced the package's dashed rule in
+    the specimen; the inset-sidebar and art-plate specimens no longer leave
+    a RESULT tab stranded at a page foot.
+- **Tests run against gutterpress 0.11.13** (devDependency, was 0.10.11).
+- **`test/fixtures/all-macros.md` and its snapshot are gone**; the design
+  guide is the fixture. `npm run test:update-snapshot` is now bun's own
+  `--update-snapshots`; `scripts/update-snapshot.mjs` is removed.
+
+### Fixed
+
+- **No blank page after a two-column page that ends in a spanner.** A
+  `@page .gp-columns-2` page ending in a full-width section printed an
+  extra blank page under the DriveThruRPG margins (Field Guide: Quickstart
+  vs. Deep Dive): the section's bottom margin pushed the page box past its
+  one-sheet minimum. A multicol page's last child has no bottom margin.
+  Design guide unchanged; Field Guide loses the blank page.
+- **The introduction page keeps the normal margins.** `.page-intro` shared
+  the `front-matter` named page with the Contents and Credits, whose side
+  and bottom margins are zeroed for their full-bleed masthead — so the
+  intro's chevron, lede and section sat flush on the sheet edge. It has its
+  own named page now, `front-matter-intro`: default margins, no footers.
+  The Field Guide writes its introduction as a plain `@page` and is
+  unaffected.
+- **No more pages printed as images.** `filter: drop-shadow()` on the
+  intro page and on the labelled chapter-opener page made Chromium print
+  each of those pages as one 300ppi bitmap with a soft mask: no live text,
+  and a transparency mask PDF/X-1a forbids. Both shadows are vector now
+  (box-shadow on the lede, section and opener badge; the opener section's
+  own clipped `::after`). Design guide: 8 pages regain live text. The
+  Field Guide uses neither and is unaffected.
+- **No hairline across the page after the credits.** The colophon fills to
+  the sheet's bottom edge, so its poster shadow's 3pt drop overflowed the
+  sheet and printed as a line across the top of the next page — over the
+  Field Guide's Contents masthead. The colophon keeps the shadow's side
+  offset and drops the downward one. (Clipping the page was rejected: it
+  would also clip a pinned or bleed plate.) Field Guide: p.2 loses the
+  line, and p.1 shows the colophon's side shadow starting level with its
+  top; nothing else changes.
+- **Specialty art plates print full bleed.** The `.page` overflow guard
+  (page-templates.css) exempted pages holding `.gp-bleed`/`.gp-pin` art but
+  not `.dc-specialty-art` or `.dc-full-page`, so a plate on a page with no
+  other pinned art was cut at the text column — a 100pt strip of bare wall
+  down its outside edge (design guide p.45, p.105). The Field Guide's
+  plates were full width only because its specialty pages also carry
+  pinned art. Field Guide unchanged.
+- **A long standalone banner title keeps its skew tab inside the margin.**
+  `.dc-spray`'s `::before` tab overhangs its right edge by 18px; a title
+  that filled its column pushed the tab past the margin, which is print
+  shrink-to-fit for the whole book once the page does not clip (found by
+  the build's width audit after the plate fix). Standalone banners cap at
+  the column less the tab; learning-path banners, which span their shell
+  with the tab pulled inside, are exempt. Field Guide unchanged.
+- **A learning-path banner stays with its first card.** The shell is never
+  split and keeps with the next card, and the first path after a
+  specialty's art page drops its 8px top margin — moved into the package
+  from the Field Guide's own sheet, which measured both. Without them the
+  design guide printed the Biting Distance banner alone, with the edge of
+  the first card's tab at the page foot. The package's `break-before:
+  always` on `.dc-learning-path` is not a value Chromium supports and does
+  nothing; it is left as is (making it valid would put every path on a new
+  page). Field Guide unchanged.
+- **A credits page that overflows no longer prints under the next page.**
+  `.page.page-credits` had an exact one-sheet `height`; when its colophon
+  did not fit, the colophon moved to a second sheet but the page box stayed
+  one sheet tall, so the following page started on that same sheet and was
+  painted over it (design guide: the Introduction over the colophon). It is
+  a `min-height` now: a page that fits is still exactly one sheet, so the
+  pinned plate still seats on the sheet edge, and the Field Guide renders
+  pixel-identical. The design guide's credits example also pins its plate
+  like the Field Guide's (`.gp-pin .gp-bottom .gp-full`) instead of placing
+  it in the colophon, which is what had made it overflow.
+- **Variable AP chips print as variable.** The plugin emitted
+  `.dc-ap.variable` but the CSS only styled `.dc-ap.var`, and a `VAR AP`
+  cost got no variable class at all. Both spellings are styled now, and
+  `VAR` is detected alongside ranges and `X`. Visible change in the Field
+  Guide: 13 pages, each a range-cost chip (`2-X AP` and the like) turning
+  from standard blue to variable magenta; no layout change.
+- **Short two-column runs no longer print full-page height.** `dc-native.css`
+  §10b set `column-fill: auto` on every `.gp-columns-*` run; with no fixed
+  height that fills the first column to the page foot, so a short column
+  panel became a full-height box with an empty right column, and a heading
+  above one was stranded alone when the box could not fit under it. The
+  rule is `balance` again, and the two per-shape `balance` exceptions it
+  made redundant are removed. A run that needs sequential fill opts in with
+  core's `.gp-columns-flow`. The Field Guide's 221 pages render
+  pixel-identical before and after.
+- **A lede never splits** (`.dc-intro { break-inside: avoid }`), and the
+  section after a lede may start a new page. Core glues every section to
+  what precedes it, which chained heading → lede → section; when the section
+  could not fit, the lede split and painted an empty panel to the page foot.
+- **`@sidebar .inset` with a single paragraph** set that paragraph in
+  centred display caps: the rail's closing-line rule matched it as the last
+  child. It now applies only from the second paragraph on. The inset rail
+  also keeps the sidebar's paper surface instead of a transparent one that
+  put its text on the brick wall.
+- Two design guide chapters (`303`, `306`) closed `@procedure` on the line
+  right after a list item, which markdown folds into that item, so the
+  marker never closed and the chapter rendered with a layout warning.
+
 ## [1.0.1] - 2026-09-25
 
 ### Changed

package/README.md

@@ -137,19 +137,59 @@ artwork and game text are not licensed by this package.
 
 ## Development
 
+The short how-to is [docs/developing.md](./docs/developing.md): the edit → preview → test → release loop, in web-dev terms.
+
+Everything you need to change the package and see the result is in this
+repository: the plugin, the stylesheets, and `design-guide/` — the Dimm City
+Design Guide, a Gutterpress book that documents every macro, token, component
+and page template by rendering it. The guide's manifest loads the package from
+this checkout (`extensions: - ../`), not from npm, so it is both the public
+documentation and the test fixture: what it shows is what the working copy
+renders.
+
 ```sh
 bun install
-bun test                     # snapshot, behaviour, package and convention tests
-bun run test:update-snapshot # only when the plugin's output is meant to change
-bun run pack:check           # what npm would publish
+npm run dev                  # live preview of the design guide, opens the browser
+npm run build                # lint + validate + render .build/design-guide.pdf (needs Chrome 148+)
+npm run build:html           # the guide as a static site, .build/design-guide-site/
+bun test                     # plugin behaviour, design-guide render + snapshot, package, conventions
+npm run test:update-snapshot # only when the plugin's output is meant to change
+npm run pack:check           # what npm would publish
 ```
 
-`plugin.js` imports nothing at runtime — `gutterpress/render` is a
-devDependency used only by the tests to run the plugin inside core's markdown
-pipeline. Releases are cut from the *Release* workflow (version in, npm and
-GitHub release out); it refuses a version with no `## [X.Y.Z]` heading in
-`CHANGELOG.md`.
-
-The design guide that documents this system in depth is a book in the
-`dimm-city/dc-op-manual` repository. Issues about the package — a macro, a
-sheet, a token, a font — belong here.
+The loop is the usual web one. `npm run dev` runs `gutterpress preview
+design-guide`: edit `plugin.js`, a sheet under `styles/`, a font or the brick
+tile, or any chapter of the guide, and the preview re-renders (the CLI lists
+each watched file as it starts). The Gutterpress desktop app does the same —
+open the `design-guide/` folder in it. `npm run build` is the PDF the
+reader gets; it runs Gutterpress's print-safety lint and source/PDF
+validation and fails on an error. Set `CHROMIUM_PATH` if your Chrome is not
+on a standard path.
+
+The tests (`bun test`) are the CI gate:
+
+- `test/design-guide.test.js` — every chapter renders through Gutterpress's
+  pipeline with no layout warning and no marker left unrendered; every macro
+  and alert type the plugin handles appears in the guide; each chapter's HTML
+  matches `test/__snapshots__/`. A change to the plugin's output fails here
+  until you run `npm run test:update-snapshot` and review the snapshot diff
+  with the code.
+- `test/plugin.test.js` — the loader contract and the behavioural edge cases.
+- `test/package.test.js` — the tarball `npm publish` would ship: every
+  declared path, every `url()` asset, one licence per font directory, the
+  cascade contract.
+- `test/conventions.test.js` — one prefix (`dc-`), no runtime imports, only
+  allow-listed core hooks.
+
+CI (`.github/workflows/ci.yml`) runs the tests and then builds the design
+guide PDF with the PR's plugin and CSS, uploaded as the `design-guide-pdf`
+artifact — open it to see what a change did to every page. On `main`, the
+*Publish design guide* workflow deploys the HTML build to GitHub Pages
+(enable it once under Settings → Pages → Source: GitHub Actions).
+
+`plugin.js` imports nothing at runtime — `gutterpress` is a devDependency used
+by the tests (`gutterpress/render`) and by the scripts (the CLI). Releases are
+cut from the *Release* workflow (version in; npm, GitHub release and the
+design guide PDF out); it refuses a version with no `## [X.Y.Z]` heading in
+`CHANGELOG.md`. Issues about the package — a macro, a sheet, a token, a font,
+or a page of the guide — belong here.

package/components.yaml

@@ -4,7 +4,7 @@
 # WHAT THIS IS
 #   One entry per component: what an author writes, what lands in the HTML,
 #   which custom properties are public, how it fragments, and which stylesheet
-#   owns it. The Dimm City Design Guide (a book in the dc-op-manual repo)
+#   owns it. The Dimm City Design Guide (design-guide/ in this repo)
 #   explains and demonstrates the components; this file is the catalog of
 #   record. It is the file package.json declares as `gutterpress.components` —
 #   Gutterpress only checks that the file exists, so the schema below is this
@@ -389,13 +389,13 @@ components:
   - name: ap-chip
     status: live
     origin: plugin
-    recipe: "1. **N AP** *Ability:* text  (inside @skill; 0 AP → .free, ranges/X → .variable; also authored as raw <span class=\"dc-ap\">)"
+    recipe: "1. **N AP** *Ability:* text  (inside @skill; 0 AP → .free, ranges/X/VAR → .variable; also authored as raw <span class=\"dc-ap\">)"
     emits: span.dc-ap[.free|.variable]
     css: [styles/components/cards.css, styles/components/specialty-identity.css]
     tokens: [--dc-ap-bg, --dc-ap-fg, --dc-ap-border]
     usage: [" AP**"]
     breaks: none
-    notes: "Modifier drift outside the check's dc- scope: the plugin emits `variable` but the CSS styles `.dc-ap.var`; `.standard/.reduced/.increased/.special` (specialty-identity.css) are never emitted, only authored raw in the gallery."
+    notes: "The plugin emits `variable`; the CSS styles both `.variable` and the raw spelling `.var`. `.standard/.reduced/.increased/.special` (specialty-identity.css) are never emitted, only authored raw — shown in the design guide's Variant Gallery."
 
   - name: distance-tags
     status: unused
@@ -667,6 +667,15 @@ components:
     css: styles/page-rules.css
     breaks: "page: clean"
 
+  - name: printer-page
+    status: live
+    origin: author
+    recipe: "@page .dc-printer-page  (the last marker of a book's last chapter)"
+    emits: div.page.dc-printer-page
+    css: [styles/page-rules.css, styles/dc-native.css]
+    breaks: "page: printer-blank; break-before: page"
+    notes: "A completely blank final page — no wall, no footer — for DriveThruRPG's reserved printer page. With `print: signature: 4` in the manifest, gutterpress pads to the next multiple of 4, so the book always ends blank. Used by the Field Guide."
+
   - name: cover-page
     status: unused
     origin: author

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gp-dimm-city",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Dimm City design system for Gutterpress: the markdown-it macros (@skill, @specialty, @learning-path, @callout, …), print stylesheets, design tokens, fonts and page templates the Dimm City TTRPG books are set in.",
   "type": "module",
   "main": "plugin.js",
@@ -59,12 +59,16 @@
     "snippets": "snippets"
   },
   "scripts": {
+    "dev": "gutterpress preview design-guide --open",
+    "build": "gutterpress build design-guide --format pdf --out .build/design-guide.pdf",
+    "build:html": "gutterpress build design-guide --format html --out .build/design-guide-site",
+    "lint": "gutterpress lint design-guide",
     "test": "bun test",
-    "test:update-snapshot": "bun scripts/update-snapshot.mjs",
+    "test:update-snapshot": "bun test --update-snapshots",
     "pack:check": "npm pack --dry-run"
   },
   "devDependencies": {
-    "gutterpress": "0.10.11",
+    "gutterpress": "0.11.13",
     "markdown-it": "^14.1.0"
   },
   "peerDependencies": {

package/plugin.js

@@ -490,7 +490,7 @@ function parseAbilityFromListItem(html) {
   // Determine AP class
   let apClass = 'dc-ap';
   if (apVal === '0 AP' || apVal === '0AP') apClass += ' free';
-  else if (apVal.includes('-') || apVal.toUpperCase().includes('X')) apClass += ' variable';
+  else if (apVal.includes('-') || /X|VAR/.test(apVal.toUpperCase())) apClass += ' variable';
 
   return {
     apVal: apVal,

package/styles/components/cards.css

@@ -480,8 +480,20 @@
   --dc-ap-bg: var(--blood);
 }
 
-.dc-ap.var {
+/* The plugin emits `.variable` (a range, X or VAR); `.var` is the raw
+   authored spelling. Only `.var` was styled, so plugin chips never showed
+   as variable. */
+.dc-ap:is(.var, .variable) {
   --dc-ap-bg: var(--hud-magenta);
 }
 
+/* A card title is a wide display word in a narrow box (a gear card in a
+   two-column run is ~3.4in). One that cannot fit ran past the card and into
+   the page margin — "ACCELERATOR" printed 0.41in from the trim, inside
+   DriveThruRPG's 0.5in text minimum. It now breaks, as a last resort; a
+   soft hyphen (­) in the source picks a better break. */
+.dc-card :is(h2, h3, h4) {
+  overflow-wrap: break-word;
+}
+
 }

package/styles/components/chrome.css

@@ -130,6 +130,14 @@ h1.dc-chevron {
      `isolation: isolate`, and with neither. */
   clip-path: polygon(0 0, 100% 0, 100% 100%, 25px 100%, 0 calc(100% - 15px));
   margin: 0;
+  /* Leave room for the ::before skew tab, which overhangs the right edge
+     (right: -8px, 14px wide, skewed): 18px measured. A long title that
+     filled its column pushed the tab past the margin — "What Makes a Good
+     Cross-Specialty Moment", scrollWidth 726px in a 708px column — which a
+     clipping .page hid, and which on a page that may not clip (one holding
+     plate or bleed art) is print shrink-to-fit for the whole book. Such a
+     title now wraps one tab-width earlier; shorter banners are untouched. */
+  max-width: calc(100% - 18px);
   word-break: break-word;
   overflow: visible;
 }
@@ -329,6 +337,21 @@ h1.dc-chevron {
   padding: 0 14px 10px 18px;
   margin: 0 0 calc(0.1in + 3pt) 0;
   box-shadow: var(--shadow-poster);
+  /* A lede is one to three short paragraphs: never split it. Split, its
+     panel painted on to the page foot with the last paragraph overleaf
+     (design guide p.82, "How Abilities Work"). */
+  break-inside: avoid;
+}
+
+/* Core glues every section to whatever precedes it (`:where(.section) >
+   :where(:first-child) { break-before: avoid }`), which chains heading →
+   lede → section into one unbreakable run. When that section cannot fit,
+   Chromium has to break inside the chain: it split the lede, or with the
+   lede kept whole, stranded the heading at the page foot. A lede stands on
+   its own, so the section after it may start a new page; the section's own
+   break-inside: avoid still moves it whole. */
+.dc-intro + .section > :first-child {
+  break-before: auto;
 }
 
 /* ── Spec tweak section header ────────────────────────────────────────── */

package/styles/components/data.css

@@ -100,6 +100,10 @@
 
 .dc-path-shell>h2.dc-spray {
   width: stretch;
+  /* A path banner spans its shell edge to edge, with its tab pulled inside
+     (`right: -5px` below): it takes none of the standalone banner's
+     tab allowance (chrome.css .dc-spray). */
+  max-width: none;
 }
 
 .dc-path-shell>h2.dc-spray:first-child {

package/styles/components/images.css

@@ -44,10 +44,10 @@
    `.page.page-sidebar` template in page-templates.css: a rail is meaningless
    without a page that reserved room for it, and scoping it there means a
    stray `@sidebar .inset` on an ordinary page stays a readable floated
-   sidebar instead of painting over the body text. */
+   sidebar instead of painting over the body text. The rail keeps the
+   sidebar's paper surface: it was transparent, which put its text straight
+   on the brick wall. */
 .dc-sidebar.inset {
-  --dc-sidebar-surface: transparent;
-
   border-left: none;
 }
 
@@ -102,7 +102,9 @@
   padding: 0.06in 0.1in;
 }
 
-.dc-sidebar.inset>p:last-child {
+/* The rail's closing line — only when it is not also the rail's only (first)
+   paragraph, or a one-paragraph rail sets its whole body in display caps. */
+.dc-sidebar.inset>p:last-child:not(:first-of-type) {
   margin-top: 0.1in;
   margin-bottom: 0;
   padding-top: 0.08in;

package/styles/components/section.css

@@ -940,16 +940,16 @@ h3 + .section {
   border-top: 4pt solid var(--dc-chapter-opener-accent);
 }
 
-/* Cohesive drop shadow for the entire chapter-opener composite.
-   `filter: drop-shadow()` follows the union of the page's visible child
-   silhouettes — badge, tapered chevron, clipped section — and renders
-   ONE continuous shadow that looks like the composite is pinned to the
-   wall and casting a single offset. Applied on the page wrapper rather
-   than per-element so the diagonal join between chevron's tapered right
-   edge and the section's vertical right edge is preserved in the shadow
-   shape. */
-.chapter[data-chapter-label] > .page[data-page="intro"] {
-  filter: drop-shadow(var(--dc-chapter-opener-shadow));
+/* Chapter-opener shadow — vector, per element. This was ONE
+   `filter: drop-shadow()` on the page wrapper; Chromium prints a filtered
+   subtree as a bitmap, so every opener page went to the PDF as a single
+   300ppi image with a transparency mask — no live text, and a soft mask
+   that PDF/X-1a forbids. The badge takes a box-shadow; the section's own
+   ::after (below) draws its shadow on the same clipped silhouette as its
+   substrate, the way the base .section card does. The chevron sits inside
+   the section box, so the section's shadow covers it. */
+.chapter-opener {
+  box-shadow: var(--dc-chapter-opener-shadow);
 }
 
 /* Section substrate for the chapter-opener intro section. Selector
@@ -988,11 +988,21 @@ h3 + .section {
   );
 }
 
-/* Suppress the .section::after fake-shadow on the chapter-opener composite:
-   the chapter badge above already provides the upper visual weight, and a
-   vector shadow offset would visually clip at the indented right edge. */
+/* The chapter-opener section's shadow: the base ::after, offset like
+   --dc-chapter-opener-shadow and clipped to the same straight right edge
+   at the clip-tail as the substrate above. */
 .chapter[data-chapter-label] > .page[data-page="intro"] > .section::after {
-  content: none;
+  top: 4px;
+  left: 3px;
+  right: -3px;
+  bottom: -4px;
+  background: rgba(0, 0, 0, 0.28);
+  clip-path: polygon(
+    0 0,
+    calc(100% - var(--dc-chapter-opener-clip-tail)) 0,
+    calc(100% - var(--dc-chapter-opener-clip-tail)) 100%,
+    0 100%
+  );
 }
 
 /* Auto-style the section's first h1 as a chevron banner — no markdown

package/styles/dc-native.css

@@ -42,6 +42,12 @@
   background-blend-mode: multiply;
 }
 
+/* The printer page (page-rules.css) carries no wall: DriveThruRPG wants
+   the final page free of any page background. */
+@page printer-blank {
+  background: none;
+}
+
 /* ── 3. FOLIO + CHAPTER STICKERS ────────────────────────────────────────────
    Chrome for the chip content page-rules.css declares on @bottom-left /
    @bottom-right. Sticker identity swaps by spread side in page-rules.css's
@@ -73,11 +79,20 @@
    Shrinking the box no longer punches a hole in the margin band: §1's
    `@page` background paints underneath, so the wall shows through the rest
    of the slot on its own. */
+/* `align-self: flex-start`: on a page whose footer band a `.gp-flush` pin
+   frees, gutterpress re-homes these chips into a flex slot the size of the
+   margin box, centred vertically (gutterpress-agent setFlushFurniture,
+   `align-items: center`), and copies these declarations onto the chip. A
+   native margin box anchors a fit-content chip at the TOP of the band;
+   centred, a re-homed chip printed 0.24in from the trim, against
+   DriveThruRPG's 0.5in text minimum (Field Guide p.9, p.10, p.16). The
+   declaration does nothing to a native margin box, which is not a flex item. */
 @page :left {
   @bottom-left {
     /* folio sticker — civic register */
     width: fit-content;
     height: fit-content;
+    align-self: flex-start;
     font-family: var(--font-mono);
     font-size: 9pt;
     font-weight: 700;
@@ -92,6 +107,7 @@
     /* chapter sticker — stamped coupon */
     width: fit-content;
     height: fit-content;
+    align-self: flex-start;
     font-family: var(--font-display);
     font-size: 9pt;
     font-weight: 700;
@@ -109,6 +125,7 @@
     /* chapter sticker — stamped coupon */
     width: fit-content;
     height: fit-content;
+    align-self: flex-start;
     font-family: var(--font-display);
     font-size: 9pt;
     font-weight: 700;
@@ -123,6 +140,7 @@
     /* folio sticker — civic register */
     width: fit-content;
     height: fit-content;
+    align-self: flex-start;
     font-family: var(--font-mono);
     font-size: 9pt;
     font-weight: 700;
@@ -183,14 +201,19 @@
   padding-bottom: 0.75in;
 }
 /* Credits page as a full-height flex column so a pinned founders plate
-   (`.gp-pin .gp-bottom .gp-full`) seats on the sheet edge. Exact `height`
-   rather than core's `min-height` cushion so the pin's containing block ends
-   exactly on the sheet edge. Carried from the field guide's native sheet in
-   1.0.0: every Dimm City book writes this page. */
+   (`.gp-pin .gp-bottom .gp-full`) seats on the sheet edge. Carried from the
+   field guide's native sheet in 1.0.0: every Dimm City book writes this page.
+
+   `min-height`, not `height`. A page whose credits fit is exactly one sheet
+   either way, so the pin still seats on the sheet edge. An exact `height`
+   broke the page whose credits do NOT fit: the colophon went to a second
+   sheet while the page box stayed one sheet tall, so the next page started
+   on that same second sheet and printed on top of it (design guide, the
+   Introduction over the credits colophon). */
 .page.page-credits {
   display: flex;
   flex-direction: column;
-  height: var(--gp-content-h);
+  min-height: var(--gp-content-h);
   padding-bottom: 0;
 }
 .page.page-credits .section.credits-colophon {
@@ -199,6 +222,14 @@
   display: flex;
   flex-direction: column;
   margin-bottom: 0;
+  /* The colophon fills to the sheet's bottom edge (this template has no
+     bottom margin), so the poster shadow's 3pt drop landed past the sheet,
+     and Chromium printed that overflow as a hairline across the top of the
+     NEXT sheet — the Field Guide's Contents masthead, the design guide's
+     Introduction. The shadow keeps its side offset and loses the drop; the
+     colophon's foot sits under the pinned plate in any case. (Clipping the
+     page instead would also clip a pinned or bleed plate on it.) */
+  box-shadow: 2pt 0 0 rgba(0, 0, 0, 0.28);
 }
 /* The masthead escapes the padding back to the sheet edges — visible paint
    inside the full-width content box. `margin-top: 0` is deliberate: a
@@ -250,44 +281,35 @@ figure {
    value depends on whether the run fragments, and only the author knows).
    page-templates.css used to answer `balance` for the whole book; under
    native print the wrapper fragments across pages, and Chromium's
-   balance-in-fragmentation leaves every non-final fragment with a dead right
-   column (measured: proof17 p12/p13). Sequential fill packs both columns per
-   page — the behavior the engine's multicol fixture verified. */
+   balance-in-fragmentation left every non-final fragment with a dead right
+   column (measured: proof17 p12/p13), so this rule said `auto`.
+
+   It says `balance` again (2026-10). `auto` with no fixed height fills the
+   first column to the BOTTOM OF THE PAGE, so every short run — a column
+   panel, a pair of gear entries — printed as a full-height box with an
+   empty right column, and a heading above one was stranded alone on its
+   page when the full-height box could not fit under it (design guide
+   p.83, p.111). Measured against the change, under gutterpress 0.11.13:
+   the Field Guide's 221 pages render pixel-identical with `balance`, and
+   the design guide loses 6 pages of holes. A run that genuinely needs
+   sequential fill opts in with core's `.gp-columns-flow`. */
 .gp-columns-2,
 .gp-columns-3 {
-  column-fill: auto;
+  column-fill: balance;
 }
-/* Per the measured rule (docs/native-engine-styling-guide.md §5): balance is
-   correct for single-page multicol, auto only for FRAGMENTING multicol.
-   The general `.gp-columns-2`/`.gp-columns-3` rule above stays `auto` — it is
-   load-bearing for the WRAPPER shape (a plain div around several `.section`
-   children, e.g. p12/p13's "THE PACK SHOULD BE WEIRD" walkthrough, and
-   p243's CORE ELEMENTS section, where the dc-alert callout is itself taller
-   than a column and MUST be allowed to fragment; see §13 below). A
-   `.section` that is ITSELF the multicol container is NOT reliably short —
-   CORE ELEMENTS is that same DOM shape (`.section.gp-columns-2`) and needs
-   `auto`, so shape alone can't tell "fits on one page" from "runs long".
+/* The per-shape exceptions that used to follow — `.dc-citizen-walkthrough
+   .gp-columns-2` and `.page.gp-columns-2` set back to `balance` — are gone:
+   the rule above now says `balance` for every run. The Field Guide pages they
+   were measured on (p12/p13 "THE PACK SHOULD BE WEIRD", p243 CORE ELEMENTS,
+   p7 "Image Is Everything") are among the 221 that render pixel-identical. */
 
-   Two exceptions, both scoped so they cannot catch the fragmenting case:
-
-   (a) p7's "Image Is Everything" aside — a short paragraph + a short callout,
-   nothing left to balance — scoped to its own authored classes rather than
-   promoted to a general `.section.gp-columns-2` rule that would also catch,
-   and break, CORE ELEMENTS. If a future page reuses
-   `.dc-citizen-walkthrough.gp-columns-2` with long enough content to actually
-   fragment, the compiler's own multicol-fragmentation check flags it and
-   tells the author to add column-fill: auto locally — not a silent trap.
-
-   (b) a PAGE that is itself the multicol container. A `.page` is one sheet by
-   construction, so its run does not fragment and balance is the correct
-   value. This carries forward the `.page.two-column { column-fill: balance }`
-   that page-templates.css used to win with on specificity alone (0-2-0 over
-   this file's 0-1-0); stating it here puts it next to the reasoning and the
-   measurements instead of leaving it to load order. Live user:
-   `@page .dc-citizen-file-page .gp-columns-2` in the design guide. */
-.dc-citizen-walkthrough.gp-columns-2,
-.page.gp-columns-2 {
-  column-fill: balance;
+/* A PAGE that is itself the multicol container (`@page .gp-columns-2`) and
+   ends in a full-width spanner: the spanner's bottom margin pushed the page
+   box past its one-sheet minimum height, and the overflow printed as a blank
+   page (Field Guide: Quickstart vs. Deep Dive, after the DriveThruRPG
+   margins). A page's last child needs no bottom margin. */
+.page:is(.gp-columns-2, .gp-columns-3) > :last-child {
+  margin-bottom: 0;
 }
 
 /* ── 12. WALL ART placement is the markdown's, via core's gp-* classes ──────

package/styles/dc-palette.css

@@ -123,7 +123,20 @@
   --dc-card-gap:   0.15in;  /* ~11pt */
 
   --gutter:        0.15in;  /* two-column structural gutter */
-  --page-margin:   0.5in;
+  /* Page margins, measured from the SHEET edge. The sheet is the trim plus
+     DriveThruRPG's 0.125in bleed on the top, bottom and outside edge (none
+     at the spine), so each bleed-side margin is the trim distance + 0.125in.
+     DriveThruRPG "Quick Specifications for Print Books": all text at least
+     0.5in inside the page (trim) edge; non-bleeding art 0.25in from the
+     outside three edges and 0.5in from the binding edge.
+       top     0.625in  = 0.5in from the trim  (was 0.5in: 0.375in, out of spec)
+       bottom  0.875in  = 0.75in from the trim (was 0.75in: the folio and
+                          chapter chips sit in this band and printed 0.43in
+                          from the trim, out of spec)
+       outside 0.625in  = 0.5in from the trim
+       binding 0.75in   = 0.75in from the spine (no bleed on that edge) */
+  --page-margin:   0.625in;
+  --bottom-margin: 0.875in;
   --outer-margin:  0.625in; /* outer (non-binding) page margin */
   --sidebar-width: 3.05in;
 

package/styles/page-rules.css

@@ -56,7 +56,7 @@
    --page-height in dc-palette.css: change both together. */
 @page {
   size: 8.625in 11.25in;
-  margin: var(--page-margin) var(--outer-margin) 0.75in;
+  margin: var(--page-margin) var(--outer-margin) var(--bottom-margin);
   background-color: var(--bg);
 }
 
@@ -90,12 +90,26 @@
   @bottom-right { content: none; }
 }
 
-.page.page-intro,
 .page.page-toc,
 .page.page-credits {
   page: front-matter;
 }
 
+/* The introduction is front matter too — unnumbered — but it is not part
+   of the full-bleed masthead composite: its chevron, lede and section sit
+   inside the ordinary text column. It used to share `front-matter`, whose
+   zeroed side and bottom margins (dc-native.css §5) put the whole page
+   flush against the sheet edge. Its own name keeps the default margins and
+   drops only the footers. */
+@page front-matter-intro {
+  @bottom-left  { content: none; }
+  @bottom-right { content: none; }
+}
+
+.page.page-intro {
+  page: front-matter-intro;
+}
+
 /* ---------------------------------------------------------------------------
    Chapter start — footers suppressed; the chevron banner IS the visual
    identity. dc-native.css refills the two bottom boxes with the brick
@@ -137,6 +151,28 @@
   @bottom-right { content: none; }
 }
 
+/* ---------------------------------------------------------------------------
+   Printer page — a completely blank last page. DriveThruRPG reserves a
+   book's final page for printer information: the interior must be one page
+   short of its signature (4 pages for US Letter), or end on a page "devoid
+   of page backgrounds, page numbers, etc." (Quick Specifications for Print
+   Books). End the last chapter with `@page .dc-printer-page` and set
+   `print: signature: 4` in the manifest: gutterpress pads with blank pages
+   to the next multiple of 4, so the book always ends blank whatever its
+   length. dc-native.css drops the wall on this page.
+   --------------------------------------------------------------------------- */
+
+@page printer-blank {
+  @bottom-left  { content: none; }
+  @bottom-right { content: none; }
+}
+
+.dc-printer-page {
+  page: printer-blank;
+  break-before: page;
+  height: var(--gp-content-h);
+}
+
 .dc-suppress-footer {
   page: clean;
 }
@@ -147,25 +183,34 @@
    are left alone, so these pages keep the body footers.
    --------------------------------------------------------------------------- */
 
+/* The running head is TEXT, so DriveThruRPG wants it 0.5in inside the trim
+   — below the default top margin, whose whole band lies within 0.5in of
+   the trim. These pages carry a deeper top margin and set the head at the
+   foot of it: 0.875in from the sheet edge, head baseline ~0.7in, 0.58in
+   from the trim. (It printed at 0.1in from the trim.) */
 @page citizen-file:right {
+  margin-top: 0.875in;
   @top-right {
     content: "Citizen File";
     color: var(--amber);
     font-family: var(--font-display);
     letter-spacing: 0.1em;
     font-size: 0.8em;
-    padding-top: 0.1in;
+    vertical-align: bottom;
+    padding-bottom: 0.08in;
   }
 }
 
 @page citizen-file:left {
+  margin-top: 0.875in;
   @top-left {
     content: "Citizen File";
     color: var(--amber);
     font-family: var(--font-display);
     letter-spacing: 0.1em;
     font-size: 0.8em;
-    padding-top: 0.1in;
+    vertical-align: bottom;
+    padding-bottom: 0.08in;
   }
 }
 

package/styles/page-templates.css

@@ -102,8 +102,16 @@
 
 /* The exception the guard above is scoped around: a page holding pinned or
    bleed art must not clip it. `.gp-behind` is included because it is pinned
-   art by another name (a `.gp-pin` that paints under the text). */
-.page:is(:has(.gp-bleed), :has(.gp-pin), :has(.gp-behind)) {
+   art by another name (a `.gp-pin` that paints under the text). The two
+   full-sheet plates are bleed art too: `.dc-specialty-art` and
+   `.dc-full-page` are sheet-wide on their zero-margin `full` page while the
+   `.page` around them keeps the body column's width, so the guard cut them
+   off at the column edge — a 100pt strip of bare wall down the outside of
+   every specialty plate on a page with no other pinned art (design guide
+   p.45, p.105). The Field Guide escaped only because its specialty pages
+   also carry pinned art. */
+.page:is(:has(.gp-bleed), :has(.gp-pin), :has(.gp-behind),
+         :has(.dc-specialty-art), :has(.dc-full-page)) {
   overflow-x: visible;
 }
 
@@ -537,6 +545,28 @@
   break-inside: auto;
 }
 
+/* The learning-path BANNER (the shell: title, intro, sticker row) is never
+   split and stays on the page of the first card after it. Note the rule
+   above does NOT do this: Chromium does not support `break-before: always`
+   and drops the declaration (measured by the Field Guide). Targets the
+   shell, not .dc-learning-path, which usually also holds the path's cards.
+   Without it the design guide printed the Biting Distance banner alone on
+   a page, with the edge of the first card's tab at the page foot. Carried
+   from the Field Guide's own sheet, where it is measured; the Field Guide
+   renders pixel-identical with it here. */
+.dc-specialty .dc-path-shell {
+  break-inside: avoid;
+  break-after: avoid;
+}
+
+/* A banner that opens a page sits flush with its top. Chromium drops the
+   shell's 8px top margin at every unforced break but keeps it after the
+   forced break that ends a specialty's art page — and those 8px were all
+   that kept the first card off its banner's page. */
+.dc-specialty > .dc-learning-path:first-child > .dc-path-shell {
+  margin-top: 0;
+}
+
 /* ── PAGE TEMPLATE: INTRO (chapter intro / narrative entry) ─────────────────
    KEEPS the default .dc-chevron heading styling (magenta banner with its
    own bottom-right diagonal clip-path) — that's the established intro
@@ -552,21 +582,18 @@
      - Section gets a clean paper-cream substrate with the same 4px
        magenta left rail as the lede; rail runs continuously through
        both.
-     - ONE filter: drop-shadow on the .page wrapper follows the union
-       silhouette of all three children — chevron's clip-path included
-       — so the shadow respects the chevron's diagonal cut and there's
-       no top-right gap on the lede (per-child box-shadow with offset-y
-       leaves a few-pixel notch at every child's top-right; the wrapper
-       filter never does). Per-child box-shadows therefore SUPPRESSED.
-       MEMORY R8: composite shadows via filter:drop-shadow on the
-       common wrapper.
+     - Vector shadows, per element: the lede and section each carry
+       --shadow-poster; the clipped chevron carries none. This was ONE
+       `filter: drop-shadow()` on the .page wrapper, which Chromium
+       prints as a bitmap — the whole intro page went to the PDF as a
+       300ppi image with a soft mask (no live text; PDF/X-1a forbids the
+       mask).
 
    --intro-accent is the single recolor knob, mirroring --frontmatter-
    accent's role on the TOC/Credits template. */
 .page.page-intro {
   --intro-accent: var(--brand-magenta-deep);
   --dc-intro-accent: var(--intro-accent);
-  filter: drop-shadow(var(--shadow-poster));
 }
 
 /* Chevron geometry on the standalone intro page. This page is NOT a
@@ -591,20 +618,18 @@
 }
 
 /* Lede flush-attaches to the chevron above; bottom margin zeroed so
-   the next sibling .section sits flush below. box-shadow suppressed —
-   page-level filter:drop-shadow provides the composite shadow. */
+   the next sibling .section sits flush below. It keeps the component's
+   own --shadow-poster. */
 .page.page-intro .dc-intro {
   margin-bottom: 0;
   padding-bottom: 0;
-  box-shadow: none;
 }
 .page.page-intro .dc-intro > :last-child {
   margin-bottom: 0;
 }
 
 /* Section content — paper-cream substrate, magenta 4px left rail
-   continuing from the lede. box-shadow suppressed; page filter handles
-   the composite shadow. */
+   continuing from the lede, with the poster shadow. */
 .page.page-intro > .section {
   background: linear-gradient(
     to right,
@@ -612,7 +637,7 @@
     var(--paper-cream) 4px
   );
   padding: 0.18in 0.22in;
-  box-shadow: none;
+  box-shadow: var(--shadow-poster);
 }
 
 /* Suppress the .section base ::before (magenta gradient + 18px top-right