@heroiclands/package-build 22.13.0 → 22.13.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @heroiclands/package-build
 
+## 22.13.1
+
+### Patch Changes
+
+Content authors can keep pinned document identities and compendium placement alongside shared note facts.
+
 ## 22.13.0
 
 ### Minor Changes

package/docs/api.md

@@ -119,28 +119,29 @@ Deterministic document ids, derived by hashing rather than stored, so compile pa
 
 The per-system frontmatter block: how one note feeds more than one game system through properties named after that system (`<system>.system`, `<system>.type`, `<system>.img`, `<system>.items` on actors). Resolves a field's value through the block, the shared top level, and a retiring position in that order, and merges an authored `<system>.system` onto a compiler-built one without disturbing what the builder already wrote.
 
-| Export                      | Signature                                     | Returns                                | Use it when                                                                                   |
-| --------------------------- | --------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `SYSTEM_DATA_KEY`           | `const SYSTEM_DATA_KEY`                       | —                                      | naming the key inside a system block whose contents are the system's own vocabulary           |
-| `BLOCK_DOCUMENT_PROPERTIES` | `const BLOCK_DOCUMENT_PROPERTIES`             | —                                      | mapping a system-block key to the document property it becomes                                |
-| `BLOCK_DIRECTIVES`          | `const BLOCK_DIRECTIVES`                      | —                                      | recognizing a build directive (e.g. `pack`) that names no document property                   |
-| `SYSTEM_BLOCK_KEYS`         | `const SYSTEM_BLOCK_KEYS`                     | —                                      | enumerating every key any system block may carry                                              |
-| `setPath`                   | `setPath(target, dotted, value)`              | `object` — `target`, for chaining      | writing a value at a dotted path in a document's `system` block                               |
-| `systemBlock`               | `systemBlock(fm, block)`                      | `Record<string, unknown> \| undefined` | reading one system's whole block off a note, or nothing when it is absent or malformed        |
-| `carriesSystemBlock`        | `carriesSystemBlock(fm, block)`               | `boolean`                              | deciding whether a pack that declares a system should compile a note at all                   |
-| `systemData`                | `systemData(fm, block)`                       | `Record<string, unknown>`              | reading a system block's `system` sub-block, `{}` when absent                                 |
-| `blockField`                | `blockField(fm, block, key, defaultValue)`    | the value                              | reading a key from one system's block, falling back to the top level                          |
-| `sharedProperty`            | `sharedProperty(fm, source, defaultValue)`    | the value                              | reading a shared top-level property by a possibly-dotted path, blind to every system block    |
-| `blockProperty`             | `blockProperty(fm, block, key, defaultValue)` | the value                              | reading a property a system block may override, else the shared top-level one                 |
-| `legacyKeyOf`               | `legacyKeyOf(field)`                          | `string \| undefined`                  | finding the key a field is authored at inside a system block                                  |
-| `retiredTopLevelKey`        | `retiredTopLevelKey(field)`                   | `string \| undefined`                  | finding the bare top-level key a `data:`-sourced field is being swept off                     |
-| `authoredKey`               | `authoredKey(name)`                           | `string`                               | reading a shared source as the key an author writes, without the `data:` container holding it |
-| `resolveFieldValue`         | `resolveFieldValue(field, fm, ...)`           | `{value, from}`                        | resolving one declared field against a note, in the declared source order                     |
-| `systemDataPaths`           | `systemDataPaths(data, prefix)`               | `string[]`                             | listing every path a note authors under `<system>.system`, containers included                |
-| `undeclaredPaths`           | `undeclaredPaths(data, declared, prefix)`     | `string[]`                             | finding authored paths a system's published schema does not declare                           |
-| `unknownBlockKeys`          | `unknownBlockKeys(fm, block, ...)`            | `string[]`                             | finding keys directly under a system block that neither this format nor the system recognizes |
-| `claimedPaths`              | `claimedPaths(fields)`                        | `Set<string>`                          | listing the exact `system` paths a field declaration writes, for `mergeSystemData`            |
-| `mergeSystemData`           | `mergeSystemData(built, fm, ...)`             | `object` — `built`, for chaining       | merging a note's `<system>.system` verbatim onto a built `system` block                       |
+| Export                      | Signature                                         | Returns                                | Use it when                                                                                   |
+| --------------------------- | ------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `SYSTEM_DATA_KEY`           | `const SYSTEM_DATA_KEY`                           | —                                      | naming the key inside a system block whose contents are the system's own vocabulary           |
+| `BLOCK_DOCUMENT_PROPERTIES` | `const BLOCK_DOCUMENT_PROPERTIES`                 | —                                      | mapping a system-block key to the document property it becomes                                |
+| `BLOCK_DIRECTIVES`          | `const BLOCK_DIRECTIVES`                          | —                                      | recognizing a build directive (e.g. `pack`) that names no document property                   |
+| `SYSTEM_BLOCK_KEYS`         | `const SYSTEM_BLOCK_KEYS`                         | —                                      | enumerating every key any system block may carry                                              |
+| `setPath`                   | `setPath(target, dotted, value)`                  | `object` — `target`, for chaining      | writing a value at a dotted path in a document's `system` block                               |
+| `systemBlock`               | `systemBlock(fm, block)`                          | `Record<string, unknown> \| undefined` | reading one system's whole block off a note, or nothing when it is absent or malformed        |
+| `carriesSystemBlock`        | `carriesSystemBlock(fm, block)`                   | `boolean`                              | deciding whether a pack that declares a system should compile a note at all                   |
+| `systemData`                | `systemData(fm, block)`                           | `Record<string, unknown>`              | reading a system block's `system` sub-block, `{}` when absent                                 |
+| `blockField`                | `blockField(fm, block, key, defaultValue)`        | the value                              | reading a key from one system's block, falling back to the top level                          |
+| `sharedProperty`            | `sharedProperty(fm, source, defaultValue)`        | the value                              | reading a shared top-level property by a possibly-dotted path, blind to every system block    |
+| `blockProperty`             | `blockProperty(fm, block, key, defaultValue)`     | the value                              | reading a property a system block may override, else the shared top-level one                 |
+| `blockDataProperty`         | `blockDataProperty(fm, block, key, defaultValue)` | the value                              | reading a system override, then shared `data`, then a top-level value                         |
+| `legacyKeyOf`               | `legacyKeyOf(field)`                              | `string \| undefined`                  | finding the key a field is authored at inside a system block                                  |
+| `retiredTopLevelKey`        | `retiredTopLevelKey(field)`                       | `string \| undefined`                  | finding the bare top-level key a `data:`-sourced field is being swept off                     |
+| `authoredKey`               | `authoredKey(name)`                               | `string`                               | reading a shared source as the key an author writes, without the `data:` container holding it |
+| `resolveFieldValue`         | `resolveFieldValue(field, fm, ...)`               | `{value, from}`                        | resolving one declared field against a note, in the declared source order                     |
+| `systemDataPaths`           | `systemDataPaths(data, prefix)`                   | `string[]`                             | listing every path a note authors under `<system>.system`, containers included                |
+| `undeclaredPaths`           | `undeclaredPaths(data, declared, prefix)`         | `string[]`                             | finding authored paths a system's published schema does not declare                           |
+| `unknownBlockKeys`          | `unknownBlockKeys(fm, block, ...)`                | `string[]`                             | finding keys directly under a system block that neither this format nor the system recognizes |
+| `claimedPaths`              | `claimedPaths(fields)`                            | `Set<string>`                          | listing the exact `system` paths a field declaration writes, for `mergeSystemData`            |
+| `mergeSystemData`           | `mergeSystemData(built, fm, ...)`                 | `object` — `built`, for chaining       | merging a note's `<system>.system` verbatim onto a built `system` block                       |
 
 ### `engine.codeFences`
 

