gp-dimm-city 1.2.0-alpha.2 → 1.2.0

package/CHANGELOG.md

@@ -7,10 +7,11 @@ cut a version that has no `## [X.Y.Z]` heading below.
 
 ## [Unreleased]
 
-## [1.2.0] - prerelease
+## [1.2.0] - 2026-10-10
 
-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.
+Requires Gutterpress 0.11.16 or newer (the desktop app or CLI): older
+versions reject the `section: true` markers below and do not report a
+mistyped `@callout` variant (`unknown_variant`).
 Books pinned to an earlier gp-dimm-city are unaffected until re-pinned.
 
 ### Changed
@@ -33,9 +34,10 @@ Books pinned to an earlier gp-dimm-city are unaffected until re-pinned.
 - `@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.
+  The `@block` snippet uses the variant word, and the chapter-start snippet
+  opens its excerpt with `@fiction-excerpt`.
 - **Nine section-styled components are declared as real core sections**
-  (Gutterpress 0.11.16-alpha.2, `section: true`): `@column-panel`, `@tabbed`,
+  (Gutterpress 0.11.16, `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
@@ -94,12 +96,49 @@ Books pinned to an earlier gp-dimm-city are unaffected until re-pinned.
   cause is an `@end-learning-path` above the skills it was meant to close.
 - Snippets: `specialty` shows the whole specialty > learning path > skill
   hierarchy, and `learning-path` shows its skills.
-- devDependency `gutterpress` is `0.11.16-alpha.2`.
+- **`@callout` and `@dm-note` are declared, and the state machine is gone.**
+  `@callout` is a declared wrapper (`div.dc-alert` + the variant's class,
+  author classes and `label="…"` as before) and `@dm-note` is its alias with
+  the `dm` variant preset, so `@dm-note` is `@callout dm` and `@end-dm-note`
+  still closes it. One small core rule (`dcCallouts`) adds the variant's
+  default label ("Note", "Warning", "Dream Master Note", "Vibe", "Origin",
+  "Visit", "Gear") when there is no `label="…"`; an explicit label wins. A
+  missing or unrecognised variant is a plain note, as before. With `@tape`
+  and the retired `@roll-table` / `@options-table` stripper gone too,
+  `dimm_city_transform` and its `closeAll()` are deleted. What is left are
+  four small core rules: the `@continue` bridge into skill cards, `> [!TYPE]`
+  alerts, `ROLL THE DIE!`, and the image-only paragraph class (now
+  `dcImageParagraphs`). `plugin.js` goes from 1,557 to 1,381 lines.
+  The emitted callout is the same element, classes and label span as before.
+  Core adds `data-callout="<variant>"` (and `data-label` when labelled) and
+  `data-source-range`, and writes no newline between the wrapper and its label.
+- `docs/adding-macros.md` and `docs/macros.md` now describe a plugin with no
+  hand-written markers: the "hand-written marker" recipe is gone.
+- devDependency `gutterpress` is `0.11.16`.
 - `docs/plans/specialty-section-variants.md`: the plan for styling section
   components per specialty (`@npc-stat wirephreak`), for a later release.
 
 ### Removed
 
+- **`@callout variant=…` is gone**, with no compatibility mapping: the variant
+  is a bare word (`@callout note`, `@callout vibe`, `@callout .float-right
+  origin label="…"`). Core reads `variant=origin` as a plain attribute, so the
+  callout would render as a note; instead every `@callout` or `@dm-note`
+  written that way gets one Problems message on its line: `@callout: no longer
+  takes variant=origin; write "@callout origin" instead.` Edit the books:
+  `variant=note` to `note`, `variant="vibe"` to `vibe`, `variant=origin` or
+  `variant="origin"` to `origin`.
+- **`@tape` is removed.** The marker was one line with no body and no
+  `@end-tape`, which a declared marker cannot express yet: a `selfClosing`
+  marker feature was requested upstream as gutterpress#344, and `@tape` can
+  return as a declared marker once it exists. Until then write the raw
+  `<div class="dc-tape">Label</div>` (`dc-flush` to run edge to edge), which
+  renders the same HTML; the `.dc-tape` CSS stays. The design guide's
+  examples use the raw form. A leftover `@tape label="…"` line now prints as
+  the text it is.
+- **The `@roll-table` / `@options-table` no-op handling** (deprecated in
+  17.3.0), its `roll-table` entry in `components.yaml` and the design guide's
+  note. Neither is a marker any more, so a stray one prints as text.
 - `@block variant=panel`. No book or guide page used it; write `@block panel`.
 - `@end-skills` (no book used it; it is plain text now).
 - `@end-skill` no longer closes the `@learning-path` around the skill. It
