@heroiclands/package-build 25.5.4 → 25.5.5

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @heroiclands/package-build
 
+## 25.5.5
+
+**Languages and scripts**
+
+- Ch'alish P'ilam Ceremonial text passes character checks and is recognized as native script alongside Common.
+- Core vocabulary reports name the languages left unmeasured, including when no language opts into coverage.
+- Generated NPC names capitalize their name words for English prose while keeping connecting words as written.
+- Distinct source names keep their authored spelling under the culture's language code, except when the selected pattern draws English words.
+- The language reference explains that Roman inventories list language additions and refuse shared punctuation and whitespace in the list.
+- A language can supply one list of given names for everyone; NPC generation draws from it for every gender.
+
+**Verse**
+
+- Metre checks allow multi-syllable function words to go unstressed, so lines can scan without placing a beat on every particle or pronoun.
+- Verse inside blockquotes and nested lists keeps its line breaks, stanza boundaries and indentation, with findings located at the authored text.
+- Verse metre checks count a linked name's visible words without adding beats from its address.
+
+**Rendering and sites**
+
+- A book can break the page at a chosen point with `--- {.page-break}`.
+- Website previews start immediately, keep the last successful pages available during rebuilds, and report progress while building pages and search.
+
 ## 25.5.4
 
 **Builds and commands**

package/README.md

@@ -53,6 +53,13 @@ repository’s setup installs the two canonical shell hooks; it installs no
 pre-push hook. Run `npm test` and the other checks directly, or use
 `package-build ci` for a container run.
 
