gp-dimm-city 1.1.4 → 1.2.0-alpha.1

package/CHANGELOG.md

@@ -7,6 +7,83 @@ cut a version that has no `## [X.Y.Z]` heading below.
 
 ## [Unreleased]
 
+## [1.2.0] - prerelease
+
+Requires Gutterpress 0.11.16-alpha.2 or newer (the desktop app or CLI at
+that version): older versions reject the `section: true` markers below.
+Books pinned to an earlier gp-dimm-city are unaffected until re-pinned.
+
+### Changed
+
+- **Eleven plain wrappers are now declared in a `markers` table** instead of
+  being hand-written in the plugin's state machine: `@sidebar`,
+  `@sidebar-box`, `@definition`, `@specialty-intro`, `@specialty-art`,
+  `@specialty-card`, `@gear`, `@toc`, `@lede`, `@glossary` and `@block`.
+  Gutterpress core now parses, nests and closes them, and the editor lists
+  them. The emitted elements and classes are unchanged; rendering the design
+  guide and both books through the old and new plugin gives the same HTML
+  apart from the attributes listed below. The state machine loses about 300
+  lines.
+- New on these wrappers: `data-source-range`, `data-label="…"` on a labelled
+  `@block`, and `data-sidebar="inset"` when written `@sidebar inset`.
+- `@sidebar inset` works beside `@sidebar .inset`. `@block panel|slate|shard|codex`
+  works beside `@block .dc-panel` (the `.dc-*` class form is unchanged).
+- `@lede`, `@toc` and `@glossary` now accept extra classes and an `#id`,
+  as the other wrappers always did.
+- `@specialty-card`'s `data-position="odd|even"` now comes from a small core
+  rule that numbers the cards in document order, as before.
+- Snippets for `@sidebar-box`, `@glossary`, `@toc` and `@specialty-intro`.
+  The `@block` snippet uses the variant word.
+- **Nine section-styled components are declared as real core sections**
+  (Gutterpress 0.11.16-alpha.2, `section: true`): `@column-panel`, `@tabbed`,
+  `@card-grid`, `@citizen-walkthrough`, `@fiction-excerpt`, `@npc-stat`,
+  `@flaws`, `@ideals` and `@dreams`, each with an `@end-…` closer and a
+  snippet. `@npc-stat` is exactly `@section .dc-npc-stat`: same element, same
+  classes, so every book that writes `@section .dc-…` renders as before.
+  Modifier classes stay author classes (`@column-panel .gp-columns-2`). No
+  variants: none of these is styled per specialty. The design guide uses the
+  new markers; `components.yaml` lists them as plugin-origin, and its
+  `card-variants` entry now describes `.section.dc-flaws` (the class the CSS
+  actually selects).
+- devDependency `gutterpress` is `0.11.16-alpha.2`.
+- `docs/plans/specialty-section-variants.md`: the plan for styling section
+  components per specialty (`@npc-stat wirephreak`), for a later release.
+
+### Removed
+
+- `@block variant=panel`. No book or guide page used it; write `@block panel`.
+
+### Behaviour notes
+
+- Declared wrappers nest as a stack and close at the next `@page`,
+  `@section` or `@chapter`, or at the end of the file. A hand-written marker
+  (`@learning-path`, `@callout`, …) no longer closes a wrapper that is still
+  open. No book relied on that.
+- A wrapper's `key=value` attribute is always `data-key` now: `lang=en` is
+  `data-lang`, where the old code emitted `lang` (likewise `dir`, `role`,
+  `tabindex` and `aria-*`).
+- `@end-<wrapper>` with no open wrapper now warns
+  (`declared_marker_close_without_open`) instead of being ignored.
+
+## [1.1.5] - 2026-10-09
+
+### Changed
+
+- **The chapter-opener chevron rules move from `chrome.css` into the
+  chapter-opener template in `page-templates.css`.** No component sheet
+  selects `.chapter`/`.page` any more, and the integrity test enforces
+  that with no exceptions. Pixel-identical in both books.
+- `docs/cleanup-backlog.md` gains a "Still considering" section:
+  - the Field Guide's sidebar areas, with the inset-rail rules;
+  - the specialty-card redesign;
+  - the configurable chapter prefix;
+  - the offset tokens.
+- `docs/css-roadmap.md` records the warnings that are known and accepted:
+  - the design guide's 8 heading jumps inside component examples, which
+    need an `h4`;
+  - the `clip-path` and `page-containment` lint false positives, reported
+    as dimm-city/gutterpress#339.
+
 ## [1.1.4] - 2026-10-09
 
 ### Changed

package/components.yaml

@@ -18,7 +18,7 @@
 #   styles/) · breaks (documentation; omitted where the component has no
 #   fragmentation rule of its own — variants inherit their parent's) · usage
 #   (literal strings that mark a use of a component with no marker or class:
-#   `ROLL THE DIE!`, `| highlight`, `variant=panel`, …) · unstyled (emitted
+#   `ROLL THE DIE!`, `| highlight`, …) · unstyled (emitted
 #   classes acknowledged to have no CSS) · notes.
 #
 #   Status meanings (measured against the Dimm City books that consume this
@@ -115,7 +115,7 @@ components:
   - name: sidebar
     status: live
     origin: plugin
