@heroiclands/package-build 25.2.1 → 25.3.0

package/docs/diagnostics.md

@@ -297,36 +297,34 @@ Like a culture conflict, each fails the index and every command that reads it
 without collecting problems. The rules are under
 [a note's language](reference/format-details.md#a-notes-language).
 
-## A worked case: a verse in columns
+## A worked case: versions of a work
 
-A [verse in columns](authoring/links-and-markup.md#verse-in-columns) has a
-positive whole-number `cols` value. Invalid counts are located at their
-value. With multiple columns, every content line needs a numeric prefix and
-one or more spaces. Missing prefixes point to the line's first content
-character; out-of-range or decreasing numbers point to the authored number.
-
-This row has a decreasing column number on its third content line:
+[Versions of a work](authoring/links-and-markup.md#versions-and-stanza-labels)
+share a page-local `work=` key and the same stanza shape. For example:
 
 ````markdown
-```verse {cols=3 lang=en}
-1 The first reading.
-3 A later column.
-2 Out of order within this row.
+```verse {work=watch lang=en}
+The watch arrives.
+
+The harbor wakes.
+```
+
+```verse {work=watch lang=en}
+Another telling has only one stanza.
 ```
 ````
 
-The finding points to `2`. A blank line before it would start another row,
-where the column order begins again. A number above three or below one is
-out of bounds. Skipping a column is valid and leaves an empty cell; repeating
-a number is valid and adds another reading to that column. The first reading
-in every column is foreground and its later readings are grey.
+The opening lines receive findings naming canto 1 and its differing stanza
+counts, two and one. The first version is included in the disagreement. A key
+used by only one version is also a finding at that fence's opening line.
 
-Language and native-font findings retain their authored locations inside a
-reading, including the column prefix and indentation before it. An unknown
-mapping or face points to that run's attribute; an unknown word or a character
-the face cannot draw points to the original word or character. A language-only
-Roman repeat is checked in its own language, independently of a native run.
-The build reports invalid input rather than publishing an inferred layout.
+A concrete `enc=` creates its own script and Roman presentations from one
+original; the display does not add a second authored version. Source newlines
+join unless `/` ends the line. Blank lines and `//` end stanzas. A leading,
+trailing or consecutive `***` without a stanza between is located at the break
+itself. Language and encoding findings retain their positions in the single
+authored original, including text inside names, directions and speaker labels.
+The content index records that original once in `runs`.
 
 ## Emphasis in non-English spans
 
@@ -603,9 +601,10 @@ finding naming its `⟦U+XXXX⟧` spelling. Use that notation, or the chosen
 encoding's codage name, inside the literal markers. The encoder checks the
 codes; the Roman validator leaves their contents immutable.
 
-A verse fence uses its authored line endings for boundaries. A literal `/`
-inside it is an error at that slash. Visual indentation does not add periods
-to the encoded text. Source positions survive Markdown escapes and nested
+A verse fence uses `/` for logical line endings, `//` or blank lines for
+stanzas, and standalone `***` for cantos. A literal slash is written `\/`.
+Visual indentation at a logical line boundary does not add periods to the
+encoded text; a period on a joined continuation line remains text. Source positions survive Markdown escapes and nested
 `.emph` or `.name` spans.
 
 Language-run diagnostic columns count Unicode code points, so a supplementary

package/docs/guides/writing-in-invented-scripts.md

@@ -106,10 +106,9 @@ escapes are removed before encoding, and diagnostics retain the source position.
 
 Every `Zs` space separator and U+0009 through U+000D count as whitespace. A run
 of them is one word separator, which the encoding writes by its own rule.
-Newlines in prose are whitespace. In a verse fence, line endings supply line
-boundaries, blank lines supply stanza boundaries, and `--- {.canto}` on its
-own line supplies a canto boundary. Do not type a verse slash `/` inside the
-fence; an inline quotation of verse may use it. Verse indentation is layout,
+Newlines join as whitespace. In a verse fence, `/` ends a logical line,
+blank lines or `//` end stanzas, and standalone `***` ends a canto. A literal
+slash is written `\/`. Indentation at a logical line boundary is layout,
 not a punctuation character added to the encoded words.
 
 A `.name` child in a language run reaches the encoding with standard `{…}`
@@ -495,58 +494,46 @@ paragraphs: indentation, line breaks and spans survive formatting untouched.
 
 ````markdown
 ```verse {lang=vyl font=semaron-kuriale enc=vylsemaronenc}
-Lokazor lonak.
-  lokamen zaron.
+Lokazor lonak./
+.lokamen zaron.
 ```
 ````
 
-### Verse in columns
+### Versions of a work
 
-`form=epic` records the poem's kind without inferring its layout or metre.
-`cols` is a positive whole number, defaulting to `1`. A single-column poem
-uses its physical lines without numeric prefixes. With `cols` above one,
-every content line starts with a column number and one or more spaces.
-Blank lines separate logical verse rows, and `***` separates stanzas.
+`form=epic` records the author's literary form without inferring layout or metre.
 
-Numbers are in `1..cols` and nondecreasing within a row. Skip a number to
-leave that cell empty. Repeat a number for as many readings as the column
-needs: its first reading is foreground, and all its later readings are grey.
-That choice is independent for each column and resets at each new row.
-
-Here is a sparse three-column poem. The first row omits column two. The next
-fills it, and the last row begins a new stanza:
+A `verse` fence with a concrete `enc=` sets one original in its script on the
+left and Roman on the right. The author writes the text once; the two
+presentations align logical lines at full weight. `/` ends a logical line,
+source newlines otherwise join, a blank line or `//` ends a stanza, and a line
+of only `***` ends a canto. Leading periods at a logical line boundary indent
+that line. Use `\/` for a literal slash.
 
 ````markdown
-```verse {numstep=1 lang=vyl cols=3}
-1 [Lokazor lonak zaron.]{lang=vyl enc=vylsemaronenc}
-3 [He walks the oath road.]{lang=en}
-3 [Lokazor lonak zaron.]{lang=vyl enc=default}
+```verse {work=walking lang=en}
+He walks the oath road.
 
-1 [Lokamen lonak zaron.]{lang=vyl enc=vylsemaronenc}
-2 [Nothing to say]{lang=en}
-3 [I walk the oath road.]{lang=en}
-3 [Lokamen lonak zaron.]{lang=vyl enc=default}
+I walk the oath road.
+```
 
-***
+```verse {work=walking lang=vyl enc=vylsemaronenc}
+Lokazor lonak zaron.
 
-1 [alathos lokazor.]{lang=vyl enc=vylsemaronenc}
-3 [That one walks.]{lang=en}
-3 [alathos lokazor.]{lang=vyl enc=default}
+Lokamen lonak zaron.
 ```
 ````
 
-Each native span opts in explicitly and uses the Vylari note's configured
-map and font. Each Roman repeat is authored separately and stays Roman.
-`lang=` identifies the language without choosing a column; number prefixes
-alone place the readings. Inline links, language changes and authored spaces
-remain inside the chosen reading. Leading periods indent that reading.
-
-`numstep=N` counts logical rows, so repeated readings and empty cells do not
-advance its counter. Every target aligns each row's cells at the top, and
-narrow web or Foundry displays stack the cells in numbered order. A
-right-to-left reading stays in its cell and follows its own script's direction.
-Invalid counts and prefixes are located at the authored value or number;
-missing prefixes are located at the line's first content character.
+`work=` groups the versions within the page. Their stanza labels match, and the
+build checks that their canto counts and stanza counts per canto agree. The
+English fence is one column, and `enc=default` also stays one Roman column.
+The original's encoded and Roman presentations share one label per stanza.
+Names, `⟦…⟧` codage, language gaps and other inline spans retain their meaning;
+codage draws its glyphs on the left and appears as codage on the right. The
+content index records the original once with its fence language and encoding.
+See [versions and stanza labels](../authoring/links-and-markup.md#versions-and-stanza-labels)
+for poetry and prose examples, and [directions and speakers](../authoring/links-and-markup.md#directions-and-speakers)
+for plain semantic span hooks.
 
 ### Metre
 
@@ -567,7 +554,7 @@ whose language note states `data.sounds.stress` is counted line by line:
 
 ````markdown
 ```verse {lang=vyl scan=trimeter}
-Lokazor lonak zaron.
+Lokazor lonak zaron./
 Lokamen lonak zaron.
 ```
 ````
@@ -613,8 +600,6 @@ anything, each an error:
 
 > ``the language `vyl` is not a configured language with a `note`, so it has no stress rule for `scan=` to count beats by``
 
-> `` `scan=` counts the beats of one language's lines; a verse with cols>1 groups independent physical lines ``
-
 A repeated metre name is an error too:
 
 > `` `data.metres[1].name` is `trimeter`, which this note declares twice; a metre's name is unique ``
@@ -1158,9 +1143,8 @@ where the characters are the code points above: `Lokazor` begins with the
 capital `L` of the rows, `zaron` is the exception's long vowel, and each period
 writes the script's pause point.
 
-A poem in columns and a poem with its metre checked sit on one note. Both parse
-with no finding: the first sets native Vylari in column one and English over Roman
-Vylari in column three, with a sparse middle cell, and the second's lines each carry three beats.
+A work's English and original versions sit on one note. Its original is written
+once and appears beside its Roman presentation; a separate fence checks metre.
 
 **`assets/content/Lore/Walking.md`**
 
@@ -1175,25 +1159,20 @@ The walking of the oath road is sung in two settings. The first sets the poem
 beside its translation, and the second keeps the metre that the court keeps, so
 that a line with the wrong count is reported to the author who wrote it.
 
-```verse {numstep=1 lang=vyl cols=3}
-1 [Lokazor lonak zaron.]{lang=vyl enc=vylsemaronenc}
-3 [He walks the oath road.]{lang=en}
-3 [Lokazor lonak zaron.]{lang=vyl enc=default}
+```verse {work=walking lang=en}
+He walks the oath road.
 
-1 [Lokamen lonak zaron.]{lang=vyl enc=vylsemaronenc}
-2 [Nothing to say]{lang=en}
-3 [I walk the oath road.]{lang=en}
-3 [Lokamen lonak zaron.]{lang=vyl enc=default}
+I walk the oath road.
+```
 
-***
+```verse {work=walking lang=vyl enc=vylsemaronenc}
+Lokazor lonak zaron.
 
-1 [alathos lokazor.]{lang=vyl enc=vylsemaronenc}
-3 [That one walks.]{lang=en}
-3 [alathos lokazor.]{lang=vyl enc=default}
+Lokamen lonak zaron.
 ```
 
 ```verse {lang=vyl scan=trimeter}
-Lokazor lonak zaron.
+Lokazor lonak zaron./
 Lokamen lonak zaron.
 ```
 ````

package/docs/reference/format-details.md

@@ -2297,7 +2297,6 @@ its count can be the metre's.
 | A `scan=` no `data.metres` entry names, at the value                                            | error    |
 | A `scan=` on a fence with no `lang=`, at the key                                                | error    |
 | A `scan=` on a fence whose language states no stress rule or names no language note, at `lang=` | error    |
-| A `scan=` on a verse in columns, at the key                                                     | error    |
 
 > ``this line has 4 beats (5 with secondary beats); the metre `hexameter` has 6``
 

package/docs/reference/theme-pages.md

@@ -333,63 +333,36 @@ Caption classes are unrestricted. The built-in `border` class draws the block as
 
 ## Verse
 
-A verse fence reaches the page as a `.verse` block holding a paragraph per
-stanza and a `.verse-line` per line, its indent level as `i1` to `i8`. Its
-keys reach the block as written, `lang` as its language and the rest as
-`data-*` attributes. A numbered verse also carries `.verse-numbered`, and each
-numbered line starts with its `.verse-number`.
-
-A [verse in columns](../authoring/links-and-markup.md#verse-in-columns) also
-carries `.verse-columns`, and each logical row is one `.verse-row`. The
-block carries `data-cols` and `--verse-columns` with its positive column
-count. Every row contains that many `.verse-column` cells, including empty
-ones:
-
-```html
-<div
-  class="verse verse-columns verse-numbered"
-  lang="art-x-vyl"
-  data-numstep="5"
-  data-cols="3"
-  style="--verse-columns: 3">
-  <p>
-    <span class="verse-row"
-      ><span class="verse-number"></span
-      ><span class="verse-column"
-        ><span class="verse-part"
-          ><span class="script hl-semaron-kuriale" lang="art-x-vyl">…</span></span
-        ></span
-      ><span class="verse-column"></span
-      ><span class="verse-column"
-        ><span class="verse-part"><span lang="en">The hallowed boundary I sing,</span></span
-        ><span class="verse-part verse-secondary"
-          ><span lang="art-x-vyl">Thiruthriman sorimamen,</span></span
-        ></span
-      ></span
-    >
-    …
-  </p>
-</div>
-```
-
-A numbered verse in columns gives every logical row a `.verse-number`, empty
-on rows it does not number, so repeated readings do not advance the counter.
-The grid remains left to right while inline text follows its own script
-direction. Each row has its own grid and aligns all its cells at the top. Below a block width of `32rem` a row stacks
-its columns in order; it is a container query, so a narrow journal window
-stacks as well. The Foundry stylesheet draws the same.
-
-| class              | drawn as                                                      |
-| ------------------ | ------------------------------------------------------------- |
-| `.verse`           | the poem                                                      |
-| `.verse-line`      | one line of a poem without columns                            |
-| `.verse-numbered`  | a numbered poem, with a margin for its numbers                |
-| `.verse-number`    | a line's number, muted                                        |
-| `.verse-columns`   | a poem in columns, and the container its rows are measured by |
-| `.verse-row`       | one logical verse row: its number and its cells               |
-| `.verse-column`    | one numbered cell, possibly empty, with its readings stacked  |
-| `.verse-part`      | one entry's text, in the body serif unless its face sets it   |
-| `.verse-secondary` | every reading after a column's first in that row, grey        |
+A `verse` fence reaches the page as `.verse`, with one `.verse-stanza` per
+stanza and `.verse-line` per logical line. Indentation uses `i1` through `i8`;
+deeper levels carry their complete `--verse-indent`. `.verse-canto-break`
+separates cantos. A work-labelled fence adds `.verse-labelled`, and each stanza
+opens with a small `.verse-label` shared across its presentations.
+
+A concrete fence encoding adds `.verse-paired`. Each `.verse-row` aligns one
+`.verse-native` cell with one `.verse-roman` cell at full weight. The script is
+on the left; its direction applies within its cell. A narrow container stacks
+the native presentation before the Roman presentation. An unencoded fence or
+`enc=default` is one Roman column. See [versions of a work](../authoring/links-and-markup.md#versions-and-stanza-labels).
+
+| Class                | Meaning                                        |
+| -------------------- | ---------------------------------------------- |
+| `.verse`             | A version of a work                            |
+| `.verse-stanza`      | One stanza or prose paragraph                  |
+| `.verse-line`        | One logical line                               |
+| `.verse-labelled`    | A version carrying automatic stanza labels     |
+| `.verse-label`       | The stanza number or canto:stanza label        |
+| `.verse-paired`      | Script and Roman presentations of one original |
+| `.verse-row`         | Matching logical lines in both presentations   |
+| `.verse-native`      | Encoded text on the left                       |
+| `.verse-roman`       | Roman text on the right                        |
+| `.verse-canto-break` | A canto boundary                               |
+| `.direction`         | An instruction, inside or outside verse        |
+| `.speaker`           | A speaker label, inside or outside verse       |
+
+Direction and speaker classes have plain defaults. The book preserves the same
+classes through `book-span`, with plain `book-direction` and `book-speaker`
+hooks for their presentation.
 
 ## Emphasis in a script
 

package/engine/content-blocks.mjs

@@ -256,11 +256,12 @@ function attributeText(block, target, classes) {
  * @param {object} [options]
  * @param {(markdown: string) => string} [options.renderInline] - How a title
  *   is rendered; omitted, a title is plain inline Markdown.
+ * @param {Map<string, object>} [options.verses] - Shared encoded verse presentations.
  * @returns {{markdown: string, errors: Array<{line: number, column: number, message: string}>}}
  */
-export function renderBlocks(source, target, { renderInline } = {}) {
+export function renderBlocks(source, target, { renderInline, verses } = {}) {
     const { errors } = scanBlocks(source);
-    source = renderScroll(renderVerse(source).markdown).markdown;
+    source = renderScroll(renderVerse(source, { verses }).markdown).markdown;
     const renderedBlocks = scanBlocks(source).blocks;
     if (!renderedBlocks.length) return { markdown: String(source ?? ""), errors };
     const lines = String(source ?? "").split("\n");

package/engine/content-render.mjs

@@ -79,7 +79,7 @@ import { imagePlugin } from "./content-images.mjs";
 import { renderRuns } from "./content-scripts.mjs";
 import { renderSpans, spanMarkdownPlugin } from "./content-spans.mjs";
 import { cartoucheFigures, renderSymbolSpans } from "./content-symbols.mjs";
-import { hasColumns, inlineVerse, scanVerse, verseGroups, verseStanzas } from "./content-verse.mjs";
+import { inlineVerse, scanVerse } from "./content-verse.mjs";
 import { replaceOutsideCode } from "./code-fences.mjs";
 import { dictionaryEntryPlugin } from "./dictionary-layout.mjs";
 import { headingAttributesPlugin, headingIdsPlugin } from "./heading-attributes.mjs";
@@ -132,32 +132,30 @@ function verseInlinePlugin(md) {
                 continue;
             token.meta ??= {};
             const source = `${token.markup}${token.info}\n${token.content}${token.markup}`;
-            const poem = scanVerse(source).blocks[0];
-            if (hasColumns(poem)) {
-                token.meta.verseGroups = verseGroups(poem, source.split("\n")).map((group) => {
-                    if (group.stanzaBreak) return group;
-                    return {
+            const poem = scanVerse(source, { checkWorks: false }).blocks[0];
+            if (!poem) continue;
+            const paired = state.env.verses?.get(token.content.replace(/\n$/, ""));
+            const model = paired?.model ?? poem.model;
+            token.meta.verse = poem;
+            token.meta.versePaired = paired;
+            const parse = (text) => {
+                const children = [];
+                state.md.inline.parse(inlineVerse(text), state.md, state.env, children);
+                return children;
+            };
+            token.meta.verseGroups = model.groups.map((group) =>
+                group.cantoBreak ?
+                    { ...group, children: group.text ? parse(group.text) : [] }
+                :   {
                         ...group,
-                        parts: group.parts.map((part) => {
-                            const children = [];
-                            state.md.inline.parse(
-                                inlineVerse(part.text),
-                                state.md,
-                                state.env,
-                                children,
-                            );
-                            return { ...part, children };
-                        }),
-                    };
-                });
-                continue;
-            }
-            token.meta.verseStanzas = verseStanzas(token.content).map((stanza) =>
-                stanza.map(({ text, level }) => {
-                    const children = [];
-                    state.md.inline.parse(inlineVerse(text), state.md, state.env, children);
-                    return { children, level, stanzaBreak: /^\*{3}$/.test(text) };
-                }),
+                        lines: group.lines.map((line) => ({
+                            ...line,
+                            children: parse(line.text),
+                            ...(paired ?
+                                { romanChildren: parse(line.romanText ?? line.text) }
+                            :   {}),
+                        })),
+                    },
             );
         }
     });
@@ -433,8 +431,12 @@ export function createRenderer(target, options = {}) {
     const prepare = (markdown, env = {}) => {
         let text = String(markdown ?? "");
         if (preview) text = sourceMalformedAlerts(text);
-        if (env.runs)
-            text = renderRuns(text, env.runs, undefined, { target: RUN_TARGET[target] }).markdown;
+        let verses = env.verses;
+        if (env.runs) {
+            const marked = renderRuns(text, env.runs, undefined, { target: RUN_TARGET[target] });
+            text = marked.markdown;
+            verses = marked.verses;
+        }
         // A glyph and a cartouche are pictures on every target that draws
         // HTML, so they are written before any stage renders a fragment. The
         // buffer-only preview shows a glyph as the source it was written in
@@ -448,7 +450,7 @@ export function createRenderer(target, options = {}) {
             { resolveRole: env.resolveRole, renderInline },
         );
         text = renderAlerts(
-            renderBlocks(figured.markdown, target, { renderInline }).markdown,
+            renderBlocks(figured.markdown, target, { renderInline, verses }).markdown,
             target,
             {
                 renderInline,