@heroiclands/package-build 25.3.0 → 25.5.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @heroiclands/package-build
 
+## 25.5.0
+
+**Languages and scripts**
+
+- A `.`, `?`, `‼` or `!` placed at the start of a sentence in invented-language roman is reported at that mark.
+
+**Verse**
+
+- A `--- {.canto}` break keeps the stanza break before it and decodes back without adding an extra line ending.
+- Inline `[…]{.verse}` keeps repeated and trailing `//` stanza marks alongside its `/` line marks and footnotes, including in files with CRLF line endings.
+- A literal `\/` in verse stays inside its line and decodes with its backslash intact.
+- A link inside verse is written in the link label's own language, not the verse's.
+- A verse line that looks like a footnote definition or a code fence stays ordinary verse text instead of raising a footnote error or swallowing what follows.
+- A scroll placed after verse renders and reports its own findings correctly, whichever line endings the file uses.
+- A nested shorthand verse div takes the language of the verse around it and shows no stray attribute text on the page.
+- Verse findings inside lists and block quotes point to the verse's opening mark, and leave out the column when the position is unknown.
+- `package-build format` keeps block quotes that contain verse, aligns tables that quote verse, and gives each document one consistent line ending.
+- `package-build markdown` leaves verse untouched while still checking and fixing the prose around it.
+- The authoring guide describes verse scansion and the warnings for names as the build applies them.
+
+**Upgrading**
+
+- Move any `.`, `?`, `‼` or `!` that opens a sentence in invented-language roman to the end of that sentence.
+
+## 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**

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

@@ -131,6 +131,38 @@
     margin: 0;
 }
 