-    recipe: "@sidebar [.inset] … @end-sidebar  (also authored as raw <div class=\"dc-sidebar\"> around an NPC human-callout)"
+    recipe: "@sidebar [inset | .inset] … @end-sidebar  (also authored as raw <div class=\"dc-sidebar\"> around an NPC human-callout)"
     emits: div.dc-sidebar
     css: [styles/components/images.css, styles/page-templates.css]
     tokens:
@@ -160,26 +160,25 @@ components:
   - name: block
     status: live
     origin: plugin
-    recipe: "@block .dc-panel|.dc-slate|.dc-shard|.dc-codex label=\"Title\" … @end-block"
+    recipe: "@block panel|slate|shard|codex label=\"Title\" … @end-block  (`.dc-panel` class form works too)"
     emits: div.dc-block > div.dc-block-title
     css: styles/components/section.css
     tokens: [--dc-block-bg, --dc-block-fg, --dc-block-accent, --dc-block-title-bg, --dc-block-title-fg]
     breaks: "break-inside: avoid"
-    notes: "The variant class is author-supplied (see block-variants; also accepted as variant=panel). Design guide only."
+    notes: "A declared marker: the variant word (or the .dc-* class) selects the treatment (see block-variants). The old variant=panel attribute form was dropped; no book used it. Design guide only."
 
   - name: block-variants
     status: live
     origin: author
-    recipe: "@block .dc-panel | .dc-slate | .dc-shard | .dc-codex"
+    recipe: "@block panel | slate | shard | codex"
     emits: div.dc-block.dc-panel|.dc-slate|.dc-shard|.dc-codex
     css: styles/components/section.css
-    usage: [variant=panel, variant=slate, variant=shard, variant=codex]
-    notes: "Four clip-path/surface treatments on .dc-block; the class is passed through from the marker, or built by the plugin from variant=x (a concatenation the check's plugin scan cannot see — hence origin: author and the usage literals)."
+    notes: "Four clip-path/surface treatments on .dc-block. The variant word maps to the class in the plugin's `markers` table; `@block .dc-panel` passes the class straight through."
 
   - name: card
     status: live
     origin: plugin
