@heroiclands/package-build 22.22.0 → 22.24.0

package/engine/content-images.mjs

@@ -58,10 +58,12 @@
  * agree: a figure is a block on all three, and nothing has to decide what a
  * floated run of text inside a paragraph would mean.
  *
- * **The alt text is the caption.** Print has no `alt` attribute and has to put
- * those words somewhere visible; rather than one surface showing them and two
- * hiding them, every surface draws them under the picture, and the HTML
- * surfaces carry them as `alt` as well.
+ * **Alt text renders as a caption on no surface.** A caption is drawn only for
+ * an image inside a `:::figure` fence that carries an authored caption, and the
+ * text drawn is always that caption. An image with no fence, or a fence with no
+ * caption, draws no line under the picture anywhere. The HTML surfaces still
+ * carry the alt text as the `img` element's `alt` attribute, for the reader a
+ * screen reader serves.
  *
  * ## Where the address resolves
  *
@@ -79,7 +81,9 @@ import path from "node:path";
 import { matchAllOutsideCode } from "./code-fences.mjs";
 import { parseExtensionAttributes } from "./extension-attributes.mjs";
 import { positionInBody } from "./diagnostics.mjs";
+import { FOOTNOTE_REFERENCE } from "./content-footnotes.mjs";
 import { foundryAddressProblem, pathnameProblem, servesFoundry } from "./pathnames.mjs";
+import { ASSET_ROLES } from "./asset-index.mjs";
 
 /**
  * The width classes an image may carry, and what each means to a renderer.
@@ -273,13 +277,27 @@ export function parseImageDirective(raw) {
 }
 
 /**
- * The classes a figure carries, from a parsed directive.
+ * The class a picture's role names, or `""` for no role or one outside the
+ * closed set — the same silent-degrade rule every other unrecognised value
+ * here gets, since a role this far downstream has already been validated or
+ * dropped by the asset record that carries it.
  *
- * @param {{classes?: string[], size?: string, float?: string}} [directive] - As parsed.
+ * @param {string} [role] - The role, from the resolved asset record.
+ * @returns {string} The class, or `""`.
+ */
+export function roleClass(role) {
+    return role && ASSET_ROLES.includes(role) ? `note-image-role-${role}` : "";
+}
+
+/**
+ * The classes a figure carries, from a parsed directive and its asset's role.
+ *
+ * @param {{classes?: string[], size?: string, float?: string, role?: string}} [directive] -
+ *   As parsed, plus the role the resolved asset record carries, if any.
  * @returns {string} A space-separated class list, always naming
  *   {@link IMAGE_FIGURE_CLASS} first.
  */