package/docs/content-format.md

@@ -308,6 +308,12 @@ finding that names the key you meant; the same misspelling at top level would
 silently become a theme parameter, which is exactly why these cannot live
 together.
 
+Every note type may put a pinned document id in `data.id`, a shared compendium
+route in `data.pack`, a shared folder Address in `data.packFolder`, and source
+details in `data.harnworld`. A system block's `pack` or `packFolder` overrides
+the shared value for that system. A `being` may also describe its social profile
+in `data.social`.
+
 **Tags are open, except the ones that classify.** `tags:` shares the top level's
 openness: a tag naming a theme or a region — `underworld`,
 `byzaria`, `riverlands` — is the author's own and this build has no opinion about it.
@@ -569,8 +575,8 @@ type.
 | ----------------------- | ------------------------- | ---------------------------- |
 | `name.full`             | `name`                    | `name`                       |
 | `data.icon`             | `img`                     | `img`                        |
-| `id`                    | `_id`                     | `_id`                        |
-| `packFolder`            | `folder`                  | `folder`                     |
+| `data.id`               | `_id`                     | `_id`                        |
+| `data.packFolder`       | `folder`                  | `folder`                     |
 | `shortcode`             | `system.shortcode`        | NA                           |
 | `data.templatePriority` | `system.templatePriority` | `flags.hm3.templatePriority` |
 | `actionDefs`            | `system.actionDefs`       | NA                           |