-    recipe: "@card [.dc-flaws|.dc-ideals|.dc-dreams] / #### Heading / > pull quote / body / > footer … @end-card"
+    recipe: "@card / #### Heading / > pull quote / body / > footer … @end-card"
     emits:
       - div.dc-card > div.dc-card-heading + div.dc-card-pull + div.dc-card-body
       - div.dc-card-body > blockquote.dc-card-footer (the last body blockquote, dc#44)
@@ -188,11 +187,11 @@ components:
 
   - name: card-variants
     status: live
-    origin: author
-    recipe: "@card .dc-flaws | .dc-ideals | .dc-dreams"
-    emits: div.dc-card.dc-flaws|.dc-ideals|.dc-dreams
+    origin: plugin
+    recipe: "@flaws | @ideals | @dreams … @end-flaws | @end-ideals | @end-dreams  (or @section .dc-flaws | .dc-ideals | .dc-dreams)"
+    emits: div.section.dc-flaws|.dc-ideals|.dc-dreams
     css: styles/components/section.css
-    notes: "Citizen-file card accents; the class is passed through from the marker."
+    notes: "Citizen-file card accents: a section of @card blocks whose class colors every card's left rule (`.section.dc-flaws > .dc-card`)."
 
   - name: gear
     status: live
@@ -427,16 +426,16 @@ components:
   # ── Author classes on core markers, attrs and raw HTML ────────────────
   - name: column-panel
     status: live
-    origin: author
-    recipe: "@section .gp-columns-2 .dc-column-panel"
+    origin: plugin
+    recipe: "@column-panel [.gp-columns-2] … @end-column-panel  (or @section .gp-columns-2 .dc-column-panel)"
     emits: div.section.dc-column-panel
     css: styles/components/section.css
     breaks: "first heading glued to its first paragraph"
 
   - name: tabbed
     status: live
-    origin: author
-    recipe: "@section .dc-tabbed"
+    origin: plugin
+    recipe: "@tabbed … @end-tabbed  (or @section .dc-tabbed)"
     emits: div.section.dc-tabbed
     css: styles/components/section.css
     tokens: [--dc-section-tab-indent, --dc-section-tab-overlap]
@@ -444,16 +443,16 @@ components:
 
   - name: card-grid
     status: live
-    origin: author
-    recipe: "@section .dc-card-grid"
+    origin: plugin
+    recipe: "@card-grid … @end-card-grid  (or @section .dc-card-grid)"
     emits: div.section.dc-card-grid
     css: [styles/components/section.css, styles/page-templates.css]
     breaks: "break-inside: auto on the grid; each specialty card avoid"
 
   - name: citizen-walkthrough
     status: live
-    origin: author
-    recipe: "@section .dc-citizen-walkthrough [.gp-columns-2]"
+    origin: plugin
+    recipe: "@citizen-walkthrough [.gp-columns-2] … @end-citizen-walkthrough  (or @section .dc-citizen-walkthrough)"
     emits: div.section.dc-citizen-walkthrough
     css: [styles/components/section.css, styles/dc-native.css]
     notes: "Themed through the section chassis tokens --dc-section-accent / --dc-section-bg (see section), which the design guide documents."
@@ -468,8 +467,8 @@ components:
 
   - name: fiction-excerpt
     status: live
-    origin: author
-    recipe: "@section .dc-fiction-excerpt"
+    origin: plugin
+    recipe: "@fiction-excerpt … @end-fiction-excerpt  (or @section .dc-fiction-excerpt)"
     emits: div.section.dc-fiction-excerpt
     css: [styles/components/section.css]
     tokens:
@@ -483,8 +482,8 @@ components:
 
   - name: npc-stat
     status: live
-    origin: author
-    recipe: "@section .dc-npc-stat"
+    origin: plugin
+    recipe: "@npc-stat … @end-npc-stat  (or @section .dc-npc-stat)"
     emits: div.section.dc-npc-stat
     css: [styles/components/section.css]
     tokens:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gp-dimm-city",
-  "version": "1.1.4",
+  "version": "1.2.0-alpha.1",
   "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",
@@ -65,10 +65,11 @@
     "lint": "gutterpress lint design-guide",
     "test": "bun test",
     "test:update-snapshot": "bun test --update-snapshots",
+    "book-diff": "bun scripts/book-diff.mjs",
     "pack:check": "npm pack --dry-run"
   },
   "devDependencies": {
-    "gutterpress": "0.11.15",
+    "gutterpress": "0.11.16-alpha.2",
     "markdown-it": "^14.1.0"
   },
   "peerDependencies": {

package/plugin.js

@@ -4,26 +4,34 @@
  * IMPORTANT: This plugin only transforms content marked with special markers.
  * Regular markdown content passes through unchanged.
  *
- * MARKERS (support optional key="value" attributes):
- *   @sidebar            → Start a dc-sidebar wrapper
- *   @end-sidebar        → End sidebar wrapper
- *   @sidebar-box        → Start a dc-sidebar-box wrapper
- *   @end-sidebar-box    → End sidebar-box wrapper
+ * DECLARED MARKERS (the `markers` export at the bottom of this file — core
+ * Gutterpress parses, nests, closes and source-maps these; this file only
+ * names the element, classes and variants). Each also has an `@end-<name>`:
+ *   @sidebar [inset]     → div.dc-sidebar (`.inset` shorthand works too)
+ *   @sidebar-box         → div.dc-prose-panel.dc-sidebar-box
+ *   @definition          → div.dc-prose-panel.dc-definition-block
+ *   @specialty-intro     → div.dc-specialty-intro
+ *   @specialty-art       → div.dc-specialty-art (full-bleed art panel)
+ *   @specialty-card      → div.dc-specialty-card[data-position=odd|even]
+ *   @gear                → div.dc-card.dc-gear
+ *   @toc                 → div.dc-toc
+ *   @lede                → div.dc-intro
+ *   @glossary            → div.dc-terms
+ *   @block [panel|slate|shard|codex] label="Title"
+ *                        → div.dc-block.dc-<variant> + div.dc-block-title
+ *                          (`@block .dc-panel` class form works too)
+ *
+ * HAND-WRITTEN MARKERS (support optional key="value" attributes; handled by
+ * the dimm_city_transform state machine below):
  *   @specialty          → Start a specialty wrapper (auto-closes any prior specialty,
  *                          learning-path, or skill)
  *   @end-specialty      → Manually end a specialty wrapper
- *   @definition         → Start a dc-definition-block wrapper
- *   @end-definition     → End definition wrapper
  *   @procedure          → Start a dc-steps procedure wrapper
  *   @end-procedure      → End procedure wrapper (auto-closes on EOF with a warning)
  *   @callout            → Start a dc-alert callout (variant=note|warning|dm|vibe|origin|visit|gear)
  *   @end-callout        → End callout wrapper
  *   @dm-note            → Start a Dream Master note (sugar for @callout variant=dm)
  *   @end-dm-note        → End dm-note wrapper
- *   @block              → Section enclosure card (.dc-panel|.dc-slate|.dc-shard|.dc-codex label="Title")
- *   @end-block          → End block enclosure
- *   @lede               → Start a dc-intro lede wrapper
- *   @end-lede           → End lede wrapper
  *   @learning-path      → Start a learning path section (auto-closes previous sections)
  *   @end-learning-path  → Manually end a learning path section
  *   @skill              → Start a skill card (auto-closes previous skill)
@@ -31,19 +39,7 @@
  *   @continue           → Continuation marker — emits a card with a "{name} ▸"
  *                          tab so an oversized skill card can be split across pages
  *                          while keeping a visible link to its origin card
- *   @specialty-intro    → Cosmetic specialty intro wrapper
- *   @end-specialty-intro
- *   @specialty-card     → Individual specialty card
- *   @end-specialty-card
- *   @specialty-art      → Full-bleed specialty art panel (.dc-specialty-art)
- *   @end-specialty-art
- *   @gear               → Gear card (shorthand for @card .dc-gear)
- *   @end-gear
  *   (chapter-opener composite is now markup-driven — see CSS notes below)
- *   @toc                → Table-of-contents wrapper
- *   @end-toc
- *   @glossary           → Glossary wrapper
- *   @end-glossary
  *   @outcome            → 5-rung d20 outcome ladder block
  *   @end-outcome
  *   @tape               → Inline tape divider (`<div class="dc-tape">— § —</div>`)
@@ -866,6 +862,23 @@ function dcAlertsTransform(state) {
   state.tokens = newTokens;
 }
 
+/**
+ * `data-position="odd|even"` on every @specialty-card, counted across the
+ * document in order so the card grid alternates its tilt/offset. The wrapper
+ * itself is a declared marker (see `markers` below); this rule only numbers
+ * the open tokens core produced. It never runs under bare markdown-it, which
+ * has no declared markers.
+ */
+function dcSpecialtyCardPositions(state) {
+  let count = 0;
+  for (const tok of state.tokens) {
+    if (tok.type !== 'layout_component_open') continue;
+    if (!(tok.attrGet('class') || '').split(/\s+/).includes('dc-specialty-card')) continue;
+    count++;
+    tok.attrSet('data-position', count % 2 === 0 ? 'even' : 'odd');
+  }
+}
+
 /**
  * Main plugin function - the default export Gutterpress loads
  */
@@ -885,6 +898,8 @@ export default function dimmCityPlugin(md, options = {}) {
     '<span class="dc-roll-the-die">' + esc(tokens[idx].content) + '</span>';
   md.core.ruler.push('dc_roll_the_die', dcRollDieTransform);
 
+  md.core.ruler.push('dc_specialty_card_positions', dcSpecialtyCardPositions);
+
   // NOTE: Chapter-opener composite behaviour is intentionally NOT handled
   // by the plugin. The author markdown
   //
@@ -918,21 +933,10 @@ export default function dimmCityPlugin(md, options = {}) {
       let inOutcomeBlock = false;
       let outcomeBlockItems = [];
       let outcomeBlockFlush = false;
-      let inLede = false;
-      let inSidebar = false;
-      let inSidebarBox = false;
-      let inDefinition = false;
       let inProcedure = false;
       let inCallout = false;
       let inDmNote = false;
-      let inBlock = false;
       let inCard = false;
-      let inGear = false;
-      let inToc = false;
-      let inGlossary = false;
-      let inSpecialtyCard = false;
-      let inSpecialtyIntro = false;
-      let inSpecialtyArt = false;
       let cardHeadingDone = false;
       let cardPullDone = false;
       let cardBodyOpen = false;
@@ -958,7 +962,6 @@ export default function dimmCityPlugin(md, options = {}) {
         between Part 1 and the continuation. */
      let lastCardTitle = '';
      let lastCardTier = '';
-     let specialtyCardCount = 0;  // resets per-specialty; used to emit data-position="even/odd"
 
      // Helper to close all open structures EXCEPT specialty (specialty
      // wraps the entire chapter section and is closed separately).
@@ -974,22 +977,6 @@ export default function dimmCityPlugin(md, options = {}) {
           cardPullDone = false;
           lastCardBodyBlockquote = null;
         }
-        if (inLede) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inLede = false;
-        }
-        if (inSidebar) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inSidebar = false;
-        }
-        if (inSidebarBox) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inSidebarBox = false;
-        }
-        if (inDefinition) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inDefinition = false;
-        }
         if (inSkillCard) {
           newTokens.push(makeToken('html_block', '</div></div></div>\n'));
           inSkillCard = false;
@@ -1010,34 +997,6 @@ export default function dimmCityPlugin(md, options = {}) {
           newTokens.push(makeToken('html_block', '</div>\n'));
           inDmNote = false;
         }
-        if (inBlock) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inBlock = false;
-        }
-        if (inGear) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inGear = false;
-        }
-        if (inSpecialtyCard) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inSpecialtyCard = false;
-        }
-        if (inSpecialtyIntro) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inSpecialtyIntro = false;
-        }
-        if (inSpecialtyArt) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inSpecialtyArt = false;
-        }
-        if (inToc) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inToc = false;
-        }
-        if (inGlossary) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inGlossary = false;
-        }
         inProcedure = false;
         learningPathHasTitle = false;
         inSkillMode = false;