@@ -139,13 +178,25 @@ Books pinned to an earlier gp-dimm-city are unaffected until re-pinned.
   swallow the rest of the file without a word. `@card` still closes silently.
 - `@end-card`, `@end-outcome` and `@end-procedure` with nothing open now warn
   (`declared_marker_close_without_open`) instead of being ignored.
-- `@callout` and `@dm-note` are still hand-written, so they no longer close a
-  `@card` or `@procedure` that is open, and a card or procedure no longer
-  closes them. `@callout`, `@procedure`, `@end-procedure`, `@end-callout` is a
+- `@callout` and `@dm-note` nest like every declared marker: a new one closes
+  the one still open (with what is inside it), `@end-callout` and
+  `@end-dm-note` close it, and `@page`, `@section`, `@chapter` and `@continue`
+  close it (a callout left open at a `@page` used to run on, and the next
+  page's `<div>` ended up inside it). `@callout`, `@procedure`, `@end-procedure`, `@end-callout` is a
   callout with the procedure in it. One book chapter wrote exactly that; it
   used to close the callout at the `@procedure` and leave the steps and the
   closing paragraph outside its box, and now renders them inside it, as
   written.
+- A callout written in a skill (even after its card, with no `@end-skill`)
+  stays in the skill's card, as before. A stray `@end-callout` or
+  `@end-dm-note` warns (`declared_marker_close_without_open`) instead of being
+  ignored, and a bare word that is not a variant (`@callout vibes`) is a note
+  with core's `unknown_variant` warning.
+- `@dm-note` now takes author classes and an `#id` like `@callout` (it used to
+  ignore them).
+- A callout or `@dm-note` glued to the line above it (no blank line) is now a
+  marker, as every declared marker is; it used to be folded into the
+  paragraph.
 - A bare word after `@card`, `@outcome` or `@procedure` is no longer a class
   (core reads it as a variant, and only `flush` is one): write `@card .wide`.
   No book or guide page used one.

package/README.md

@@ -43,7 +43,7 @@ byte for byte on every build.
   `@specialty-art` / `@specialty-card`, `@learning-path`, `@skill` (with
   `@continue` for a card that spans a page break), `@outcome`, `@callout`,
   `@dm-note`, `@sidebar`, `@sidebar-box`, `@block`, `@card`, `@gear`,
-  `@definition`, `@procedure`, `@lede`, `@toc`, `@tape`, `@glossary`, GFM
+  `@definition`, `@procedure`, `@lede`, `@toc`, `@glossary`, GFM
   alerts (`> [!NOTE]`, `[!WARNING]`, `[!DM]`, `[!VIBE]`, `[!ORIGIN]`,
   `[!VISIT]`, `[!GEAR]`, `[!FLAVOR]`, `[!PULLQUOTE]`), and the automatic
   `ROLL THE DIE!` chip. `docs/macros.md` is the inventory;

package/components.yaml

@@ -26,8 +26,7 @@
 #     live           at least one class styled; used at least once in a book;
 #                    plugin-origin entries must actually be emitted/parsed
 #     unused         styled or emitted, but used by no book
-#     retired        no class styled, none emitted, none used (a retired marker
-#                    may still be parsed as a no-op stripper)
+#     retired        no class styled, none emitted, none used
 #     unimplemented  no class styled, none emitted — documented or authored,
 #                    never built.
 #
@@ -72,7 +71,7 @@ components:
   - name: callout
     status: live
     origin: plugin
-    recipe: "@callout variant=note|warning|dm|vibe|origin|visit|gear label=\"…\" … @end-callout"
+    recipe: "@callout [note|warning|dm|vibe|origin|visit|gear] label=\"…\" … @end-callout"
     emits:
       - div.dc-alert.dc-note > span.dc-alert-label
       - div.dc-alert.dc-note.warning
@@ -83,7 +82,7 @@ components:
       - div.dc-alert.dc-gear-callout
     css: styles/components/callouts.css
     breaks: "as alert"
-    notes: "Same DOM and tokens as alert; the macro form allows multiple paragraphs and a custom label."
+    notes: "Same DOM and tokens as alert; the macro form allows multiple paragraphs and a custom label. The variant is a bare word (`@callout vibe`); `variant=` is no longer accepted and is reported as a problem. With no label=\"…\" the variant's name is the label."
 
   - name: dm-note
     status: live
@@ -92,7 +91,7 @@ components:
     emits: div.dc-alert.dc-dm-note > span.dc-alert-label
     css: [styles/components/callouts.css, styles/dc-native.css]
     breaks: "as alert; first child glued to the box start (dc-native.css)"
-    notes: "Sugar for @callout variant=dm. Used by the design guide only."
+    notes: "An alias of @callout with the dm variant preset: `@dm-note` is `@callout dm`. Used by the design guide only."
 
   - name: flavor
     status: live
@@ -217,12 +216,13 @@ components:
 
   - name: tape
     status: live
-    origin: plugin
-    recipe: "@tape label=\"…\"  (also authored as raw <div class=\"dc-tape dc-flush\">…</div>)"
+    origin: author
+    recipe: "<div class=\"dc-tape\">…</div>  (add dc-flush to run edge to edge)"
     emits: div.dc-tape
     css: styles/components/chrome.css
     tokens: [--dc-tape-bg, --dc-tape-border, --dc-tape-color]
     breaks: "break-inside: avoid"
+    notes: "Raw HTML only. The @tape marker was removed in 1.2.0: a one-line marker with no body and no @end- needs a selfClosing declaration core does not have yet (gutterpress#344)."
 
   - name: toc
     status: live
@@ -771,13 +771,6 @@ components:
     emits: .dc-callout
     notes: "Removed 2026-10-08 (dc-native.css): nothing emits .dc-callout; the alert family is .dc-alert."
 
-  - name: roll-table
-    status: retired
-    origin: plugin
-    recipe: "@roll-table … @end-roll-table / @options-table … @end-options-table"
-    emits: []
-    notes: "Removed in plugin 17.3.0; the markers are still parsed and stripped as no-ops. Use @outcome or a plain table."
-
   - name: rules-definition
     status: retired
     origin: author

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gp-dimm-city",
-  "version": "1.2.0-alpha.2",
+  "version": "1.2.0",
   "description": "Dimm City design system for Gutterpress: the markdown-it macros (@skill, @specialty, @learning-path, @callout, …), print stylesheets, design tokens, fonts and page templates the Dimm City TTRPG books are set in.",
   "type": "module",
   "main": "plugin.js",
@@ -69,7 +69,7 @@
     "pack:check": "npm pack --dry-run"
   },
   "devDependencies": {
-    "gutterpress": "0.11.16-alpha.2",
+    "gutterpress": "0.11.16",
     "markdown-it": "^14.1.0"
   },
   "peerDependencies": {

package/plugin.js

@@ -37,6 +37,11 @@
  *                          per `roll | name | text` line (crit, hit, mixed, miss, fail)
  *   @procedure           → ol.dc-steps: each numbered list inside becomes the
  *                          zero-padded step list (the wrapper renders nothing)
+ *   @callout [variant]   → div.dc-alert.<variant class> > span.dc-alert-label.
+ *                          Variants (bare word): note, warning, dm, vibe, origin,
+ *                          visit, gear; none is a note. The label is `label="…"`,
+ *                          or the variant's name. `@dm-note` is `@callout dm`
+ *                          (an alias). `variant=` is gone: validate reports it.
  *   Core's nesting rule is the only one: a declared marker that is already
  *   open is closed (with everything inside it) when it opens again;
  *   `@end-<name>` closes that marker and what is inside it; `@page`,
@@ -45,12 +50,7 @@
  *   made of rows, a procedure of a numbered list) are the plugin's:
  *   the `validate` of each declaration.
  *