+The repository's `vitest.config.ts` limits both `npm test` and `npm run
+test:watch` to two workers, with Vitest's isolated fork pool. CI runs the same
+`npm test` command. This bounds concurrent test files on the shared runner,
+including files that start CLI subprocesses, load SQL databases, or emit
+TypeScript declarations. Keep this bound when reproducing CI failures locally;
+a percentage of the host's CPUs does not reserve resources for other jobs.
+
 ## Documentation
 
 The documentation lives in the Markdown files in this repository. Start with [the documentation home](docs/index.md). This toolchain does not build its own site or book.

package/bin/content-commands.mjs

@@ -1289,7 +1289,12 @@ function lintCommand() {
                 // Text marked with a language, a font or a map, checked against
                 // the languages this package declares, the faces it installed
                 // and the maps its notes declare.
-                const runs = runContext(config, records);
+                const runs = runContext(config, records, {
+                    referenceName: (target) => {
+                        const hit = index.resolveAddress(target) ?? index.manifestHit(target);
+                        return hit?.fm?.name?.full ?? hit?.name;
+                    },
+                });
                 const loaderLocations = new Set(
                     (runs.encodingFindings ?? []).map((one) =>
                         JSON.stringify([one.file, one.line, one.column, one.message]),
@@ -2346,7 +2351,11 @@ function siteBuildCommand() {
                 const config = argv[CONTENT_CONFIG] ?? loadPackConfig();
                 const root = path.resolve(config.rootDir, argv.out ?? DEPLOY_ROOT);
                 const out = siteDirectory(config, root);
-                const result = await buildPackageSite({ config, out });
+                const result = await buildPackageSite({
+                    config,
+                    out,
+                    progress: (message) => log.info(message),
+                });
                 // A note in error is written as its page shows it, and the
                 // build fails without indexing a site that is not to be
                 // deployed.
@@ -2374,6 +2383,7 @@ function siteBuildCommand() {
                     base: siteBase(config),
                     out: root,
                     search: config.site.search,
+                    progress: (message) => log.info(message),
                 });
                 if (search) {
                     log.info(
@@ -2429,8 +2439,10 @@ function siteServeCommand() {
                     host: argv.host,
                     port: argv.port,
                     report: (event) => {
-                        if (event.kind === "error") reportFailure(event.error);
-                        else if (event.kind === "failed") {
+                        if (event.kind === "progress") log.info(event.message);
+                        else if (event.kind === "error") {
+                            if (!event.fatal) reportFailure(event.error);
+                        } else if (event.kind === "failed") {
                             if (event.built) reportSiteBuild(event.built);
                             for (const finding of event.findings ?? []) emitDiagnostic(finding);
                         } else {
@@ -2444,11 +2456,22 @@ function siteServeCommand() {
                     },
                 });
                 log.info(`serving ${served.url} — interrupt to stop`);
-                await new Promise((resolve) => {
-                    process.once("SIGINT", resolve);
-                    process.once("SIGTERM", resolve);
+                let interrupt;
+                const interrupted = new Promise((resolve) => {
+                    interrupt = resolve;
+                    process.once("SIGINT", interrupt);
+                    process.once("SIGTERM", interrupt);
                 });
-                await served.close();
+                try {
+                    await Promise.race([interrupted, served.done]);
+                } catch (err) {
+                    reportFailure(err);
+                    process.exitCode = 1;
+                } finally {
+                    process.removeListener("SIGINT", interrupt);
+                    process.removeListener("SIGTERM", interrupt);
+                    await served.close();
+                }
             } catch (err) {
                 reportFailure(err);
                 process.exitCode = 1;
@@ -3467,6 +3490,7 @@ function newNpc(config, argv) {
             profile,
             names,
             language: languageKey,
+            languageCode: code,
             seed: argv.seed,
             currentDate: config.currentDate,
             dateContext: reckoningContext(index),

package/docs/api.md

@@ -1329,12 +1329,30 @@ content tree can also compile into Foundry compendium packs.
 | `renderPages`         | `function renderPages(pages, options)`           | `{{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}`                                                   | Renders every page.                                                                                                        |
 | `resolveSitePass`     | `function resolveSitePass(name, options)`        | `{{beforeLinks?: Function}}` The bundle.                                                                                                             | Resolves `site.pass` to its bundle.                                                                                        |
 | `sitePageDecorator`   | `sitePageDecorator(config, index)`               | Function                                                                                                                                             | Add the site's infobox and being metadata to a rendered page.                                                              |
-| `buildSite`           | `buildSite({ config, sqlTables })`               | `{{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], mapFindings: object[], manifests: object\|null, site?: object}}` | Collects, checks and renders a content tree's pages, and reports what it found; returns each page for the site's renderer. |
+| `buildSite`           | `buildSite({ config, sqlTables, progress })`     | `{{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], mapFindings: object[], manifests: object\|null, site?: object}}` | Collects, checks and renders a content tree's pages, and reports what it found; returns each page for the site's renderer. |
 
 `siteGates` takes `{ config, records, sqlTables? }`. Pass the prepared
 `sqlTables` map so anchors emitted by automatic dictionary sections are present in the
 index for checking page links.
 
+`buildSite`, `engine/site-render.mjs`'s `buildPackageSite` and `writeSite`, and
+`engine/site-root.mjs`'s `writeSiteRoot` accept an optional `progress(message)`
+callback for phase summaries. It receives prose, independently of findings.
+
+`engine/site-serve.mjs`'s `serveSite({ config, out, root?, host?, port?, search?,
+year?, report? })` resolves with `{ url, settled, close, done }` when HTTP listens,
+before the initial build. Await `settled()` to wait for that build and queued
+edits, and `close()` to stop watching and serving. `done` resolves on close;
+an unexpected HTTP failure rejects it and stops the watchers. Its `report` callback
+receives `progress` events with a `message`, alongside `built`, `page`,
+`theme`, `failed` and `error` events; a fatal HTTP error has `fatal: true`.
+Failed builds are reported through that
+callback and leave the previous output in service. HTTP runs in a separate
+thread so synchronous rendering does not stall requests; the resolved
+configuration and incremental render state stay in the calling thread. Every
+update is prepared in a separate output tree, then installed between HTTP
+requests so readers receive complete files.
+
 ### `engine.contentRender`
 
 `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.
@@ -1362,6 +1380,16 @@ 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.
 
+Verse regions retain the authored `body` and its absolute `bodyStart` and
+`bodyEnd`. Their `logicalBody` excludes Markdown list and blockquote prefixes;
+`bodyOffsets` maps each logical UTF-16 position, including the exclusive end,
+back to an authored body offset. `parseVerse(logicalBody, {sourceOffsets:
+bodyOffsets, footnotes})` returns the whole model in authored body coordinates:
+line bounds and character offsets, stanza and canto bounds, boundaries, layout
+ranges and findings all use that map. Omitted prefixes are layout ranges, so
+Roman and native projections exclude them. Add `bodyStart` to a model offset to
+locate it in the complete source. LF and CRLF retain their authored lengths.
+
 | 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.                 |
