@heroiclands/package-build 25.2.1 → 25.4.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @heroiclands/package-build
 
+## 25.4.0
+
+**Verse**
+
+- Verse is written as a `.verse` div, or quoted inside prose as a `[…]{.verse}` span. An encoded div sets script beside Roman; an encoded quotation flows in the prose as script only.
+- A canto break can carry a heading and an anchor.
+- The formatter leaves verse untouched.
+- Footnotes in an encoded work appear in its Roman column only, with one number and one definition each.
+- A footnote inside any encoded passage appears after its script text, in the ordinary font.
+
+**Upgrading**
+
+- Rewrite each ```` ```verse ```` fence as `::: {.verse …}` (or `:::verse {…}`) with the same attributes, closed by `:::`. A verse fence is an error.
+- Replace each typed `***` with `--- {.canto}` on its own line after a blank line, with a stanza on both sides. A typed `***` is an error.
+
+## 25.3.0
+
+**Verse**
+
+- Versions of a work share automatic stanza labels and a check that their stanza shapes agree. An encoded original is written once and appears as aligned script and Roman text. Directions and speaker labels carry plain presentation hooks.
+
+**Upgrading**
+
+- Verse fences join source newlines: add `/` at intended line endings. Blank lines or `//` end stanzas, and standalone `***` ends a canto.
+- Remove `numstep=` and `cols=` from verse fences and remove column prefixes. Write each original once with its fence-level `lang=` and `enc=`; update the package and convert its content together.
+
 ## 25.2.1
 
 **Rendering and sites**

package/README.md