-export function figureClasses({ classes = [], size = "auto", float = "" } = {}) {
+export function figureClasses({ classes = [], size = "auto", float = "", role = "" } = {}) {
     const names = [IMAGE_FIGURE_CLASS];
     for (const name of classes) {
         const spec = IMAGE_CLASSES[/** @type {keyof typeof IMAGE_CLASSES} */ (name)];
@@ -288,6 +306,8 @@ export function figureClasses({ classes = [], size = "auto", float = "" } = {})
     if (size !== "auto" && IMAGE_SIZES.includes(size)) names.push(`note-image-size-${size}`);
     const position = IMAGE_FLOATS[/** @type {keyof typeof IMAGE_FLOATS} */ (float)];
     if (position) names.push(position.class);
+    const roleName = roleClass(role);
+    if (roleName) names.push(roleName);
     return names.join(" ");
 }
 
@@ -313,30 +333,85 @@ export function escapeHtml(text) {
  * function, so the two cannot drift into styling the same directive through
  * different class names.
  *
+ * **No `<figcaption>` is emitted here.** A `:::figure` fence draws its own
+ * label and authored caption around whatever this returns; the alt text stays
+ * on the `img` element alone.
+ *
+ * **The role class and the `width`/`height` attributes are what a stylesheet
+ * elsewhere keys a role's size on.** This module states none — the measure a
+ * `portrait` fills on a page is a Hugo theme's or a Foundry system's own
+ * decision — and emits only what the resolved asset record states: a role
+ * class when the picture declares one, and the attributes whenever the
+ * picture resolved to an asset record at all, blank for a vector. The
+ * attributes reserve the picture's own layout space before it loads, which is
+ * what lets a page avoid reflowing as pictures load in.
+ *
  * @param {object} image - The image.
  * @param {string} image.src - The address, resolved for the surface.
- * @param {string} [image.alt] - The alt text, which is also the caption.
+ * @param {string} [image.alt] - The alt text, for a reader who cannot see the
+ *   picture.
  * @param {string[]} [image.classes] - Width classes, from the directive.
  * @param {string} [image.size] - Named display size, from the directive.
  * @param {string} [image.float] - The float position, from the directive.
+ * @param {string} [image.role] - The picture's declared role, from the
+ *   resolved asset record.
+ * @param {number|""} [image.width] - The file's own pixel width, from the
+ *   resolved asset record; `""` for a vector. Omitted entirely when the
+ *   address resolved to no asset record at all.
+ * @param {number|""} [image.height] - As `width`.
  * @returns {string} The figure, as one HTML block.
  */
-export function imageFigureHtml({ src, alt = "", classes = [], size = "auto", float = "" }) {
-    const caption = alt ? `\n<figcaption>${escapeHtml(alt)}</figcaption>` : "";
+export function imageFigureHtml({
+    src,
+    alt = "",
+    classes = [],
+    size = "auto",
+    float = "",
+    role = "",
+    width,
+    height,
+}) {
+    const dims =
+        width !== undefined && height !== undefined ?
+            ` width="${escapeHtml(String(width))}" height="${escapeHtml(String(height))}"`
+        :   "";
     return (
-        `<figure class="${figureClasses({ classes, size, float })}">\n` +
-        `<img src="${escapeHtml(src)}" alt="${escapeHtml(alt)}">${caption}\n` +
+        `<figure class="${figureClasses({ classes, size, float, role })}">\n` +
+        `<img src="${escapeHtml(src)}" alt="${escapeHtml(alt)}"${dims}>\n` +
         `</figure>`
     );
 }
 
+/**
+ * A body extension's own delimiter — a `:::` opener or closer, or a figure's
+ * `///`.
+ *
+ * It bounds a paragraph exactly as a blank line does: the line belongs to the
+ * construct rather than to the prose, and the pass that owns the construct
+ * hands its body on by itself. So a picture written tight against one is a
+ * block of its own, which is how `:::figure` is written.
+ */
+const DELIMITER = /^(?::{3,}[^\n]*|\/{3,}[ \t]*)$/;
+
+/**
+ * A footnote reference immediately trailing a match, anchored so it only
+ * consumes one sitting right against the end of it.
+ */
+const TRAILING_FOOTNOTE_REFERENCE = new RegExp(`^${FOOTNOTE_REFERENCE.source}`);
+
 /**
  * Whether a match sits alone in its own paragraph.
  *
- * "Alone" is the whole of a block: nothing else on its line, and a blank line
- * or the end of the body either side of it. A leading `>` or list marker
- * disqualifies it for the same reason a word does — the paragraph it belongs to
- * holds something the figure would have to be lifted out of.
+ * "Alone" is the whole of a block: nothing else on its line, and a blank line,
+ * a body-extension delimiter or the end of the body either side of it. A
+ * leading `>` or list marker disqualifies it for the same reason a word does —
+ * the paragraph it belongs to holds something the figure would have to be
+ * lifted out of.
+ *
+ * **A footnote reference trailing the match is not "other text."** `[^note]`
+ * annotates the picture rather than sitting beside it in prose, the same
+ * standing its own directive already has, so `![A ranger](r.webp)[^note]` is
+ * still alone.
  *
  * @param {string} text - The body the match indexes into.
  * @param {number} start - Where the match begins.
@@ -350,12 +425,18 @@ export function standsAlone(text, start, end) {
     // makes it an indented code block, which `matchAllOutsideCode` skips.
     if (!/^[ \t]*$/.test(src.slice(lineStart, start))) return false;
     const lineEnd = src.indexOf("\n", end);
-    if (!/^[ \t]*$/.test(src.slice(end, lineEnd === -1 ? src.length : lineEnd))) return false;
+    const afterMatch = src.slice(end, lineEnd === -1 ? src.length : lineEnd);
+    const reference = TRAILING_FOOTNOTE_REFERENCE.exec(afterMatch);
+    if (!/^[ \t]*$/.test(reference ? afterMatch.slice(reference[0].length) : afterMatch))
+        return false;
 
     const before = src.slice(0, lineStart);
-    if (before.trim() && !/\n[ \t]*\n[ \t]*$/.test(before)) return false;
+    const previous = before.replace(/\n$/, "").split("\n").pop() ?? "";
+    if (before.trim() && !/\n[ \t]*\n[ \t]*$/.test(before) && !DELIMITER.test(previous))
+        return false;
     const after = lineEnd === -1 ? "" : src.slice(lineEnd);
-    if (after.trim() && !/^\n[ \t]*\n/.test(after)) return false;
+    const next = after.replace(/^\n/, "").split("\n")[0] ?? "";
+    if (after.trim() && !/^\n[ \t]*\n/.test(after) && !DELIMITER.test(next)) return false;
     return true;
 }
 
@@ -414,6 +495,9 @@ export function imageSourcesIn(body) {
  * @param {object} [opts]
  * @param {number} [opts.bodyLine=1] - The 1-based file line the body starts on.
  * @param {number} [opts.bodyColumn=1] - The 1-based file column it starts at.
+ * @param {Array<{line: number, generated: boolean}>} [opts.lineMap] - From
+ *   table expansion, mapping each line of `body` back to the line an author
+ *   wrote, for a caller handing in a body whose tables already expanded.
  * @param {object} [opts.config] - The resolved build configuration. Supplied,
  *   an address is also held to the one surface a pathname can be dead on
  *   without any other pass noticing — see the Foundry address below. Omitted,
@@ -423,7 +507,7 @@ export function imageSourcesIn(body) {
  *   severity: "error", message: string}>} One finding per defect, in source
  *   order.
  */
-export function checkImages(body, file, { bodyLine = 1, bodyColumn = 1, config } = {}) {
+export function checkImages(body, file, { bodyLine = 1, bodyColumn = 1, lineMap, config } = {}) {
     const text = String(body ?? "");
     if (!text) return [];
 
@@ -434,7 +518,7 @@ export function checkImages(body, file, { bodyLine = 1, bodyColumn = 1, config }
      * @param {string} message - What is wrong.
      */
     const report = (offset, message) => {
-        const { line, column } = positionInBody(text, offset, { bodyLine, bodyColumn });
+        const { line, column } = positionInBody(text, offset, { bodyLine, bodyColumn, lineMap });
         findings.push({ file, line, column, severity: /** @type {"error"} */ ("error"), message });
     };
 
@@ -454,7 +538,7 @@ export function checkImages(body, file, { bodyLine = 1, bodyColumn = 1, config }
             report(
                 image.index,
                 `\`"${image.title}"\` is a title on an image, and no surface here draws ` +
-                    "one — an image's alt text is its caption",
+                    "one — a caption is written in a `:::figure` fence's /// section",
             );
         }
         if (!image.block) {
@@ -587,9 +671,13 @@ export function lintContentImages(contentBase, { skipDirectories = [], config }
  * @param {(src: string) => string} [resolveSrc] - Translates an authored
  *   pathname into the address this surface serves. The default is the identity,
  *   for a caller rendering the format rather than publishing it.
+ * @param {(src: string) => {type?: string, role?: string, width?: number|"", height?: number|""}|undefined}
+ *   [lookupAsset] - What the resolved asset record says about the address, as
+ *   authored — before `resolveSrc` translates it. The default answers nothing,
+ *   which is what an address resolving to no asset record gets anyway.
  * @returns {string} The same body, with each block image as a `<figure>`.
  */
-export function renderImageFigures(body, resolveSrc = (src) => src) {
+export function renderImageFigures(body, resolveSrc = (src) => src, lookupAsset = () => undefined) {
     const text = String(body ?? "");
     let out = "";
     let last = 0;
@@ -598,12 +686,16 @@ export function renderImageFigures(body, resolveSrc = (src) => src) {
         const { classes, size, float, problems } = parseImageDirective(image.directive);
         if (problems.length) continue;
         out += text.slice(last, image.index);
+        const asset = lookupAsset(image.src);
         out += imageFigureHtml({
             src: resolveSrc(image.src),
             alt: image.alt,
             classes,
             size,
             float,
+            role: asset?.role,
+            width: asset?.width,
+            height: asset?.height,
         });
         last = image.index + image.length;
     }
@@ -632,9 +724,13 @@ export function renderImageFigures(body, resolveSrc = (src) => src) {
  *   address into the one this surface serves. Foundry is handed the path inside
  *   the install; a renderer that resolves the address itself — the book stages
  *   its own copy — passes nothing and gets the address as authored.
+ * @param {(src: string) => {type?: string, role?: string, width?: number|"", height?: number|""}|undefined}
+ *   [lookupAsset] - What the resolved asset record says about the address, as
+ *   authored — before `resolveSrc` runs. The default answers nothing, which is
+ *   what an address resolving to no asset record gets anyway.
  * @returns {(md: object) => void} A markdown-it plugin.
  */
-export function imagePlugin(resolveSrc = (src) => src) {
+export function imagePlugin(resolveSrc = (src) => src, lookupAsset = () => undefined) {
     return (md) => {
         /** @type {any} */ (md).core.ruler.push("heroiclands_image", (state) => {
             attachImageDirectives(state.tokens);
@@ -649,12 +745,17 @@ export function imagePlugin(resolveSrc = (src) => src) {
         ) => {
             const token = tokens[idx];
             if (!token.meta?.block) return base(tokens, idx, options, env, self);
+            const src = token.attrGet("src") ?? "";
+            const asset = lookupAsset(src);
             return `${imageFigureHtml({
-                src: resolveSrc(token.attrGet("src") ?? ""),
+                src: resolveSrc(src),
                 alt: token.content ?? "",
                 classes: token.meta.classes,
                 size: token.meta.size,
                 float: token.meta.float,
+                role: asset?.role,
+                width: asset?.width,
+                height: asset?.height,
             })}\n`;
         };
     };

package/engine/content-index.mjs

@@ -104,6 +104,8 @@ import { checkForeignAssetBindings } from "./asset-bindings.mjs";
 import { addressSlug, canonicalKey } from "./content-address.mjs";
 import { ownDocumentSystem } from "./address.mjs";
 import { NOTE_SYSTEM } from "./systems.mjs";
+import { assetAddressIndex } from "./art-fields.mjs";
+import { embedRole } from "./content-embeds.mjs";
 // One reader for a note's anchors, shared with the link checker and with the
 // builds that emit a link. Re-exported because this is where callers
 // have always addressed it.
@@ -443,6 +445,10 @@ function assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage) {
  *   entries are derived against.
  * @param {object} [options.addressContext] - Address resolution context.
  * @param {object} [options.dateContext] - Calendar conversion context.
+ * @param {(address: string) => string|undefined} [options.resolveRole] - From
+ *   a picture's address to the role its asset declares, so a figure anchor's
+ *   `name` reads `Map 1` rather than `Figure 1` where it is due — see
+ *   {@link module:engine/content-figures.scanFigures}.
  * @returns {Record<string, any>} The record, keys sorted at every depth. A
  *   **stub** — a note with an empty body, on a type an empty body suppresses —
  *   carries `address` and `anchors` as `null`: it publishes no page, so it
@@ -464,6 +470,7 @@ export function buildIndexRecord({
     manifest,
     addressContext,
     dateContext,
+    resolveRole,
 }) {
     assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage);
 
@@ -514,7 +521,7 @@ export function buildIndexRecord({
                 // there rather than search for the heading.
                 anchors:
                     stub ? null : (
-                        collectAnchors(body, bodyLine).map((a) => ({
+                        collectAnchors(body, bodyLine, resolveRole).map((a) => ({
                             ...a,
                             link: address ? `${address.slug}#${a.slug}` : null,
                         }))
@@ -615,6 +622,7 @@ export function indexRecordsForNote({
     manifest,
     addressContext,
     dateContext,
+    resolveRole,
 }) {
     resolveNoteId(frontmatter, { pkg: contentPackage });
     const record = buildIndexRecord({
@@ -627,6 +635,7 @@ export function indexRecordsForNote({
         manifest,
         addressContext,
         dateContext,
+        resolveRole,
     });
     const records = [decodeIndexAddresses(record, addressContext ?? { package: contentPackage })];
     const address = noteAddress(frontmatter, contentPackage);
@@ -726,7 +735,24 @@ export function collectContentIndex(
     // this same walk states one — the whole tree is already in memory, so no
     // second read is needed to answer a question about all of it.
     const present = presentAmongFrontmatters(parsedNotes.map((n) => n.frontmatter));
-    const dates = reckoningContext({ notes: parsedNotes.map((n) => n.frontmatter) });
+    // Carried on the same context `resolvedDateFields` reads: a recurring
+    // event's `next` is computed against this present exactly as a being's
+    // `age` already is, above.
+    const dates = {
+        ...reckoningContext({ notes: parsedNotes.map((n) => n.frontmatter) }),
+        present,
+    };
+
+    // Walked ahead of the notes, rather than after them as the records
+    // themselves are emitted: a note's anchors are collected below, and a
+    // figure fence's `map` counter needs this package's own asset roles
+    // before the first note is read, the same precedent the book's own
+    // cross-file numbering sets. A package with no `assetsBase` resolves no
+    // role, which is the one it would have resolved anyway.
+    const assetRecords =
+        assetsBase ? collectAssetRecords(assetsBase, { contentPackage, problems }) : [];
+    const assetIndex = assetAddressIndex(assetRecords, { config: { contentPackage } });
+    const resolveRole = (address) => embedRole(assetIndex, address);
 
     for (const { frontmatter, body, bodyLine, absPath } of parsedNotes) {
         const fm = frontmatter ?? {};
@@ -744,6 +770,7 @@ export function collectContentIndex(
                     manifest,
                     addressContext,
                     dateContext: dates,
+                    resolveRole,
                 }),
             );
         } catch (err) {
@@ -776,14 +803,13 @@ export function collectContentIndex(
         }
     }
 
-    if (assetsBase) {
-        // Sorted at every depth like a note's record, and for the same reason:
-        // the declaration order of the `asset` fields is a fact about the
-        // emitter, not about the content, and the artifact is meant to be
-        // byte-identical across two runs over an unchanged tree.
-        for (const record of collectAssetRecords(assetsBase, { contentPackage, problems })) {
-            records.push(/** @type {Record<string, any>} */ (sortKeysDeep(record)));
-        }
+    // Sorted at every depth like a note's record, and for the same reason: the
+    // declaration order of the `asset` fields is a fact about the emitter, not
+    // about the content, and the artifact is meant to be byte-identical across
+    // two runs over an unchanged tree. Collected above, ahead of the notes —
+    // see `resolveRole` — rather than walked a second time here.
+    for (const record of assetRecords) {
+        records.push(/** @type {Record<string, any>} */ (sortKeysDeep(record)));
     }
 
     // Source path, then the canonical address, then the note id. The walk

package/engine/field-reference.mjs

@@ -123,16 +123,41 @@ function fieldTable(fields) {
     return padTable(rows);
 }
 
+/**
+ * The one line explaining why a single field's shared top-level fallback is
+ * off.
+ *
+ * **The field's reason stands on its own** — a complete sentence, or more
+ * than one — rather than completing a clause the frame starts. A field that
+ * collides with a top-level spelling meaning something else can say so
+ * ("`weight` is the item's own, independent of the note's."); a field whose
+ * top-level spelling is refused outright by the closed vocabulary can say
+ * that instead, honestly, which "there it means …" cannot: a refused key
+ * carries no meaning to report.
+ *
+ * Exported so a guard can walk every field declaring `topLevelMeans` across
+ * every registry and check that each one composes into a grammatical
+ * sentence, without reimplementing the frame it is checking.
+ *
+ * @param {import("./field-spec.mjs").FieldSpec} field - A field declaring
+ *   `topLevelMeans`.
+ * @returns {string} The composed markdown line.
+ */
+export function topLevelExemptionLine(field) {
+    return `**\`${field.name}\` is not read from the note's top level.** ${field.topLevelMeans}`;
+}
+
 /**
  * The fields of one type that are **not** filled from the note's top level.
  *
  * A field ordinarily falls back to the top-level property spelled like its
  * name, so an author who writes `weight: 3` at the top of a note reasonably
- * expects it to reach the document. Where that spelling means something else at
- * the note level the fallback is off, and an author has no way to tell from the
- * table — the field is there, the value is written, and the document ships the
- * default. So the reason each such field declares is rendered beside its table
- * rather than left in the source.
+ * expects it to reach the document. Where that spelling is wrong at the note
+ * level — it means something else there, or the closed top-level vocabulary
+ * refuses it outright — the fallback is off, and an author has no way to tell
+ * from the table — the field is there, the value is written, and the document
+ * ships the default. So the reason each such field declares is rendered
+ * beside its table rather than left in the source.
  *
  * Below the table, not inside it: the reason is a sentence or two, and
  * {@link padTable} pads every column to its widest cell, so a cell holding it
@@ -144,11 +169,7 @@ function fieldTable(fields) {
 function sharedExemptions(fields) {
     const exempt = authoredFields(fields).filter((field) => field.topLevelMeans);
     if (!exempt.length) return [];
-    return exempt.flatMap((field) => [
-        `**\`${field.name}\` is not read from the note's top level.** There it means ` +
-            `${field.topLevelMeans}`,
-        "",
-    ]);
+    return exempt.flatMap((field) => [topLevelExemptionLine(field), ""]);
 }
 
 /**

package/engine/field-spec.mjs

@@ -84,19 +84,21 @@ export { legacyKeyOf, retiredTopLevelKey, setPath };
  *   retiring one — so a field can move into `data:` while the corpus catches
  *   up, instead of on a flag day across four repositories. A declaration that
  *   names one is mid-sweep by construction; see {@link readsLegacyKey}.
- * @property {string} [topLevelMeans] - **What the note's top-level key of this
- *   name means instead** — declared only where it means something else, and
- *   stating it removes the shared top-level position from this field's
- *   resolution order.
+ * @property {string} [topLevelMeans] - **Why the note's top-level key of this
+ *   name is not this field's source** — declared wherever that key's spelling
+ *   means something else at the note level, or the closed top-level
+ *   vocabulary refuses it outright, and stating either removes the shared
+ *   top-level position from this field's resolution order.
  *
  *   A field's `name` doubles as its identity and as the shared property it
  *   draws from, which is right wherever the two levels state the same quantity
  *   — `data.weight` is the weight, whoever reads it. It is wrong wherever a
- *   spelling collides across the two vocabularies. An `affiliation` item's
+ *   spelling collides across the two vocabularies, or names a key the closed
+ *   top-level vocabulary does not admit at all. An `affiliation` item's
  *   `system.title` is the style of address an office carries; a note's
- *   top-level `title` is the note's own heading. Nothing relates them, and
- *   before this key one silently fed the other, stringifying an authored
- *   `title: null` into fifteen documents.
+ *   top-level `title` is refused outright. Nothing relates them, and before
+ *   this key one silently fed the other, stringifying an authored `title:
+ *   null` into fifteen documents.
  *
  *   **The value is the reason**, not a flag with a comment beside it. A boolean
  *   would record the decision and lose the case for it, and the next person