@@ -1446,17 +1474,17 @@ The charset authored content is held to, so a book can choose its face. The pack
 
 ### `engine.romanCharacters`
 
-Exact permitted Roman source characters for configured languages, before script
-encoding. Inventories come from `data.roman` on each language's own note.
+A configured language's Roman additions to the shared punctuation standard,
+before script encoding. Inventories come from `data.roman` on each language's own note.
 
-| Export                    | Signature                                    | Returns                       | Use it when                                                                                                                                                          |
-| ------------------------- | -------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `isRomanWhitespace`       | `isRomanWhitespace(char)`                    | `boolean`                     | recognizing standard spaces and ASCII tab or line whitespace                                                                                                         |
-| `romanInventoryProblems`  | `romanInventoryProblems(value)`              | `string[]`                    | checking NFC, repeated characters and forbidden whitespace or controls in a literal inventory                                                                        |
-| `romanInventoriesOf`      | `romanInventoriesOf(records, languages)`     | `Map<string, RomanInventory>` | looking up a configured language's own inventory by name or BCP 47 tag                                                                                               |
-| `romanTextProblems`       | `romanTextProblems(text, inventory, stream)` | `{offset, message}[]`         | validating standard Roman punctuation and language additions with exact UTF-16 offsets; pass a `stream` state to continue sentences and quotations from earlier runs |
-| `romanPunctuationState`   | `romanPunctuationState()`                    | `{sentenceStart, quotes}`     | starting a stream of runs whose sentences and quotations continue from one run to the next                                                                           |
-| `romanUnclosedQuotations` | `romanUnclosedQuotations(quotes)`            | `{offset, message}[]`         | reporting the quotations still open where a stream of runs ends                                                                                                      |
+| Export                    | Signature                                    | Returns                       | Use it when                                                                                                                                                              |
+| ------------------------- | -------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `isRomanWhitespace`       | `isRomanWhitespace(char)`                    | `boolean`                     | recognizing standard spaces and ASCII tab or line whitespace                                                                                                             |
+| `romanInventoryProblems`  | `romanInventoryProblems(value)`              | `string[]`                    | checking NFC, repeats and forbidden whitespace, controls, standard punctuation, literal markers, semicolons, colons, English double quotes and setting-script characters |
+| `romanInventoriesOf`      | `romanInventoriesOf(records, languages)`     | `Map<string, RomanInventory>` | looking up a configured language's own inventory by name or BCP 47 tag                                                                                                   |
+| `romanTextProblems`       | `romanTextProblems(text, inventory, stream)` | `{offset, message}[]`         | validating standard Roman punctuation and language additions with exact UTF-16 offsets; pass a `stream` state to continue sentences and quotations from earlier runs     |
+| `romanPunctuationState`   | `romanPunctuationState()`                    | `{sentenceStart, quotes}`     | starting a stream of runs whose sentences and quotations continue from one run to the next                                                                               |
+| `romanUnclosedQuotations` | `romanUnclosedQuotations(quotes)`            | `{offset, message}[]`         | reporting the quotations still open where a stream of runs ends                                                                                                          |
 
 ### `engine.pathCharset`
 
@@ -2573,6 +2601,16 @@ points derive their own inputs. Generation and pack compilation accept
 `reportPreparation` (default true); a coordinating caller may set it false
 only after reporting the shared source findings itself.
 
+`engine/content-scripts` exposes `runContext(config, records?, {referenceName}?)`.
+It returns the language, encoding and metre context used by run scanning.
+`referenceName(target)` supplies the rendering or validation index's current
+name for an Address, including dependency targets, or `undefined` when none
+resolves. This lookup takes precedence over the local-record fallback and
+belongs only to the returned context; shared cached lexical data does not
+share a lookup between page or audience views. A metre line whose empty link
+label has no resolved spoken text stays unscanned, while the link validator
+reports invalid targets independently.
+
 `buildLinkIndex` and `buildContentLinkIndex` accept an optional `foreign` view
 from the same session; their diagnostic and routed resolver contracts remain
 distinct. `collectAnchors`, `markupAnchorFindings`, `markupFindings`, journal