@@ -1056,44 +1015,11 @@ export default function dimmCityPlugin(md, options = {}) {
       }
        currentSpecialtyCode = '';
       currentLearningPathIndex = 0;
-      // specialtyCardCount intentionally NOT reset here — it counts
-      // all cards emitted in the current section so even/odd alternation
-      // works across multiple @specialty blocks in the same card-grid.
     }
 
     for (let i = 0; i < tokens.length; i++) {
       const tok = tokens[i];
 
-      // --- @sidebar / @end-sidebar ---
-      const sidebarMarker = parseMarker(tok, tokens, i, '@sidebar');
-      if (sidebarMarker.matched) {
-        if (inSidebar) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inSidebar = false;
-        }
-        if (inSidebarBox) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inSidebarBox = false;
-        }
-        if (inDefinition) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inDefinition = false;
-        }
-        newTokens.push(makeToken('html_block', '<div' + buildAttrs(sidebarMarker.attrs, 'dc-sidebar') + '>\n'));
-        inSidebar = true;
-        i += 2;
-        continue;
-      }
-
-      if (isMarker(tok, tokens, i, '@end-sidebar')) {
-        if (inSidebar) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inSidebar = false;
-        }
-        i += 2;
-        continue;
-      }
-
       // --- @roll-table / @options-table (DEPRECATED 17.3.0) ---
       // These macros emitted tier-colored classes (dc-roll-table*, dc-options-table*)
       // with ZERO backing CSS and had zero usage in the book. They are now no-ops:
@@ -1231,66 +1157,6 @@ export default function dimmCityPlugin(md, options = {}) {
         continue;
       }
 
-      // Check for @specialty marker (must come before @learning-path/@skill
-      // since it auto-closes everything else)
-      const sidebarBoxMarker = parseMarker(tok, tokens, i, '@sidebar-box');
-      if (sidebarBoxMarker.matched) {
-        if (inSidebarBox) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inSidebarBox = false;
-        }
-        if (inSidebar) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inSidebar = false;
-        }
-        if (inDefinition) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inDefinition = false;
-        }
-        newTokens.push(makeToken('html_block', '<div' + buildAttrs(sidebarBoxMarker.attrs, 'dc-prose-panel dc-sidebar-box') + '>\n'));
-        inSidebarBox = true;
-        i += 2;
-        continue;
-      }
-
-      if (isMarker(tok, tokens, i, '@end-sidebar-box')) {
-        if (inSidebarBox) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inSidebarBox = false;
-        }
-        i += 2;
-        continue;
-      }
-
-      const definitionMarker = parseMarker(tok, tokens, i, '@definition');
-      if (definitionMarker.matched) {
-        if (inDefinition) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inDefinition = false;
-        }
-        if (inSidebar) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inSidebar = false;
-        }
-        if (inSidebarBox) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inSidebarBox = false;
-        }
-        newTokens.push(makeToken('html_block', '<div' + buildAttrs(definitionMarker.attrs, 'dc-prose-panel dc-definition-block') + '>\n'));
-        inDefinition = true;
-        i += 2;
-        continue;
-      }
-
-      if (isMarker(tok, tokens, i, '@end-definition')) {
-        if (inDefinition) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inDefinition = false;
-        }
-        i += 2;
-        continue;
-      }
-
       const procedureMarker = parseMarker(tok, tokens, i, '@procedure');
       if (procedureMarker.matched) {
         // @procedure auto-closes any prior open section so a forgotten
@@ -1371,40 +1237,6 @@ export default function dimmCityPlugin(md, options = {}) {
         continue;
       }
 
-      // --- @block (section enclosures) ---
-      // Reusable card-like text section enclosures. Four variants with distinct
-      // clip-path geometry, surface, and accent colors. Each emits a .dc-block
-      // container with an optional titled header band (.dc-block-title).
-      //
-      // Syntax:   @block .dc-panel|.dc-slate|.dc-shard|.dc-codex label="Title"
-
-      const blockUnifiedMarker = parseMarker(tok, tokens, i, '@block');
-      if (blockUnifiedMarker.matched) {
-        closeAll();
-        const blockLabel = blockUnifiedMarker.attrs['label'] ? esc(blockUnifiedMarker.attrs['label']) : '';
-        const blockTitleHtml = blockLabel ? '<div class="dc-block-title">' + blockLabel + '</div>\n' : '';
-        let blockClass = 'dc-block';
-        if (blockUnifiedMarker.attrs['class']) {
-          blockClass += ' ' + blockUnifiedMarker.attrs['class'];
-        } else if (blockUnifiedMarker.attrs['variant']) {
-          blockClass += ' dc-' + blockUnifiedMarker.attrs['variant'].toLowerCase();
-        }
-        newTokens.push(makeToken('html_block', '<div class="' + blockClass + '">\n' + blockTitleHtml));
-        inBlock = true;
-        i += 2;
-        continue;
-      }
-
-
-      if (isMarker(tok, tokens, i, '@end-block')) {
-        if (inBlock) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inBlock = false;
-        }
-        i += 2;
-        continue;
-      }
-
       // --- @card / @end-card ---
       // Generic card primitive. Emits .dc-card with optional sub-elements:
       //   .dc-card-heading  — first h4 after @card
@@ -1454,112 +1286,6 @@ export default function dimmCityPlugin(md, options = {}) {
         continue;
       }
 