- * HAND-WRITTEN MARKERS (support optional key="value" attributes; handled by
- * the dimm_city_transform below):
- *   @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
+ * THE REST OF WHAT THIS FILE DOES (plain markdown-it rules, no markers):
  *   @continue           → Continuation marker — inside a skill's card it emits a
  *                          card with a "{name} ▸" tab so an oversized skill card
  *                          can be split across pages while keeping a visible link
@@ -58,7 +58,8 @@
  *                          before core's layout transform; anywhere else it is
  *                          core's section continuation)
  *   (chapter-opener composite is now markup-driven — see CSS notes below)
- *   @tape               → Inline tape divider (`<div class="dc-tape">— § —</div>`)
+ *   `ROLL THE DIE!`      → span.dc-roll-the-die
+ *   an image-only paragraph gets p.dc-img-wrapper
  *
  * GFM ALERT SYNTAX:
  *   `> [!NOTE]` / `[!WARNING]` / `[!DM]` / `[!VIBE]` / `[!ORIGIN]` / `[!VISIT]`
@@ -470,125 +471,6 @@ function parseAbilityFromListItem(html) {
 }
 
 
-// Parse key="value", key='value', key=value, bare .class / #id tokens,
-// and {.class #id} attribute blocks from the body string following a marker keyword.
-//
-// Grammar matches parseMarkerLine() in Gutterpress's markers.js — inlined here
-// rather than imported, because plugin code cannot resolve Gutterpress at runtime:
-//   - Quote-aware tokenization: key="a b" and key='a b' preserve spaces inside quotes
-//   - .classname  — shorthand class (multiple allowed)
-//   - #id         — shorthand id
-//   - key=value   — arbitrary attribute; key="class" splits on whitespace/commas
-//   - bare token  — treated as a class (DC markers have no positional "name" slot)
-//
-// Back-compat: brace blocks {.class #id} are stripped and injected as tokens
-// before the main pass so @specialty {.augmerc} continues to work alongside
-// the new bare-token form @specialty .augmerc.
-function parseAttrs(str) {
-  // Pre-pass: extract brace blocks {.class1 .class2 #id} for back-compat,
-  // then remove them from the string so the main tokenizer doesn't see them.
-  const braceClasses = [];
-  const braceIds = [];
-  const strNoBraces = str.replace(/\{([^}]+)\}/g, (_, inside) => {
-    for (const part of inside.trim().split(/\s+/)) {
-      if (part.startsWith('.')) braceClasses.push(part.slice(1));
-      else if (part.startsWith('#')) braceIds.push(part.slice(1));
-    }
-    return ' ';
-  });
-
-  // Tokenize the remaining string using the same quote-aware tokenizer as
-  // markers.js's parseMarkerLine().
-  const tokens = [];
-  let buf = '';
-  let quote = null;
-  for (let i = 0; i < strNoBraces.length; i++) {
-    const ch = strNoBraces[i];
-    if (quote) {
-      if (ch === quote) quote = null;
-      else buf += ch;
-      continue;
-    }
-    if (ch === '"' || ch === "'") {
-      quote = ch;
-      continue;
-    }
-    if (/\s/.test(ch)) {
-      if (buf) tokens.push(buf);
-      buf = '';
-      continue;
-    }
-    buf += ch;
-  }
-  if (buf) tokens.push(buf);
-
-  // Process tokens: mirrors parseMarkerLine's attr-accumulation loop.
-  // DC markers have no positional "name" slot — bare tokens become classes.
-  const attrs = {};
-  const classes = [...braceClasses];
-  if (braceIds.length) attrs['id'] = braceIds[braceIds.length - 1];
-
-  for (const t of tokens) {
-    if (t.startsWith('.')) {
-      const c = t.slice(1).trim();
-      if (c) classes.push(c);
-      continue;
-    }
-    if (t.startsWith('#')) {
-      const id = t.slice(1).trim();
-      if (id) attrs['id'] = id;
-      continue;
-    }
-    const eq = t.indexOf('=');
-    if (eq > 0) {
-      const key = t.slice(0, eq).trim();
-      const val = t.slice(eq + 1).trim();
-      if (!key) continue;
-      if (key === 'class') {
-        val.split(/[,\s]+/).filter(Boolean).forEach((c) => classes.push(c));
-      } else if (key === 'id') {
-        if (val) attrs['id'] = val;
-      } else {
-        attrs[key] = val;
-      }
-      continue;
-    }
-    // Bare token (no . # =) — becomes a class for DC markers
-    if (t) classes.push(t);
-  }
-
-  if (classes.length) attrs['class'] = classes.join(' ');
-  return attrs;
-}
-
-// Check if a paragraph contains a marker and extract any attributes
-// Returns { matched: true, attrs: {...} } or { matched: false }
-function parseMarker(tok, tokens, i, marker) {
-  if (tok.type !== 'paragraph_open') return { matched: false };
-  const inline = tokens[i + 1];
-  if (!inline || inline.type !== 'inline') return { matched: false };
-
-  const content = inline.content.trim();
-
-  // Exact match (no attributes)
-  if (content === marker) {
-    return { matched: true, attrs: {} };
-  }
-
-  // Check if starts with marker followed by space
-  if (content.startsWith(marker + ' ')) {
-    const rest = content.slice(marker.length + 1).trim();
-    return { matched: true, attrs: parseAttrs(rest) };
-  }
-
-  return { matched: false };
-}
-
-// Legacy helper for simple marker checks (no attrs needed)
-function isMarker(tok, tokens, i, marker) {
-  return parseMarker(tok, tokens, i, marker).matched;
-}
-
 // Gutterpress owns bare @continue as a generic section marker and parses it
 // before custom core rules run. Claim the exact bare marker first, then decide
 // before Gutterpress's layout transform whether it belongs to a skill card or