@@ -2922,10 +2960,13 @@ const inferred = encode(data, null, "say", { enc: "aelwsemaronenc" });
 
 Both functions take `(data, language, text, options?)` and return
 `{text, findings}`; encoding with a language also returns source-positioned
-`pieces`. A language key selects its encoding, face and lexical inputs.
-`options.enc` and `options.font` override the encoding and face; `options.verse`
-asks the encoder to interpret verse structure. With `language: null`, `enc` is
-required and only the encoding's rows apply.
+`pieces`. `options.enc` selects a consumer-authored encoding document, which
+supplies its language and font. An explicit language must agree with that
+document; a null or omitted language infers it and uses its lexical inputs.
+`options.font` must agree with the encoding's font; `options.verse` asks the
+encoder to interpret verse structure. An omitted `enc`, or `enc: "default"`,
+preserves the Roman text. Bare conversion without lexical inputs uses the
+pure `encodeText` and `decodeText` functions in `engine/encoding.mjs`.
 
 Language conversion uses the same pure `encodeWithLanguage` and
 `decodeWithLanguage` functions as the build. Recorded native writings and
@@ -2933,7 +2974,7 @@ parts precede encoding rows, and decoding can recover an unmarked word from
 the lexicon. An unknown word gives a positioned finding. A bare refusal
 returns empty text and an error finding. Findings carry `severity`, `message`,
 `offset` (UTF-16), and one-based Unicode-code-point `line` and `column`.
-Invalid data, unknown languages and missing encoding selections throw an
+Invalid data, unknown languages and unknown encoding selections throw an
 error before conversion. `validateData(data)` returns the validated data or
 throws; it opens no files.
 

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

@@ -237,6 +237,30 @@ A captioned item inside the section is withheld with it: in Foundry the item's o
 
 The special Actor anchors `{#appearance}` and `{#dossier}` feed the same authored sections to each system's Actor fields, and take an H1 only — not the lower-level heading a journal page may otherwise start from. The section runs to the next H1, nested headings included. An anchor declared on a lower heading is still found, and is a build error rather than a quietly empty field: move the heading to the top level, or drop the anchor if the section is meant to stay unaddressed prose.
 
+## Book page breaks
+
+Write `--- {.page-break}` on its own line between blocks, with blank lines around it:
+
+```markdown
+The first passage ends here.
+
+--- {.page-break}
+
+The next passage starts on a fresh book page.
+```
+
+The book starts a fresh page without drawing a rule. If the marker already
+falls at the top of a page, it adds no blank page. The website, Foundry and
+both editor preview views omit the marker. Plain `---`, `***` and `___` keep
+their ordinary horizontal rules. Code blocks and verse divs keep the marker
+as literal text.
+
+Only `---` accepts `.page-break`; `*** {.page-break}` and `___ {.page-break}`
+are findings. Other classes, ids and attributes on an attributed `---` line
+are findings too. A page break stands between blocks at the top level of a
+note: putting one inside a list, block quote, alert, secret block or fenced
+div is a finding at the marker's line and column.
+
 ## Captions and numbered references
 
 Write a caption on its own line **before** the item it describes, with a blank line before and after the caption. `:` produces an unnumbered caption; `:@` produces a numbered caption. One or more spaces separate the marker from its text. An optional attribute block at the end accepts an identifier, classes and named attributes:
@@ -424,6 +448,20 @@ Periods inside the first inline span can set indentation; periods in later spans
 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.
 
