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

package/CHANGELOG.md

@@ -7,6 +7,155 @@ 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).
+- **`@specialty`, `@learning-path` and `@skill` are declared too, then
+  transformed** ("declare, then transform"). Core now opens, nests and closes
+  them, and two ordinary markdown-it core rules (`dcLearningPaths`,
+  `dcSkillCards`, over a small inlined `forEachComponent` helper) rewrite what
+  sits inside: the path's title, subtitle and sticker chain, `data-path-ref`,
+  and one skill card per `####` heading. The state machine drops from 865 to
+  468 lines (`plugin.js` is 97 lines shorter overall, new rules included):
+  its skill, path and specialty flags and branches are gone. `@continue`
+  inside a skill's card still opens the
+  `{name} ▸` continuation card; the classifier that claims it ahead of core
+  now reads core's marker tokens instead of the raw paragraphs.
+- **`@card`, `@outcome` and `@procedure` are declared and transformed the same
+  way.** Three more core rules (`dcCards`, `dcOutcomes`, `dcProcedures`) run
+  ahead of the skill rules and rewrite what sits inside each. The state
+  machine drops from 468 to 122 lines: it now holds only `@callout`,
+  `@dm-note`, `@tape`, the retired `@roll-table` / `@options-table` no-ops and
+  the image-only paragraph class. `plugin.js` is another 208 lines shorter
+  (1,765 to 1,557), new rules, validation and docs comments included. The
+  emitted HTML is unchanged: rendering the design guide and both books
+  through the old and new plugin gives the same markup apart from the
+  attributes and the one page listed below.
+  - `@card` is `div.dc-card` with its heading, pull quote, body and footer as
+    before, and takes classes, `#id` and `key=value` as before.
+  - `@outcome` is `div.dc-outcomes`; `flush` is now a declared variant (it
+    adds `.dc-flush` and `data-outcome="flush"`), and `@outcome .dc-flush`
+    works too. The compact form (rows with no blank lines) still works.
+  - `@procedure` still renders only the `ol.dc-steps`: its declared wrapper is
+    hidden, so no `div` appears in the HTML.
+  - A `@card`, `@outcome` or `@procedure` inside a skill stays inside the
+    skill's card, as before.
+  - New on cards and outcomes: `data-source-range`, so the editor can map them.
+- **More structure checks.** An `@outcome` line that is not `roll | name |
+  text`, a table, list or heading inside an `@outcome` (they are left out), an
+  `@outcome` with no rows, and a `@procedure` with no numbered list are
+  reported in plain words, at the line.
+- `@specialty augmerc` is the new spelling for a specialty (names:
+  `augmerc`, `proxy`, `streetwarden`, `gutterdruid`, `cybersurgeon`,
+  `wirephreak`, `technosorcerer`, `etherlock`, `dualist`, `generalist`, each
+  styled by `.dc-specialty.<name>`). `@specialty .augmerc` and
+  `@specialty {.augmerc}` work unchanged and give the same element.
+  `data-path-ref` reads the enclosing specialty's variant or class, so
+  `@specialty .augmerc` still gives `AUG1`.
+- **Structure checks, in plain words.** Skills sitting directly in a
+  `@specialty` are reported once per run, at the first one ("This skill (and
+  any right after it) is outside a learning path…"), and so
+  is a `@learning-path` or `@specialty` that starts inside a skill. The usual
+  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`.
+- `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`.
+- `@end-skills` (no book used it; it is plain text now).
+- `@end-skill` no longer closes the `@learning-path` around the skill. It
+  closes the skill, like every declared closer; `@end-learning-path` ends the
+  path.
+
+### 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. That now
+  includes a stray `@end-skill`, `@end-learning-path` and `@end-specialty`.
+- Specialties, paths and skills close like every declared marker: a new one
+  of the same kind closes the previous and what is inside it, `@end-<name>`
+  closes it and what is inside it, and `@page`, `@section`, `@chapter` and
+  `@continue` close all of them. A `@page` written inside a specialty used to
+  leave the specialty open across the page; it now ends the specialty. Use
+  `@page-break` to break a page inside one.
+- A `@skill` glued to the line above it (no blank line) is now a marker, as
+  every declared marker is; it used to print as the text "@skill".
+- A skill inside a learning path is numbered `PATHREF.N` by its place in the
+  path. An `@end-skill` in the middle of a path used to end the path (the
+  skills after it lost their tier); the path now stays open.
+- A closer straight under a list item or a quote is a closer now, because core
+  reads declared markers there: `@end-procedure` under the last step and
+  `@end-card` under the footer quote no longer need a blank line (they used to
+  be folded into the item or the quote and never closed).
+- `@procedure` and `@outcome` left open at the end of a file warn with core's
+  `declared_marker_eof_close` ("An open @procedure reached end-of-document…"),
+  replacing the plugin's `unclosed_procedure`. An unclosed `@outcome` used to
+  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 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 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.
+- An `@outcome` shows only the lines of its own paragraphs: a list or heading
+  inside it is no longer read as a row (it is reported instead).
+- Core drops a declared marker that is already open and nests the next one, so
+  a book that closes a path early (`@end-learning-path` above its skills) now
+  has its next `@learning-path` nested in the last skill. The checks above name
+  each place; remove the early `@end-learning-path`.
+
 ## [1.1.5] - 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:
@@ -156,43 +156,44 @@ components:
     emits: ol.dc-steps > li > span.dc-step-no
     css: styles/components/data.css
     breaks: "break-inside: avoid"
+    notes: "Declared marker; no element of its own (its wrapper renders nothing), each numbered list inside is the step list. Left open at the end of the file it warns (declared_marker_eof_close); with no numbered list inside it is reported."
 
   - 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)
     css: styles/components/section.css
     breaks: "break-inside: avoid"
+    notes: "Declared marker, no variants: author classes (@card .dc-flaws), #id and key=value attributes ride on the wrapper. Inside a skill it stays in the skill's card. Left open at the end of the file it closes silently."
 
   - 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
@@ -243,7 +244,7 @@ components:
   - name: outcome
     status: live
     origin: plugin
-    recipe: "@outcome [flush] / 20 | Crit | text … @end-outcome, or a | Roll | Outcome | table inside a skill card"
+    recipe: "@outcome [flush] / 20 | Triumph | text / 11–19 | Success | text / 6–10 | Hard Choice | text / 2–5 | Failure | text / 1 | Catastrophe | text … @end-outcome, or a | Roll | Outcome | table inside a skill card"
     emits:
       - div.dc-outcomes[.dc-flush] > div.dc-outcomes-label
       - div.dc-outcome-row.crit|hit|mixed|miss|fail > span.dc-outcome-key.tier-* > span.dc-outcome-name + span.dc-outcome-roll
@@ -261,11 +262,12 @@ components:
       - --dc-outcome-name-opacity
     usage: ["| Roll | Outcome"]
     breaks: "break-inside: avoid; the skill-table form adds data-break-inside=avoid only when the parent card allows splitting"
+    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."
 
   - name: specialty
     status: live
     origin: plugin
-    recipe: "@specialty .augmerc|.proxy|.streetwarden|.gutterdruid|.cybersurgeon|.wirephreak|.technosorcerer|.etherlock|.dualist|.generalist … @end-specialty"
+    recipe: "@specialty augmerc|proxy|streetwarden|gutterdruid|cybersurgeon|wirephreak|technosorcerer|etherlock|dualist|generalist (or .augmerc, {.augmerc}) … @end-specialty"
     emits: div.dc-specialty.<name>
     css:
       - styles/components/specialty-identity.css
@@ -286,7 +288,7 @@ components:
       - --dc-specialty-intro-title-shape
       - --dc-specialty-intro-clip
     breaks: "none on the wrapper; children carry their own"
-    notes: "Parent-selector model: every card, path and intro inside inherits shape and colour from .dc-specialty.<name>. Auto-closes any open path or skill."
+    notes: "Parent-selector model: every card, path and intro inside inherits shape and colour from .dc-specialty.<name>. Declared marker: the word and the .class spelling give the same wrapper. A new @specialty, @end-specialty, @page, @section or @chapter closes it with every path and skill inside; a skill sitting directly in it (outside a learning path) is reported."
 
   - name: specialty-intro
     status: live
@@ -346,11 +348,12 @@ components:
       - --dc-path-shell-padding-bottom
       - --dc-arrow-color
     breaks: "break-before/after: auto on the block; the h3 stays with what follows"
+    notes: "Declared marker. data-path-ref is the enclosing specialty's code and the path's number in it (AUG1, PRX2; PATH1 for a specialty with no code). @end-learning-path closes the path and the skills inside it; a new @learning-path closes the previous one."
 
   - name: skill
     status: live
     origin: plugin
-    recipe: "@skill [id=…] [{.dc-allow-split}] [{.dc-two-col}] / #### Name | Tier / > flavor / 1. **N AP** *Ability:* text / ##### Sub-header … @end-skill (alias @end-skills)"
+    recipe: "@skill [id=…] [{.dc-allow-split}] [{.dc-two-col}] / #### Name | Tier / > flavor / 1. **N AP** *Ability:* text / ##### Sub-header … @end-skill"
     emits:
       - div.dc-skill-card[name][data-break-inside=avoid] > div.dc-card-tab > h4.dc-tab-title + span.dc-tab-tier
       - div.dc-card-body > div.dc-card-inner > p.dc-flavor + div.dc-sub-header
@@ -365,7 +368,7 @@ components:
       - --dc-card-gap
       - --dc-card-tab-shadow
     breaks: "data-break-inside=avoid by default; {.dc-allow-split} opts into splitting (see allow-split); tab break-after: avoid; last two abilities glued"
-    notes: "A ##### Outcomes sub-header is swallowed (the outcomes block carries its own label)."
+    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)."
 
   - name: skill-highlight
     status: live
@@ -427,16 +430,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 +447,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 +471,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 +486,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.5",
+  "version": "1.2.0-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",
@@ -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": {