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

package/CHANGELOG.md

@@ -45,6 +45,55 @@ Books pinned to an earlier gp-dimm-city are unaffected until re-pinned.
   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.
@@ -52,6 +101,10 @@ Books pinned to an earlier gp-dimm-city are unaffected until re-pinned.
 ### 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
 
@@ -63,7 +116,45 @@ Books pinned to an earlier gp-dimm-city are unaffected until re-pinned.
   `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
 

package/components.yaml

@@ -156,6 +156,7 @@ 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
@@ -184,6 +185,7 @@ components:
       - 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
@@ -242,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
@@ -260,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
@@ -285,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
@@ -345,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
@@ -364,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

package/package.json

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