+A verse div may sit inside a blockquote, a list item, or nested combinations of
+both. Write the surrounding container prefix on each line, including blank
+stanza lines. Container markers stay outside the verse text; logical lines,
+indentation and stanza boundaries follow the same rules as a standalone div.
+Findings point to the authored line and column, including its container prefix.
+
+```markdown
+> ::: {.verse}
+> One/..Two
+>
+> Three
+> :::
+```
+
 These two bodies have the same lines and indentation:
 
 ```markdown
@@ -491,13 +529,23 @@ language's stress rules; it reports an error at the line:
 Speaker labels and stage directions (`.speaker` and `.direction`) are presentation
 only: their text is not scanned, and a line containing only those spans is skipped.
 
+Wikilinks contribute only their visible labels to the beat count. An empty label
+(`[[place-ashkarad|]]`) contributes the indexed target's name, including a name
+from a dependency. Address segments, anchors and link attributes contribute no
+beats. If an empty label has no resolved spoken text, the line is not scanned;
+the link check reports invalid targets separately. Empty same-page caption
+references depend on page or book numbering and leave the line unscanned when
+that display text is unavailable.
+
 Beats are counted this way:
 
 - **Syllables** are vowel groups. A vowel is a letter whose base is `a`, `e`,
   `i`, `o` or `u`, and a pair the language lists in
   `data.sounds.syllables.vowelPairs` is one syllable.
-- **Every word of two or more syllables has one beat**, on its stressed
-  syllable. The language's stress rule places it: `two` for a word of two
+- **A word of two or more syllables has one beat**, on its stressed
+  syllable, but may go unstressed when every lexicon class is a function class:
+  any base other than `n`, `v`, `adj`, `num` or `name`. A word with any content
+  class, or no lexicon entry, keeps its beat. The language's stress rule places it: `two` for a word of two
   syllables, `longer` for a word of three or more, and a vowel carrying the
   rule's `mark` is stressed wherever it sits.
 - **A one-syllable noun, verb, adjective, numeral or name has a beat.** A
@@ -506,7 +554,7 @@ Beats are counted this way:
   through `lang=` as it is for the word check, including words inherited from
   its family. All entries for a spelling in the nearest lexicon supply their
   classes. A form the
-  language's own rules derive takes its word's class. A word whose entries differ in class is a
+  language's own rules derive takes its word's class. A one-syllable word with both content and function classes has a
   beat that may be left out.
 - **A one-syllable word the lexicon does not hold is a content word** and has a
   beat. The word check reports the word separately.

package/docs/commands.md

@@ -2255,11 +2255,12 @@ dependencies; exact Item UUID validation remains part of compilation. Reads
 the content tree named by `root`, defaulting to
 `paths.content`; writes nothing.
 
-Every configured language note declares `data.roman`, its exact NFC Roman
-source characters. Lint checks language-tagged text before mapping, using the
+Every configured language note declares `data.roman`, the NFC Roman characters
+the language adds to the shared standard: letters in accepted cases, accents,
+catch signs and digits. Lint checks language-tagged text before mapping, using the
 same inventory for a configured name and its BCP 47 tag. Visible linked labels
 are checked; destinations, attributes and verse structure are excluded. An
-explicit empty inventory declares no written characters. External tags without
+explicit empty inventory declares no additions. External tags without
 a language-note association retain their ordinary behavior. Standalone
 `package-build markdown` does not load these inventories.
 
@@ -2698,6 +2699,11 @@ links, tables, expressions, generated sections, maps — and rendered by the
 same renderer the Foundry journals and the editor preview use, then drawn by
 the site theme's layouts.
 
+Progress goes to stdout as each phase starts: indexing content, rendering
+pages, writing pages, and building the search index. Rendering and writing
+include page counts; the search summary gives the number indexed. Diagnostics
+remain on stderr in `file:line:column: severity: message` form.
+
 **A site is its homepage and its pages.** The `type: homepage` note is the
 package's front page at `/<contentPackage>/`; every other note is one page at
 `/<contentPackage>/<type>-<shortcode>/`. Nothing is generated between them
@@ -2770,8 +2776,12 @@ findings of severity `warning` included.
 
 ```
 $ package-build site build
+[…] indexing content
+[…] rendering 4306 page(s)
+[…] writing 4306 page(s)
 package-build.config.yaml:38:24: warning: the page-not-found links to /thalorna/polity/, which the site does not publish, so the link is left out
 […] wrote 4306 page(s) to build/site/thalorna
+[…] building the search index
 […] indexed 4307 page(s) for search into build/site/thalorna/pagefind
 ```
 
@@ -2794,13 +2804,25 @@ package-build site serve [--port <port>] [--host <address>] [--out <dir>]
 
 **DESCRIPTION**
 
-Builds the site as `package-build site build` does, indexes it for search once,
-and serves the deployed directory over HTTP, so every page is at the address it
+Starts HTTP and prints the listening address before the first build begins.
+Builds the site as `package-build site build` does and indexes it for search,
+while serving the deployed directory, so every page is at the address it
 is deployed at: `http://127.0.0.1:1313/<contentPackage>/`, or the path
 `site.base` states. An address the site does not publish is answered with its
 `404.html`. A search index `site.mergeIndexes` names is not served, since it is
 another site's; the site's own index is.
 