+/* 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.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;
+}
+
 /* Logical stanzas share labels across native and Roman presentations. */
 :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .verse {
     margin: 1.5rem 0;

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,

package/docs/authoring/links-and-markup.md

@@ -260,7 +260,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          |
 
@@ -409,10 +409,10 @@ Foundry renders a secret section; the website renders an expandable spoiler, and
 
 ### Verse
 
-A `verse` fence sets a version of a work, whether poetry or prose. `/` ends a
+A `.verse` div sets a version of a work, whether poetry or prose. `/` ends a
 logical line. Source newlines otherwise join with whitespace, so prose can wrap
 across source lines. A blank line or `//` ends a stanza (a paragraph); a line
-containing only `***` ends a canto (a section). The last line before either
+of `--- {.canto}`, preceded by a blank line, ends a canto (a section). The last line before either
 boundary needs no `/`. A literal slash in text is written `\/`; slashes inside
 Markdown syntax, such as a link destination, remain syntax.
 
@@ -421,33 +421,34 @@ level, and are removed from the display. They may follow `/` on the same source
 line. Leading spaces do not set indentation. A period beginning a continuation
 source line is literal text when the preceding text has no logical line ending.
 Periods inside the first inline span can set indentation; periods in later spans
-are literal. Tabs inside a verse fence are errors.
+are literal. Tabs inside a verse div are errors. The div body is opaque to Markdown block syntax:
+lines beginning `- `, `1. `, `# `, `> ` or four spaces stay verse text.
 
 These two bodies have the same lines and indentation:
 
-````markdown
-```verse {lang=en}
+```markdown
+::: {.verse lang=en}
 To be or not to be,/
 ..that is the question!
-```
+:::
 
-```verse {lang=en}
+::: {.verse lang=en}
 To be or not to be,/..that is the question!
+:::
 ```
-````
 
 Verse is upright by default. English text accepts Markdown emphasis; other
 languages use their declared [script emphasis](#emphasis-in-a-script). Inline
 links, names, language spans and footnotes keep their ordinary meanings.
 The optional `form=` records the author's literary form, `lang=` identifies the
 language, and `font=` selects a face. `enc=` selects an encoding document. An
-optional `#id` addresses the fence. `scan=` checks a declared metre.
+optional `#id` addresses the div. `scan=` checks a declared metre.
 
-A concrete `enc=` draws the original in its script on the left and the same text
+On a div, a concrete `enc=` draws the original in its script on the left and the same text
 in Roman on the right. Write the original once, with no column prefixes. Each
 logical line aligns with its counterpart at full weight; indentation and breaks
 match. `⟦…⟧` codage draws glyphs on the left and remains codage on the right.
-Names, nested language choices and `lang=zxx` gaps retain their scope. A fence
+Names, nested language choices and `lang=zxx` gaps retain their scope. A div
 with no `enc=`, or with `enc=default`, has one Roman column. The content index's
 `runs` relation records the authored original once, in its language and encoding.
 
@@ -467,21 +468,21 @@ 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 verse fence that states `scan=` with the declared name, and `lang=` with a
+A verse div that states `scan=` with the declared name, and `lang=` with a
 language whose `note` names a language note stating
 [`data.sounds.stress`](../reference/format-details.md#a-languages-register-sounds-and-history),
 is counted line by line. A line that cannot have the metre's beats is a warning
 at that line:
 
-````markdown
-```verse {form=epic scan=hexameter lang=vyl}
+```markdown
+::: {.verse form=epic scan=hexameter lang=vyl}
 Thiruthriman sorimamen, ul alathas kedis alatha valmazor,
+:::
 ```
-````
 
 > ``this line has 4 beats (5 with secondary beats); the metre `hexameter` has 6``
 
-`scan=` uses the fence's one language to count beats. If a verse line contains
+`scan=` uses the div's one language to count beats. If a verse line contains
 a run in another language, the build does not scan that run with the fence
 language's stress rules; it reports an error at the line:
 
@@ -512,77 +513,166 @@ Beats are counted this way:
 - The caesura is not written.
 
 `scan=` is refused where it cannot mean anything: a name no `data.metres`
-declares, a fence with no `lang=`, a language without a stress rule. A fence with no `scan=` is not counted. Readers see nothing of the
-count; the fence carries `data-scan` with the metre's name.
+declares, a div with no `lang=`, a language without a stress rule. A div with no `scan=` is not counted. Readers see nothing of the
+count; the div carries `data-scan` with the metre's name.
 
-To number and caption a poem, put a leading numbered caption before the verse fence:
+To number and caption a poem, put a leading numbered caption before the verse div:
 
-````markdown
+```markdown
 :@ A song sung by the harbor watch. {#watch-song}
 
-```verse {form=ballad}
+::: {.verse form=ballad}
 The watch has gone to sea,/
 The lantern marks the shore.
+:::
 ```
-````
 
 This uses the **Poem** counter, so `{{ref "#watch-song"}}` reads **Poem 1**. Use `:` for a caption without a number.
 
 #### Versions and stanza labels
 
-`work=<key>` names a work within the page. Every fence with that key is a version
+`work=<key>` names a work within the page. Every div with that key is a version
 of the same work. Each stanza opens with its automatically counted label: `1`,
 `2`, and so on for a work with no canto break, or `1:1`, `1:2`, `2:1`, and so on
-when the fence contains cantos. Stanza numbering starts at one in each canto.
+when the div contains cantos. Stanza numbering starts at one in each canto.
 The website, Foundry journals and book show the same labels. A paired original
-has one label shared by both presentations. A fence without `work=` has no label.
+has one label shared by both presentations. A div without `work=` has no label.
 
 Versions must have the same number of cantos and the same number of stanzas in
 each canto. Their line counts can differ. A work with only one version is a
 finding. Shape disagreements are findings at the opening lines of the versions,
-naming the canto and the counts. A `***` at the edge of a fence, or beside another
+naming the canto and the counts. A canto break at the edge of a div, or beside another
 canto break with no intervening stanza, is a finding at the break itself.
+Authored `***` inside verse is a finding.
 
 This poem's English version and Sinale original share stanza `1`. The original
 is authored once and displays as script beside Roman:
 
-````markdown
-```verse {form=lay work=asking lang=en}
+```markdown
+::: {.verse form=lay work=asking lang=en}
 A child comes up the hill at night/
 .and leaves a loaf beneath the birch./
 .She does not wait. She does not search/
 the dark for us. We stand in sight.
-```
+:::
 
-```verse {form=lay work=asking lang=sina enc=sinaveldikkoenc}
+::: {.verse form=lay work=asking lang=sina enc=sinaveldikkoenc}
 irtal nysse auldiho nalduho/
 .penvai onsa tarnevinu halpi polpeho/
 .ahi sennevi onsa ahi syltete onsa/
 ehii nalduho setty ehii nelkis yinserseho
+:::
 ```
-````
 
-Prose uses the same fence and omits line-ending marks. Source lines join into
+Prose uses the same div and omits line-ending marks. Source lines join into
 paragraphs. Both versions below have stanzas `1` and `2`; the original's paragraphs
 also appear beside their Roman text:
 
-````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.
+:::
 ```
-````
 
 See [work shape diagnostics](../diagnostics.md#a-worked-case-versions-of-a-work)
 for how findings locate a disagreement.
 
+#### Inline quotations
+
+Quoted verse inside a prose paragraph uses a `.verse` span:
+
+```markdown
+The reply is [to be or not to be/..that is the question!//]{.verse} in the telling.
+```
+
+A quotation uses `/` for line endings and `//` for stanza endings, with the same
+indentation and source-line joining as a div. It takes ordinary span attributes,
+including `lang=` and `enc=`. An unencoded quotation draws Roman text with its
+line and stanza layout. A concrete encoding draws only its script, continuously
+inside the surrounding prose, like any encoded span. Its `/` and `//` reach the
+encoder as verse controls, so a script with verse signs draws them. Consecutive
+stanza endings and a trailing stanza ending each retain their control. Only divs
+have paired script and Roman columns.
+Inline verse has no `work=`, `form=`, `scan=`, stanza labels or canto breaks.
+Directions, speaker labels, links, names and shared note footnotes work inside it.
+
+#### Footnotes in works and encoded spans
+
+Footnote references are valid after a line or word inside verse. Their definitions
+sit below the work, as ordinary note footnotes:
+
+```markdown
+::: {.verse work=walking lang=en}
+He walks the oath road.[^image]
+:::
+
+::: {.verse work=walking lang=vyl enc=vylsemaronenc}
+Lokazor lonak[^oath] zaron.
+:::
+
+[^image]: The road names the obligation as well as the route.
+
+[^oath]: This word carries the oath image in the original.
+```
+
+The English reference renders normally. In the encoded original, the reference
+appears only in the Roman column, beside the word it follows. The script column
+has no marker. Displaying a line twice adds no duplicate number, definition or
+backlink. References never add lines, stanzas or labels and never affect work
+shape.
+
+This rule also applies to every encoded span, whether or not it carries
+`.verse`. A footnote marker is removed before encoding and restored after the
+span's text, outside its script font, as an ordinary reference:
+
+```markdown
+The inscription reads [Lokazor lonak[^word] zaron.]{lang=vyl enc=vylsemaronenc}.
+The reply is [Lokazor lonak[^reply] zaron./Lokamen lonak zaron.//]{.verse lang=vyl enc=vylsemaronenc}.
+
+[^word]: A note about the inscription's wording.
+
+[^reply]: A note about the reply's wording.
+```
+
+Markers never reach an encoder, draw a script glyph or cause an encoding finding.
+The website, Foundry journals and book share the note's footnote numbering and
+definitions.
+
+#### Canto headings
+
+A canto break stands alone after a blank line, with a stanza on both sides.
+Its optional `title` appears as a heading and its optional `#id` is an anchor
+within the work, without starting a separate Foundry journal page:
+
+```markdown
+::: {.verse lang=en}
+The watch crosses the shore.
+
+--- {.canto #choosing title="The Choosing"}
+The captain raises the lamp.
+:::
+```
+
+The heading appears once across an encoded div's presentations. Its title is
+heading text, separate from the letters passed to the encoder. A valid break
+supplies the encoder's standard Roman `***` canto control. `package-build format`
+preserves each verse div and quotation's text, spacing, delimiters and
+attributes while formatting surrounding prose. Quote and list
+containers remain intact, table columns use inline verse's authored width, and
+verse follows the same configured line endings as surrounding prose.
+
+The stanza mark before a canto is retained; whitespace after its encoded
+control adds no extra line mark. An encoded literal `\/` uses a separate
+invisible mark and decodes to `\/`, keeping it distinct from a line ending.
+
 #### Directions and speakers
 
 A `.direction` span identifies an instruction or stage direction; `.speaker`
@@ -591,29 +681,29 @@ Each version writes its own directions and speaker names in its own language.
 Write ordinary case; these classes do not rewrite the text. The classes are
 valid outside verse as well.
 
-````markdown
-```verse {form=rite work=weighing lang=en}
+```markdown
+::: {.verse form=rite work=weighing lang=en}
 Let the household enter. Let the creditor enter./
 [The reader names the year of the reign, the season, the day, and the dead.]{.direction}/
 One person of this household goes down to the West.
-```
+:::
 
-```verse {form=rite work=weighing lang=khel enc=khelqalezuenc}
+::: {.verse form=rite work=weighing lang=khel enc=khelqalezuenc}
 galun garqen. galun zeqatar./
 [zethul nemar …]{.direction}/
 yarul genar lazen elu garqen nizar ez ithnar.
-```
+:::
 
-```verse {form=roll work=thresholds lang=en}
+::: {.verse form=roll work=thresholds lang=en}
 [The Captain]{.speaker}/
 Is the stone here?
-```
+:::
 
-```verse {form=roll work=thresholds lang=tarv enc=tarvsemaronenc}
+::: {.verse form=roll work=thresholds lang=tarv enc=tarvsemaronenc}
 [thrumar]{.speaker}/
 eza goitsa ared ir denon sedon.
+:::
 ```
-````
 
 Their text is encoded normally. The classes themselves are presentation hooks;
 they add no emphasis, encoding controls or stanza boundaries. A direction alone
@@ -645,7 +735,7 @@ A scroll fence is a real code fence, so Markdown never reformats its body.
 - **`rows=`** is the number of characters in a column, and **`cols=`** the
   number of columns in a panel. Each is a whole number above zero, and either
   may be left out.
-- **`lang=`, `font=` and `enc=`** work as they do on a verse fence. See
+- **`lang=`, `font=` and `enc=`** work as they do on a verse div. See
   [marking language, font and encoding](#marking-language-font-and-encoding).
   The text is encoded before layout. Own and composed lexical spellings precede
   rows; a written separator follows the selected definition. An explicit `enc=`
@@ -733,7 +823,7 @@ Use the guillemet pairs instead of English double quotation marks or `<<` and
 Whitespace is every Unicode space-separator (`Zs`) and U+0009 through U+000D.
 A contiguous run of that whitespace is one word separator, written as the
 chosen encoding specifies. A source newline joins as whitespace. In verse,
-`/` ends a logical line, blank lines or `//` end stanzas, and standalone `***`
+`/` ends a logical line, blank lines or `//` end stanzas, and `--- {.canto}` after a blank line
 ends a canto. Visual indentation at a logical line boundary stays layout,
 outside the encoded letters. Write `\/` for a literal slash.
 
@@ -774,7 +864,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`.
 
 ### A language's script
@@ -1162,7 +1252,7 @@ that `lint` reports and that fails nothing:
 | ``a span in non-English language `vyl` holds no bold or italic markup``                                                                                   | Remove the markup, or escape its delimiter characters.                                                                    |
 | `` `vyl` marks emphasis with a word, not a mark; write the word ``                                                                                        | Remove the emphasis marks and write the word the language stresses with.                                                  |
 | ``a div marked `lang=vyl font=semaron-kuriale enc=vylsemaronenc` holds paragraphs and line breaks only, not a list``                                      | Move the list out of the div.                                                                                             |
-| `` `font=` is read on a span, a div or a verse fence, not on a secret block ``                                                                            | Put a marked div inside the secret block.                                                                                 |
+| `` `font=` is read on a span, a div or a verse div, not on a secret block ``                                                                              | Put a marked div inside the secret block.                                                                                 |
 | `` `vly` is read as a BCP 47 tag; did you mean the declared language `vyl`? `` (a warning)                                                                | Write the declared name, or ignore it when the tag is meant.                                                              |
 
 A character the face does not draw is reported once per run, at its first
@@ -1319,7 +1409,7 @@ const lantern = "lit"; // the harbor light
 ```
 ````
 
-A fence named `sql`, `pagelist` or `verse` is not a listing: a query is replaced by its table, and verse is set as a work.
+A fence named `sql` or `pagelist` is a query. Verse uses a `.verse` div or quotation.
 
 ## SQL generated tables
 
@@ -1341,7 +1431,7 @@ A column's heading is its SQL alias, so `AS "Name"` is what a reader sees. A cel
 | `entries`          | Every note, stubs included.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `events`           | One row per event a `lore`, `place` or `affiliation` note writes in `data.events`, with `whenSort` to order them by date.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `names`            | Each authored `.name` span, with its containing NOTE Address, visible text, optional type/subtype and source line/column.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `runs`             | Each span, div and verse fence marked with `lang=`, `font=` or `enc=`, with its containing NOTE Address, its `kind`, `lang` as written, the `tag` it resolves to, the `font` and `enc` it is set with (its own, inherited, or its language's [script](#a-languages-script)), and source line/column. See [marking language, font and encoding](#marking-language-font-and-encoding).                                                                                                                                                                                                                                                   |
+| `runs`             | Each span, div and verse div marked with `lang=`, `font=` or `enc=`, with its containing NOTE Address, its `kind`, `lang` as written, the `tag` it resolves to, the `font` and `enc` it is set with (its own, inherited, or its language's [script](#a-languages-script)), and source line/column. See [marking language, font and encoding](#marking-language-font-and-encoding).                                                                                                                                                                                                                                                     |
 | `natives`          | One row per native form a language note's word states in `native`, with that note as its `language`, the word's place as `word`, its `form`, the entry's place as `native`, and its `enc`, `font` and `"text"`. See [what `enc=` takes](#what-enc-takes).                                                                                                                                                                                                                                                                                                                                                                              |
 | `words`            | One row per word a language note writes in `data.words`, with that note as its `language`, its `position` and what it is built from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `affixes`          | One row per affix a language note writes in `data.affixes`, with that note as its `language`, its `position`, and each key the affix states: `form` (`NULL` on a zero affix), `zero`, `kind`, `given`, `"where"`, `gloss`, `attaches`, `replaces`, `attachesTo`, `lengthens`, `front`, `examples`, `barredAfter` and `tones`, then `written`, the form as a table prints it, `∅` for a zero affix.                                                                                                                                                                                                                                     |

package/docs/commands.md

@@ -1097,7 +1097,7 @@ and `**Rendering**`, and `### Patch Changes` holding `**Miscellaneous**` and
 
 **Verse**
 
-- A verse fence keeps its line breaks.
+- A verse div keeps its line breaks.
 - A stanza break renders as a blank line.
 
 **Rendering**
@@ -2574,6 +2574,12 @@ overrides the rules and the ignore list; an option the file cannot mean is
 refused as `file:line:column: error:` and nothing is linted. See
 [Project setup](project-setup.md) for the accepted keys.
 
+Closed `.verse` div bodies and inline `.verse` quotation contents are excluded
+from Markdown rules and inline lint directives. Their authored bytes stay
+unchanged under `--fix`, including their line endings. The div's opening and
+closing lines and surrounding prose are still checked, with diagnostics at
+their original source locations. Verse markup validation remains active.
+
 **OPTIONS**
 
 | Positional | Type      | Default                               | Description                     |
@@ -2626,7 +2632,7 @@ with visible text, nullable type/subtype and original source line/column.
 Local and dependency SQL schemas expose them through `names`; they travel in
 the metadata artifact.
 
-Metadata includes each own note's spans, divs and verse fences marked with
+Metadata includes each own note's spans, divs and verse divs marked with
 `lang=`, `font=` or `enc=` under `runs`, with the language as written, its
 resolved tag, font, encoding document Address and original source line/column.
 Roman runs use the default encoding and receive no inferred script face.

package/docs/content-format.md

@@ -29,11 +29,11 @@ A nonempty note body creates one system-agnostic Foundry JournalEntry. Content b
 
 Leading `:` captions describe the next supported block; `:@` captions also number it. The optional type accepts `figure`, `table`, `verse`, `code`, `prose`, and `example`. Captions support identifiers, classes and named attributes; unsupported following blocks are errors. See [captions and numbered references](authoring/links-and-markup.md#captions-and-numbered-references).
 
-A `verse` fence sets poetry or prose. `/` ends a logical line; source newlines
-otherwise join. Blank lines or `//` end stanzas, and standalone `***` ends a canto.
+A `.verse` div (`::: {.verse ...}` or `:::verse {...}`) sets poetry or prose. `/` ends a logical line; source newlines
+otherwise join. Blank lines or `//` end stanzas, and a standalone `--- {.canto}` after a blank line ends a canto.
 Leading periods indent a logical line, including after `/` within a source line;
 a period on a joined continuation line is text. `\/` writes a literal slash.
-A concrete `enc=` sets the original once in two presentations, script on the left
+A concrete `enc=` on a div sets the original once in two presentations, script on the left
 and Roman on the right, aligned by logical line at full weight. No `enc=`, or
 `enc=default`, produces one Roman column. Inline names, codage, language gaps and
 footnotes retain their meaning. `work=<key>` groups versions within the page,
@@ -44,13 +44,21 @@ side is a finding at that separator. `.direction` and `.speaker` spans identify
 instructions and speakers inside or outside verse, retain plain presentation
 hooks in HTML and Typst, and change neither encoding nor shape. See
 [verse and worked examples](authoring/links-and-markup.md#verse). Its numbered
-caption uses the **Poem** label. Generic `:::` divs and `[inline spans]{.class}`
+caption uses the **Poem** label. Inline quotations use `[text/..line//]{.verse}` with span presentation
+attributes and no work, form, scan, canto or labels. An encoded quotation is
+script-only and flows inside prose, with `/` and `//` drawn through its encoding;
+an unencoded quotation retains Roman verse layout. Footnotes are excluded from
+encoding: an encoded div shows each reference only beside its Roman word, and
+every encoded span restores its references after the span, outside the script
+font. A reference adds no line or stanza and creates no display duplicate. `--- {.canto #id title="Heading"}`
+adds a visible canto heading and anchor inside its work. Authored `***` is a
+finding. The formatter preserves complete verse divs and spans byte for byte. Generic `:::` divs and `[inline spans]{.class}`
 accept attributes; see [fenced divs](authoring/links-and-markup.md#fenced-divs)
 and [inline spans](authoring/links-and-markup.md#inline-spans).
 
-A code fence with language `scroll` sets text in a script whose script note states `direction: vertical-rl` as columns, top to bottom, read from the right. The lines of a paragraph are joined, and each paragraph starts a fresh column. `rows=N` is the characters in a column and `cols=M` the columns in a panel, each a whole number above zero; `lang=`, `font=` and `enc=` mark the text as on a verse fence, an explicit `enc=` selects an encoding document and its language and font. The site, the preview and Foundry set it with `writing-mode: vertical-rl` in a panel that scrolls sideways from the right; the book draws its panels as images from the face's outlines, each with its roman text as alt text. A scroll fence in a script written in lines is an error. See [scrolls](authoring/links-and-markup.md#scrolls).
+A code fence with language `scroll` sets text in a script whose script note states `direction: vertical-rl` as columns, top to bottom, read from the right. The lines of a paragraph are joined, and each paragraph starts a fresh column. `rows=N` is the characters in a column and `cols=M` the columns in a panel, each a whole number above zero; `lang=`, `font=` and `enc=` mark the text as on a verse div, an explicit `enc=` selects an encoding document and its language and font. The site, the preview and Foundry set it with `writing-mode: vertical-rl` in a panel that scrolls sideways from the right; the book draws its panels as images from the face's outlines, each with its roman text as alt text. A scroll fence in a script written in lines is an error. See [scrolls](authoring/links-and-markup.md#scrolls).
 
-A span, generic div, verse or scroll fence uses `enc=default` unless it selects
+A span, generic div, verse div or scroll fence uses `enc=default` unless it selects
 an encoding document. `enc=` is an Address whose default type is `doc`; the
 document names its language and font, and explicit `lang=` or `font=` values
 must agree. Each encoding tries authored native writings, complete parts and