@@ -657,16 +663,20 @@ refused at all four slots: a sound is not art, and a value naming one — `icon:
 audio-thunder`, say — is an error naming the set the slot accepts, never a
 silent fall back to the note's default art.
 
-**Two of them are legal on _every_ note**, whatever its type. `data:` is a
+**These properties are legal on _every_ note**, whatever its type. `data:` is a
 closed container and the per-type vocabularies below are the only lists there
 are, so a key legal everywhere is stated once here rather than repeated in
 twenty-five tables where the one that was mistyped would be the one nobody
 noticed:
 
-| shared `data` property | Values    | Description                                                          |
-| ---------------------- | --------- | -------------------------------------------------------------------- |
-| `icon`                 | `Address` | The document's profile art — an `icon` address, resolved into `img`. |
-| `banner`               | `Address` | The page's hero image — an `image` address.                          |
+| shared `data` property | Values                 | Description                                                          |
+| ---------------------- | ---------------------- | -------------------------------------------------------------------- |
+| `id`                   | `string`               | A pinned document identity.                                          |
+| `pack`                 | `string`               | The shared compendium route.                                         |
+| `packFolder`           | `Address` or pack map  | The shared compendium folder Address.                                |
+| `harnworld`            | `Map<string, unknown>` | HârnWorld source details.                                            |
+| `icon`                 | `Address`              | The document's profile art — an `icon` address, resolved into `img`. |
+| `banner`               | `Address`              | The page's hero image — an `image` address.                          |
 
 `icon` is legal everywhere because most types compile into a document that
 carries one; where a type's passes emit none, the lint says so and the value is
@@ -847,10 +857,11 @@ on any type, and the frontmatter lint never reports it.
 
 #### The pack a note compiles into
 
-`pack` names which configured compendium receives the note's document.
+`data.pack` names which configured compendium receives the note's document.
 
 ```yaml
-pack: items-hm3
+data:
+  pack: items-hm3
 ```
 
 It is deliberately close to the retired `package:` and deliberately not the same
@@ -867,7 +878,8 @@ system: each block the note carries sends its own document where that block
 says, and a note carrying two blocks may place them in two packs.
 
 ```yaml
-pack: items-sohl
+data:
+  pack: items-sohl
 hm3:
   pack: items-hm3
 ```
@@ -898,10 +910,11 @@ and in no compendium — a page of developer documentation, a page about the
 package itself:
 
 ```yaml
+shortcode: architecture
 type: doc
 subType: concept
-shortcode: architecture
-pack: none
+data:
+  pack: none
 ```
 
 A link to such a note resolves everywhere the note is addressable. On the web
@@ -1046,16 +1059,17 @@ none. It is the same principle that turned `folder: ONXsqZAIZr2qzxTb` into
 `packFolder: <address>` above: an opaque derived identity does not belong in
 authored content.
 
-**An authored `id` still wins**, and that is how a document's identity is
+**An authored `data.id` wins**, and that is how a document's identity is
 **pinned**:
 
 ```yaml
-type: miscgear
 shortcode: bowlcer
-id: plaiQQm2T5zVK5mO # pinned: this document keeps this id
+type: miscgear
+data:
+  id: plaiQQm2T5zVK5mO # pinned: this document keeps this id
 ```
 
-A blank `id:` is not a pin — it is a deleted value with the key left behind, and
+A blank `data.id:` is not a pin — it is a deleted value with the key left behind, and
 is treated as absent.
 
 **A rename moves the id, and that is the trade.** The address carries the
@@ -1144,7 +1158,8 @@ of the same entry is a warning; the declaration still works.
 A note says which folder of its pack it lands in:
 
 ```yaml
-packFolder: poisonsandtoxins # a folder note's address
+data:
+  packFolder: poisonsandtoxins # a folder note's address
 ```
 
 **`packFolder` is a folder note's address** — an ordinary address, resolved the