+Existing output stays available while a whole build runs. Incremental page and
+theme updates also prepare their files separately before replacing the served
+tree, so requests receive complete pages and styles. The new pages and
+search index replace it together after a successful build. A failed render,
+font delivery or search build leaves the previous site available. Without
+existing output, requests receive HTTP 503 with a message pointing to the
+terminal until a build succeeds; reload the page after the build completes.
+The build's indexing, rendering, writing and search phases print to stdout,
+with page counts where available. Diagnostics keep their located format on
+stderr. Whole rebuilds also refresh the search index.
+
 The content tree and the theme are watched. A change to a note's body or
 frontmatter writes that note's page again; a note whose name, type or
 shortcode changed, a new or removed note, a note holding an `sql` table, and
@@ -2825,15 +2847,21 @@ running. Interrupt it to stop.
 
 **EXIT STATUS**
 
-1 when the site's settings or its cached menu cannot be read. Otherwise 0 once
-interrupted.
+1 when the site's settings or its cached menu cannot be read, or HTTP cannot
+start or stops unexpectedly. Build failures are reported while the server keeps running. Otherwise
+0 once interrupted.
 
 **EXAMPLES**
 
 ```
 $ package-build site serve
-[…] built the site
 […] serving http://127.0.0.1:1313/thalorna/ — interrupt to stop
+[…] indexing content
+[…] rendering 4306 page(s)
+[…] writing 4306 page(s)
+[…] building the search index
+[…] indexed 4307 page(s) for search
+[…] built the site
 […] wrote build/site/thalorna/place-vedyara/index.html
 ```
 
@@ -3389,17 +3417,20 @@ reads the words of its `data.family` chain as its own. The languages are listed
 by name; each block gives the number missing, then the missing concepts under
 their groups in list order, each group with its count, each concept as its `id`
 and `gloss` separated by a tab. A language with no concept missing is reported as
-covering them all. Writes nothing.
+covering them all. The default report ends with `Not covered (no data.core): …`,
+naming language notes without `data.core: true` in name order, when any exist.
+An explicit `--language` measures only the requested language and prints no
+skip line. Writes nothing.
 
 A missing concept is a fact to work through, never a finding, so the report does
 not change the exit status.
 
 **OPTIONS**
 
-| Option       | Type    | Default | Description                                                                                                                                                            |
-| ------------ | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--language` | string  | —       | Report this language alone, by its name, its shortcode or its reference, whether or not it states `data.core`.                                                         |
-| `--json`     | boolean | `false` | Print `{ concepts, languages }` instead, each language `{ name, language, core, total, covered, missing }` and each missing group `{ group, count, total, concepts }`. |
+| Option       | Type    | Default | Description                                                                                                                                                                                                                                                |
+| ------------ | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--language` | string  | —       | Report this language alone, by its name, its shortcode or its reference, whether or not it states `data.core`.                                                                                                                                             |
+| `--json`     | boolean | `false` | Print `{ concepts, notCovered, languages }` instead; `notCovered` lists unmeasured language names (empty with `--language`), each language `{ name, language, core, total, covered, missing }` and each missing group `{ group, count, total, concepts }`. |
 
 **EXIT STATUS**
 
@@ -3505,7 +3536,7 @@ exactly as given, at every depth, and every field it leaves out is generated:
 
 | Field                                                   | Generated value                                                                                                                           |
 | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `name.full`                                             | Drawn from the culture's language's name lists by one of its patterns for `data.gender`, the given name from the list for that gender.    |
+| `name.full`                                             | Drawn by a pattern for `data.gender`; given names use the shared or gendered list, and drawn words start with capitals.                   |
 | `shortcode`                                             | The name transliterated to lowercase letters and digits and cut to twelve characters; a counter replaces its tail where a being holds it. |
 | `type`, `subType`, `tags`                               | `being`, `npc`, `[generated, draft]`.                                                                                                     |
 | `data.icon`, `data.species`, `data.packFolder`          | The commonest value among the package's npcs of the same culture, else among all its npcs; left out where none states one.                |
