gp-dimm-city 1.6.2 → 1.6.3-alpha.2

package/CHANGELOG.md

@@ -7,6 +7,94 @@ cut a version that has no `## [X.Y.Z]` heading below.
 
 ## [Unreleased]
 
+## [1.6.3] - 2026-10-12
+
+Content and markers by default, overrides when wanted: the defaults now do more,
+so a book writes fewer `.dc-avoid-split`, `.dc-snug`, `{.dc-chevron}` and `gp-*`
+classes, and every override that stays is documented and has a token a book can
+set from its own CSS.
+
+### Changed
+
+- **A creature stays whole by default.** An `@npc-stat` with no `####`, or one (a
+  species and its one variant), is one creature, read at one glance: it keeps its
+  padding inside its box and moves to the next page rather than splitting, as
+  `.dc-avoid-split` did. `.dc-avoid-split` on one is now redundant. A block with
+  two or more `####` entries is unchanged (it breaks between entries, never inside
+  one). `--dc-npc-stat-break-inside: auto` lets one split.
+- **A catalog splits by default, and an explicit override still wins.** A
+  `@section catalog` reads its own token, `--dc-catalog-break-inside` (default
+  `auto`), because a run of entries kept whole leaves the foot of the page before
+  it blank. An author's `.dc-avoid-split` on it still keeps it whole, as it always
+  did, and so does `--dc-catalog-break-inside: avoid` from a book's CSS. A
+  container's `--dc-section-break-inside` does not reach a catalog.
+- **Keeping a box whole is a token per component.** `--dc-section-break-inside`,
+  `--dc-catalog-break-inside`, `--dc-npc-stat-break-inside`,
+  `--dc-skill-card-break-inside` and `--dc-faction-break-inside` are declared at
+  `:root` (`avoid` or `auto`), and each component reads its own. `.dc-avoid-split`
+  is now a setter of them (and of `--dc-section-edge: 0px`, which keeps a whole
+  section's padding inside its box), so a book writes the same declarations for
+  one box from its own sheet (`#core-loop { --dc-section-break-inside: avoid;
+  --dc-section-edge: 0px; }`). A sheet that sets only the first still keeps the
+  section whole; the second keeps the pagination identical to the class. Sections,
+  skill cards and factions render as before. The skill card's `:not(.dc-avoid-split)`
+  guards on its keep-with-next chains are gone: a card kept whole is unaffected by
+  chains until it is taller than a page.
+- **The space under paragraphs and list items is `--dc-flow-gap`.** `.dc-snug` is
+  now a setter of it (0.04in), and a book sets it on any box. Unset, each
+  component keeps its own spacing, so nothing changes until it is set. A
+  `revert-layer` fallback in the template layer hands the margin back to the
+  component while the token is unset.
+- **Entry art has a default.** An image with no class inside a `@gear` entry
+  floats right at half the card (`--dc-entry-art-width`, 50%), as
+  `{.gp-right .gp-medium}` does. An image with no class on its own line under the
+  credits colophon is a band across the foot of the sheet, the page's full width
+  and `--dc-credits-art-height` (2.75in) tall, cropped to fit. Both read only an
+  image with no class, so a `gp-*` class an author writes still wins (the plugin's
+  layer outranks core's).
+- **A front-matter title is a chevron by context.** The plugin writes `.dc-chevron`
+  on the `h1` straight under `@page intro`, `credits` and `contents`, so those
+  titles need no `{.dc-chevron}`; the class still works on any other heading and
+  is not doubled where it is written. The snippets for the three pages no longer
+  write it.
+
+### Fixed
+
+- **A ladder table keeps what the author wrote on it.** `{#id .class}` after a
+  table of the five bands, outside a skill card and in one, was dropped with the
+  table; it now lands on the `.dc-outcomes` element, with any other attribute.
+- **`@procedure` keeps the attributes on its line.** The wrapper renders nothing,
+  so `@procedure #steps .tight` lost its id and class; they now land on the list
+  (the first, when there are several, so an id stays unique).
+
+### Removed
+
+- **Two selectors that matched nothing in the design guide or either book:**
+  `.dc-skill-card:only-child` and `.dc-sidebar:empty`, and the
+  `.dc-card.dc-faction.dc-avoid-split` rule the faction token replaces. The 94
+  selectors that match nothing in the two books were checked against the design
+  guide too: 79 are documented there (`.dc-stat*`, `.dc-tape`, `.dc-spec-tweak`,
+  `.dc-npc-compact`, `.dc-img-float-*`, `.dc-sidebar`, the `@npc-stat` stat-line
+  rules and others), and the rest are element baselines, a rule a test asserts, or
+  the loose-list half of a live selector, so they stay (see
+  `docs/cleanup-backlog.md`).
+
+### Added
+
+- **README: "Author overrides".** One section for the supported overrides: core's
+  `gp-*` classes (a pointer to the Gutterpress guide), each plugin modifier with
+  what it does and the token that does the same from a book's CSS,
+  `@page-break`, `@columns`, `{#id}`, and the coming `[data-name]` hook. The
+  "what are you writing" tables no longer list `.dc-avoid-split`, `.dc-snug` or
+  `.dc-sidebar` as if ordinary content needed them, in the README and the design
+  guide.
+- **The catalog names every class an author can write.** `components.yaml`:
+  `modifier:` takes a class or a list, `description:` is one line for every
+  modifier and author-facing class, and `.dc-h3` … `.dc-h6`, `.dc-chevron`,
+  `.dc-flush`, `.dc-spray`, `.dc-spec-tweak` / `.dc-no-top`, `.dc-sidebar` and the
+  image floats are entries with their modifier, for the app's completions. The
+  integrity test checks both.
+
 ## [1.6.2] - 2026-10-12
 
 ### Changed

package/README.md

@@ -46,7 +46,6 @@ package renders and prints; `docs/macros.md` is the full inventory and
 | I am writing… | Use |
 |---|---|
 | Rules or reference text under a heading | `@section panel` |
-| The same, kept on one page | `@section panel .dc-avoid-split` |
 | Unboxed text that carries the accent rail | `@section flat` |
 | A table or list to look up (prices, conditions, a menu of options) | `@section reference` |
 | World or setting text | `@section lore` |
@@ -56,7 +55,6 @@ package renders and prints; `docs/macros.md` is the full inventory and
 | A boxed note, warning, DM note, vibe, origin or visit | `@callout …` (`@dm-note`) |
 | A worked example | `@callout example` |
 | A box in one of three registers: panel, slate, shard | `@block …` |
-| A callout floated beside the text | `@callout note .dc-sidebar` |
 | Fiction, a chapter-opener story | `@fiction-excerpt` |
 | A creature or NPC | `@npc-stat` (small ones: `@npc-stat compact`) |
 | An organization: megacorp, cabal, cult, enforcers | `@faction megacorp`, `cabal`, `cult`, `enforcer` |
@@ -74,14 +72,16 @@ package renders and prints; `docs/macros.md` is the full inventory and
 | The specialty catalog | `@card-grid` |
 | A specialty, its learning paths and skill cards | `@specialty`, `@learning-path`, `@skill` |
 | Grouping, with no styling | `@section` |
-| A section that overflows by a line or two | add `.dc-snug` |
 | Where it sits | `@page chapter-start`, `intro`, `credits`, `contents`, `citizen-file` (and core's `blank`, `full-bleed`); `@chapter rules`, `lore`, `citizen-file`, `specialty` |
 
 The named components are also words on `@section` (`@npc-stat` is
 `@section npc`, `@fiction-excerpt` is `@section fiction`); either spelling
 renders the same. `reference`, `lore`, `dm` and `choose` are words only: panels
-that say what kind of text they hold. Sections split across pages by default. A page or chapter
-word draws no box of its own: it re-tunes the sections inside it.
+that say what kind of text they hold. Write the content and the marker that says
+what it is: the defaults set how it looks and where it breaks (sections split
+across pages, a catalog too, and a creature and a callout stay whole). A page
+or chapter word draws no box of its own: it re-tunes the sections inside it. To
+change how one block sits, see [Author overrides](#author-overrides).
 
 Also in the box:
 
@@ -126,6 +126,66 @@ to lay down the front matter, and reach for *Skill*, *Learning Path* and
 *Specialty* as you write. `page-rules.css` sets a Letter page with bleed; keep
 the manifest's `page:` in step with it.
 
+## Author overrides
+
+A book's markdown holds the content and the markers that say what it is
+(`@section panel`, `@npc-stat`, `@gear augment`); the defaults above make it
+look right and break sensibly. None of what follows is needed for that. These
+are the supported ways to change one block when the defaults do not suit it:
+written in the markdown, or from the book's own CSS, with the same effect. They
+are documented and kept; the defaults only make them needed less often.
+
+**Core Gutterpress classes (`gp-*`).** Image placement and size (`.gp-left`,
+`.gp-right`, `.gp-center`, `.gp-full`, `.gp-bleed`, `.gp-small`, `.gp-medium`,
+`.gp-large`), pinning art to the page (`.gp-pin` with `.gp-top`, `.gp-bottom`,
+`.gp-flush`, `.gp-behind`), wrapping text around a shape (`.gp-shape`) and the
+fragmentation helpers (`.gp-no-break`, `.gp-break-before`) belong to Gutterpress,
+not to this package. They are written as `![alt](image.png){.gp-right
+.gp-medium}` and are documented in the Gutterpress user guide
+([Visual elements](https://github.com/dimm-city/gutterpress/blob/main/examples/gutterpress-user-guide/03-visual-elements.md)).
+This package's defaults for art (below) read only an image with no class, so a
+`gp-*` class always wins.
+
+**Modifiers from this package.** Written after a marker (`@section panel
+.dc-snug`) or in braces after an element (`## Title {.dc-h3}`). Each has a
+matching setting for a book's CSS, so a book can do the same without a markdown
+edit.
+
+| Write | What it does | The same from a book's CSS |
+|---|---|---|
+| `.dc-avoid-split` on `@section`, `@skill`, `@faction` or `@npc-stat` | Keep that box on one page: it moves to the next page rather than splitting | `--dc-section-break-inside: avoid` with `--dc-section-edge: 0px` (a section), `--dc-skill-card-break-inside`, `--dc-faction-break-inside`, `--dc-npc-stat-break-inside` |
+| `.dc-snug` on `@section` or `@page` | Tighten the space under paragraphs and list items, for one that overflows by a line or two | `--dc-flow-gap: 0.04in` |
+| `.dc-h3` … `.dc-h6` on a heading or paragraph | Give it the look of that level without changing its place in the outline | none: a class only |
+| `.dc-chevron` on a heading | Set it as a chevron banner (the title under `@page intro`, `credits` and `contents` already is one) | `--dc-chevron-bg`, `--dc-chevron-color`, `--dc-chevron-font-size` |
+| `.dc-flush` | Run a tape, stat block, sticker chain, pull quote or `@outcome` edge to edge | none: a class only |
+| `.dc-sidebar` on a callout | Float it right at about a third of the width, text wrapping on its left (`@callout note .dc-sidebar`) | none: a class only |
+| `.dc-spray`, `.dc-spec-tweak`, `.dc-no-top`, `.dc-img-float-left`, `.dc-img-float-right` | Heading banners and an image float | none: classes only |
+
+A catalog (`@section catalog`) splits across pages by default, since one kept
+whole leaves the foot of the page before it blank; an explicit `.dc-avoid-split`
+on it still keeps it whole, as does `--dc-catalog-break-inside: avoid` from a
+book's CSS. An `@npc-stat` with at most one `####` is one creature and stays whole without
+`.dc-avoid-split` (`--dc-npc-stat-break-inside: auto` lets one split). An image
+with no class in a `@gear` entry floats right at half the card
+(`--dc-entry-art-width`), and one on its own line under the credits colophon is
+a band across the foot of the sheet (`--dc-credits-art-height`).
+
+**Core markers and attributes.** `@page-break` starts a new page at that line;
+`@columns 2` … `@end-columns` (one to five columns, and `@column-break` to move
+to the next) is the one way to set text in columns. Both are Gutterpress's, not
+this package's. `{#id}` (or `#id` on a marker line) names a block for a link and
+for a book's CSS: `#core-loop { --dc-section-break-inside: avoid; }`. Written after
+a table the package turns into an outcome ladder, or on an `@procedure` line, the
+id and classes land on the ladder or the list.
+
+**Coming: `[data-name]`.** Gutterpress will stamp a stable `data-name` on every
+marker block, image and heading (from `name="…"`, then `label="…"`, then the
+slug of its first heading, or the image's file name), so a book's CSS can tune
+one block without touching the markdown:
+`[data-name="core-loop"] { --dc-section-break-inside: avoid; }`. Until your
+Gutterpress does, `name="…"` on a marker line writes it and `#id` works
+everywhere.
+
 ## Your own CSS: the layer convention
 
 List your sheets under `styles:` in the manifest. Gutterpress (0.11.0+) wraps
@@ -174,6 +234,14 @@ of every page). Public API for semver purposes: the macro vocabulary, the
 classes and tokens marked `live` in `components.yaml`, the page templates, and
 the layer names. `CHANGELOG.md` lists what each release changes.
 
+### Moving from 1.6.2 or earlier
+
+1.6.3 changes a default, so rebuild and compare:
+
+- An `@npc-stat` with at most one `####` (one creature) stays whole. Add
+  `--dc-npc-stat-break-inside: auto` to let one split. A `.dc-avoid-split` on one
+  is now redundant.
+
 ### Moving from 1.6.1 or earlier
 
 1.6.2 folds the item markers into `@gear` and gives the SPECS box one spelling.

package/components.yaml

@@ -16,8 +16,12 @@
 #   each exactly as written: "@npc-stat", "@section npc", "@page intro",
 #   "@chapter rules"; a retired entry lists the spellings that no longer
 #   work) · snippet (the file or files in snippets/ that insert it, by name
-#   without .md) · modifier (a class that changes a component without being
-#   one: dc-avoid-split, dc-snug) · replaced_by (retired entries: what to
+#   without .md) · modifier (the class, or list of classes, an author writes
+#   in `{…}` or after a marker to change a box without being a component:
+#   dc-avoid-split, dc-snug, dc-chevron, dc-h3…dc-h6; the app offers each as
+#   a completion) · description (one line, what an author gets from the
+#   class or word; every author-facing entry and every modifier has one) ·
+#   replaced_by (retired entries: what to
 #   write now) · recipe · emits (DOM strings, one or a list) · css
 #   (package-relative paths; required for live/unused, and at least one must
 #   style one of the entry's classes) · tokens (must be declared under
@@ -169,6 +173,7 @@ components:
   - name: block-variants
     status: live
     origin: author
+    description: "The three looks of a @block: panel (HUD), slate (dark) and shard (zine)."
     recipe: "@block panel | slate | shard"
     emits: div.dc-block.dc-panel|.dc-slate|.dc-shard
     css: styles/components/section.css
@@ -218,9 +223,9 @@ components:
     recipe: "@gear [augment|treasure|vehicle|drug] #### Name … @end-gear  (a @gear after a @gear closes the first)"
     emits: div.dc-card.dc-entry.dc-gear
     css: styles/components/entries.css
-    tokens: [--dc-entry-accent, --dc-entry-ink, --dc-entry-surface, --dc-entry-rail, --dc-entry-rule, --dc-entry-kind]
+    tokens: [--dc-entry-accent, --dc-entry-ink, --dc-entry-surface, --dc-entry-rail, --dc-entry-rule, --dc-entry-kind, --dc-entry-art-width]
     breaks: "break-inside: avoid (via .dc-card)"
-    notes: "The item entry, and the one marker for every kind of item: bare `@gear` is general gear, and a bare word picks a kind (`augment`, `treasure`, `vehicle`, `drug`, the four entries below). A .dc-card of the entry family with an orange rail; the name (### or ####), the italic tagline paragraph and the bold price paragraph are picked out by shape. A `**SPECS:**` paragraph is a `@field specs`. Reports an entry with no name or with a second one, and a word that is not a kind (read as general gear). Not a section, so there is no `@section` word for it. A run of entries goes in a `@section catalog`; each kind is told apart by its rail colour and the small kind word over its name."
+    notes: "The item entry, and the one marker for every kind of item: bare `@gear` is general gear, and a bare word picks a kind (`augment`, `treasure`, `vehicle`, `drug`, the four entries below). A .dc-card of the entry family with an orange rail; the name (### or ####), the italic tagline paragraph and the bold price paragraph are picked out by shape. An image with no class in an entry is the item's picture: floated right at --dc-entry-art-width (half the card); a class the author writes (`{.gp-left .gp-large}`) places it instead. A `**SPECS:**` paragraph is a `@field specs`. Reports an entry with no name or with a second one, and a word that is not a kind (read as general gear). Not a section, so there is no `@section` word for it. A run of entries goes in a `@section catalog`; each kind is told apart by its rail colour and the small kind word over its name."
 
   - name: augment
     status: live
@@ -313,6 +318,7 @@ components:
   - name: tape
     status: live
     origin: author
+    description: "A torn-tape divider with a label (raw HTML div)."
     recipe: "<div class=\"dc-tape\">…</div>  (add dc-flush to run edge to edge)"
     emits: div.dc-tape
     css: styles/components/chrome.css
@@ -352,7 +358,7 @@ components:
       - --dc-outcome-name-color
       - --dc-outcome-name-opacity
     usage: ["| 20 |"]
-    breaks: "break-inside: avoid; the skill-table form adds data-break-inside=avoid only when the parent card allows splitting"
+    breaks: "break-inside: avoid"
     notes: "Declared marker; `flush` is its one variant (also writable .dc-flush). One row per `roll | name | text` line, coloured by position; a sixth row is a plain hit. Left open at the end of the file it warns (declared_marker_eof_close); a line that is not a row, a non-row block, or no rows at all is reported. The table form is recognised by its band values, not its headers: a table with any other set of bands (six bands, three, a split at 10) is a plain table, or an @roll-table. A table row's tier and name come from its band (20 crit, 11-19 hit, 6-10 hard choice, 2-5 miss, 1 catastrophe)."
 
   - name: specialty
@@ -470,7 +476,8 @@ components:
       - --dc-card-body-mark
       - --dc-card-gap
       - --dc-card-tab-shadow
-    breaks: "splits across pages by default (a card is a third to half a page, so whole cards left pages one card deep); a split card never opens with only its tab, an ability row is never cut, a lead-in stays with what it introduces, and the last block stays with the one above it. {.dc-avoid-split} keeps one whole (and writes data-break-inside=avoid)"
+      - --dc-skill-card-break-inside
+    breaks: "splits across pages by default (a card is a third to half a page, so whole cards left pages one card deep); a split card never opens with only its tab, an ability row is never cut, a lead-in stays with what it introduces, and the last block stays with the one above it. {.dc-avoid-split} keeps one whole, as --dc-skill-card-break-inside: avoid does"
     notes: "Declared marker. Every #### heading in one @skill is its own card, with the @skill line's classes and attributes. @end-skill closes only the skill, never the path around it. A ##### Outcomes sub-header is swallowed (the outcomes block carries its own label). Part of a card's body can sit in columns: wrap it in `@columns 2` … `@end-columns`; the run (and any `@column-break` in it) stays inside the card's .dc-card-inner, in place."
 
   - name: skill-highlight
@@ -526,6 +533,8 @@ components:
   - name: flush
     status: live
     origin: plugin
+    modifier: dc-flush
+    description: "Run a tape, stat block, sticker chain, pull quote or outcome ladder edge to edge, with no side margin."
     recipe: "@outcome flush, > [!PULLQUOTE], or .dc-flush on raw .dc-tape / .dc-stat / .dc-stickers"
     emits: .dc-flush (edge-to-edge modifier)
     css: [styles/components/chrome.css, styles/components/data.css]
@@ -598,7 +607,8 @@ components:
       - --dc-npc-stat-label-color
       - --dc-npc-stat-rule
       - --dc-npc-stat-rule-width
-    breaks: "a block with #### entries breaks between entries, never inside one (keep-with-next chain), whether the entries are direct children or sit in an @columns run inside it; a block with no #### splits like any section (.dc-avoid-split keeps it whole)"
+      - --dc-npc-stat-break-inside
+    breaks: "a block with #### entries breaks between entries, never inside one (keep-with-next chain), whether the entries are direct children or sit in an @columns run inside it; a block with no ####, or one, is one creature and stays whole (--dc-npc-stat-break-inside: auto lets one split)"
 
   - name: npc-stat-compact
     status: live
@@ -630,9 +640,9 @@ components:
     recipe: "@page credits"
     emits: div.page.dc-page-credits
     css: [styles/page-templates.css, styles/page-rules.css, styles/dc-native.css]
-    tokens: [--dc-intro-gap, --dc-intro-pad-bottom, --dc-section-gap, --dc-section-grow, --dc-section-drop]
+    tokens: [--dc-intro-gap, --dc-intro-pad-bottom, --dc-section-gap, --dc-section-grow, --dc-section-drop, --dc-credits-art-height]
     breaks: "page: front-matter (no footer)"
-    notes: "The credits page: masthead, lede and colophon stacked flush. The colophon names go in `@columns 2` inside `@section flat`; the page sets the flat section's accent, drop, gap and grow by tokens."
+    notes: "The credits page: masthead, lede and colophon stacked flush. The title is a chevron banner by context, with no `{.dc-chevron}`. The colophon names go in `@columns 2` inside `@section flat`; the page sets the flat section's accent, drop, gap and grow by tokens. An image with no class on its own line under the colophon is the plate: a band across the foot of the sheet, --dc-credits-art-height tall, cropped to fit; a class the author writes places it instead."
 
   - name: page-contents
     status: live
@@ -644,7 +654,7 @@ components:
     css: [styles/page-templates.css, styles/page-rules.css, styles/dc-native.css]
     tokens: [--dc-toc-rail-y, --dc-toc-rail-x, --dc-toc-shadow, --dc-toc-badge, --dc-intro-gap, --dc-intro-pad-bottom]
     breaks: "page: front-matter (no footer)"
-    notes: "The contents page: masthead, lede and the @toc card stacked flush. The page sets the card's rails, shadow and number-chip colour by tokens."
+    notes: "The contents page: masthead, lede and the @toc card stacked flush. The title is a chevron banner by context, with no `{.dc-chevron}`. The page sets the card's rails, shadow and number-chip colour by tokens."
 
   - name: page-intro
     status: live
@@ -656,7 +666,7 @@ components:
     css: [styles/page-templates.css, styles/page-rules.css]
     tokens: [--dc-intro-gap, --dc-intro-pad-bottom, --dc-chevron-bg, --dc-section-accent, --dc-section-drop]
     breaks: "page: front-matter-intro (no footer, ordinary margins)"
-    notes: "The introduction: chevron, lede, then a `@section flat`. The page sets the lede's and the flat section's tokens."
+    notes: "The introduction: chevron, lede, then a `@section flat`. The title is a chevron banner by context, with no `{.dc-chevron}`. The page sets the lede's and the flat section's tokens."
 
   # ── Chapter words: a register for the sections in the chapter ──────────
   - name: chapter-rules
@@ -706,14 +716,19 @@ components:
   - name: chevron
     status: live
     origin: author
+    modifier: dc-chevron
+    description: "Set a heading as a chevron banner (an h1 under @page intro, credits or contents already is one)."
     recipe: "# Title {.dc-chevron}  (the chapter-opener h1 gets the same treatment structurally)"
     emits: h1.dc-chevron
     css: [styles/components/chrome.css, styles/dc-native.css, styles/page-templates.css]
     tokens: [--dc-chevron-bg, --dc-chevron-color, --dc-chevron-font-size]
+    notes: "The plugin writes the class on the h1 straight under @page intro, credits or contents, so a front-matter title needs none. It is the override for a heading anywhere else, and for a page that is not one of the three (a bare @page holding the introduction)."
 
   - name: spray
     status: live
     origin: author
+    modifier: dc-spray
+    description: "Set a heading as a spray-paint banner."
     recipe: "## Title {.dc-spray}  (also emitted by @learning-path for its title)"
     emits: ["h2.dc-spray (authored)", "h3.dc-spray (a @learning-path title)"]
     css: [styles/components/chrome.css, styles/components/data.css]
@@ -723,6 +738,8 @@ components:
   - name: spec-tweak
     status: live
     origin: author
+    modifier: [dc-spec-tweak, dc-no-top]
+    description: "Set a heading as a Spec Tweak title; .dc-no-top drops its top margin."
     recipe: "### Title {.dc-spec-tweak [.dc-no-top]}"
     emits: h3.dc-spec-tweak[.dc-no-top]
     css: styles/components/chrome.css
@@ -730,6 +747,7 @@ components:
   - name: classtag
     status: live
     origin: author
+    description: "A pill naming a specialty, with that specialty's colour dot (raw HTML span)."
     recipe: "raw <span class=\"dc-classtag <specialty>\">"
     emits: span.dc-classtag.<specialty>
     css: styles/components/chrome.css
@@ -738,6 +756,7 @@ components:
   - name: tag
     status: live
     origin: author
+    description: "A small keyword or cost label (raw HTML span)."
     recipe: "raw <span class=\"dc-tag\">"
     emits: span.dc-tag
     css: styles/components/chrome.css
@@ -745,6 +764,7 @@ components:
   - name: human-callout
     status: live
     origin: author
+    description: "A boxed NPC capsule, usually floated inside a .dc-sidebar (raw HTML div)."
     recipe: "raw <div class=\"dc-sidebar\"><div class=\"dc-human-callout\">…  (NPC sidebar)"
     emits: div.dc-human-callout
     css: styles/components/images.css
@@ -753,6 +773,7 @@ components:
   - name: at-a-glance-card
     status: live
     origin: author
+    description: "A label-and-value card, three to a row inside @columns 3 (raw HTML div)."
     recipe: "@columns 3 / raw <div class=\"dc-at-a-glance-card\"> × 3 / @end-columns"
     emits: div.dc-at-a-glance-card
     css: styles/components/data.css
@@ -760,6 +781,7 @@ components:
   - name: stat-block
     status: live
     origin: author
+    description: "A four-cell stat grid with a name and a class line (raw HTML div; a creature's HP and Damage table is a stat strip instead)."
     recipe: "raw <div class=\"dc-stat [dc-flush]\"> with .dc-stat-head, .dc-stat-grid cells and .dc-stat-line"
     emits:
       - div.dc-stat > div.dc-stat-head > span.dc-stat-name + span.dc-stat-class
@@ -772,26 +794,41 @@ components:
     status: live
     origin: author
     modifier: dc-avoid-split
+    description: "Keep this section, skill card, faction or creature on one page: it moves to the next page rather than splitting."
     snippet: avoid-split
-    recipe: "@section panel .dc-avoid-split  |  @skill .dc-avoid-split"
+    recipe: "@section panel .dc-avoid-split  |  @skill .dc-avoid-split  |  from a book's sheet: #id { --dc-section-break-inside: avoid; --dc-section-edge: 0px; }"
     emits: .dc-avoid-split (on the section or skill card it is written on)
     css: [styles/components/section.css, styles/components/cards.css]
-    breaks: "break-inside: avoid — the section or card moves to the next page rather than splitting. Sections and skill cards split by default, so nothing else in this package sets break-inside on one (a skill card also carries data-break-inside=avoid)"
-    notes: "Replaces .dc-allow-split on sections and on skill cards. Avoid it on a section taller than a column inside @columns: it cannot split, and the facing column goes empty. On a skill card it costs a page of one card: use it for a card that must read as one object."
+    tokens: [--dc-section-break-inside, --dc-section-edge, --dc-npc-stat-break-inside, --dc-skill-card-break-inside, --dc-faction-break-inside]
+    breaks: "break-inside: avoid. The class is a setter of the keep-whole tokens on the box it is written on, nothing more; a book writes the same declarations from its own sheet. A catalog splits by default, but the class keeps one whole (it sets --dc-catalog-break-inside: avoid)"
+    notes: "Replaces .dc-allow-split on sections and on skill cards. Avoid it on a section taller than a column inside @columns: it cannot split, and the facing column goes empty. On a skill card it costs a page of one card: use it for a card that must read as one object. A creature (an @npc-stat with at most one ####) needs none: it stays whole by default."
 
   - name: snug
     status: live
     origin: author
     modifier: dc-snug
+    description: "Tighten the space under paragraphs and list items in this section or page, for one that overflows by a line or two."
     snippet: snug
-    recipe: "@section .dc-snug  /  @page .dc-snug"
+    recipe: "@section .dc-snug  /  @page .dc-snug  |  from a book's sheet: #id { --dc-flow-gap: 0.04in; }"
     emits: .dc-snug (on the section or page it is written on)
     css: styles/page-templates.css
-    notes: "Paragraph and list-item margin-bottom drops to 0.04in so a section or page that overflows by a line or two fits. Type size and leading are untouched."
+    tokens: [--dc-flow-gap]
+    notes: "A setter of --dc-flow-gap, the margin-bottom of a paragraph or list item inside it, to 0.04in. Unset, each component keeps its own spacing; set on a box or anything above it, it is the space under every paragraph and list item in it. Type size and leading are untouched."
+
+  - name: heading-look
+    status: live
+    origin: author
+    modifier: [dc-h3, dc-h4, dc-h5, dc-h6]
+    description: "Give a heading, or a paragraph, the look of a lower level without changing its place in the outline."
+    recipe: "## Useful Items {.dc-h3}  |  {.dc-h4}  |  {.dc-h5}  |  {.dc-h6}"
+    emits: .dc-h3 | .dc-h4 | .dc-h5 | .dc-h6 (on the heading or paragraph it is written on)
+    css: [styles/dc-core.css, styles/components/section.css]
+    notes: "A heading's level is its place in the outline and its look follows the level; the class sets the look of that level and the outline stays unbroken (`#` then `##`, never `#` then `###`). An `##` with .dc-h3 that opens a panel takes the subordinate title bar. On a paragraph it sets a line in heading type without adding it to the outline."
 
   - name: full-page
     status: live
     origin: author
+    description: "A page that is one full-bleed plate, edge to edge (the same page as core's @page full-bleed)."
     recipe: "@page .dc-full-page  (core's @page full-bleed gets the same geometry and named page)"
     emits: div.page.dc-full-page
     css: [styles/page-templates.css, styles/page-rules.css, styles/dc-native.css]
@@ -801,6 +838,8 @@ components:
   - name: img-float
     status: live
     origin: author
+    modifier: [dc-img-float-left, dc-img-float-right]
+    description: "Float an image to one side at 44% of the column, text wrapping beside it (core's .gp-left and .gp-right do the same)."
     recipe: "![alt](src){.dc-img-float-left|.dc-img-float-right}"
     emits: img.dc-img-float-left|.dc-img-float-right
     css: styles/components/images.css
@@ -822,8 +861,8 @@ components:
     recipe: "@section panel … @end-section  (or @section .dc-section-panel)"
     emits: div.section.dc-section-panel
     css: [styles/components/section.css, styles/dc-component-defaults.css]
-    tokens: [--dc-section-bg, --dc-section-accent, --dc-section-surface, --dc-section-shadow, --dc-section-clip, --dc-section-rail, --dc-section-gap, --dc-section-pad-top, --dc-section-pad-right, --dc-section-pad-bottom, --dc-section-pad-left]
-    breaks: "splits by default; add .dc-avoid-split to keep it whole"
+    tokens: [--dc-section-bg, --dc-section-accent, --dc-section-surface, --dc-section-shadow, --dc-section-clip, --dc-section-rail, --dc-section-gap, --dc-section-edge, --dc-section-break-inside, --dc-section-pad-top, --dc-section-pad-right, --dc-section-pad-bottom, --dc-section-pad-left]
+    breaks: "splits by default; add .dc-avoid-split to keep it whole (it sets --dc-section-break-inside: avoid and --dc-section-edge: 0px, which a book can set from its own sheet)"
     notes: "The card: cream substrate, accent rail, clipped corner, shadow, and the first ## or ### as a title bar. @npc-stat, @citizen-walkthrough, @flaws, @ideals and @dreams are panels carrying their own class."
 
   - name: section-catalog
@@ -834,8 +873,8 @@ components:
     recipe: "@section catalog ## Title … @columns 2 @gear augment … @end-columns @end-section"
     emits: div.section.dc-section-panel.dc-catalog
     css: styles/components/entries.css
-    tokens: [--dc-entry-surface, --dc-entry-rail, --dc-entry-rule]
-    breaks: "a panel; its entries may split across a column or page (ruled, not boxed, so there is no frame to cut), the name keeps with what follows it"
+    tokens: [--dc-entry-surface, --dc-entry-rail, --dc-entry-rule, --dc-catalog-break-inside]
+    breaks: "a panel that splits by default (--dc-catalog-break-inside: auto); .dc-avoid-split, or --dc-catalog-break-inside: avoid, keeps one whole; its entries may split across a column or page (ruled, not boxed, so there is no frame to cut), the name keeps with what follows it"
     notes: "A panel for a run of entries (@gear, of any kind). Its entries are ruled instead of boxed (and may split across columns, as the plain text they replace did): no card, no rail, a rule in the entry's own accent over each, so no `---` is needed between entries (a `---` left in draws nothing). Columns are core's: write `@columns 2` under the intro."
 
   - name: section-flat
@@ -902,8 +941,8 @@ components:
     recipe: "@faction [megacorp|cabal|cult|enforcer] [label=\"…\"] / #### Name / fields and prose … @end-faction"
     emits: [div.dc-card.dc-faction.dc-faction-megacorp|.dc-faction-cabal|.dc-faction-cult|.dc-faction-enforcer, span.dc-faction-kind]
     css: [styles/components/section.css]
-    tokens: [--dc-faction-accent, --dc-faction-badge-fg]
-    breaks: "break-inside: avoid (via .dc-card)"
+    tokens: [--dc-faction-accent, --dc-faction-badge-fg, --dc-faction-break-inside]
+    breaks: "splits between paragraphs by default (--dc-faction-break-inside: auto); .dc-avoid-split keeps one whole"
     notes: "An organization's profile: a card whose rail and kind badge take the kind's colour (megacorp blue, cabal violet, cult blood, enforcer yellow). The kind is the bare word; the badge reads it unless label=\"…\" names its own; with neither there is no badge."
 
   - name: stat-strip
@@ -919,6 +958,8 @@ components:
   - name: sidebar-float
     status: live
     origin: author
+    modifier: dc-sidebar
+    description: "Float a callout to the right at about a third of the width, body text wrapping on its left."
     recipe: "@callout note .dc-sidebar label=\"…\"  (also raw <div class=\"dc-sidebar\"> around a human-callout)"
     emits: .dc-sidebar (on the callout or div it is written on)
     css: [styles/components/images.css]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gp-dimm-city",
-  "version": "1.6.2",
+  "version": "1.6.3-alpha.2",
   "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",

package/plugin.js

@@ -65,6 +65,10 @@
  *   `ROLL THE DIE!` (also ROLL A DIE!, ROLLS A DIE!, ROLLING THE DIE!)
  *                        → span.dc-roll-the-die
  *   an image-only paragraph gets p.dc-img-wrapper
+ *   the h1 under `@page intro | credits | contents` gets .dc-chevron
+ *   a table of the five standard bands is the outcome ladder (it keeps the
+ *                          table's `{#id .class}`); `@procedure` keeps the
+ *                          attributes written on its line, on its list
  *
  * GFM ALERT SYNTAX:
  *   `> [!NOTE]` / `[!WARNING]` / `[!DM]` / `[!VIBE]` / `[!ORIGIN]` / `[!VISIT]`
@@ -419,9 +423,16 @@ function outcomeRowsHtml(rows, md, head = []) {
   return html;
 }
 
-// A table of the five standard bands: tier and name come from the band.
-function buildLadderBlock({ head, rows }, md) {
-  return '<div class="dc-outcomes">\n' + outcomeRowsHtml(rows, md, head) + '</div>\n';
+// A table of the five standard bands: tier and name come from the band. The
+// ladder replaces the table, so what the author wrote on the table (`{#id
+// .class}`) and what the renderer threaded on it move to the ladder.
+function buildLadderBlock({ head, rows }, md, table) {
+  const attrs = [['class', 'dc-outcomes']];
+  for (const [name, value] of table.attrs || []) {
+    if (name === 'class') attrs[0][1] += ' ' + value;
+    else attrs.push([name, value]);
+  }
+  return '<div' + md.renderer.renderAttrs({ attrs }) + '>\n' + outcomeRowsHtml(rows, md, head) + '</div>\n';
 }
 
 // Parse ability from list item - handles rendered HTML: "<strong>0 AP</strong> <em>Name:</em> Description"
@@ -575,8 +586,15 @@ function collectOrderedListItems(tokens, startIndex, md) {
   return { items: items, endIndex: i };
 }
 
-function buildProcedureList(items) {
-  let html = '<ol class="dc-steps">\n';
+// `attrs` are what the author wrote on the `@procedure` line: the wrapper
+// renders nothing, so the list takes them.
+function buildProcedureList(items, attrs, md) {
+  const list = [['class', 'dc-steps']];
+  for (const [name, value] of attrs) {
+    if (name === 'class') list[0][1] += ' ' + value;
+    else list.push([name, value]);
+  }
+  let html = '<ol' + md.renderer.renderAttrs({ attrs: list }) + '>\n';
   items.forEach((itemHtml, idx) => {
     const stepNo = String(idx + 1).padStart(2, '0');
     html += '  <li><span class="dc-step-no">' + esc(stepNo) + '</span><span>' + itemHtml.trimEnd() + '</span></li>\n';
@@ -708,6 +726,31 @@ function dcImageParagraphs(state) {
   }
 }
 
+// The title of a front-matter page is a chevron banner because of where it
+// sits: the `h1` straight under `@page intro | credits | contents` is a
+// `.dc-chevron`, so the author writes no `{.dc-chevron}`. The class stays
+// available on any other heading.
+const FRONT_MATTER_PAGES = ['dc-page-intro', 'dc-page-credits', 'dc-page-contents'];
+
+function dcFrontMatterTitles(state) {
+  let front = false;
+  let depth = 0; // layout containers open inside the page: a heading in one is not the page's title
+  for (const tok of state.tokens) {
+    if (tok.type === 'layout_page_open') {
+      front = (tok.attrGet('class') || '').split(/\s+/).some((c) => FRONT_MATTER_PAGES.includes(c));
+      depth = 0;
+    } else if (tok.type === 'layout_page_close') {
+      front = false;
+    } else if (/^layout_.+_open$/.test(tok.type)) {
+      depth++;
+    } else if (/^layout_.+_close$/.test(tok.type)) {
+      depth--;
+    } else if (front && !depth && tok.type === 'heading_open' && tok.tag === 'h1') {
+      addTokenClass(tok, 'dc-chevron');
+    }
+  }
+}
+
 /**
  * `data-position="odd|even"` on every @specialty-card, counted across the
  * document in order so the card grid alternates its tilt/offset. The wrapper
@@ -991,7 +1034,7 @@ function dcSkillCards(state) {
         const tableTokens = collectTableTokens(content, i);
         const ladder = tok.meta?.rollTable ? null : ladderRows(readTable(tableTokens));
         if (ladder) {
-          emit(buildLadderBlock(ladder, md));
+          emit(buildLadderBlock(ladder, md, tok));
           i = skipToTableClose(content, i);
           continue;
         }
@@ -1096,7 +1139,7 @@ function dcLadderTables(state) {
     const tableTokens = collectTableTokens(tokens, i);
     const ladder = ladderRows(readTable(tableTokens));
     if (!ladder) continue;
-    tokens.splice(i, tableTokens.length, makeToken('html_block', buildLadderBlock(ladder, state.md)));
+    tokens.splice(i, tableTokens.length, makeToken('html_block', buildLadderBlock(ladder, state.md, tokens[i])));
   }
 }
 
@@ -1157,13 +1200,17 @@ function dcProcedures(state) {
     const [open, close] = [run[0], run[run.length - 1]];
     open.hidden = close.hidden = true;
     const out = [];
+    let attrs = open.attrs || []; // the first list takes them: an id stays unique
     for (let i = 1; i < run.length - 1; i++) {
       if (run[i].type !== 'ordered_list_open') {
         out.push(run[i]);
         continue;
       }
       const { items, endIndex } = collectOrderedListItems(run, i, state.md);
-      if (items.length > 0) out.push(makeToken('html_block', buildProcedureList(items)));
+      if (items.length > 0) {
+        out.push(makeToken('html_block', buildProcedureList(items, attrs, state.md)));
+        attrs = [];
+      }
       i = endIndex;
     }
     return [open, ...out, close];
@@ -1445,6 +1492,7 @@ export default function dimmCityPlugin(md, options = {}) {
   // (p.dc-img-wrapper { padding:0; margin:0 }) lives in components/data.css.
   // Per-page rules can further refine position via .page.my-class p.dc-img-wrapper.
   md.core.ruler.push('dc_image_paragraphs', dcImageParagraphs);
+  md.core.ruler.push('dc_front_matter_titles', dcFrontMatterTitles);
 
   // Declared components. Callouts, cards, outcomes and procedures go first so
   // one inside a skill is already rewritten when the skill's rule looks at it.

package/snippets/credits-page.md

@@ -1,6 +1,6 @@
 @page credits
 
-# Credits {.dc-chevron}
+# Credits
 
 @section flat
 

package/snippets/intro-page.md

@@ -1,6 +1,6 @@
 @page intro
 
-# {{title}} {.dc-chevron}
+# {{title}}
 
 @lede
 

package/snippets/toc-page.md

@@ -1,6 +1,6 @@
 @page contents
 
-# Contents {.dc-chevron}
+# Contents
 
 @lede
 

package/styles/components/cards.css

@@ -8,6 +8,7 @@
      --dc-card-tab-bg          → tab background (default --ink-dark)
      --dc-card-tab-title-color → tab title text color (default --paper-cream)
      --dc-card-body-mark       → decorative ::before mark color (default --crimson)
+     --dc-skill-card-break-inside → `avoid` keeps a card whole (default auto: it splits)
    Specialty themes override these via .dc-specialty.<name> .dc-skill-card { }.
    Adding a new specialty: copy a sibling block (.dc-specialty.augmerc .dc-skill-card)
    and replace token values with the new specialty's --<name>-* aliases. */
@@ -35,6 +36,7 @@
   overflow-x: clip;
   /* A card splits across pages by default (its chains are below); the
      `.dc-avoid-split` modifier keeps one whole. */
+  break-inside: var(--dc-skill-card-break-inside);
   /* --dc-card-gap is the VISIBLE gap; the +6px clears chrome bleed on top of
      it. Margin is layout space, but the shadow and outline pseudos paint
      outside the border-box without affecting it: this card's hard poster
@@ -284,15 +286,15 @@
 /* A card splits across pages by default: one is 30-50% of a page, so keeping
    it whole left most specialty pages holding a single card and a third of the
    sheet empty. `.dc-avoid-split` (a modifier on the `@skill` line, as on a
-   section) keeps one whole. Where it may split, it splits at sensible places. */
-.dc-skill-card.dc-avoid-split {
-  break-inside: avoid;
-}
+   section) keeps one whole, through `--dc-skill-card-break-inside`. Where it
+   may split, it splits at sensible places: the chains below. They stay on a
+   card that is kept whole, where they change nothing until it is taller than
+   a page. */
 
 /* A card never opens with just its tab and a line or two at a page foot: its
    first two blocks (the flavor line and a possibly one-line ability) stay with
    the first two lines of what follows, or the card moves to the next page. */
-.dc-skill-card:not(.dc-avoid-split) .dc-card-inner > :nth-child(-n+2) {
+.dc-skill-card .dc-card-inner > :nth-child(-n+2) {
   break-after: avoid;
 }
 
@@ -316,14 +318,14 @@
    `strong:only-child` also takes a paragraph whose only markup is one bold
    run. A last child is left out: its break-after would pass up to the card
    and glue the next path banner to it. */
-.dc-skill-card:not(.dc-avoid-split) .dc-card-inner > :is(.dc-ability, p:has(> strong:only-child)):not(:last-child),
-.dc-skill-card:not(.dc-avoid-split) .dc-card-inner > p:has(+ :is(ul, ol, table)) {
+.dc-skill-card .dc-card-inner > :is(.dc-ability, p:has(> strong:only-child)):not(:last-child),
+.dc-skill-card .dc-card-inner > p:has(+ :is(ul, ol, table)) {
   break-after: avoid;
 }
 
 /* The closing line of a card (a one-line sign-off, a trailing note) stays
    with the block above it, so a continuation never opens with it alone. */
-.dc-skill-card:not(.dc-avoid-split) .dc-card-inner > :last-child:not(:first-child) {
+.dc-skill-card .dc-card-inner > :last-child:not(:first-child) {
   break-before: avoid;
 }
 

package/styles/components/data.css

@@ -775,11 +775,6 @@ table.dc-stat-strip {
   break-before: avoid;
 }
 
-.dc-skill-card:only-child {
-  width: 100%;
-  max-width: 7.25in;
-}
-
 /* .dc-img-wrapper: the plugin replaces p:has(img) with an explicit class */
 p.dc-img-wrapper {
   padding: 0;

package/styles/components/entries.css

@@ -25,6 +25,7 @@
      --dc-entry-rail     — width of the left rail (a catalog sets 0)
      --dc-entry-rule     — width of the top rule (a catalog sets it)
      --dc-entry-kind     — a quoted word printed small above the name, or `none`
+     --dc-entry-art-width — width of the item's picture, floated right (50%)
 
    The labelled fields inside an entry (`@field`, `**SPECS:**`) are the last
    section of this file; they work outside an entry as well.
@@ -75,6 +76,17 @@
   margin: 0 0 var(--space-xs);
 }
 
+/* The item's picture: an image written in an entry with no class floats to the
+   right, `--dc-entry-art-width` of the card (half), and the text wraps on its
+   left. An image the author places with a class (core's `.gp-left`, `.gp-large`,
+   …) is left where they put it: this rule only reads an image with none. */
+.dc-entry img:not([class]) {
+  float: right;
+  width: var(--dc-entry-art-width);
+  max-width: 100%;
+  margin: 0 0 1em 1em;
+}
+
 /* A `---` kept at the end of an entry would draw a rule inside the card. */
 .dc-entry > hr:last-child {
   display: none;
@@ -163,6 +175,14 @@
   display: none;
 }
 
+/* A catalog is a run of entries that may run past a page, and kept whole it
+   leaves the foot of the page before it blank, so by default it splits.
+   `.dc-avoid-split`, or `--dc-catalog-break-inside: avoid` from a book's sheet,
+   keeps one whole. */
+.dc-section-panel.dc-catalog {
+  --dc-section-break-inside: var(--dc-catalog-break-inside);
+}
+
 /* ═════════════════════════════════════════════════════════════════════════
    FIELD — `@field <variant>`, and `**Label:** …` inside a card
    ═════════════════════════════════════════════════════════════════════════

package/styles/components/images.css

@@ -34,11 +34,6 @@
   break-inside: avoid;
 }
 
-/* Hides empty .dc-sidebar wrappers. */
-.dc-sidebar:empty {
-  display: none;
-}
-
 .dc-human-callout {
   background: var(--paper-cream);
   border: 2px solid var(--ink);

package/styles/components/section.css

@@ -12,9 +12,14 @@
      npc, walkthrough, flaws, ideals, dreams  = a panel plus the component class
      fiction, cards              = the component class alone
 
-   Sections split across pages by default. `.dc-avoid-split` keeps one whole.
+   Sections split across pages by default. `.dc-avoid-split` keeps one whole,
+   by setting `--dc-section-break-inside` (below).
 
    Public tokens (defaults declared in dc-component-defaults.css :root):
+     --dc-section-break-inside — `avoid` keeps a section whole, `auto` lets it
+                            split. An `@npc-stat` with at most one `####` and a catalog
+                            have their own (`--dc-npc-stat-break-inside`,
+                            `--dc-catalog-break-inside`).
      --dc-section-bg      — panel / flat background surface
      --dc-section-accent  — rail and title-bar colour; the one accent knob
      --dc-section-surface / --dc-section-shadow — `content` of the panel's
@@ -37,7 +42,11 @@
                             box-shadow, never as layout), and margin-bottom
                             grows by it. `.dc-avoid-split`
                             and every box that paints its own surface keep it
-                            at 0px.
+                            at 0px. A book that keeps one section whole from
+                            its own sheet sets both
+                            (`--dc-section-break-inside: avoid;
+                            --dc-section-edge: 0px`): the first keeps the box
+                            whole, the second keeps its padding inside it.
    A variant or template owns its chrome by setting these on its own rule. */
 
 /* Float containment. flow-root makes the box a block formatting context so
@@ -79,11 +88,29 @@
   --dc-section-edge: var(--dc-section-pad-bottom);
 }
 
-/* Keep one section whole: it moves to the next page entirely if it does not
-   fit. The dead zone at the foot of the previous page is the price. */
-.section.dc-avoid-split {
-  break-inside: avoid;
+/* Keep a section whole, or let it split: the token is the one setting.
+   `:where()` keeps this at zero specificity, so a rule on one kind of section
+   (a creature, below) outranks it. The bare `.section.dc-avoid-split` is the
+   one section with no variant class that still honours the modifier. */
+:where(.dc-section-panel, .dc-section-flat, .dc-fiction-excerpt, .dc-card-grid, .section.dc-avoid-split) {
+  break-inside: var(--dc-section-break-inside);
+}
+
+/* `.dc-avoid-split` keeps one box whole: it moves to the next page entirely if
+   it does not fit, and the dead zone at the foot of the previous page is the
+   price. It is a setter of the keep-whole tokens on what it is written on (a
+   section, a skill card, a faction, an `@npc-stat`), nothing more, so a book
+   can write the same declarations for one box from its own sheet. A section
+   that is whole keeps its padding inside the box (`--dc-section-edge`). A
+   catalog splits by default, but the class keeps one whole all the same: an
+   author's override wins over a default. */
+.dc-avoid-split {
+  --dc-section-break-inside: avoid;
   --dc-section-edge: 0px;
+  --dc-catalog-break-inside: avoid;
+  --dc-npc-stat-break-inside: avoid;
+  --dc-skill-card-break-inside: avoid;
+  --dc-faction-break-inside: avoid;
 }
 
 /* clip-path + left accent band on ::before.
@@ -561,7 +588,7 @@ h3 + .dc-section-panel {
    first, floated to the right so the name and the text run beside it.
    Splits across pages by default (see below).
    Token contract: --dc-faction-accent (rail and badge fill),
-   --dc-faction-badge-fg (badge text). */
+   --dc-faction-badge-fg (badge text), --dc-faction-break-inside. */
 .dc-card.dc-faction {
   border-left-width: 5px;
   border-left-color: var(--dc-faction-accent);
@@ -570,10 +597,7 @@ h3 + .dc-section-panel {
      left half-empty pages through a chapter of factions. It splits between
      paragraphs like an entry; the name keeps with its first lines (below), and
      `.dc-avoid-split` on the marker keeps one whole. */
-  break-inside: auto;
-}
-.dc-card.dc-faction.dc-avoid-split {
-  break-inside: avoid;
+  break-inside: var(--dc-faction-break-inside);
 }
 .dc-card.dc-faction > :is(h3, h4):first-of-type {
   font-size: var(--fs-h4);
@@ -663,6 +687,7 @@ h3 + .dc-section-panel {
      --dc-npc-stat-label-color  → h5 subsection-label color (default --hud-blue-dark)
      --dc-npc-stat-primary      → primary stat-line color, e.g. "2 HP — 1 Damage" (default --hud-blue-dark)
      --dc-npc-stat-secondary    → secondary stat-line color (default --ink-smoke)
+     --dc-npc-stat-break-inside → `avoid` (default) keeps a block with no `####`, or one, whole
    Override per chapter / per faction in the book's own sheet selector chains. */
 /* Page breaks. A section splits across pages by default. A block with `####`
    entries is a RUN of creatures: it may break between entries and never inside
@@ -672,8 +697,9 @@ h3 + .dc-section-panel {
    an entry is itself unbreakable so a paragraph cannot split between columns.
    Chromium keeps a chain together when it fits a page and lets it break only
    when it cannot. The title bar (h3) and its intro chain on to the first entry,
-   so the bar is never alone at a page foot. A block with no `h4` is ONE
-   creature (the bar names it); add `.dc-avoid-split` to keep it whole.
+   so the bar is never alone at a page foot. A block with no `h4`, or one, is
+   ONE creature (the bar names it), read at one glance, so it stays whole:
+   `--dc-npc-stat-break-inside: auto` lets one split.
 
    The entries are either direct children of the section (one column) or the
    children of the `@columns` run inside it (`.gp-columns`); the rules below take
@@ -693,6 +719,14 @@ h3 + .dc-section-panel {
   break-inside: avoid;
 }
 
+/* One creature, one glance: a block with no `####`, or with one (a species and
+   its one variant), stays whole, with its padding inside the box as
+   `.dc-avoid-split` leaves it. `h4 ~ h4` is a second entry beside the first. */
+.dc-section-panel.dc-npc-stat:not(:has(h4 ~ h4)) {
+  break-inside: var(--dc-npc-stat-break-inside);
+  --dc-section-edge: 0px;
+}
+
 /* The `@columns` run of an entries block is glued to the bar and intro above it,
    as a direct entry list is (the h3's own `break-after: avoid` plus the chain
    above). Without this, Chromium can end a page with the bar and an EMPTY first

package/styles/dc-component-defaults.css

@@ -45,6 +45,21 @@
   --dc-section-gap:       12pt;
   --dc-section-grow:      0;
 
+  /* Keep whole, per component: `avoid` moves the box to the next page rather
+     than splitting it, `auto` lets it split. `.dc-avoid-split` sets all of
+     these to `avoid` on the box it is written on, and a book sets one the same
+     way from its own sheet (`#core-loop { --dc-section-break-inside: avoid; }`).
+     A custom property inherits, so one set on a container reaches what is
+     inside it. A section splits by default, and so does a catalog (it reads its
+     own token, so a container's `--dc-section-break-inside` does not keep a
+     catalog whole), and an `@npc-stat` with at most
+     one `####` is one creature and stays whole. */
+  --dc-section-break-inside:    auto;
+  --dc-catalog-break-inside:    auto;
+  --dc-npc-stat-break-inside:   avoid;
+  --dc-skill-card-break-inside: auto;
+  --dc-faction-break-inside:    auto;
+
   /* ─── Component Public Token Defaults ────────────────────────────────────
      The override surface for per-chapter and per-project theming. They live
      on :root so the book's own sheet can override them at chapter-id scope
@@ -151,6 +166,10 @@
   --dc-entry-rail:           3px;                   /* a catalog sets 0 */
   --dc-entry-rule:           0px;                   /* a catalog sets it */
   --dc-entry-kind:           none;                  /* a quoted word over the name */
+  --dc-entry-art-width:      50%;                   /* the item's picture, floated right; a classed image is the author's */
+
+  /* credits page: the plate under the colophon (an image with no class) */
+  --dc-credits-art-height:   2.75in;
 
   /* .dc-field public API (@field, and the **Label:** shortcut); each variant sets these on its own class */
   --dc-field-accent:         var(--ink-dark);       /* rail and label chip */

package/styles/dc-native.css

@@ -229,11 +229,13 @@ figure {
    initial value and what a column run gets; core has no sequential-fill
    opt-in. */
 
-/* ── 6. WALL ART placement is the markdown's, via core's gp-* classes ──────
-   Do not add a position/float/margin declaration to a book class that the
-   markdown also pins. A book's class beats `.gp-pin` at equal specificity —
-   the book's sheets load after GUTTERPRESS_CSS — so such a rule silently
-   DE-PINS whatever the author asked for. */
+/* ── 6. WALL ART placement is the author's: core's gp-* classes, or the defaults ──
+   An image the author gives a class (core's `.gp-*`) is placed by that class,
+   and the plugin's defaults for art (an entry's picture, the credits plate)
+   read only an image with no class. A book's own sheet is unlayered, so a
+   position/float/margin declaration on a book class that the markdown also
+   pins beats `.gp-pin` at any specificity and silently DE-PINS whatever the
+   author asked for. */
 
 /* ── 7. NO EMPTY FIRST FRAGMENTS on boxed callouts ─────────────────────────
    Core's `break-after: avoid` on headings keeps a heading with the box that

package/styles/page-templates.css

@@ -115,12 +115,12 @@
    visual contract for the two-page TOC + Credits frontmatter, written as:
 
      @page contents
-     # Contents {.dc-chevron}
+     # Contents
      @lede ... @end-lede
      @toc ... @end-toc
 
      @page credits
-     # Credits {.dc-chevron}
+     # Credits
      @lede ... @end-lede
      @section flat
      @columns 2
@@ -331,6 +331,19 @@
   line-height: 1.6;
 }
 
+/* The publisher's plate: a picture on its own line under the colophon, with no
+   class, is a band across the foot of the sheet. It is the page's full width
+   (the masthead's side pull, above), `--dc-credits-art-height` tall, and
+   cropped to fit. An image the author places with a class is left alone. */
+.page.dc-page-credits > p > img:not([class]) {
+  display: block;
+  width: calc(100% + 1.25in);
+  max-width: none;
+  height: var(--dc-credits-art-height);
+  margin: 0 -0.625in;
+  object-fit: cover;
+}
+
 /* Chapter-start page: the h1 drops core's rule and gets headroom below the
    page top. The title is never fragmented across sheets and stays with the
    first block after it (a title wraps to several lines in the display face,
@@ -392,14 +405,21 @@
   margin-top: 0;
 }
 
-/* ── SNUG — `@section .dc-snug` / `@page .dc-snug` ──────────────────────────
-   Halves the space between paragraphs and list items so a section or page
-   that overflows by a line or two fits. Type size and leading are
-   untouched. Lives in dc.templates so it outranks the dc.components and
-   dc.base paragraph/list margins; only the contents-page rows and the
-   credits colophon, which fix their own spacing here, outrank it. */
-:is(.section, .page).dc-snug :is(p, li) {
-  margin-bottom: 0.04in;
+/* ── FLOW GAP — `--dc-flow-gap`, and `.dc-snug`, which sets it ───────────────
+   The space under a paragraph or list item. Unset, each keeps the spacing its
+   own component gives it; set (on a box, or on anything above it, from a
+   sheet or by `.dc-snug`), it is the space under every one of them in that
+   box. `.dc-snug` halves it, so a section or page
+   that overflows by a line or two fits; type size and leading are untouched.
+   Lives in dc.templates so it outranks the dc.components and dc.base
+   paragraph/list margins, and `revert-layer` hands the margin back to them
+   while the token is unset. The contents-page rows and the credits colophon,
+   which fix their own spacing here, outrank it. */
+:is(p, li) {
+  margin-bottom: var(--dc-flow-gap, revert-layer);
+}
+.dc-snug {
+  --dc-flow-gap: 0.04in;
 }
 
 /* ── PAGE TEMPLATE: INTRO (chapter intro / narrative entry) ─────────────────