-      // --- @specialty-card / @end-specialty-card ---
-      // Summary card used in the choose-specialty overview grid.
-      // Shape and color inherited from .specialty.<name> parent container.
-      const specialtyCardMarker = parseMarker(tok, tokens, i, '@specialty-card');
-      if (specialtyCardMarker.matched) {
-        closeAll();
-        specialtyCardCount++;
-        const positionAttr = ' data-position="' + (specialtyCardCount % 2 === 0 ? 'even' : 'odd') + '"';
-        newTokens.push(makeToken('html_block', '<div' + buildAttrs(specialtyCardMarker.attrs, 'dc-specialty-card') + positionAttr + '>\n'));
-        inSpecialtyCard = true;
-        i += 2;
-        continue;
-      }
-
-      if (isMarker(tok, tokens, i, '@end-specialty-card')) {
-        if (inSpecialtyCard) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inSpecialtyCard = false;
-        }
-        i += 2;
-        continue;
-      }
-
-      // --- @specialty-intro / @end-specialty-intro ---
-      // Full-page specialty intro panel. Shape/color from .specialty.<name> parent.
-      const specialtyIntroMarker = parseMarker(tok, tokens, i, '@specialty-intro');
-      if (specialtyIntroMarker.matched) {
-        closeAll();
-        newTokens.push(makeToken('html_block', '<div' + buildAttrs(specialtyIntroMarker.attrs, 'dc-specialty-intro') + '>\n'));
-        inSpecialtyIntro = true;
-        i += 2;
-        continue;
-      }
-
-      if (isMarker(tok, tokens, i, '@end-specialty-intro')) {
-        if (inSpecialtyIntro) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inSpecialtyIntro = false;
-        }
-        i += 2;
-        continue;
-      }
-
-      // --- @specialty-art / @end-specialty-art ---
-      // Full-bleed art panel for a specialty profile. Emits .dc-specialty-art
-      // (CSS: components/*.css + page-rules.css `.dc-specialty-art { page: full; }`).
-      const specialtyArtMarker = parseMarker(tok, tokens, i, '@specialty-art');
-      if (specialtyArtMarker.matched) {
-        closeAll();
-        newTokens.push(makeToken('html_block', '<div' + buildAttrs(specialtyArtMarker.attrs, 'dc-specialty-art') + '>\n'));
-        inSpecialtyArt = true;
-        i += 2;
-        continue;
-      }
-
-      if (isMarker(tok, tokens, i, '@end-specialty-art')) {
-        if (inSpecialtyArt) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inSpecialtyArt = false;
-        }
-        i += 2;
-        continue;
-      }
-
-
-      // --- @toc / @end-toc ---
-      const tocMarker = parseMarker(tok, tokens, i, '@toc');
-      if (tocMarker.matched) {
-        closeAll();
-        newTokens.push(makeToken('html_block', '<div class="dc-toc">\n'));
-        inToc = true;
-        i += 2; continue;
-      }
-      if (isMarker(tok, tokens, i, '@end-toc')) {
-        if (inToc) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inToc = false;
-        }
-        i += 2; continue;
-      }
-
-      // Removed 2026-05-17: @two-column / @three-column / @no-break.
-      // Use @section .gp-columns-2 / @section .gp-columns-3 instead — markers.js
-      // emits identical layout semantics, with the added `.section` class that
-      // picks up `break-inside: avoid` from MARKER_CSS.
-
-      // --- @gear / @end-gear ---
-      // Shorthand for @card .dc-gear — emits a bare `.dc-card.dc-gear`.
-      // NOTE: there is NO .section.dc-gear-list wrapper (an earlier comment
-      // claimed one, and components/*.css carried ~40 lines of CSS keyed on
-      // it that could never match). Style `.dc-card.dc-gear` directly.
-      const gearMarker = parseMarker(tok, tokens, i, '@gear');
-      if (gearMarker.matched) {
-        closeAll();
-        newTokens.push(makeToken('html_block', '<div' + buildAttrs(gearMarker.attrs, 'dc-card dc-gear') + '>\n'));
-        inGear = true;
-        i += 2; continue;
-      }
-      if (isMarker(tok, tokens, i, '@end-gear')) {
-        if (inGear) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inGear = false;
-        }
-        i += 2; continue;
-      }
-
       // --- @tape (single-line tape divider) ---
       const tapeMarker = parseMarker(tok, tokens, i, '@tape');
       if (tapeMarker.matched) {
@@ -1569,41 +1295,6 @@ export default function dimmCityPlugin(md, options = {}) {
         i += 2; continue;
       }
 
-      // --- @lede / @end-lede ---
-      // Emits .dc-intro (canonical). The legacy bare `lede` class was removed
-      // 2026-05-17 — there were no CSS rules using it, only the dc-prefixed
-      // form is styled.
-      const ledeMarker = parseMarker(tok, tokens, i, '@lede');
-      if (ledeMarker.matched) {
-        closeAll();
-        newTokens.push(makeToken('html_block', '<div class="dc-intro">\n'));
-        inLede = true;
-        i += 2; continue;
-      }
-      if (isMarker(tok, tokens, i, '@end-lede')) {
-        if (inLede) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inLede = false;
-        }
-        i += 2; continue;
-      }
-
-      // --- @glossary / @end-glossary ---
-      const glossaryMarker = parseMarker(tok, tokens, i, '@glossary');
-      if (glossaryMarker.matched) {
-        closeAll();
-        newTokens.push(makeToken('html_block', '<div class="dc-terms">\n'));
-        inGlossary = true;
-        i += 2; continue;
-      }
-      if (isMarker(tok, tokens, i, '@end-glossary')) {
-        if (inGlossary) {
-          newTokens.push(makeToken('html_block', '</div>\n'));
-          inGlossary = false;
-        }
-        i += 2; continue;
-      }
-
       const specialtyMarker = parseMarker(tok, tokens, i, '@specialty');
       if (specialtyMarker.matched) {
         closeSpecialty();
@@ -2098,6 +1789,64 @@ export default function dimmCityPlugin(md, options = {}) {
 
 }
 
+/**
+ * Declared markers — plain data Gutterpress core reads off this module (the
+ * same relationship `metadata` has). Core parses `@name … @end-name`, merges
+ * author classes, threads `data-source-range`, nests containers as a stack and
+ * closes them at the next `@page`/`@section`/`@chapter`, so none of this is
+ * hand-written in the state machine above. A bare markdown-it instance never
+ * reads this table: declared markers exist only under Gutterpress.
+ *
+ * A `section: true` entry declares a section-styled component: core treats it
+ * as a real `@section` carrying the entry's class (see below).
+ *
+ * To add a plain wrapper, add one line here (element + classes), a snippet in
+ * `snippets/<name>.md`, and the usual catalog/guide entries — see
+ * docs/adding-macros.md.
+ *
+ * Variants are a bare word on the marker line (`@sidebar inset`) and only add
+ * a class, so `.inset`-style class shorthand keeps working beside them.
+ * `autoCloseAt: ['eof']` keeps these silent at end-of-document: they have
+ * never needed an explicit `@end-…`.
+ */
+const wrapper = (cls, extra = {}) => ({ class: cls, autoCloseAt: ['eof'], ...extra });
+
+export const markers = {
+  sidebar: wrapper('dc-sidebar', { variants: { inset: 'inset' } }),
+  'sidebar-box': wrapper('dc-prose-panel dc-sidebar-box'),
+  definition: wrapper('dc-prose-panel dc-definition-block'),
+  'specialty-intro': wrapper('dc-specialty-intro'),
+  'specialty-art': wrapper('dc-specialty-art'),
+  'specialty-card': wrapper('dc-specialty-card'),
+  gear: wrapper('dc-card dc-gear'),
+  toc: wrapper('dc-toc'),
+  lede: wrapper('dc-intro'),
+  glossary: wrapper('dc-terms'),
+  block: wrapper('dc-block', {
+    variants: { panel: 'dc-panel', slate: 'dc-slate', shard: 'dc-shard', codex: 'dc-codex' },
+    label: { tag: 'div', class: 'dc-block-title', from: 'attr:label' },
+  }),
+
+  // Section-styled components. `section: true` makes each one a real core
+  // @section: `@npc-stat` is exactly `@section .dc-npc-stat` (same element, same
+  // classes), so the books' existing `@section .dc-…` spellings keep working
+  // unchanged. Each class has its CSS on `.section.dc-…` in
+  // styles/components/section.css. No variants: none of these is styled per
+  // specialty (that lives on `.dc-specialty.<name>`, from `@specialty`), and
+  // modifiers such as `.dc-plain`, `.dc-snug`, `.dc-allow-split` and
+  // `.gp-columns-2` stay author classes (`@column-panel .gp-columns-2`).
+  'column-panel': { section: true, class: 'dc-column-panel' },
+  tabbed: { section: true, class: 'dc-tabbed' },
+  'card-grid': { section: true, class: 'dc-card-grid' },
+  'citizen-walkthrough': { section: true, class: 'dc-citizen-walkthrough' },
+  'fiction-excerpt': { section: true, class: 'dc-fiction-excerpt' },
+  'npc-stat': { section: true, class: 'dc-npc-stat' },
+  // Citizen-file card runs: the class sets the accent of every `@card` inside.
+  flaws: { section: true, class: 'dc-flaws' },
+  ideals: { section: true, class: 'dc-ideals' },
+  dreams: { section: true, class: 'dc-dreams' },
+};
+
 /**
  * Plugin metadata (the package version in package.json is the only version).
  */

package/snippets/block.md

@@ -1,4 +1,4 @@
-@block .dc-panel label="{{label}}"
+@block panel label="{{label}}"
 
 {{body}}
 

package/snippets/card-grid.md

@@ -0,0 +1,19 @@
+@card-grid
+
+@specialty .{{specialty}}
+
+@specialty-card #card-{{specialty}}
+
+### {{name}}
+
+![{{name}}]({{image}})
+
+> {{tagline}}
+
+{{pitch}}
+
+@end-specialty-card
+
+@end-specialty
+
+@end-card-grid

package/snippets/citizen-walkthrough.md

@@ -0,0 +1,11 @@
+@citizen-walkthrough
+
+#### {{field}}
+
+{{guidance}}
+
+#### {{field2}}
+
+{{guidance2}}
+
+@end-citizen-walkthrough

package/snippets/column-panel.md

@@ -0,0 +1,11 @@
+@column-panel .gp-columns-2
+
+## {{heading}}
+
+{{body}}
+
+@column-break
+
+{{more}}
+
+@end-column-panel

package/snippets/dreams.md

@@ -0,0 +1,15 @@
+@dreams
+
+@card
+
+#### {{name}}
+
+> {{pull-quote}}
+
+{{body}}
+
+> {{footer}}
+
+@end-card
+
+@end-dreams

package/snippets/fiction-excerpt.md

@@ -0,0 +1,9 @@
+@fiction-excerpt
+
+"{{opening line}}"
+
+![{{art}}]({{image}})
+
+{{prose}}
+
+@end-fiction-excerpt

package/snippets/flaws.md

@@ -0,0 +1,15 @@
+@flaws
+
+@card
+
+#### {{name}}
+
+> {{pull-quote}}
+
+{{body}}
+
+> {{footer}}
+
+@end-card
+
+@end-flaws

package/snippets/glossary.md

@@ -0,0 +1,7 @@
+@glossary
+
+**{{term}}** — {{meaning}}
+
+**{{term2}}** — {{meaning2}}
+
+@end-glossary

package/snippets/ideals.md

@@ -0,0 +1,15 @@
+@ideals
+
+@card
+
+#### {{name}}
+
+> {{pull-quote}}
+
+{{body}}
+
+> {{footer}}
+
+@end-card
+
+@end-ideals

package/snippets/npc-stat.md

@@ -0,0 +1,18 @@
+@npc-stat
+
+#### {{name}}
+
+> {{flavor}}
+
+{{hp}} HP — {{damage}} Damage
+{{role}} — {{size}}
+
+##### Traits
+
+**{{trait}}:** {{effect}}
+
+##### Equipment
+
+{{equipment}}
+
+@end-npc-stat

package/snippets/sidebar-box.md

@@ -0,0 +1,9 @@
+@sidebar-box
+
+#### {{heading}}
+
+---
+
+{{body}}
+
+@end-sidebar-box

package/snippets/specialty-intro.md

@@ -0,0 +1,7 @@
+@specialty-intro
+
+## {{name}}
+
+{{intro}}
+
+@end-specialty-intro

package/snippets/tabbed.md

@@ -0,0 +1,7 @@
+@tabbed
+
+## {{tab-heading}}
+
+{{body}}
+
+@end-tabbed

package/snippets/toc.md

@@ -0,0 +1,5 @@
+@toc
+
+1. [{{chapter}}](#{{id}}) — {{blurb}}
+
+@end-toc

package/styles/components/chrome.css

@@ -26,13 +26,10 @@
    miscommunicates the semantic (CONTENTS shouldn't read as a warning).
    Rubric: D9 (brand identity per chapter — chroma anchor must match
    the banner's semantic role). */
-/* Chevron banner. Applies to elements explicitly marked `.dc-chevron`
-   AND to the h1 that's the first child of a chapter-opener intro section
-   — so authors don't have to write `{.dc-chevron}` on every chapter h1.
-   The structural-selector branch is the same selector used by the
-   chapter-opener composite rules above. */
-.dc-chevron,
-.chapter[data-chapter-label] > .page[data-page="intro"] > .section > h1:first-of-type {
+/* Chevron banner on elements marked `.dc-chevron`. The chapter opener's first
+   h1 gets the same treatment without the class; that rule lives with the
+   opener template in page-templates.css. */
+.dc-chevron {
   font-family: var(--font-display);
   font-size: var(--dc-chevron-font-size);
   letter-spacing: 0.06em;
@@ -83,14 +80,6 @@ h1.dc-chevron {
   line-height: 1.2;
 }
 
-/* Chapter-opener heading runs at a smaller size than other h1.dc-chevron
-   instances so the section body weight stays the focal anchor below the
-   composite badge + banner. User-approved 2026-05-25. */
-.chapter[data-chapter-label] > .page[data-page="intro"] > .section > h1:first-of-type {
-  font-size: 1.1rem;
-  line-height: 1.2;
-}
-
 /* Front-matter chevron font-size overrides moved to the book's own sheet (unlayered) per A1
    layer-ownership (page-context rules belong in the guide-specific override
    file, not the portable component library). Three-judge gate iteration 3. */
@@ -412,9 +401,8 @@ hr {
   background: repeating-linear-gradient(90deg, color-mix(in srgb, var(--crimson) 85%, var(--dc-tape-bg)) 0 6px, var(--dc-tape-bg) 6px 10px);
 }
 
-/* Chapter-opener badge + H1 banner — see the chapter-opener composite
-   block further down (.page[data-page="intro"][data-chapter-label]).
-   The legacy .dc-chapter-opener-no rules previously here were removed
+/* Chapter-opener badge + H1 banner — see "PAGE TEMPLATE: CHAPTER OPENER"
+   in page-templates.css. The legacy .dc-chapter-opener-no rules previously here were removed
    when the legacy @chapter-opener macro was retired. */
 
 /* ── Specialty art full-page plate ─────────────────────────────────────────── */

package/styles/page-templates.css

@@ -686,9 +686,28 @@
    attribute. Negative margins cancel the section padding so it reaches the
    section's outer edges; its --clip-banner tail then tapers in by --clip-tail. */
 .chapter[data-chapter-label] > .page[data-page="intro"] > .section > h1:first-of-type {
+  /* The .dc-chevron look (components/chrome.css), applied without the class
+     so authors need not write `{.dc-chevron}` on every chapter h1. */
+  font-family: var(--font-display);
+  letter-spacing: 0.06em;
+  color: var(--dc-chevron-color);
+  text-transform: uppercase;
+  background: var(--dc-chevron-bg);
+  padding: 10px 28px 10px 14px;
+  display: block;
+  box-sizing: border-box;
+  clip-path: var(--clip-banner);
+  word-break: break-word;
+
+  /* Smaller than other h1.dc-chevron so the section body stays the focal
+     anchor below the banner. User-approved 2026-05-25. */
+  font-size: 1.1rem;
+  line-height: 1.2;
+
   margin-top:   calc(var(--dc-chapter-opener-pad-top)   * -1);
   margin-left:  calc(var(--dc-chapter-opener-pad-side)  * -1);
   margin-right: calc(var(--dc-chapter-opener-pad-right) * -1);
+  margin-bottom: 0;
   --dc-chevron-bg: var(--dc-chapter-opener-accent);
 }