@@ -3549,13 +3580,25 @@ cycle. See [culture parents](reference/format-details.md#culture-parents-and-inh
 
 A profile or name lists with problems are refused with a finding at each.
 
+Generated `name.full` is the English display form: each word drawn from a name
+list starts with a capital, while its remaining letters and the pattern's
+connecting words keep their authored case. A caseless tongue can therefore
+supply `lumawesa` and `simi manik` to produce `Lumawesa of the Simi Manik`.
+The distinct source form keeps its authored spelling under the culture's language code,
+such as `name: {full: Lumawesa of the Simi Manik, teyu: [lumawesa of the simi manik]}`.
+If the selected pattern draws any English `{en.*}` part, the command omits
+the generated native alias. An unused English pattern does not affect a name
+drawn from another pattern.
+Supplied names and language forms keep their exact spelling and case.
+
 A spec that states `name.full` keeps it, and the name must fit the language's
-lists: one of the patterns for `data.gender`, with every placeholder filled by
+source or English display lists: one of the patterns for `data.gender`, with every placeholder filled by
 a name of its list, the given name from the list for `data.gender`. A name that does not fit is an
 error naming the part that fails and the language it was checked against; from
 a `--specfile`, the error is located at the name in the file. Where the
-gender has no given list of its own, the given name is drawn from, and
-checked against, every given list together.
+language states one shared `given` list, every gender draws from and is checked
+against it. With a gender map, a gender with no list of its own draws from and
+is checked against every given list together.
 
 Two top-level spec keys are section bodies rather than frontmatter.
 `appearance` is the Appearance section's markdown, written verbatim with its

package/docs/configuration.md

@@ -2307,8 +2307,9 @@ the source directory:
 
 Optional path for a browser converter's JSON data, relative to
 `packageBuild.stageDir`. `package-build manifest` writes it during the module
-build from the same published encodings and language vocabulary that render
-native text. The path must stay within the stage, end in `.json`, and name an
+build from the same consumer-authored encoding notes, selected fonts' glyph
+metadata and language vocabulary that render native text. The path must stay
+within the stage, end in `.json`, and name an
 artifact other than `module.json`, `system.json` or `package.json`. Absolute
 paths and parent traversal are refused. Omission writes no converter file.
 

package/docs/content-format.md

@@ -27,10 +27,20 @@ Start with [your first note](authoring/first-note.md). It explains the smallest
 
 A nonempty note body creates one system-agnostic Foundry JournalEntry. Content before the first H1 becomes an introduction page; every H1 starts another JournalEntryPage. A lower-level heading with an explicit `{#anchor}` starts a page too, so a link can address it. Each page name is its heading's visible text: spans, links and emphasis contribute their text without their markup. The same prose becomes a web page and can be selected for a book. The content index records the note and its frontmatter for queries and navigation.
 
+A top-level `--- {.page-break}` line between blank lines starts a fresh book page
+without drawing a rule, and adds no blank page when it already falls at a page
+top. Foundry, the website and both editor preview views omit it. Plain thematic
+breaks remain rules; code and verse keep the marker literally. Other
+attributes, star or underscore markers, and markers inside containers are
+findings. See [book page breaks](authoring/links-and-markup.md#book-page-breaks).
+
 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` 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.
+Blockquotes and list items may contain verse divs, including nested combinations.
+Their container prefixes are excluded from verse text, while findings retain
+authored line and column positions with either LF or CRLF endings.
 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=` on a div sets the original once in two presentations, script on the left

package/docs/diagnostics.md

@@ -297,6 +297,23 @@ Like a culture conflict, each fails the index and every command that reads it
 without collecting problems. The rules are under
 [a note's language](reference/format-details.md#a-notes-language).
 
+## Book page-break findings
+
+The optional [book page break](authoring/links-and-markup.md#book-page-breaks)
+uses only `--- {.page-break}` between blocks at the note's top level.
+Other classes, ids or attributes on an attributed `---` line receive findings
+at their opening brace. A `.page-break` on `***` or `___` receives a finding
+at the marker. A marker inside a list, block quote, alert, secret block or
+fenced div receives `a page break stands between blocks at the top level of a
+note`, at that marker's line and column. Missing surrounding blank lines
+receive the same placement finding. Code blocks and complete verse divs are
+literal and receive no page-break findings.
+
+The author lint, pack compiler, site build, both preview views and book source
+generation report these errors from the same scanner. A valid marker is
+omitted on screens and emits a weak page break in the book, avoiding an extra
+blank page at a page top.
+
 ## A worked case: versions of a work
 
 [Versions of a work](authoring/links-and-markup.md#versions-and-stanza-labels)

package/docs/guides/module-project.md

@@ -716,13 +716,21 @@ packageBuild:
 ```
 
 `package-build manifest` writes the JSON beneath the build stage, so the
-release includes the data alongside the module's other files. It embeds each
-language's published encoding and the lexical inputs used by the build.
+release includes the data alongside the module's other files. It embeds the
+consumer's authored encoding definitions, the selected fonts' glyph-code
+snapshots, and the language names and lexical inputs used by the build.
+Conversion rules belong to the consumer's encoding notes; fonts supply the
+glyphs and their metadata.
 
 Bundle `@heroiclands/package-build/convert` into the module's browser code,
 fetch `modules/<module-id>/data/converter.json` once, and pass the parsed data
 to `encode` or `decode`. A picker can list `Object.entries(data.languages)`
-using each entry's `name`; each entry already states its encoding and face.
+using each entry's `name`. Offer the encoding documents in `data.encodings`
+whose `data.language` matches the selected language, and pass the selected
+document Address as `options.enc`. That document supplies its font; language
+entries carry no default encoding or face. Omitting `options.enc`, or choosing
+`default`, preserves Roman text. The JSON includes all conversion inputs, so
+the browser fetches no separate encoding or font metadata files.
 Show the returned findings alongside the text when a word cannot be recovered.
 See the [API](../api.md#browser-conversion) and
 [data format](../reference/format-details.md#converter-data-format).

package/docs/guides/site.md

@@ -302,12 +302,22 @@ index inside it. Nothing else renders the pages: the body of each is the same
 HTML the Foundry journals and the editor preview read, drawn into the site
 theme's layouts and minified.
 
+The terminal reports indexing, rendering, writing and search indexing as they
+start, including page counts where available. Progress is on stdout;
+diagnostics retain their file, line and column on stderr.
+
 ```bash
 package-build site serve
 ```
 
-`package-build site serve` builds the site the same way and serves it at
-`http://127.0.0.1:1313/<contentPackage>/`. Edit a note and its page is written
+`package-build site serve` prints its address as soon as HTTP starts, before
+building the site: `http://127.0.0.1:1313/<contentPackage>/`. Existing output
+remains available during the build. Successful whole builds replace the pages
+and search index together; failed builds leave the last successful output in
+place. A first run with no output answers HTTP 503 until a build succeeds, with
+a message pointing to progress and diagnostics in the terminal.
+
+Edit a note and its page is written
 again and the browser reloads; edit the theme and every page is drawn again.
 A change that moves, renames or adds a note builds the whole site again. See
 [`site serve`](../commands.md#package-build-site-serve) for the whole table.

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

@@ -618,11 +618,14 @@ that the language lists in `data.sounds.syllables.vowelPairs` is one syllable.
 
 **The beat convention, in plain words:**
 
-- Every word of two or more syllables has one beat, on its stressed syllable.
+- A word of two or more syllables has one beat, on its stressed syllable,
+  but may go unstressed when every lexicon class is a function class: any base
+  other than `n`, `v`, `adj`, `num` or `name`. A word with any content class,
+  or no lexicon entry, keeps its beat.
 - A one-syllable noun, verb, adjective, numeral or name has a beat. A
   one-syllable particle, preposition, conjunction, adverb or pronoun has none.
   The lexicon entry's class decides, and a form that the language's rules derive
-  takes its word's class. A word whose entries differ in class is a beat that
+  takes its word's class. A one-syllable word with both content and function classes has a beat that
   may be left out.
 - A one-syllable word the lexicon does not hold is a content word and has a
   beat; the word check reports the word separately.