@heroiclands/package-build 24.0.4 → 24.1.0

package/docs/reference/format-details.md

@@ -1962,32 +1962,45 @@ exit status. Supplied-value errors prevent publication and compilation.
 
 #### Text marked with a language, a font or a map
 
-`lang=`, `font=` and `map=` on a span, a generic div or a verse fence are read
-by the build and never written through as ordinary attributes. Each is
-optional, and a run inside a div or a fence inherits the keys the div or fence
-states, its own keys overriding them. On a named block the three keys are
-errors.
+`lang=` identifies a span, generic div, verse fence or scroll fence's
+language while retaining authored spelling and the surrounding prose font.
+`.nativefont` explicitly requests native presentation and requires `lang=` on
+that same construct; an inherited language does not satisfy the requirement.
+On a named block the language, font and map keys are errors.
 
 - **`lang=`** is a name declared in [`languages`](../configuration.md#languages),
-  and otherwise a BCP 47 tag checked for its form alone. It gives the language
-  tag, and the language's script where its note names one.
-- **`font=`** is a face of the installed `@heroiclands/fonts`, named by its
-  `fonts.json` class without `hl-`, or `mono`, `serif` or `sans`.
-- **`map=`** is the `data.map.name` of a [mapping note](#mapping-notes). The
-  text is rewritten by the map before it is set; without `map=` it is set as
-  typed. With `font=`, the face is one the map lists in `fonts`, and its own
-  rows come first.
-- **`lang=` with `map=`** reads the language's lexicon first, when
-  [`languages.<name>.note`](../configuration.md#languages) names its language
-  note: see [a map reads the dictionary first](#a-map-reads-the-dictionary-first).
-- **`lang=` without `map=` or `font=`** takes the map and the face its
-  language note names in `data.writtenIn`, where the note states one. A run
-  that states `font=` alone takes the language's map only where the map is
-  drawn in that face, and one that states `map=` alone takes the language's
-  face only where that map is drawn in it. A run stating both takes nothing.
-  The default is read after a div or fence has given the run its keys, and is
-  its own language's. See
-  [a language's script](../authoring/links-and-markup.md#a-languages-script).
+  otherwise a BCP 47 tag checked for its form alone. Language identification
+  and its existing validation do not depend on native presentation.
+- **`.nativefont`** selects that language's `data.writtenIn` map and font.
+  A native run needs an effective font; a missing default reports the
+  required `font=` override. The map is optional when the language supplies
+  none, so directly typed script code points can be set without mapping. The
+  build does not guess a font from a map's list of faces.
+- **`font=`** overrides the native font independently. Without `.nativefont`,
+  only `mono`, `serif` and `sans` are permitted.
+- **`map=`** overrides the native map independently and requires `.nativefont`.
+  It names a [mapping note](#mapping-notes). With a configured language note,
+  mapping reads that language's lexicon first; see
+  [a map reads the dictionary first](#a-map-reads-the-dictionary-first).
+
+Unmarked text follows its passage. Each marked child chooses its presentation:
+a language-only child stays Roman, even inside a native passage of that same
+language. A native child requires its own explicit `lang=` and `.nativefont`,
+uses its own language's defaults and applies only its own overrides.
+
+Standalone wikilinks accept the same attributes. `[[address|Name]]{lang=vyl}`
+stays Roman, while `[[address|Name]]{lang=vyl .nativefont}` applies native
+mapping and font to the displayed name alone. Targets, spoilers, `.show`,
+draft annotations and book page cues retain their behavior. Adjacent prose
+belongs in sibling spans; an embedded link inside a longer native run is an error.
+Parallel verse uses `cols=N`, a positive whole number defaulting to one.
+With multiple columns, each content line starts with its column number and
+one or more spaces. Blank-separated logical rows accept nondecreasing
+numbers in `1..cols`, preserving omitted cells and any number of repeated
+readings. The first reading in each column is foreground and all later ones
+in that column are grey; each row resets that choice. `numstep` counts logical
+rows, and `***` separates stanzas. Language and native script choices remain
+on the authored inline runs, independently for every reading.
 
 **A face draws the code points its `fonts.json` entry lists in `codepoints`,
 and whitespace.** After the map, any other character in a run set in a face is
@@ -2007,13 +2020,15 @@ with a real language's tag alone keeps its Markdown. See
 [marking language, font and mapping](../authoring/links-and-markup.md#marking-language-font-and-mapping).
 
 Each own-note metadata record carries `runs` in source order, an empty array
-when the body marks nothing. Every entry has exactly `kind` (`span`, `block`, `scroll` or
+when the body marks nothing. Every entry has `kind` (`span`, `block`, `scroll` or
 `verse`), `lang`, `tag`, `font`, `map`, `line` and `column`: `lang`, `font` and
-`map` as written, its own or inherited, else its language's `data.writtenIn`
-(a scroll fence that names no face takes its map's), `tag` the BCP 47 tag `lang` resolves
+`map` as written, or its language's `data.writtenIn` defaults only for an
+explicit `.nativefont` run, `tag` the BCP 47 tag `lang` resolves
 to, each `null` when absent, and the position of the span's `[`, the div's
-`:::` or the fence's opening. Every value is a string or a number and none is a
-key, so tags that differ only in case are separate values. This is derived
+`:::` or the fence's opening. An opted-in run also carries optional `nativefont: true`; Roman runs omit
+that flag and leave unused script defaults null. The `runs` SQL relation
+retains its existing columns and projects no flag column. Tags differing
+only in case remain separate values. This is derived
 metadata, not frontmatter. The [`runs` relation](#content-tables) flattens
 these entries with their containing NOTE Address.
 
@@ -2167,7 +2182,7 @@ is written word by word:
    plural or a verb ending of an exception word is a different word, and the
    rows spell it.
 
-A run with `map=` and no `lang=`, a `lang=` that is a bare BCP 47 tag, and a
+A native run with an explicit bare BCP 47 `lang=` tag, and a
 declared language with no `note` are spelled by the rows alone. A character the
 face does not draw inside a word written by its native form is an error at the
 word's start:
@@ -2176,7 +2191,9 @@ word's start:
 
 > `` `zaron` is written U+F024F by the lexicon of `vyl` for the map `semaron`, which the font `semaron-kuriale` does not draw ``
 
-**Every word of such a run is a word of the language**, case folded: a
+**Language word-book validation applies to Roman and native runs alike**,
+independently of `.nativefont` or mapping. Every word is a word of the
+language, case folded: a
 `data.words[].form`, a word of a name the language note's own `data.register`
 lists under a `tongue` other than `translation`, or a form one rule derives from a lexicon form —
 the `data.grammar.plural` plural of a noun or its own `plural`, a verb's form
@@ -2383,7 +2400,8 @@ data:
   writtenIn: { map: semaron, font: semaron-kuriale }
 ```
 
-A run marked with the language alone is mapped by `map` and set in `font`, as
+A run explicitly marked with the language and `.nativefont` is mapped by
+`map` and set in `font`, as
 [text marked with a language, a font or a map](#text-marked-with-a-language-a-font-or-a-map)
 describes. A face a language's `writtenIn` names counts as used, so the
 package's fonts are delivered for it.
@@ -3602,8 +3620,8 @@ including on an empty relation:
 | `kind`   | `VARCHAR` | `span`, `block`, `verse` or `scroll`.                                                        |
 | `lang`   | `VARCHAR` | The language as written, its own or inherited, or `NULL`.                                    |
 | `tag`    | `VARCHAR` | The BCP 47 tag `lang` resolves to, or `NULL` when it resolves to none.                       |
-| `font`   | `VARCHAR` | The font as written, its own or inherited, or `NULL`.                                        |
-| `map`    | `VARCHAR` | The map as written, its own or inherited, or `NULL`.                                         |
+| `font`   | `VARCHAR` | The selected font; language defaults apply only to native runs, else `NULL`.                 |
+| `map`    | `VARCHAR` | The selected map; language defaults apply only to native runs, else `NULL`.                  |
 | `line`   | `BIGINT`  | Original 1-based source line of the span's `[`, the div's `:::` or the fence's opening.      |
 | `column` | `BIGINT`  | Original 1-based UTF-16 source column there.                                                 |
 
@@ -6318,7 +6336,7 @@ SoHL sets `system.quantity` to `1` for each compendium item.
 | `affixes[].native[].font`                  | `string`                                                                                                                       | The one face the writing is for, one the map lists; unstated, every face it lists                                                                                                              |
 | `affixes[].native[].text`                  | `string`, required                                                                                                             | The affix as the script writes it                                                                                                                                                              |
 | `emphasis`                                 | `words`, `rubric` or `overline`                                                                                                | `language` only: how the language marks a stressed word, over its script's; `words` makes `*…*` and `**…**` in its runs an error — see [script notes and emphasis](#script-notes-and-emphasis) |
-| `writtenIn`                                | `{ map, font }`                                                                                                                | `language` only: the script the language is written in, which a run marked with the language alone takes — see [script notes and emphasis](#script-notes-and-emphasis)                         |
+| `writtenIn`                                | `{ map, font }`                                                                                                                | `language` only: the script the language is written in, which a run explicitly marked with the language and `.nativefont` takes — see [script notes and emphasis](#script-notes-and-emphasis)  |
 | `writtenIn.map`                            | `string`, required                                                                                                             | The `data.map.name` of a mapping note                                                                                                                                                          |
 | `writtenIn.font`                           | `string`, required                                                                                                             | A face the map lists                                                                                                                                                                           |
 | `script`                                   | `{ fonts, emphasis, strongEmphasis?, direction? }`                                                                             | `script` only: the faces the script is written in, how it marks emphasis and its direction — see [script notes and emphasis](#script-notes-and-emphasis)                                       |

package/docs/reference/note-types.md

@@ -483,7 +483,7 @@ These fields are accepted by every note type. A field's value can still be irrel
 | `data.negation`         | a map — `{ particle, mutation? }`                                                                                                            | How a verb is negated. A language skill note only.                                                                                                                                                                                                                                                                                                                                                    |
 | `data.naming`           | a map — `{ shapes?, edges?, draws?, heldFrom?, nearName? }`                                                                                  | The shapes, edges and sources the language's names keep beyond its words' rules. A language skill note only.                                                                                                                                                                                                                                                                                          |
 | `data.emphasis`         | `words`, `rubric` or `overline`                                                                                                              | How the language marks a stressed word, over its script's `emphasis`: `rubric` or `overline` sets `*…*` and `**…**` so in a run of the language, and `words` marks it with a word, so either is a finding. Only a skill of `subType: language` states it.                                                                                                                                             |
-| `data.writtenIn`        | a map — `{ map, font }`                                                                                                                      | The script the language is written in, as the map and the face a run marked with its name alone takes; a run's own `map=` or `font=` overrides it. Only a skill of `subType: language` states it.                                                                                                                                                                                                     |
+| `data.writtenIn`        | a map — `{ map, font }`                                                                                                                      | The script the language is written in, as the default map and face selected by a run with explicit `lang=` and `.nativefont`; a run's own `map=` or `font=` overrides its half. Only a skill of `subType: language` states it.                                                                                                                                                                        |
 | `data.script`           | a map — `{ fonts, emphasis, strongEmphasis?, direction? }`                                                                                   | A script note's faces, how it marks emphasis and the direction it is written in. Only a skill of `subType: script` states it.                                                                                                                                                                                                                                                                         |
 
 **Inner keys** — a key a field's value does not declare is an error at its own line and column.
@@ -1000,15 +1000,15 @@ 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.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.map`      | a map — `{ name, logographic?, vowels?, fonts, rows }` | A mapping, which text marked `map=` with its `name` is rewritten by before it is set. See [mapping notes](format-details.md#mapping-notes).                                |
-| `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.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.map`      | a map — `{ name, logographic?, vowels?, fonts, rows }` | A mapping, which native text marked with `lang=`, `.nativefont` and its `map=` name is rewritten by before it is set. See [mapping notes](format-details.md#mapping-notes). |
+| `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).  |
 
 **Inner keys** — a key a field's value does not declare is an error at its own line and column.
 

package/docs/reference/theme-pages.md

@@ -340,10 +340,18 @@ keys reach the block as written, `lang` as its language and the rest as
 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 verse line is one `.verse-row`:
+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">
+<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
@@ -351,6 +359,7 @@ carries `.verse-columns`, and each verse line is one `.verse-row`:
         ><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"
@@ -363,10 +372,10 @@ carries `.verse-columns`, and each verse line is one `.verse-row`:
 </div>
 ```
 
-A numbered verse in columns gives every row a `.verse-number`, empty on the
-lines it does not number, so the columns stay aligned. A part whose text runs
-right to left carries `dir="rtl"`. Each row is its own grid, so a long line
-keeps its partner level with it. Below a block width of `32rem` a row stacks
+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.
 
@@ -377,10 +386,10 @@ stacks as well. The Foundry stylesheet draws the same.
 | `.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 verse line: its number and its columns                    |
-| `.verse-column`    | one column, its entries stacked                               |
+| `.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 entry after a column's first, muted                     |
+| `.verse-secondary` | every reading after a column's first in that row, grey        |
 
 ## Emphasis in a script
 

package/engine/content-render.mjs

@@ -77,7 +77,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 { inlineVerse, verseStanzas } from "./content-verse.mjs";
+import { hasColumns, inlineVerse, scanVerse, verseGroups, verseStanzas } from "./content-verse.mjs";
 import { replaceOutsideCode } from "./code-fences.mjs";
 import { dictionaryEntryPlugin } from "./dictionary-layout.mjs";
 import { headingAttributesPlugin, headingIdsPlugin } from "./heading-attributes.mjs";
@@ -129,11 +129,32 @@ function verseInlinePlugin(md) {
             if (token.type !== "fence" || !/^verse(?:\s|$)/.test(token.info?.trim() || ""))
                 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 {
+                        ...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 };
+                    return { children, level, stanzaBreak: /^\*{3}$/.test(text) };
                 }),
             );
         }