@heroiclands/package-build 25.5.4 → 25.6.0

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
@@ -86,6 +96,8 @@ markers scoped to each note. Definition lists use a term followed by one or
 more `: definition` lines. See [footnotes and definition lists](authoring/links-and-markup.md#footnotes-and-definition-lists)
 for examples and placement in journals, web pages, and books.
 
+A query selects notes by property, tag or address, never by where a note's file sits: a fence that names `file.path`, `file.folder` or `file.name` is an error at the reference, and a note moved between folders changes no query's answer.
+
 An inline `{{sql "SELECT COUNT(*) FROM notes"}}` expression inserts one scalar query result. Use `{{words (sql "SELECT COUNT(*) FROM notes")}}` for a count in running prose, or `{{digits (sql "SELECT COUNT(*) FROM entries")}}` for grouped numerals. The query must return exactly one row and one column with a nonempty value; a mismatch is a located build error. Prefix `\{{` to show the syntax literally. The [expression reference](reference/format-details.md#dates-and-calendars) describes the helpers and the available SQL relations.
 
 Add `gm` to `tags` for a GM-only note. Public site and book builds omit it;
@@ -193,7 +205,44 @@ The [first-note guide](authoring/first-note.md) shows the build commands and how
 
 Place notes may declare a governing affiliation with `data.government`, or explicit `null` for complete anarchy. Positive population with an omitted government produces an advisory. See [place governments](authoring/frontmatter.md#place-governments).
 
-A region may list its settlements in a table under `## Settlements` — name, market, people and holder, one row each — tagged with the holding model it is written in. A row links the settlement's note where one exists, and `package-build lint` holds the two to agreement. See [a region's settlements table](reference/format-details.md#a-regions-settlements-table).
+A region declares its table in `data.settlements: { rows, tail }`. The rows
+carry the settlement's `population` and numeric `market`, and either `place`
+(the existing note's Address, default type `place`) or `name` (plain text where
+no note exists), never both. Where the region's culture holds land, a row's
+optional `heldBy` names what holds it by Address (an affiliation or a being,
+default type `affiliation`), and what that note is says how the land is held: a
+temple, a lineage, the city, a kin group. A people who hold no land state no
+`heldBy`, and their table has no Held by column. Optional `for` states why the
+settlement exists. `tail` is the sentence stating what the table leaves out.
+
+The guard reads indexed rows. A linked row's population and market agree with
+its note, and every settlement note covered through `parents` has one row in
+the nearest declaring region. `government` states who governs; it never supplies
+who holds the land. HTML, Foundry and Typst render the declared table once.
+A body table under `## Settlements` is an error at its header, naming
+`data.settlements`; no facts are read from it.
+
+```yaml
+data:
+  settlements:
+    rows:
+      - place: ashford
+        market: 4
+        population: 3400
+        heldBy: affiliation-crown
+        for: the ford on the drove road
+      - name: Weyshott
+        market: 2
+        population: 420
+        heldBy: being-aldwyn
+        for: the manor's mill
+      - name: Cold Hatch
+        market: 1
+        population: 60
+    tail: Some four hundred further villages lie in the vale, none of them named here.
+```
+
+See [a region's settlements table](reference/format-details.md#a-regions-settlements-table).
 
 A being states its gender, frame and appearance in words from one closed vocabulary: `data.gender`, `data.frame`, and `data.appearance.eye_color`, `hair_color`, `skin_color` and `complexion` each take only the words listed for them, and any other value is an error at the value. `complexion` is a list, required once a being states an appearance. `data.appearance.extra_features` lists the being's visible physical marks, each a short plain description of one, and an entry stating a colour, a skin condition or anything that is not a mark is an error. See [a being's look](reference/format-details.md#a-beings-look).
 

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, footnote definition,
+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/reference-pages.md

@@ -134,7 +134,10 @@ its language's code. It also has ASCII-folded `nameAscii` and `formsAscii`, the
 listed forms by language, for searching names typed without diacritics, and
 `lang`, the language the note is in, derived as
 [a note's language](../reference/format-details.md#a-notes-language) describes.
-A language note that `languages:` names carries its code as `languageCode`. Asset files under `assets/icons`, `assets/images`, and
+A language note that `languages:` names carries its code as `languageCode`.
+An affiliation carries `officeHolders`, each of its offices that a living
+being holds with those beings' Addresses, derived as
+[office holders](../reference/format-details.md#type-affiliation) describes. Asset files under `assets/icons`, `assets/images`, and
 `assets/audio` have records in the same index, identified by an `asset` block.
 The index is disposable build output; regenerate it from the authored tree
 when the content changes.

package/docs/guides/site.md

@@ -244,7 +244,7 @@ notes' sources. A page is reachable when an authored link leads to it:
 The links the build generates do not make a page reachable. These are the
 Related card, the previous and next links, the infobox links, and the sections
 generated after a note's text (Within, Governed by, Governed places,
-Chronology, Events, Accounts, What followed, In song and story). Each is drawn
+Office holders, Chronology, Events, Accounts, What followed, In song and story). Each is drawn
 without a link to a page outside the reachable set, and a section left with
 nothing under it is not drawn. An infobox value that names an unreachable page
 is set as plain text. So is a link in a dictionary or glossary entry, whether
@@ -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.