@heroiclands/package-build 25.3.0 → 25.4.0

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

@@ -72,9 +72,15 @@ keys makes a separate presentation choice. `enc=default` inside an encoded
 parent keeps the inherited language but does not inherit its inferred script
 face. An explicitly authored font remains a font choice.
 
+Footnotes are not letters of the tongue. A defined `[^key]` in any encoded span
+is removed before encoding and restored after the span, outside the script font.
+In an encoded verse div, a reference appears only in the Roman column, beside
+its authored word, with no duplicate number, definition or backlink. Footnotes
+never change verse shape. See [footnotes in works and encoded spans](../authoring/links-and-markup.md#footnotes-in-works-and-encoded-spans).
+
 A name's braces use the shared name controls. Resolved references encode only
 their visible labels, retaining URLs and presentation cues. These keys apply
-to spans, divs, verse fences and scroll fences. A scroll's selected font must
+to spans, divs and scroll fences. A scroll's selected font must
 belong to a script whose note declares `direction: vertical-rl`.
 
 ## Roman source and literal characters
@@ -106,8 +112,8 @@ 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 join as whitespace. In a verse fence, `/` ends a logical line,
-blank lines or `//` end stanzas, and standalone `***` ends a canto. A literal
+Newlines join as whitespace. In a verse div, `/` ends a logical line,
+blank lines or `//` end stanzas, and `--- {.canto}` after a blank line 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.
 
@@ -485,52 +491,73 @@ The keys are checked where they sit:
 
 ## Verse
 
-### A poem in a verse fence
+### A poem in a verse div
 
-A poem is written in a `verse` fence, whose lines and stanzas the build
-preserves. The keys of the previous sections go on the fence. Prettier leaves
-the contents of a fence byte for byte, which is why a poem is a fence and not
-paragraphs: indentation, line breaks and spans survive formatting untouched.
+A `.verse` div holds inline Markdown and explicit verse structure. It is opaque
+to lists, headings, quotes and code-block syntax. Its source newlines join unless
+`/` ends a logical line. The authoring formatter preserves the complete div and
+its attributes byte for byte, and also preserves inline `.verse` quotations.
 
-````markdown
-```verse {lang=vyl font=semaron-kuriale enc=vylsemaronenc}
+```markdown
+::: {.verse lang=vyl font=semaron-kuriale enc=vylsemaronenc}
 Lokazor lonak./
 .lokamen zaron.
+:::
 ```
-````
+
+Quoted verse is a span within prose, such as
+`[Lokazor lonak zaron./..Lokamen lonak zaron.//]{.verse lang=vyl}`.
+A concrete `enc=` sets a quotation in script only, continuously in the prose.
+Its `/` and `//` become the encoding's verse marks; only a div has paired script
+and Roman columns. An unencoded quotation keeps Roman line and stanza layout.
+Quotations take no `work=`, `form=`, `scan=`, labels or canto breaks.
+A div's canto separator can carry a heading and an anchor:
+
+```markdown
+::: {.verse lang=en}
+The watch arrives.
+
+--- {.canto #choosing title="The Choosing"}
+The captain answers.
+:::
+```
+
+The title is shown once as heading text; the encoder receives its Roman `***`
+canto control. Authored `***` inside verse is a finding. The canto stays within
+the work and does not open a separate journal page.
 
 ### Versions of a work
 
 `form=epic` records the author's literary form without inferring layout or metre.
 
-A `verse` fence with a concrete `enc=` sets one original in its script on the
+A `.verse` div 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
+of `--- {.canto}`, preceded by a blank line, ends a canto. Leading periods at a logical line boundary indent
 that line. Use `\/` for a literal slash.
 
-````markdown
-```verse {work=walking lang=en}
+```markdown
+::: {.verse work=walking lang=en}
 He walks the oath road.
 
 I walk the oath road.
-```
+:::
 
-```verse {work=walking lang=vyl enc=vylsemaronenc}
+::: {.verse work=walking lang=vyl enc=vylsemaronenc}
 Lokazor lonak zaron.
 
 Lokamen lonak zaron.
+:::
 ```
-````
 
 `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.
+English div 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.
+content index records the original once with its div 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.
@@ -549,15 +576,15 @@ data:
 `name` is lowercase letters, digits and `-`, unique in the package; `beats` is
 the beats of one line, a whole number above zero; `kind` is `accentual`, the
 only kind: a beat falls on a stressed syllable and the length of a syllable is
-not counted. A fence that states `scan=` with the declared name and a `lang=`
+not counted. A div that states `scan=` with the declared name and a `lang=`
 whose language note states `data.sounds.stress` is counted line by line:
 
-````markdown
-```verse {lang=vyl scan=trimeter}
+```markdown
+::: {.verse lang=vyl scan=trimeter}
 Lokazor lonak zaron./
 Lokamen lonak zaron.
+:::
 ```
-````
 
 **The stress rule** is `data.sounds.stress`, `{ two, longer, mark }`. `two`
 (`first` or `last`) places the stress in a word of two syllables; `longer`
@@ -587,14 +614,14 @@ the second beats and, in brackets, with all of them:
 
 > ``this line has 4 beats (5 with secondary beats); the metre `hexameter` has 6``
 
-**The check is author-side.** Readers see nothing of it: the rendered fence
-carries `data-metre` with the metre's name and nothing a reader sees. A fence
+**The check is author-side.** Readers see nothing of it: the rendered div
+carries `data-metre` with the metre's name and nothing a reader sees. A div
 without `scan=` is not counted. `scan=` is refused where it cannot mean
 anything, each an error:
 
 > `` `hexamter` is not a declared metre: `scan=` names the `name` of a `data.metres` entry of a `doc` note; did you mean `hexameter`? ``
 
-> `` `scan=` counts beats by a language's stress rule: the fence needs a `lang=` ``
+> `` `scan=` counts beats by a language's stress rule: the div needs a `lang=` ``
 
 > ``the language `vyl` states no `data.sounds.stress`, which `scan=` counts beats by``
 
@@ -1144,11 +1171,11 @@ capital `L` of the rows, `zaron` is the exception's long vowel, and each period
 writes the script's pause point.
 
 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.
+once and appears beside its Roman presentation; a separate div checks metre.
 
 **`assets/content/Lore/Walking.md`**
 
-````markdown
+```markdown
 ---
 shortcode: walking
 name: { full: The Walking }
@@ -1159,23 +1186,23 @@ 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 {work=walking lang=en}
+::: {.verse work=walking lang=en}
 He walks the oath road.
 
 I walk the oath road.
-```
+:::
 
-```verse {work=walking lang=vyl enc=vylsemaronenc}
+::: {.verse work=walking lang=vyl enc=vylsemaronenc}
 Lokazor lonak zaron.
 
 Lokamen lonak zaron.
-```
+:::
 
-```verse {lang=vyl scan=trimeter}
+::: {.verse lang=vyl scan=trimeter}
 Lokazor lonak zaron./
 Lokamen lonak zaron.
+:::
 ```
-````
 
 A script note gives Semaron its emphasis convention, and a run with double stars then
 sets them in red:

package/docs/reference/format-details.md

@@ -2107,7 +2107,7 @@ face. An explicitly authored font remains a font choice.
 
 A name's braces use the shared name controls. Resolved references encode only
 their visible labels, retaining URLs and presentation cues. These keys apply
-to spans, divs, verse fences and scroll fences. A scroll's selected font must
+to spans, divs and scroll fences. A scroll's selected font must
 belong to a script whose note declares `direction: vertical-rl`.
 
 #### Encodings
@@ -2273,7 +2273,7 @@ keeps a lexicon to its exceptions.
 
 #### Metres
 
-A verse fence that states `scan=` is counted against a metre declared in a
+A verse div that states `scan=` is counted against a metre declared in a
 `doc` note's `data.metres`, each entry `{ name, beats, kind }`. `name` is
 lowercase letters, digits and `-`, unique in the package, and a name declared
 twice is an error at the second. `beats` is a whole number above zero. `kind` is
@@ -3592,7 +3592,7 @@ metadata supplies `names` in that package's SQL schema. Public queries exclude
 GM-only owners; all/native contexts retain them. Only authored occurrences
 contribute rows, so generated queries and sections add no further names.
 
-**`runs`** is one row per span, generic div and verse fence an authored note
+**`runs`** is one row per span, generic div and verse div an authored note
 body marks with `lang=`, `font=` or `enc=`. Each row has these columns,
 including on an empty relation:
 
@@ -4033,7 +4033,7 @@ The caption attaches to exactly the next supported block:
 | Markdown table                       | `table`       | Table          |
 | Image, Markdown or wikilink          | `figure`      | Figure         |
 | SQL fence, including backtick SQL    | `table`       | Table          |
-| Verse fence                          | `verse`       | Poem           |
+| Verse div                            | `verse`       | Poem           |
 | Any other code fence                 | `code`        | Code           |
 | Paragraph, quote block or fenced div | `prose`       | Prose          |
 
@@ -6855,7 +6855,7 @@ closed list where its values are words:
   end, `antepenultimate`, `penultimate` or `final`; `mark` is the diacritic, `acute`,
   `grave` or `circumflex`, that marks a stress the rule would not choose and
   moves it to the syllable it sits on. Syllables are vowel groups, a pair listed
-  in `syllables.vowelPairs` counting as one. A verse fence's `scan=` counts
+  in `syllables.vowelPairs` counting as one. A verse div's `scan=` counts
   beats by this rule; see [metres](#metres).
 - `finals`: the syllable finals, each with what it sounds like and, as `ipa`,
   its sound in the International Phonetic Alphabet, for a language whose
@@ -8274,7 +8274,7 @@ Content prepared to be played — a situation with its cast, places, and possibl
 | `concepts[].id`                                   | string                                                                | Required: lowercase letters, digits and `-`, unique in the package                                                                             |
 | `concepts[].gloss`                                | string                                                                | Required: what the concept means, in brief                                                                                                     |
 | `concepts[].group`                                | string                                                                | Required: the group the report lists the concept under                                                                                         |
-| `metres`                                          | `{ name, beats, kind }[]`                                             | The metres a verse fence's `scan=` names; any subType. See [metres](#metres)                                                                   |
+| `metres`                                          | `{ name, beats, kind }[]`                                             | The metres a verse div's `scan=` names; any subType. See [metres](#metres)                                                                     |
 | `metres[].name`                                   | string                                                                | Required: what `scan=` names it by, lowercase letters, digits and `-`, unique in the package                                                   |
 | `metres[].beats`                                  | `integer`, required                                                   | The beats of one line, above zero                                                                                                              |
 | `metres[].kind`                                   | `accentual`                                                           | Required: how the beats are counted                                                                                                            |

package/docs/reference/note-types.md

@@ -997,20 +997,20 @@ Lore records in-world knowledge. A `culture` describes a people; a `custom` desc
 
 **Subtypes:** `rules`, `userguide`, `reference`, `howto`, `concept`, `settingguide`, `post`.
 
-| Field           | Shape                                | Meaning                                                                                                                                                                    |
-| --------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `data.language` | a configured language alias          | The configured language alias an encoding document writes.                                                                                                                 |
-| `data.font`     | an installed font slug               | The encoding's installed font, which supplies all glyph codes.                                                                                                             |
-| `data.accepts`  | a list of characters or ranges       | Accepted Roman letters and additions to standard punctuation.                                                                                                              |
-| `data.vowels`   | a string                             | The letters a contextual vowel match reads as vowels.                                                                                                                      |
-| `data.mappings` | Roman strings to glyph codes         | Roman source strings mapped to codes published by the selected font.                                                                                                       |
-| `data.rules`    | the closed encoding rules vocabulary | Executable normalization, matching, case, stress, vowel groups, accents and contextual mappings.                                                                           |
-| `data.concepts` | list of `{ id, gloss, group }`       | The concepts of a core vocabulary, in the order the report lists them. See [the core vocabulary](format-details.md#the-core-vocabulary).                                   |
-| `data.date`     | string                               | The day a post was published, as `YYYY-MM-DD`. Required on a `post`; no other subType states it. Posts are listed and fed newest first by it.                              |
-| `data.author`   | string                               | Who wrote a post, as the byline prints them. A post that names none carries the site's byline, the first entry of `authors`; no other subType states it.                   |
-| `data.culture`  | an Address                           | The culture a setting guide introduces, as a culture lore note. Required on `settingguide`; no other subType states it.                                                    |
-| `data.sounds`   | a map — `{ letters?, marks? }`       | A spelling guide's letters and the marks written on them, for every tongue of the setting: each letter row's `tongue` names the language notes that write it.              |
-| `data.metres`   | list of `{ name, beats, kind }`      | The metres a verse fence's `scan=` names. A fence that states one is warned at each line that cannot have its beats. See [metres](../authoring/links-and-markup.md#metre). |
+| Field           | Shape                                | Meaning                                                                                                                                                                |
+| --------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data.language` | a configured language alias          | The configured language alias an encoding document writes.                                                                                                             |
+| `data.font`     | an installed font slug               | The encoding's installed font, which supplies all glyph codes.                                                                                                         |
+| `data.accepts`  | a list of characters or ranges       | Accepted Roman letters and additions to standard punctuation.                                                                                                          |
+| `data.vowels`   | a string                             | The letters a contextual vowel match reads as vowels.                                                                                                                  |
+| `data.mappings` | Roman strings to glyph codes         | Roman source strings mapped to codes published by the selected font.                                                                                                   |
+| `data.rules`    | the closed encoding rules vocabulary | Executable normalization, matching, case, stress, vowel groups, accents and contextual mappings.                                                                       |
+| `data.concepts` | list of `{ id, gloss, group }`       | The concepts of a core vocabulary, in the order the report lists them. See [the core vocabulary](format-details.md#the-core-vocabulary).                               |
+| `data.date`     | string                               | The day a post was published, as `YYYY-MM-DD`. Required on a `post`; no other subType states it. Posts are listed and fed newest first by it.                          |
+| `data.author`   | string                               | Who wrote a post, as the byline prints them. A post that names none carries the site's byline, the first entry of `authors`; no other subType states it.               |
+| `data.culture`  | an Address                           | The culture a setting guide introduces, as a culture lore note. Required on `settingguide`; no other subType states it.                                                |
+| `data.sounds`   | a map — `{ letters?, marks? }`       | A spelling guide's letters and the marks written on them, for every tongue of the setting: each letter row's `tongue` names the language notes that write it.          |
+| `data.metres`   | list of `{ name, beats, kind }`      | The metres a verse div's `scan=` names. A div that states one is warned at each line that cannot have its beats. See [metres](../authoring/links-and-markup.md#metre). |
 
 **Inner keys** — a key a field's value does not declare is an error at its own line and column.
 
@@ -1065,7 +1065,7 @@ Lore records in-world knowledge. A `culture` describes a people; a `custom` desc
 | `data.sounds.marks[].letters`                          | a list of letters                                                     | yes      | The letters that carry it.                                                                                                                                               |
 | `data.sounds.marks[].kind`                             | one of stress, length, apart                                          | yes      | What the mark says of its letter.                                                                                                                                        |
 | `data.sounds.marks[].limit`                            | one of one, any                                                       | yes      | How many a word may carry: `one` at most, or `any`.                                                                                                                      |
-| `data.metres[].name`                                   | string                                                                | yes      | What a verse fence's `scan=` names the metre by: lowercase letters, digits and `-`, unique in the package.                                                               |
+| `data.metres[].name`                                   | string                                                                | yes      | What a verse div's `scan=` names the metre by: lowercase letters, digits and `-`, unique in the package.                                                                 |
 | `data.metres[].beats`                                  | a whole number above zero                                             | yes      | The beats of one line.                                                                                                                                                   |
 | `data.metres[].kind`                                   | one of accentual                                                      | yes      | How the beats are counted: `accentual`, one beat for each stressed syllable the language's stress rule and the beat convention give.                                     |
 

package/docs/reference/theme-pages.md

@@ -333,32 +333,40 @@ Caption classes are unrestricted. The built-in `border` class draws the block as
 
 ## Verse
 
-A `verse` fence reaches the page as `.verse`, with one `.verse-stanza` per
+A `.verse` div 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
+separates cantos. A work-labelled div 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
+A concrete div 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
+the native presentation before the Roman presentation. An unencoded div 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       |
+An unencoded quotation uses `.verse-inline` with inline-safe layout wrappers.
+An encoded quotation is a script-only span flowing within prose, with no verse
+grid or Roman companion. Its verse signs come from the encoding. Footnote
+references follow encoded spans outside their script font. In a paired div,
+references occur only in `.verse-roman`, beside their authored words.
+
+| Class                  | Meaning                                           |
+| ---------------------- | ------------------------------------------------- |
+| `.verse`               | A block or unencoded quoted verse                 |
+| `.verse-inline`        | A quotation with inline-safe span wrappers        |
+| `.verse-canto-heading` | A canto title and optional anchor within the 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`

package/engine/anchors.mjs

@@ -124,6 +124,20 @@ export function collectAnchors(body, bodyLine = 1, resolveRole, syntax) {
             });
     }
     for (const poem of scanVerse(body).blocks) {
+        for (const group of poem.model.groups)
+            if (group.cantoBreak && group.id)
+                anchors.push({
+                    slug: slugify(group.id),
+                    name: group.title || group.id,
+                    level: 0,
+                    line:
+                        bodyLine +
+                        String(body)
+                            .slice(0, poem.bodyStart + group.from)
+                            .split("\n").length -
+                        1,
+                    kind: "prose",
+                });
         if (poem.id)
             anchors.push({
                 slug: slugify(poem.id),

package/engine/code-fences.mjs

@@ -46,6 +46,7 @@
  * prevent.
  */
 
+import { verseRegions } from "./verse-regions.mjs";
 import { parseExtensionAttributes } from "./extension-attributes.mjs";
 
 /** A fence line, capturing its indent, its marker, and its info string. */
@@ -104,11 +105,10 @@ function column(space) {
  * @param {object} [options]
  * @param {boolean} [options.spans=true] - Include inline code spans. Set false
  *   to consider only block-level code.
- * @param {boolean} [options.verseAsProse=true] - Treat verse bodies as inline prose.
  * @returns {Array<{start: number, end: number}>} Non-overlapping regions, in
  *   source order. `end` is exclusive.
  */
-export function codeRegions(markdown, { spans = true, verseAsProse = true } = {}) {
+export function codeRegions(markdown, { spans = true } = {}) {
     const src = String(markdown ?? "");
     if (!src) return [];
     const lines = src.split("\n");
@@ -127,6 +127,16 @@ export function codeRegions(markdown, { spans = true, verseAsProse = true } = {}
     });
 
     const regions = [];
+    const verses = verseRegions(src);
+    const verseLines = new Set(
+        verses.flatMap((region) =>
+            Array.from({ length: region.end - region.start + 1 }, (_, i) => region.start + i),
+        ),
+    );
+    for (const verse of verses) {
+        regions.push(through(verse.start, verse.start));
+        if (verse.closed) regions.push(through(verse.end, verse.end));
+    }
     // The content column of the innermost open list item: an indented block
     // has to clear *that*, not column zero, or every list continuation would
     // read as code.
@@ -137,6 +147,7 @@ export function codeRegions(markdown, { spans = true, verseAsProse = true } = {}
 
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
+        if (verseLines.has(i)) continue;
 
         const fence = FENCE_LINE.exec(line);
         if (fence) {
@@ -145,10 +156,7 @@ export function codeRegions(markdown, { spans = true, verseAsProse = true } = {}
             let close = i + 1;
             while (close < lines.length && !closer.test(lines[close])) close++;
             // An unclosed fence runs to the end of the document.
-            if (verseAsProse && /^verse(?:\s|$)/.test(fence[3])) {
-                regions.push(through(i, i));
-                if (close < lines.length) regions.push(through(close, close));
-            } else regions.push(through(i, Math.min(close, lines.length - 1)));
+            regions.push(through(i, Math.min(close, lines.length - 1)));
             i = close;
             afterBlank = false;
             continue;
@@ -186,6 +194,7 @@ export function codeRegions(markdown, { spans = true, verseAsProse = true } = {}
         afterBlank = false;
     }
 
+    regions.sort((a, b) => a.start - b.start);
     if (spans) regions.push(...codeSpans(src, regions));
     regions.sort((a, b) => a.start - b.start);
     return regions;

package/engine/content-blocks.mjs

@@ -111,7 +111,9 @@ export function scanBlocks(source) {
     for (const token of blockTokens(source)) {
         if (
             !token.map ||
-            !["blockquote_open", "fence", "code_block", "html_block"].includes(token.type)
+            !["blockquote_open", "fence", "code_block", "html_block", "verse_div"].includes(
+                token.type,
+            )
         )
             continue;
         for (let line = token.map[0]; line < token.map[1]; line++) literalLines.add(line);
@@ -277,7 +279,7 @@ export function renderBlocks(source, target, { renderInline, verses } = {}) {
         // at every depth, never a rendered fragment.
         const held =
             BLOCK_CONTAINERS.includes(block.name) ?
-                renderBlocks(block.body, target, { renderInline }).markdown
+                renderBlocks(block.body, target, { renderInline, verses }).markdown
             :   block.body;
         if (block.name === "div") {
             output.push("", `<div ${attributes}>`, "", held, "", "</div>", "");

package/engine/content-figures.mjs

@@ -18,6 +18,7 @@ import MarkdownIt from "markdown-it";
 import footnotePlugin from "markdown-it-footnote";
 import deflistPlugin from "markdown-it-deflist";
 
+import { verseRegions } from "./verse-regions.mjs";
 import { slugify } from "./content-slug.mjs";
 import { parseExtensionAttributes, refusedAttributes } from "./extension-attributes.mjs";
 import { HEADING_LINE, splitHeadingAttributes } from "./heading-attributes.mjs";
@@ -184,9 +185,20 @@ export function scanFigures(source, { resolveRole = () => undefined } = {}) {
         errors = [],
         ids = new Set();
     const counts = {};
+    const verse = verseRegions(String(source ?? ""));
+    const verseStarts = new Map(verse.map((region) => [region.start, region]));
+    const verseLines = new Set(
+        verse.flatMap((region) =>
+            Array.from(
+                { length: region.end - region.start + 1 },
+                (_, index) => region.start + index,
+            ),
+        ),
+    );
     let codeFence = null;
     const fault = (line, message) => errors.push({ line: line + 1, column: 1, message });
     for (let i = 0; i < lines.length; i++) {
+        if (verseLines.has(i)) continue;
         const fence = FENCE.exec(lines[i]);
         if (codeFence) {
             if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length)
@@ -233,7 +245,11 @@ export function scanFigures(source, { resolveRole = () => undefined } = {}) {
         let bodyEnd;
         const firstLine = lines[bodyStart];
         let kind;
-        if (/^ {0,3}:::(?:[ \t]+\{.*\})?[ \t]*$/.test(firstLine)) {
+        if (verseStarts.has(bodyStart)) {
+            const region = verseStarts.get(bodyStart);
+            bodyEnd = region.end + 1;
+            kind = "poem";
+        } else if (/^ {0,3}:::(?:[ \t]+\{.*\})?[ \t]*$/.test(firstLine)) {
             let depth = 1,
                 literal = null;
             bodyEnd = bodyStart + 1;
@@ -305,10 +321,7 @@ export function scanFigures(source, { resolveRole = () => undefined } = {}) {
                 fault(bodyStart, "this block cannot be captioned");
                 continue;
             }
-            kind =
-                first.type === "fence" && /^verse(?:\s|$)/.test(first.info) ?
-                    "poem"
-                :   figureKind(first, contents.trim(), resolveRole);
+            kind = figureKind(first, contents.trim(), resolveRole);
         }
         if (explicit) kind = explicit === "verse" ? "poem" : explicit;
         const id = attributes.id;
@@ -338,6 +351,7 @@ export function scanFigures(source, { resolveRole = () => undefined } = {}) {
     }
     let literal = null;
     for (let at = 0; at < lines.length; at++) {
+        if (verseLines.has(at)) continue;
         const fence = FENCE.exec(lines[at]);
         if (literal) {
             if (fence && fence[1][0] === literal[0] && fence[1].length >= literal.length)

package/engine/content-footnotes.mjs

@@ -29,7 +29,8 @@
  * @module
  */
 
-import { matchAllOutsideCode } from "./code-fences.mjs";
+import { inlineSyntaxRanges, verseRegions } from "./verse-regions.mjs";
+import { codeRegions, matchAllOutsideCode } from "./code-fences.mjs";
 
 /**
  * Where a character offset in `source` falls, as a 1-based line and column.
@@ -52,9 +53,15 @@ function lineColumn(source, offset) {
 export function separateFootnotes(source) {
     const lines = String(source ?? "").split("\n");
     const body = [...lines];
+    const verseLines = new Set(
+        verseRegions(String(source ?? "")).flatMap((region) =>
+            Array.from({ length: region.end - region.start + 1 }, (_, i) => region.start + i),
+        ),
+    );
     const definitions = [];
     let fence = null;
     for (let i = 0; i < lines.length; i++) {
+        if (verseLines.has(i)) continue;
         const marker = /^ {0,3}(`{3,}|~{3,})/.exec(lines[i]);
         if (fence) {
             if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length)
@@ -240,3 +247,55 @@ export function footnoteFindings(source) {
         (a, b) => a.line - b.line || a.column - b.column,
     );
 }
+
+/**
+ * Labels defined at the top level of this note.
+ * @param {string} source - Complete authored note Markdown.
+ * @returns {Set<string>} Same-note footnote labels.
+ */
+export function footnoteLabels(source) {
+    if (!source.includes("[^")) return new Set();
+    return new Set(
+        [...separateFootnotes(source).definitions.matchAll(/^\[\^([^\]\s]+)\]:/gm)].map(
+            (match) => match[1],
+        ),
+    );
+}
+
+/**
+ * Actual defined references, excluding literal code, escapes and metadata.
+ * @param {string} source - Full note or raw inline fragment.
+ * @param {object} [options] - Definition context and source grammar.
+ * @param {ReadonlySet<string>} [options.definitions] - Same-note labels; derived from source when omitted.
+ * @param {boolean} [options.inline] - Treat all source as inline verse/prose.
+ * @returns {Array<{from:number,to:number,key:string,text:string}>} Original UTF-16 source ranges.
+ */
+export function footnoteReferences(
+    source,
+    { definitions = footnoteLabels(source), inline = false } = {},
+) {
+    if (!definitions.size || !source.includes("[^")) return [];
+    const protectedRanges = inlineSyntaxRanges(source).filter(
+        ([from]) => source[from] !== "{" || source[from - 1] === "]",
+    );
+    const code = inline ? [] : codeRegions(source);
+    return [...source.matchAll(/\[\^([^\]\s]+)\]/g)].flatMap((match) => {
+        const from = match.index,
+            to = from + match[0].length;
+        const escapes = /\\+$/.exec(source.slice(0, from))?.[0].length ?? 0;
+        if (
+            !definitions.has(match[1]) ||
+            escapes % 2 ||
+            protectedRanges.some(([first, past]) => from >= first && from < past) ||
+            code.some((range) => from >= range.start && from < range.end)
+        )
+            return [];
+        if (
+            !inline &&
+            source[to] === ":" &&
+            /^[ \t]*$/.test(source.slice(source.lastIndexOf("\n", from - 1) + 1, from))
+        )
+            return [];
+        return [{ from, to, key: match[1], text: match[0] }];
+    });
+}

package/engine/content-index.mjs

@@ -1568,7 +1568,7 @@ function dynamicPublicationBody(body) {
     const source = String(body ?? "");
     return (
         [...matchAllOutsideCode(source, EXPRESSION)].length > 0 ||
-        codeRegions(source, { spans: false, verseAsProse: false }).some(({ start, end }) => {
+        codeRegions(source, { spans: false }).some(({ start, end }) => {
             const opener = FENCE_LINE.exec(source.slice(start, end).split("\n", 1)[0]);
             const language = opener && parseHeaderArgs(opener[3]).language;
             return language === "sql" || language === PAGE_LIST_LANGUAGE;