@@ -92,7 +92,7 @@ Every icon and image is covered by a provenance record stating `attribution`, `l
 
 `package-build cdn publish --set <file> --name <display name>` uploads every icon and image the package has, shipped or not, to `<site.assets>/<contentPackage>/` in that flat layout, and writes the named set listing the pictures the package leaves out. It reads the bucket from `CDN_ENDPOINT`, `CDN_BUCKET`, `CDN_ACCESS_KEY_ID` and `CDN_SECRET_ACCESS_KEY`, in the environment or `.env.local`. See [publish pictures to the CDN](docs/guides/release-and-deploy.md#publish-pictures-to-the-cdn).
 
-Leading captions, generic fenced divs, inline spans, and verse code fences are described in [links and markup](docs/authoring/links-and-markup.md).
+Leading captions, fenced divs, inline spans, and verse quotations are described in [links and markup](docs/authoring/links-and-markup.md).
 
 Cypress end-to-end suites use pinned Chrome for Testing 155.0.8059.84 by default
 on macOS arm64 and Linux x64, downloaded once into a reusable cache. Select an

package/assets/styles/content-base.css

@@ -124,168 +124,149 @@
  * the two markers are also the editor preview's stylesheet, with the content
  * roots replaced by the preview's own. */
 
-/* Verse groups are paragraphs; explicit stanza separators add their own gap. */
-:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .verse {
-    margin: 1.5rem 0;
-    line-height: 1.7;
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    .verse
+    .verse-stanza
+    p {
+    margin: 0;
 }
 
-:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .verse p {
+/* A quotation stays within its prose paragraph; canto titles retain heading type. */
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    .verse.verse-inline {
+    display: inline-block;
+    vertical-align: baseline;
+    max-inline-size: 100%;
     margin: 0;
+    container-type: normal;
 }
-
-:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .verse p + p {
-    margin-top: 1em;
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    .verse.verse-inline
+    .verse-stanza {
+    display: block;
+    margin: 0;
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    .verse.verse-inline
+    .verse-stanza
+    + .verse-stanza {
+    margin-top: 0.5em;
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    .verse
+    .verse-canto-heading {
+    display: block;
+    margin: 0.5em 0;
+    font-family: sans-serif;
+    font-size: 1.1em;
+    font-weight: bold;
+    line-height: 1.3;
 }
 
-.verse .verse-line {
+/* Logical stanzas share labels across native and Roman presentations. */
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .verse {
+    margin: 1.5rem 0;
+    line-height: 1.7;
+    container-type: inline-size;
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    .verse
+    .verse-stanza {
+    position: relative;
+    margin: 0 0 1em;
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    .verse-labelled
+    .verse-stanza {
+    padding-inline-start: 3em;
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    .verse
+    .verse-label {
+    position: absolute;
+    inset-inline-start: 0;
+    width: 2.5em;
+    text-align: end;
+    font-size: 0.75em;
+    color: color-mix(in srgb, currentColor 60%, transparent);
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .verse .verse-line {
     display: inline-block;
     margin-inline-start: var(--verse-indent, 0em);
     white-space: pre-wrap;
 }
-
-.verse :is(.verse-line, .verse-part).i1 {
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    .verse
+    .verse-line.i1 {
     --verse-indent: 1.25em;
 }
-.verse :is(.verse-line, .verse-part).i2 {
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    .verse
+    .verse-line.i2 {
     --verse-indent: 2.5em;
 }
-.verse :is(.verse-line, .verse-part).i3 {
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    .verse
+    .verse-line.i3 {
     --verse-indent: 3.75em;
 }
-.verse :is(.verse-line, .verse-part).i4 {
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    .verse
+    .verse-line.i4 {
     --verse-indent: 5em;
 }
-.verse :is(.verse-line, .verse-part).i5 {
-    --verse-indent: 6.25em;
-}
-.verse :is(.verse-line, .verse-part).i6 {
-    --verse-indent: 7.5em;
-}
-.verse :is(.verse-line, .verse-part).i7 {
-    --verse-indent: 8.75em;
-}
-.verse :is(.verse-line, .verse-part).i8 {
-    --verse-indent: 10em;
-}
-
-.verse .verse-stanza-break {
-    display: block;
-    height: 0.5em;
-}
-
-/* Numbered verse carries its numbers in a margin. A verse in columns is one
- * grid per verse line: its number, then each column's parts stacked, the
- * first in the normal tone and the rest muted, every part in the serif unless
- * its face sets it. A narrow journal stacks the columns of each line. */
 :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
-    .verse.verse-numbered {
-    position: relative;
-    padding-inline-start: 3em;
+    .verse
+    .verse-line.i5 {
+    --verse-indent: 6.25em;
 }
-
 :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
     .verse
-    .verse-number {
-    color: color-mix(in srgb, currentColor 60%, transparent);
-    font-size: 0.8em;
+    .verse-line.i6 {
+    --verse-indent: 7.5em;
 }
-
 :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
-    .verse-numbered
-    .verse-line
-    .verse-number {
-    position: absolute;
-    inset-inline-start: 0;
-    width: 2.2em;
-    text-align: end;
+    .verse
+    .verse-line.i7 {
+    --verse-indent: 8.75em;
 }
-
 :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
-    .verse.verse-columns {
-    container-type: inline-size;
+    .verse
+    .verse-line.i8 {
+    --verse-indent: 10em;
 }
-
 :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
-    .verse-numbered.verse-columns {
-    padding-inline-start: 0;
+    .verse
+    .verse-canto-break {
+    display: block;
+    height: 0.5em;
 }
-
 :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
-    .verse-columns
+    .verse-paired
     .verse-row {
     display: grid;
-    grid-auto-flow: column;
-    grid-auto-columns: 1fr;
     direction: ltr;
-    grid-template-columns: repeat(var(--verse-columns, 2), minmax(0, 1fr));
+    grid-template-columns: repeat(2, minmax(0, 1fr));
     column-gap: 1.5rem;
-    margin-bottom: 0.5em;
-}
-
-:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
-    .verse-numbered.verse-columns
-    .verse-row {
-    grid-template-columns: 2.5em repeat(var(--verse-columns, 2), minmax(0, 1fr));
-}
-
-:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
-    .verse-columns
-    .verse-number {
-    text-align: end;
-    padding-top: 0.2em;
+    align-items: start;
 }
-
 :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
-    .verse-columns
-    :is(.verse-column, .verse-part) {
-    display: block;
+    .verse-paired
+    :is(.verse-native, .verse-roman) {
+    min-width: 0;
     white-space: pre-wrap;
 }
-
 :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
-    .verse-columns
-    .verse-part {
+    .verse-paired
+    .verse-roman {
     font-family: serif;
-    padding-inline-start: var(--verse-indent, 0em);
-}
-
-:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
-    .verse-columns
-    .verse-secondary {
-    color: color-mix(in srgb, currentColor 60%, transparent);
 }
-
-:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
-    .verse-columns
-    .verse-secondary
-    * {
-    color: inherit;
-}
-
-:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
-    .verse-columns
-    .verse-part[dir="rtl"] {
-    text-align: start;
-}
-
 @container (max-width: 32rem) {
     :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
-        .verse-columns
+        .verse-paired
         .verse-row {
-        grid-auto-flow: row;
         grid-template-columns: 1fr;
     }
-    :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
-        .verse-numbered.verse-columns
-        .verse-row {
-        grid-template-columns: 2.5em 1fr;
-    }
-    :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
-        .verse-numbered.verse-columns
-        .verse-column {
-        grid-column: 2;
-    }
 }
 
 /* Text set in one of the faces. The font family and features come from the

package/docs/api.md

@@ -1339,6 +1339,29 @@ index for checking page links.
 
 `createRenderer(target, options?)` builds the one markdown-it configuration every target renders through. `target` is `"foundry"`, `"web"`, `"preview"` or `"book"`. The renderer holds the configured parser (`md`), the names of the plugins installed (`plugins`), and three functions: `prepare` writes the constructs markdown-it has no syntax for — marked text, captioned items, named blocks, verse and alerts — as HTML between blank lines; `render` prepares and renders to HTML; `renderInline` renders one inline run. The `book` target parses only, and its Typst stage reads the tokens.
 
+Verse blocks are `::: {.verse ...}` or `:::verse {...}`; their raw bodies are
+parsed with inline Markdown through the shared verse structure. Inline
+`[text/..line//]{.verse}` quotations retain span wrappers inside prose. A blank
+line followed by `--- {.canto #id title="Heading"}` supplies a titled canto
+boundary without opening a journal page. `verseDivPlugin` from
+`engine/verse-regions.mjs` emits `verse_div` tokens before Markdown block
+interpretation. `renderVerseQuotes` emits inline-safe HTML from the same logical
+model; the book's `verse_inline` token parses quoted lines in the note's footnote
+environment. A canto title is heading metadata, while its encoder receives the
+standard Roman canto control. Encoded verse divs produce paired
+script and Roman presentations. Encoded verse spans produce ordinary script-only
+inline text with encoded verse controls, while unencoded quotations retain their
+Roman line and stanza layout. Defined footnote references are excluded before
+encoding: divs retain the references only in their Roman presentation; all
+encoded spans restore references after their script wrapper. Display generation
+adds no duplicate reference, number, definition or backlink.
+
+`parseVerse(body, {footnotes})` accepts the same-note set of defined footnote
+labels when parsing a detached body; `scanVerse` obtains that context from the
+complete source. Reference-only positions contribute no work shape. A wholly
+reference-only body carries its references in `model.notes`, rendered once
+outside native-font wrappers without a verse row or label.
+
 | Export           | Signature                          | Returns                                                      | Use it when                                                                              |
 | ---------------- | ---------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
 | `createRenderer` | `createRenderer(target, options?)` | `{ target, md, plugins, prepare, render, renderInline }`     | Rendering a note body for one target with the rules every target shares.                 |
@@ -2497,12 +2520,13 @@ Not a JavaScript module — this subpath entry exists so tooling (bundlers, `imp
 
 The engine wildcard subpath also exposes the body parsers below. Their figure exports operate on leading captions.
 
-| Module                       | Exports                                                                                   | Contract                                                                                                                                                                                                                               |
-| ---------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `engine/content-figures.mjs` | `FIGURE_NAMES`, `FIGURE_CLASSES`, `scanFigures`, `numberFigures`, `renderFigureBlocks`    | Scan leading captions and their next supported blocks; `numbered` distinguishes `:` and `:@`. `type` may override inference; `example` is supported. `FIGURE_CLASSES` retains built-in styled classes, not a closed author vocabulary. |
-| `engine/content-blocks.mjs`  | `BLOCK_NAMES`, `BLOCK_CONTAINERS`, `scanBlocks`, `renderBlocks`, `renderWithheldSections` | Read div and secret fences; generic div records have `name: "div"` and no generated title. Scanning includes verse errors.                                                                                                             |
-| `engine/content-verse.mjs`   | `verseLines`, `verseStanzas`, `inlineVerse`, `verseMarkdown`, `scanVerse`, `renderVerse`  | Read `verse` code fences, validate authored metadata and tabs, and preserve relative indent levels and stanzas.                                                                                                                        |
-| `engine/content-spans.mjs`   | `spanMarkdownPlugin`, `scanSpans`, `renderSpans`                                          | Parse bracket spans after recognized links. The scanner returns spans, the exact `.name` inventory and located errors, retaining visible text and attribute positions; rendering preserves inline Markdown and permitted attributes.   |
+| Module                       | Exports                                                                                                                     | Contract                                                                                                                                                                                                                               |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `engine/content-figures.mjs` | `FIGURE_NAMES`, `FIGURE_CLASSES`, `scanFigures`, `numberFigures`, `renderFigureBlocks`                                      | Scan leading captions and their next supported blocks; `numbered` distinguishes `:` and `:@`. `type` may override inference; `example` is supported. `FIGURE_CLASSES` retains built-in styled classes, not a closed author vocabulary. |
+| `engine/content-blocks.mjs`  | `BLOCK_NAMES`, `BLOCK_CONTAINERS`, `scanBlocks`, `renderBlocks`, `renderWithheldSections`                                   | Read div and secret fences; generic div records have `name: "div"` and no generated title. Scanning includes verse errors.                                                                                                             |
+| `engine/content-verse.mjs`   | `verseLines`, `verseStanzas`, `inlineVerse`, `parseVerse`, `verseMarkdown`, `scanVerse`, `renderVerse`, `renderVerseQuotes` | Read `.verse` divs and quotations, validate metadata and source positions, and share logical lines, stanza labels and titled canto headings across targets.                                                                            |
+| `engine/verse-regions.mjs`   | `verseRegions`, `verseDivPlugin`                                                                                            | Locate opaque raw verse div regions and install their block token rule before ordinary Markdown interpretation.                                                                                                                        |
+| `engine/content-spans.mjs`   | `spanMarkdownPlugin`, `scanSpans`, `renderSpans`                                                                            | Parse bracket spans after recognized links. The scanner returns spans, the exact `.name` inventory and located errors, retaining visible text and attribute positions; rendering preserves inline Markdown and permitted attributes.   |
 
 Inline `.secret` spans preserve their inline content, name classes and
 attributes. Site rendering uses a separate show/hide button and content span,