@heroiclands/package-build 24.0.2 → 24.0.4

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @heroiclands/package-build
 
+## 24.0.4
+
+### Patch Changes
+
+**Languages**
+
+- Core vocabulary coverage uses only the nearest definition when a language
+  redefines an inherited expression.
+
+- Inherited dictionary words appear in a daughter language’s script with the
+  applicable native spelling.
+
+**Verse**
+
+- Parallel verse keeps its Roman reading beside the native script, with
+  gaps between stanzas.
+
+## 24.0.3
+
+### Patch Changes
+
+**Sites**
+
+- Glossary and dictionary entries link only to pages a reader can reach, and such links never make a page reachable.
+
+**Configuration**
+
+- A package can no longer declare a dependency whose images replace its own: `assetReplacement` and `assetArchive` are refused as unknown options.
+
+**Languages and scripts**
+
+- A sound mark can say `apart`, beside `stress` and `length`: the mark sets a vowel to be said apart from its neighbour, as a diaeresis does.
+- A skeleton row can state `third`, the third consonants it holds for, beside `second`, so a rule that depends on the third consonant can be written.
+- Text in the Veldikko script draws no charset warnings.
+
 ## 24.0.2
 
 ### Patch Changes

package/bin/content-commands.mjs

@@ -2815,18 +2815,16 @@ async function fetchFromLocalArtifact(config, argv) {
 
 /**
  * `deps fetch` — fill the caches this build resolves other packages through:
- * the **content index** of every declared dependency, the **item catalogue
- * or asset archive** of those additionally declaring `itemCatalog: true` or
- * `assetArchive: true`, and the **site navigation** heroiclands.org
+ * the **content index** of every declared dependency, the **item catalogue**
+ * of those additionally declaring `itemCatalog: true`, and the **site navigation** heroiclands.org
  * publishes, which the site build writes its menu from.
  *
  * The dependency sets differ deliberately. Citing another package's
- * *addresses*, embedding its *items*, and staging its *asset bytes* are
- * separate edges, and a package may declare any of them without the others —
+ * *addresses* and embedding its *items* are separate edges, and a package may
+ * declare either without the other —
  * `harn-ensemble` cites no foreign address and embeds 324,016 item
  * references. The navigation is fetched for every package, because every
- * package publishes a site. A relationship declaring both `itemCatalog: true`
- * and `assetArchive: true` is fetched once.
+ * package publishes a site.
  *
  * Its own command rather than a step of `package compile` or `site`, so that
  * neither reaches the network. A build that downloads silently is not
@@ -2887,7 +2885,7 @@ function depsCommand() {
                 const indexes = await fetchAllMetadata(config);
                 if (indexes) log.info(`Fetched ${indexes} dependency content index(es).`);
                 const count = await fetchAllCatalogs(config);
-                if (count) log.info(`Fetched ${count} dependency catalogue(s) or archive(s).`);
+                if (count) log.info(`Fetched ${count} dependency catalogue(s).`);
                 if (!indexes && !count) {
                     // Distinguished from a package declaring nothing at all: a
                     // relationship may still be declared, just narrowed to the
@@ -2899,8 +2897,8 @@ function depsCommand() {
                     );
                     log.info(
                         declared ?
-                            "No declared dependency needs a fetched content index, item " +
-                                "catalogue, or asset archive."
+                            "No declared dependency needs a fetched content index or item " +
+                                "catalogue."
                         :   "This package declares no dependencies.",
                     );
                 }

package/content-config.mjs

@@ -350,8 +350,7 @@ export function publishesContentPages(config) {
  * @property {string} [stage]            Compiled LevelDB packs.
  * @property {string} [unpack]           Where `unpack` extracts JSON back to.
  * @property {string} [foreignCache]     Where a dependency declaring
- *                                       `itemCatalog: true` or
- *                                       `assetArchive: true` is unpacked.
+ *                                       `itemCatalog: true` is unpacked.
  *                                       Inbound, and fetched rather than
  *                                       committed.
  * @property {string} [metadataCache]    Where a dependency's published content
@@ -474,10 +473,6 @@ export function publishesContentPages(config) {
  *                                   its Item packs, so the actors pass can
  *                                   resolve embedded items this repository
  *                                   does not hold. Needs a `manifest`.
- * @property {boolean} [assetArchive]  Whether `deps fetch` unpacks this
- *                                   dependency's release archive for its
- *                                   asset bytes alone, building no item
- *                                   catalogue from it. Needs a `manifest`.
  * @property {boolean} [contentIndex]  Whether `deps fetch` fetches this
  *                                   dependency's content index. Default
  *                                   `true`. `false` declares the dependency
@@ -486,13 +481,6 @@ export function publishesContentPages(config) {
  *                                   `itemCatalog: true` on the same entry,
  *                                   since a catalogue is fetched from the same
  *                                   index.
- * @property {boolean} [assetReplacement]  Whether this dependency's asset
- *                                   tree answers this package's own asset
- *                                   addresses ahead of its local record.
- *                                   Default `false`. Refuses `contentIndex:
- *                                   false` on the same entry, since a
- *                                   replacement with no fetched index to
- *                                   check against resolves nothing.
  */
 
 /**
@@ -859,9 +847,7 @@ export const RELATIONSHIP_KEYS = [
     "manifest",
     "compatibility",
     "itemCatalog",
-    "assetArchive",
     "contentIndex",
-    "assetReplacement",
 ];
 const AUTHOR_KEYS = ["name", "email", "url", "discord", "role"];
 /**
@@ -2611,23 +2597,6 @@ function normalizeRelationships(value) {
                     }
                     spec.itemCatalog = rel.itemCatalog;
                 }
-                // Opt-in, sibling to `itemCatalog`: unpack this dependency's
-                // release archive for its asset bytes alone, building no item
-                // catalogue from it. Buys the archive for a package with no
-                // items of its own to extract — an asset-replacement source
-                // ships no Item packs and has no use for `itemCatalog: true`.
-                if (rel.assetArchive !== undefined) {
-                    if (typeof rel.assetArchive !== "boolean") {
-                        fail(`${at}.assetArchive`, "must be true or false");
-                    }
-                    if (rel.assetArchive && spec.manifest === undefined) {
-                        fail(
-                            `${at}.assetArchive`,
-                            "needs a `manifest` naming the package to fetch",
-                        );
-                    }
-                    spec.assetArchive = rel.assetArchive;
-                }
                 // Opt-out: declares the dependency for the Foundry manifest
                 // only, so `deps fetch` fetches no content index for it and a
                 // wikilink into it is refused rather than silently dead. A
@@ -2646,26 +2615,6 @@ function normalizeRelationships(value) {
                     }
                     spec.contentIndex = rel.contentIndex;
                 }
-                // Opt-in: this dependency's asset tree answers this
-                // package's own asset addresses ahead of its local record —
-                // the "rewrite table" `engine/asset-replacement.mjs` reads.
-                // A replacement with no fetched index to check against
-                // resolves nothing, so it cannot pair with
-                // `contentIndex: false`.
-                if (rel.assetReplacement !== undefined) {
-                    if (typeof rel.assetReplacement !== "boolean") {
-                        fail(`${at}.assetReplacement`, "must be true or false");
-                    }
-                    if (rel.assetReplacement && rel.contentIndex === false) {
-                        fail(
-                            `${at}.assetReplacement`,
-                            "cannot be true together with `contentIndex: false` — a " +
-                                "replacement with no fetched index to check against resolves " +
-                                "nothing",
-                        );
-                    }
-                    spec.assetReplacement = rel.assetReplacement;
-                }
                 return Object.freeze(spec);
             }),
         );

package/docs/api.md

@@ -2624,14 +2624,15 @@ occupies one line and the file ends with a newline.
 `@heroiclands/package-build/engine/dictionary-layout` renders SQL results as
 Markdown for the dictionary or glossary on its owner's note:
 
-| Export                    | Signature                            | Returns                    | Use it when                                                                         |
-| ------------------------- | ------------------------------------ | -------------------------- | ----------------------------------------------------------------------------------- |
-| `LAYOUT_REQUIRED_COLUMNS` | `const LAYOUT_REQUIRED_COLUMNS`      | Required columns by layout | Checking the columns a dictionary or glossary query must select.                    |
-| `COMMON_MARK`             | `const COMMON_MARK`                  | `string`                   | Reading the mark a common glossary entry opens with.                                |
-| `DICTIONARY_ENTRY_CLASS`  | `const DICTIONARY_ENTRY_CLASS`       | `string`                   | Identifying generated headword spans that are native dictionary targets in Foundry. |
-| `dictionaryEntryPlugin`   | `dictionaryEntryPlugin(md)`          | `void`                     | Registering native dictionary headword rendering on the Foundry Markdown parser.    |
-| `renderDictionary`        | `renderDictionary(result, options?)` | `string`                   | Rendering a language's words with classes, etymology, senses and citations.         |
-| `renderGlossary`          | `renderGlossary(result, options?)`   | `string`                   | Rendering an owner's glossary entries, ranks and offices.                           |
+| Export                    | Signature                            | Returns                    | Use it when                                                                                                  |
+| ------------------------- | ------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `LAYOUT_REQUIRED_COLUMNS` | `const LAYOUT_REQUIRED_COLUMNS`      | Required columns by layout | Checking the columns a dictionary or glossary query must select.                                             |
+| `COMMON_MARK`             | `const COMMON_MARK`                  | `string`                   | Reading the mark a common glossary entry opens with.                                                         |
+| `DICTIONARY_ENTRY_CLASS`  | `const DICTIONARY_ENTRY_CLASS`       | `string`                   | Identifying generated headword spans that are native dictionary targets in Foundry.                          |
+| `LEXICAL_LINK_CLASS`      | `const LEXICAL_LINK_CLASS`           | `string`                   | Identifying the links an entry writes, which a site sets as text where they lead nowhere a reader can reach. |
+| `dictionaryEntryPlugin`   | `dictionaryEntryPlugin(md)`          | `void`                     | Registering native dictionary headword rendering on the Foundry Markdown parser.                             |
+| `renderDictionary`        | `renderDictionary(result, options?)` | `string`                   | Rendering a language's words with classes, etymology, senses and citations.                                  |
+| `renderGlossary`          | `renderGlossary(result, options?)`   | `string`                   | Rendering an owner's glossary entries, ranks and offices.                                                    |
 
 `result` is `{ columns: string[], rows: object[] }`. Both layouts require
 `name`, `senses` and `usage`; a missing column throws an error naming it.
@@ -2677,6 +2678,11 @@ headword's span and paragraph. `anchorsOf` maps this dictionary target to
 its containing page's UUID with the word fragment; generic authored spans
 keep their containing-page behavior.
 
+`LEXICAL_LINK_CLASS` is `"lexical-ref"`. Every link an entry writes to
+another note, a citation, a headword's link to its dictionary word or a
+wikilink in a gloss, carries it as an attribute. A site build sets such a link
+as its text when the target is a page a reader cannot reach.
+
 ## Automatic dictionary and glossary sections
 
 `@heroiclands/package-build/engine/lexical-sections` derives and inserts the

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

@@ -490,7 +490,11 @@ column stacks one or more **entries**, joined by `:`. An entry is
 - **`mapping`** names a [mapping note](#mapping-notes), which rewrites the
   line before it is set. Left out, the line is set as written.
 - **`font`** names a face or a generic family, as `font=` does. Left out, the
-  line is set in the roman serif.
+  line keeps the page's normal typeface.
+
+A language-only entry stays in Roman letters even when the language's
+`data.writtenIn` names its usual script. Ordinary language-marked prose still
+selects that script automatically; columns use the entry's explicit mapping.
 
 A poem has at most two columns, and either may be left out. In every column
 the first entry is set in the normal tone and each later one in grey.
@@ -805,7 +809,12 @@ is one of them.
 
 **With `lang=`, the language's dictionary comes first.** Where
 [`languages.<name>.note`](../configuration.md#languages) names the language's
-note, each word of the run is looked up in its `data.words`:
+note, each word of the run is looked up in its `data.words` and the words of
+its `data.family` chain. The nearest exact NFC form supplies the entire word
+entry, including variants and native spellings; an override replaces the whole
+ancestor entry. Case and word separators remain part of that identity.
+Grammar, registered names and the default writing script remain the daughter's
+own. An inherited native spelling applies only to the map and face it names:
 
 1. **A word whose entry states a `native` form for the map** is written by it:
    the form stated for the run's face where there is one, else the form stated
@@ -1469,7 +1478,7 @@ A column's heading is its SQL alias, so `AS "Name"` is what a reader sees. A cel
 | `joining`          | One row per entry of a language note's `data.sounds.joining`: `first`, `second`, `written` and `example`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `joins`            | One row per entry of a language note's `data.sounds.joins`: `meeting`, `rule`, `letters` and `"where"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `marks`            | One row per entry of a language note's or a spelling guide's `data.sounds.marks`: `mark`, `letters`, `kind` and `"limit"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `skeleton`         | One row per entry of a language note's `data.sounds.skeleton`: `second` and `between`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `skeleton`         | One row per entry of a language note's `data.sounds.skeleton`: `second`, `third` and `between`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `frames`           | One row per frame of a language note's `data.sounds.frames`: `frame`, `shape`, `class`, `makes` and `examples` as `{ root, form }`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `read_past`        | One row per entry of a language note's `data.sounds.readPast`: `written`, `readAs` and `what`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `mutations`        | One row per entry of a language note's `data.sounds.mutations`: `mutation`, `sound`, `becomes` and `example`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

package/docs/commands.md

@@ -1718,13 +1718,11 @@ package-build deps fetch [--from <zip|dir>] [--id <id>]
 The only action is `fetch`, which fills three caches under `build/cache/`:
 the **content index** of every declared dependency and of every
 `recommends` or `conflicts` relationship that declares `itemCatalog: true`,
-the **item catalogue or
-asset archive** of those that additionally declare `itemCatalog: true` or
-`assetArchive: true`, and the **site navigation** —
+the **item catalogue** of those that additionally declare `itemCatalog: true`,
+and the **site navigation** —
 `https://www.heroiclands.org/nav.json`, the header menu every package site
 renders, fetched for every package because every package publishes a site.
-A relationship declaring both `itemCatalog: true` and `assetArchive: true`
-is fetched once. Its own command rather than a step of `package compile` or
+Its own command rather than a step of `package compile` or
 `site`, so neither reaches the network — a build that downloads silently is
 not reproducible and hides a dependency's version change behind a passing
 run. Each cache is stamped complete only once its fetch finishes, so a
@@ -1766,7 +1764,7 @@ including when the repository declares no dependencies at all.
 ```
 $ package-build deps fetch
 […] Fetched the site navigation to build/cache/navigation/nav.json.
-[…] No relationship declares `itemCatalog: true` or `assetArchive: true`; nothing to fetch.
+[…] No relationship declares `itemCatalog: true`; nothing to fetch.
 […] This package declares no dependencies.
 
 $ package-build deps fetch --from build/dist/module.zip

package/docs/configuration.md

@@ -606,7 +606,7 @@ HeroicLands layout, resolved against `rootDir`:
 | `paths.packJson`        | `build/packs-json`       | Build-only per-entry JSON intermediate.                                                                                            |
 | `paths.stage`           | `build/stage/packs`      | Compiled LevelDB packs.                                                                                                            |
 | `paths.unpack`          | `build/tmp/packs`        | Where `unpack` extracts JSON back to.                                                                                              |
-| `paths.foreignCache`    | `build/cache/foreign`    | Where a dependency declaring `itemCatalog: true` or `assetArchive: true` is unpacked.                                              |
+| `paths.foreignCache`    | `build/cache/foreign`    | Where a dependency declaring `itemCatalog: true` is unpacked.                                                                      |
 | `paths.metadataCache`   | `build/cache/metadata`   | Where a published content index is fetched to, for every declared dependency and every relationship declaring `itemCatalog: true`. |
 | `paths.navigationCache` | `build/cache/navigation` | Where the site navigation heroiclands.org publishes is fetched to, for the site's menu.                                            |
 
@@ -1228,7 +1228,7 @@ writes its own `sitemap.xml` whether or not it states this key.
 ```yaml
 site:
   base: /
-  sitemaps: [sohl, hm3, thalorna, kethira, thalornaaltart, harnensemble, harnadventures]
+  sitemaps: [sohl, hm3, thalorna, kethira, harnensemble, harnadventures]
 ```
 
 `site.mergeIndexes` names the package sites, by `contentPackage`, whose search
@@ -1275,7 +1275,7 @@ site:
     projects: doc-projects
   feed: blog
   tags: true
-  sitemaps: [sohl, hm3, thalorna, kethira, thalornaaltart, harnensemble, harnadventures]
+  sitemaps: [sohl, hm3, thalorna, kethira, harnensemble, harnadventures]
   mergeIndexes: [sohl, thalorna, kethira, harnensemble]
 ```
 
@@ -1645,17 +1645,15 @@ system relationship it declares — see [`stats.systemVersion`](#statssystemvers
 
 Each entry, in any of the four lists:
 
-| Key (under `relationships.<kind>[]`)       | Type                            | Required | Default |
-| ------------------------------------------ | ------------------------------- | -------- | ------- |
-| `relationships.systems[].id`               | string                          | yes      | —       |
-| `relationships.systems[].contentPackage`   | string                          | no       | the id  |
-| `relationships.systems[].type`             | string                          | no       | none    |
-| `relationships.systems[].manifest`         | string                          | no       | none    |
-| `relationships.systems[].compatibility`    | object, `{minimum?, verified?}` | no       | none    |
-| `relationships.systems[].itemCatalog`      | boolean                         | no       | `false` |
-| `relationships.systems[].assetArchive`     | boolean                         | no       | `false` |
-| `relationships.systems[].contentIndex`     | boolean                         | no       | `true`  |
-| `relationships.systems[].assetReplacement` | boolean                         | no       | `false` |
+| Key (under `relationships.<kind>[]`)     | Type                            | Required | Default |
+| ---------------------------------------- | ------------------------------- | -------- | ------- |
+| `relationships.systems[].id`             | string                          | yes      | —       |
+| `relationships.systems[].contentPackage` | string                          | no       | the id  |
+| `relationships.systems[].type`           | string                          | no       | none    |
+| `relationships.systems[].manifest`       | string                          | no       | none    |
+| `relationships.systems[].compatibility`  | object, `{minimum?, verified?}` | no       | none    |
+| `relationships.systems[].itemCatalog`    | boolean                         | no       | `false` |
+| `relationships.systems[].contentIndex`   | boolean                         | no       | `true`  |
 
 (the same keys apply under `requires[]`, `recommends[]` and
 `conflicts[]`.)
@@ -1664,7 +1662,7 @@ Each entry, in any of the four lists:
 
 > ``package-build config: `relationships.<kind>[<index>].id` must be a non-empty string.``
 
-> ``package-build config: `relationships.<kind>[<index>].<key>` is not a recognized option (expected one of: id, contentPackage, type, manifest, compatibility, itemCatalog, assetArchive, contentIndex, assetReplacement).``
+> ``package-build config: `relationships.<kind>[<index>].<key>` is not a recognized option (expected one of: id, contentPackage, type, manifest, compatibility, itemCatalog, contentIndex).``
 
 `contentPackage` names what the other package's _content_ is called, where
 that differs from its Foundry id. A note addresses a file by the content
@@ -1685,31 +1683,6 @@ embedded-item addresses the compile does. It requires a `manifest`:
 
 > ``package-build config: `relationships.<kind>[<index>].itemCatalog` needs a `manifest` naming the package to fetch.``
 
-`assetArchive` opts into unpacking the named package's release archive for
-its asset bytes alone — the sibling of `itemCatalog`, for a dependency whose
-bytes are wanted and whose items are not. It builds no item catalogue from
-the archive, which is what distinguishes it from `itemCatalog: true`. It
-requires a `manifest`:
-
-> ``package-build config: `relationships.<kind>[<index>].assetArchive` must be true or false.``
-
-> ``package-build config: `relationships.<kind>[<index>].assetArchive` needs a `manifest` naming the package to fetch.``
-
-A relationship with no items of its own to extract, such as an asset
-replacement module, declares only `assetArchive: true`:
-
-```yaml
-relationships:
-  requires:
-    - id: thalornaaltart
-      manifest: https://…/releases/latest/download/module.json
-      compatibility: { verified: "1.0.0" }
-      assetArchive: true
-```
-
-A relationship declaring both `itemCatalog: true` and `assetArchive: true` is
-fetched once: `deps fetch` does not download the archive twice for one entry.
-
 `contentIndex` and `itemCatalog` are the two edges a relationship may declare,
 and a package may have either without the other. `itemCatalog` says a
 dependency supplies _items_; `contentIndex`, `true` by default, says
@@ -1729,35 +1702,6 @@ demand.
 
 > ``package-build config: `relationships.<kind>[<index>].contentIndex` cannot be false together with `itemCatalog: true` — a catalogue is fetched from the same index.``
 
-`assetReplacement` opts a relationship into serving this package's own asset
-addresses from the named dependency's tree instead of its local one —
-`engine/asset-replacement.mjs`'s `resolveAssetReplacement` is what reads the
-declaration. Off by default: declaring a dependency is not the same as
-wanting its pictures in place of the ones this package ships itself. It
-requires a fetched index to check the replacement against, so it cannot pair
-with `contentIndex: false`:
-
-```yaml
-relationships:
-  requires:
-    - id: thalornaaltart
-      manifest: https://…/releases/latest/download/module.json
-      assetReplacement: true
-      contentIndex: true
-```
-
-With that declared, an address `thalorna` would otherwise answer itself —
-`thalorna-none-image-thorn` — resolves against
-`thalornaaltart-none-image-thorn` first, falling back to `thalorna`'s own
-record when `thalornaaltart` carries no file at that address. A package
-declaring more than one `assetReplacement: true` relationship is tried in
-the order the relationships are declared, and the first one carrying the
-address wins.
-
-> ``package-build config: `relationships.<kind>[<index>].assetReplacement` must be true or false.``
-
-> ``package-build config: `relationships.<kind>[<index>].assetReplacement` cannot be true together with `contentIndex: false` — a replacement with no fetched index to check against resolves nothing.``
-
 ### `systems`
 
 **Type:** object (`{id: spec}`) · **Optional** · default `{}`. Refused in a

package/docs/guides/site.md

@@ -247,7 +247,9 @@ generated after a note's text (Within, Governed by, Governed places,
 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. A link written in prose or produced by a query is kept
+is set as plain text. So is a link in a dictionary or glossary entry, whether
+it names a word's entry, cites a note or sits in a gloss; it does not make its
+target reachable. A link written in prose or produced by a query is kept
 wherever it points, and it is what makes its target reachable.
 
 A page that is not reachable is the way to preview a page in place. Write the