@@ -2481,6 +2496,7 @@ Generates a living (or undead, or spirit) being.
 | `templatePriority`          | `number`                                       | Template priority, _null_ = not a template                                                       |
 | `archetypes`                | `Archetype[]`                                  | What sort of character this is. **Always an array** — `[]` where none apply; `null` is an error. |
 | `occupation`                | `string`                                       | Name of the character's occupation                                                               |
+| `social`                    | `Map<string, unknown>`                         | The being's social profile                                                                       |
 | `stations`                  | `Address[]`                                    | Name of the stations the character belongs to                                                    |
 | `lore`                      | `Address[]`                                    | Lore concerning this being — the people it is of, the standing it holds, the law it lives under  |
 | `homes`                     | `Address[]`                                    | Place the being calls home                                                                       |
@@ -2743,7 +2759,8 @@ no Foundry document: it is a page and nothing else.
 It declares a `shortcode` — conventionally `root` — because that is what a
 link is written with: `[[homepage-root|Text]]` is an ordinary wikilink, and it
 resolves to `/<package>/`. The shortcode names the page in links; its address
-is the package root. `title` defaults to `packageBuild.manifest.title`; a
+is the package root. The page heading reads `name.full` and defaults to
+`packageBuild.manifest.title`; a
 `description` and a `banner` are read by the theme's hero; any other
 top-level key is passed through to the page as a theme parameter.
 

package/engine/folder-notes.mjs