@@ -836,6 +718,19 @@ function dcAlertsTransform(state) {
   state.tokens = newTokens;
 }
 
+/**
+ * Mark image-only paragraphs with `.dc-img-wrapper`, so layout rules can
+ * target them without relying on `p:has(img)`.
+ */
+function dcImageParagraphs(state) {
+  const tokens = state.tokens;
+  for (let i = 0; i + 2 < tokens.length; i++) {
+    const [open, inline, close] = [tokens[i], tokens[i + 1], tokens[i + 2]];
+    if (open.type !== 'paragraph_open' || inline.type !== 'inline' || close.type !== 'paragraph_close') continue;
+    if (inline.children?.length === 1 && inline.children[0].type === 'image') open.attrSet('class', 'dc-img-wrapper');
+  }
+}
+
 /**
  * `data-position="odd|even"` on every @specialty-card, counted across the
  * document in order so the card grid alternates its tilt/offset. The wrapper
@@ -1047,8 +942,8 @@ function dcSkillCards(state) {
         continue;
       }
 
-      // A @card, @outcome or @procedure is content of the skill's card; a
-      // break or another component (@sidebar, @specialty-art, …) ends it.
+      // A @callout, @card, @outcome or @procedure is content of the skill's card;
+      // a break or another component (@sidebar, @specialty-art, …) ends it.
       if (tok.type === 'layout_component_open' && CARD_CONTENT.has(tok.meta.kind)) {
         let end = i;
         let depth = 0;
@@ -1129,7 +1024,7 @@ function dcSkillCards(state) {
 // run BEFORE dcLearningPaths and dcSkillCards: a card, outcome or procedure
 // inside a skill must already be in its final form when the skill's rule
 // reads it. They stay inside the skill's card (see CARD_CONTENT).
-const CARD_CONTENT = new Set(['card', 'outcome', 'procedure']);
+const CARD_CONTENT = new Set(['callout', 'card', 'outcome', 'procedure']);
 
 /**
  * `@card`: the wrapper is `div.dc-card` (the declared token itself). Inside it,
@@ -1225,6 +1120,43 @@ function dcProcedures(state) {
   });
 }
 
+// ── Declared component: @callout (and its alias @dm-note) ──────────────────
+//
+// `@callout note|warning|dm|vibe|origin|visit|gear` is a declared wrapper:
+// core adds `dc-alert`, the variant's class and any author classes. What core
+// cannot know is each variant's default label, so a rule adds it when the
+// author wrote no `label="…"`. A missing or unrecognised variant is a plain
+// note, as it always was.
+const CALLOUTS = {
+  note: { class: 'dc-note', label: 'Note' },
+  warning: { class: 'dc-note warning', label: 'Warning' },
+  dm: { class: 'dc-dm-note', label: 'Dream Master Note' },
+  vibe: { class: 'dc-vibe-callout', label: 'Vibe' },
+  origin: { class: 'dc-origin-callout', label: 'Origin' },
+  visit: { class: 'dc-visit-callout', label: 'Visit' },
+  gear: { class: 'dc-gear-callout', label: 'Gear' },
+};
+
+function dcCallouts(state) {
+  forEachComponent(state.tokens, 'callout', ([open, ...rest]) => {
+    const variant = Object.hasOwn(CALLOUTS, open.meta.variant) ? open.meta.variant : 'note';
+    if (variant !== open.meta.variant) {
+      // no variant class came from core: the default note keeps its place right after dc-alert
+      open.attrSet('class', open.attrGet('class').replace('dc-alert', 'dc-alert dc-note'));
+    }
+    if (open.meta.labelled) return; // an explicit label="…" wins
+    const label = makeToken('html_block', '<span class="dc-alert-label">' + esc(CALLOUTS[variant].label) + '</span>\n');
+    return [open, label, ...rest];
+  });
+}
+
+// `variant=` was the old way to pick one; it now reads as a plain attribute
+// and would silently render a note, so say so once, on the marker's line.
+function validateCallout({ attrs }) {
+  if (attrs.variant === undefined) return [];
+  return [`no longer takes variant=${attrs.variant}; write "@callout ${attrs.variant}" instead.`];
+}
+
 /**
  * Structure checks (core runs these on the declared markers below and reports
  * them as layout warnings). They are the plugin's rules, not core's: core
@@ -1329,133 +1261,15 @@ export default function dimmCityPlugin(md, options = {}) {
   // variant chrome, the chevron-styled h1) is provided by CSS attribute
   // selectors in components/*.css matching this structure.
 
-  // The hand-written markers that remain: @callout, @dm-note, @tape and the
-  // retired @roll-table / @options-table no-ops, plus the image-only paragraph class.
-  md.core.ruler.push('dimm_city_transform', function (state) {
-    const tokens = state.tokens;
-    const newTokens = [];
-    let inCallout = false;
-    let inDmNote = false;
-
-    // A new @callout or @dm-note closes the one still open.
-    function closeAll() {
-      if (inCallout) newTokens.push(makeToken('html_block', '</div>\n'));
-      if (inDmNote) newTokens.push(makeToken('html_block', '</div>\n'));
-      inCallout = inDmNote = false;
-    }
-
-    for (let i = 0; i < tokens.length; i++) {
-      const tok = tokens[i];
-
-      // --- @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:
-      // the markers (and their @end- counterparts) are stripped so any stray
-      // occurrence renders nothing. Use standard GFM pipe tables instead — they are
-      // auto-styled by dc-core.
-      if (isMarker(tok, tokens, i, '@roll-table') ||
-          isMarker(tok, tokens, i, '@end-roll-table') ||
-          isMarker(tok, tokens, i, '@options-table') ||
-          isMarker(tok, tokens, i, '@end-options-table')) {
-        i += 2;
-        continue;
-      }
-
-      // --- @callout / @end-callout ---
-      // Block-level alert wrapper. variant="note|warning|dm|vibe|origin|visit|gear"
-      const calloutMarker = parseMarker(tok, tokens, i, '@callout');
-      if (calloutMarker.matched) {
-        closeAll();
-        const variant = (calloutMarker.attrs['variant'] || 'note').toLowerCase();
-        const CALLOUT_VARIANTS = {
-          'note':    { classes: 'dc-note',           label: 'Note' },
-          'warning': { classes: 'dc-note warning',   label: 'Warning' },
-          'dm':      { classes: 'dc-dm-note',        label: 'Dream Master Note' },
-          'vibe':    { classes: 'dc-vibe-callout',   label: 'Vibe' },
-          'origin':  { classes: 'dc-origin-callout', label: 'Origin' },
-          'visit':   { classes: 'dc-visit-callout',  label: 'Visit' },
-          'gear':    { classes: 'dc-gear-callout',   label: 'Gear' },
-        };
-        const cfg = CALLOUT_VARIANTS[variant] || CALLOUT_VARIANTS['note'];
-        const labelOverride = calloutMarker.attrs['label'];
-        const labelText = labelOverride ? esc(labelOverride) : cfg.label;
-        const calloutClass = 'dc-alert ' + cfg.classes +
-          (calloutMarker.attrs['class'] ? ' ' + esc(calloutMarker.attrs['class']) : '');
-        newTokens.push(makeToken('html_block',
-          '<div class="' + calloutClass + '">\n' +
-          '<span class="dc-alert-label">' + labelText + '</span>\n'
-        ));
-        inCallout = true;
-        i += 2;
-        continue;
-      }
-
-      if (isMarker(tok, tokens, i, '@end-callout')) {
-        if (inCallout) newTokens.push(makeToken('html_block', '</div>\n'));
-        inCallout = false;
-        i += 2;
-        continue;
-      }
-
-      // --- @dm-note / @end-dm-note ---
-      // Block-level DM note wrapper. Equivalent to > [!DM] but supports multi-paragraph content.
-      const dmNoteMarker = parseMarker(tok, tokens, i, '@dm-note');
-      if (dmNoteMarker.matched) {
-        closeAll();
-        const labelOverride = dmNoteMarker.attrs['label'];
-        const labelText = labelOverride ? esc(labelOverride) : 'Dream Master Note';
-        newTokens.push(makeToken('html_block',
-          '<div class="dc-alert dc-dm-note">\n' +
-          '<span class="dc-alert-label">' + labelText + '</span>\n'
-        ));
-        inDmNote = true;
-        i += 2;
-        continue;
-      }
+  // Mark image-only paragraphs so layout rules can target them without
+  // relying on p:has(img). The base CSS rule
+  // (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);
 
-      if (isMarker(tok, tokens, i, '@end-dm-note')) {
-        if (inDmNote) newTokens.push(makeToken('html_block', '</div>\n'));
-        inDmNote = false;
-        i += 2;
-        continue;
-      }
-
-      // --- @tape (single-line tape divider) ---
-      const tapeMarker = parseMarker(tok, tokens, i, '@tape');
-      if (tapeMarker.matched) {
-        const labelAttr = tapeMarker.attrs['label'] || '';
-        const extraClass = tapeMarker.attrs['class'] ? ' ' + esc(tapeMarker.attrs['class']) : '';
-        newTokens.push(makeToken('html_block', '<div class="dc-tape' + extraClass + '">' + esc(labelAttr) + '</div>\n'));
-        i += 2; continue;
-      }
-
-      // Mark image-only paragraphs so layout rules can target them without
-      // relying on p:has(img). The base CSS rule
-      // (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.
-      if (tok.type === 'paragraph_open') {
-        const inlineTok = tokens[i + 1];
-        const closeTok = tokens[i + 2];
-        if (inlineTok && inlineTok.type === 'inline' && closeTok && closeTok.type === 'paragraph_close') {
-          const hasOnlyImage = Array.isArray(inlineTok.children)
-            && inlineTok.children.length === 1
-            && inlineTok.children[0].type === 'image';
-          if (hasOnlyImage) {
-            tok.attrSet('class', 'dc-img-wrapper');
-          }
-        }
-      }
-
-      newTokens.push(tok);
-    }
-
-    closeAll(); // a @callout or @dm-note left open closes at the end of the document
-
-    state.tokens = newTokens;
-  });
-
-  // Declared components. Cards, outcomes and procedures go first so one inside
-  // a skill is already rewritten when the skill's rule looks at it.
+  // 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.
+  md.core.ruler.push('dc_callouts', dcCallouts);
   md.core.ruler.push('dc_cards', dcCards);
   md.core.ruler.push('dc_outcomes', dcOutcomes);
   md.core.ruler.push('dc_procedures', dcProcedures);
@@ -1468,7 +1282,7 @@ export default function dimmCityPlugin(md, options = {}) {
  * 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
+ * hand-written in a marker parser. 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
@@ -1511,6 +1325,16 @@ export const markers = {
   outcome: { class: 'dc-outcomes', variants: { flush: 'dc-flush' }, validate: validateOutcome },
   procedure: { validate: validateProcedure },
 
+  // `@callout` takes its variant as a bare word (`@callout vibe`); `@dm-note` is
+  // the same marker with the `dm` variant preset. A default label comes from
+  // `dcCallouts`, an explicit `label="…"` from core.
+  callout: wrapper('dc-alert', {
+    variants: Object.fromEntries(Object.entries(CALLOUTS).map(([name, { class: cls }]) => [name, cls])),
+    label: { tag: 'span', class: 'dc-alert-label', from: 'attr:label' },
+    validate: validateCallout,
+  }),
+  'dm-note': { alias: 'callout', preset: { variant: 'dm' } },
+
   sidebar: wrapper('dc-sidebar', { variants: { inset: 'inset' } }),
   'sidebar-box': wrapper('dc-prose-panel dc-sidebar-box'),
   definition: wrapper('dc-prose-panel dc-definition-block'),

package/snippets/callout.md

@@ -1,4 +1,4 @@
-@callout variant={{variant}} label="{{label}}"
+@callout note label="{{label}}"
 
 {{body}}
 

package/snippets/chapter-start-page.md

@@ -4,8 +4,8 @@
 
 # {{title}}
 
-@section .dc-fiction-excerpt
+@fiction-excerpt
 
 {{excerpt}}
 
-@end-section
+@end-fiction-excerpt