@@ -274,7 +274,8 @@ export function collectFolderNotes(notes, pkg) {
 
         const { parent, color } = folderFields(fm);
         const address = folderAddress(pkg, shortcode);
-        const authoredId = fm.id == null ? "" : String(fm.id).trim();
+        const pinnedId = fm.data?.id ?? fm.id;
+        const authoredId = pinnedId == null ? "" : String(pinnedId).trim();
 
         folders.push({
             shortcode,

package/engine/frontmatter.mjs

@@ -348,7 +348,7 @@ export function parseValueDesc(raw) {
 /**
  * The compendium folder a note names.
  *
- * **There is one spelling.** `packFolder:` is a folder note's **address**
+ * `data.packFolder` is a folder note's **address**
  * (`folder-poisonsandtoxins`), resolved through the address index the whole
  * build shares. The `folder:` Foundry-id spelling this function once read
  * beside it, and the per-pack `*-folders.yaml` that id was resolved against,
@@ -372,7 +372,7 @@ export function parseValueDesc(raw) {
  *   two spellings, and there is only one left to be.
  */
 export function folderField(fm) {
-    const asAddress = sohlField(fm, "packFolder", null);
+    const asAddress = fm?.sohl?.packFolder ?? fm?.data?.packFolder ?? fm?.packFolder ?? null;
     if (asAddress != null && asAddress !== "") return { value: asAddress, isAddress: true };
     return { value: null, isAddress: true };
 }

package/engine/homepage.mjs

@@ -340,8 +340,8 @@ function positionOfType(file) {
  * The one defaulted value on the page, and it defaults to the package's own
  * `packageBuild.manifest.title` — the name Foundry already shows for the
  * package — so a homepage that adds nothing to it need not restate it. An
- * authored `title` wins, because a front page is allowed to greet a reader
- * differently from a package browser.
+ * authored `name.full` wins, because a front page may greet a reader
+ * differently from a package browser. A top-level `title` is also readable.
  *
  * Falls back to `contentPackage` last, so a package that has no manifest of its
  * own still yields a titled page rather than a blank heading.
@@ -351,7 +351,7 @@ function positionOfType(file) {
  * @returns {string} The title.
  */
 export function homepageTitle(fm, config) {
-    const authored = fm?.title;
+    const authored = fm?.name?.full ?? fm?.title;
     if (typeof authored === "string" && authored.trim()) return authored;
     const manifest = /** @type {Record<string, unknown>|undefined} */ (
         config?.packageBuild?.manifest

package/engine/item-compiler.mjs

@@ -64,7 +64,12 @@ import { documentSubtype, subtypeRow } from "./document-subtypes.mjs";
 // The note-level `<system>:` block: `<system>.system` onto the document's
 // `system` verbatim, and `<system>.img` / `.effects` / `.flags` overriding
 // their shared top-level forms for this system alone.
-import { blockField, blockProperty, claimedPaths, mergeSystemData } from "./system-block.mjs";
+import {
+    blockDataProperty,
+    blockProperty,
+    claimedPaths,
+    mergeSystemData,
+} from "./system-block.mjs";
 // The other direction of the same declaration: a field the *document* writes in
 // play, which a note may not author and the builder does not emit.
 import { assertNoDerivedFields } from "./derived-fields.mjs";
@@ -379,7 +384,7 @@ export class SystemItemCompiler extends BasePackCompiler {
         // one spelling: `packFolder` names a folder note by its address, the
         // `folder:` id spelling having been retired with the per-pack YAML it
         // resolved against.
-        const folder = this.folderResolver(blockField(fm, system, "packFolder", null), {
+        const folder = this.folderResolver(blockDataProperty(fm, system, "packFolder", null), {
             isAddress: true,
         });
 

package/engine/map-places.mjs

@@ -207,7 +207,9 @@ export function placesFromRecords(records, { contentBase, base }) {
                 folder: record.file?.folder ?? "",
                 package: String(record.package ?? ""),
                 local: true,
-                hasPackFolder: Object.hasOwn(record, "packFolder"),
+                hasPackFolder:
+                    Object.hasOwn(record.data ?? {}, "packFolder") ||
+                    Object.hasOwn(record, "packFolder"),
             });
         } else if (record.type === "affiliation" && record.subType === "polity") {
             polities.push({

package/engine/note-ids.mjs

@@ -105,7 +105,7 @@ function text(value) {
  */
 export function noteDocId(fm, { pkg, maps = KNOWN_DOCUMENT_SUBTYPE_MAPS } = {}) {
     if (!fm || typeof fm !== "object") return undefined;
-    const pinned = text(fm.id);
+    const pinned = text(fm.data?.id) ?? text(fm.id);
     if (pinned) return pinned;
     const type = text(fm.type);
     const shortcode = text(fm.shortcode);

package/engine/note-vocabulary.mjs

@@ -277,6 +277,29 @@ const TOKEN_ICON = Object.freeze({
  * @type {readonly DataFieldSpec[]}
  */
 export const SHARED_DATA_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "id",
+        ...TEXT,
+        describe: "A fixed document identity when the derived identity is unsuitable.",
+    }),
+    Object.freeze({
+        name: "pack",
+        ...TEXT,
+        describe: "The shared compendium route, with a system block overriding it.",
+    }),
+    Object.freeze({
+        name: "packFolder",
+        ...LINK_BY_PACK,
+        ref: "folder",
+        accepts: ["folder"],
+        describe: "The shared compendium folder Address, with a system block overriding it.",
+    }),
+    Object.freeze({
+        name: "harnworld",
+        shape: "map",
+        kind: "map",
+        describe: "HârnWorld source details shared by every system.",
+    }),
     Object.freeze({
         name: "icon",
         ...LINK,
@@ -605,6 +628,7 @@ export const NOTE_VOCABULARY = Object.freeze({
         // package's declared present compute — see `engine/being-age.mjs`.
         check: checkBeingAge,
         data: Object.freeze([
+            { name: "social", shape: "map", kind: "map", describe: "The being's social profile." },
             TOKEN_ICON,
             TEMPLATE_PRIORITY,
             { name: "archetypes", ...LIST, describe: "Archetypal behaviours the being fits." },

package/engine/pack-router.mjs

@@ -82,7 +82,7 @@
 
 import { NO_PACK, packForType } from "./ids.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
-import { blockProperty, systemBlock } from "./system-block.mjs";
+import { blockDataProperty, systemBlock } from "./system-block.mjs";
 
 /**
  * A note that cannot be routed to a pack. Thrown rather than returned so no
@@ -131,7 +131,9 @@ export { NO_PACK };
  */
 export function declaresNoPack(fm, system) {
     const declared =
-        system === undefined ? fm?.[PACK_FIELD] : blockProperty(fm, system, PACK_FIELD);
+        system === undefined ?
+            (fm?.data?.[PACK_FIELD] ?? fm?.[PACK_FIELD])
+        :   blockDataProperty(fm, system, PACK_FIELD);
     return declared === NO_PACK;
 }
 
@@ -270,7 +272,9 @@ export function createPackRouter(packs) {
         const inBlock = system === undefined ? undefined : systemBlock(fm, system)?.[PACK_FIELD];
         const authoredInBlock = inBlock != null && inBlock !== "";
         let declared =
-            system === undefined ? fm?.[PACK_FIELD] : blockProperty(fm, system, PACK_FIELD);
+            system === undefined ?
+                (fm?.data?.[PACK_FIELD] ?? fm?.[PACK_FIELD])
+            :   blockDataProperty(fm, system, PACK_FIELD);
         // The declaration names where the note's *own* document goes. A pass
         // writing a document derived from it — an item's prose becoming a
         // JournalEntry — is not what the author was addressing.

package/engine/system-block.mjs

@@ -361,6 +361,25 @@ export function blockProperty(fm, block, key, defaultValue = undefined) {
     return shared === undefined || shared === null ? defaultValue : shared;
 }
 
+/**
+ * A system override followed by a shared `data:` value. The top-level value
+ * remains readable while content repositories move their authored fields.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - The system block key.
+ * @param {string} key - The shared property.
+ * @param {any} [defaultValue] - Returned when no position declares it.
+ * @returns {any} The selected value.
+ */
+export function blockDataProperty(fm, block, key, defaultValue = undefined) {
+    const declared = systemBlock(fm, block)?.[key];
+    if (declared !== undefined && declared !== null) return declared;
+    const shared = isMapping(fm?.data) ? fm.data[key] : undefined;
+    if (shared !== undefined && shared !== null) return shared;
+    const legacy = isMapping(fm) ? fm[key] : undefined;
+    return legacy === undefined || legacy === null ? defaultValue : legacy;
+}
+
 /**
  * The key a field is authored at **inside** a system block — step 2.
  *

package/hm3/actors.mjs

@@ -63,7 +63,12 @@ import {
 // The note-level `hm3:` block: `hm3.system` onto the document's `system`
 // verbatim, and `hm3.img` / `hm3.items` / `hm3.effects` / `hm3.flags`
 // overriding their shared top-level forms for this system alone.
-import { blockField, blockProperty, mergeSystemData } from "../engine/system-block.mjs";
+import {
+    blockDataProperty,
+    blockField,
+    blockProperty,
+    mergeSystemData,
+} from "../engine/system-block.mjs";
 
 /**
  * Native HM3 facts shared by its actor subtypes.
@@ -324,7 +329,7 @@ export class Hm3Actors extends SystemActorCompiler {
         // by its address. This pass once read only the Foundry id, so an HM3
         // tree could not file an actor by address at all — which its own sweep
         // needs; the id spelling is retired outright.
-        const folder = this.folderResolver(blockField(fm, block, "packFolder", null), {
+        const folder = this.folderResolver(blockDataProperty(fm, block, "packFolder", null), {
             isAddress: true,
         });
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.13.0",
+    "version": "22.13.1",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/frontmatter.d.mts

@@ -149,7 +149,7 @@ export function parseValueDesc(raw: any): {
 /**
  * The compendium folder a note names.
  *
- * **There is one spelling.** `packFolder:` is a folder note's **address**
+ * `data.packFolder` is a folder note's **address**
  * (`folder-poisonsandtoxins`), resolved through the address index the whole
  * build shares. The `folder:` Foundry-id spelling this function once read
  * beside it, and the per-pack `*-folders.yaml` that id was resolved against,

package/types/engine/homepage.d.mts

@@ -119,8 +119,8 @@ export function checkHomepageCount(found: ReadonlyArray<{
  * The one defaulted value on the page, and it defaults to the package's own
  * `packageBuild.manifest.title` — the name Foundry already shows for the
  * package — so a homepage that adds nothing to it need not restate it. An
- * authored `title` wins, because a front page is allowed to greet a reader
- * differently from a package browser.
+ * authored `name.full` wins, because a front page may greet a reader
+ * differently from a package browser. A top-level `title` is also readable.
  *
  * Falls back to `contentPackage` last, so a package that has no manifest of its
  * own still yields a titled page rather than a blank heading.

package/types/engine/system-block.d.mts

@@ -93,6 +93,17 @@ export function sharedProperty(fm: object, source: string, defaultValue?: any):
  * @returns {any} The value.
  */
 export function blockProperty(fm: object, block: string, key: string, defaultValue?: any): any;
+/**
+ * A system override followed by a shared `data:` value. The top-level value
+ * remains readable while content repositories move their authored fields.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - The system block key.
+ * @param {string} key - The shared property.
+ * @param {any} [defaultValue] - Returned when no position declares it.
+ * @returns {any} The selected value.
+ */
+export function blockDataProperty(fm: object, block: string, key: string, defaultValue?: any): any;
 /**
  * The key a field is authored at **inside** a system block — step 2.
  *