@heroiclands/package-build 22.22.0 → 22.23.0

package/engine/asset-types.mjs

@@ -46,6 +46,8 @@
  * @module
  */
 
+import fs from "node:fs";
+
 import { ADDRESS_SEGMENT_PATTERN } from "./address-charset.mjs";
 
 /**
@@ -190,3 +192,241 @@ export function assetTypeOfRoot(root) {
 export function isAssetShortcode(shortcode) {
     return typeof shortcode === "string" && ADDRESS_SEGMENT_PATTERN.test(shortcode);
 }
+
+/**
+ * The PNG (and APNG, which shares the signature) header.
+ *
+ * @param {Buffer} bytes
+ * @returns {{width: number, height: number}|undefined}
+ */
+function pngDimensions(bytes) {
+    if (bytes.length < 24) return undefined;
+    if (bytes.toString("hex", 0, 8) !== "89504e470d0a1a0a") return undefined;
+    return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+}
+
+/**
+ * The GIF header's logical screen size.
+ *
+ * @param {Buffer} bytes
+ * @returns {{width: number, height: number}|undefined}
+ */
+function gifDimensions(bytes) {
+    if (bytes.length < 10) return undefined;
+    const signature = bytes.toString("ascii", 0, 6);
+    if (signature !== "GIF87a" && signature !== "GIF89a") return undefined;
+    return { width: bytes.readUInt16LE(6), height: bytes.readUInt16LE(8) };
+}
+
+/**
+ * The BMP header's size, carried as a signed value so a bottom-up bitmap's
+ * negative height still reads as a pixel count.
+ *
+ * @param {Buffer} bytes
+ * @returns {{width: number, height: number}|undefined}
+ */
+function bmpDimensions(bytes) {
+    if (bytes.length < 26) return undefined;
+    if (bytes.toString("ascii", 0, 2) !== "BM") return undefined;
+    return {
+        width: Math.abs(bytes.readInt32LE(18)),
+        height: Math.abs(bytes.readInt32LE(22)),
+    };
+}
+
+/**
+ * The size a JPEG's first SOF (start-of-frame) segment states, found by
+ * walking its markers rather than assuming a fixed offset — a JPEG carries an
+ * arbitrary run of metadata segments before the frame header.
+ *
+ * @param {Buffer} bytes
+ * @returns {{width: number, height: number}|undefined}
+ */
+function jpegDimensions(bytes) {
+    if (bytes.length < 4 || bytes.readUInt16BE(0) !== 0xffd8) return undefined;
+    let pos = 2;
+    while (pos + 1 < bytes.length) {
+        if (bytes[pos] !== 0xff) return undefined;
+        const marker = bytes[pos + 1];
+        pos += 2;
+        // TEM and the restart markers carry no segment length; EOI ends the
+        // stream with no frame header found.
+        if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) continue;
+        if (marker === 0xd9) return undefined;
+        if (pos + 2 > bytes.length) return undefined;
+        const length = bytes.readUInt16BE(pos);
+        const isStartOfFrame =
+            marker >= 0xc0 &&
+            marker <= 0xcf &&
+            marker !== 0xc4 &&
+            marker !== 0xc8 &&
+            marker !== 0xcc;
+        if (isStartOfFrame) {
+            if (pos + 7 > bytes.length) return undefined;
+            return { height: bytes.readUInt16BE(pos + 3), width: bytes.readUInt16BE(pos + 5) };
+        }
+        pos += length;
+    }
+    return undefined;
+}
+
+/**
+ * A WebP file's size, read from whichever of the three chunk layouts the
+ * format defines — the plain lossy frame, the lossless bitstream, or the
+ * extended header a file with alpha, animation or metadata carries instead.
+ *
+ * @param {Buffer} bytes
+ * @returns {{width: number, height: number}|undefined}
+ */
+function webpDimensions(bytes) {
+    if (bytes.length < 30) return undefined;
+    if (bytes.toString("ascii", 0, 4) !== "RIFF" || bytes.toString("ascii", 8, 12) !== "WEBP") {
+        return undefined;
+    }
+    const chunk = bytes.toString("ascii", 12, 16);
+    if (chunk === "VP8 ") {
+        return {
+            width: bytes.readUInt16LE(26) & 0x3fff,
+            height: bytes.readUInt16LE(28) & 0x3fff,
+        };
+    }
+    if (chunk === "VP8L") {
+        const bits = bytes.readUInt32LE(21);
+        return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 };
+    }
+    if (chunk === "VP8X") {
+        return {
+            width: (bytes[24] | (bytes[25] << 8) | (bytes[26] << 16)) + 1,
+            height: (bytes[27] | (bytes[28] << 8) | (bytes[29] << 16)) + 1,
+        };
+    }
+    return undefined;
+}
+
+/**
+ * A TIFF's `ImageWidth`/`ImageLength` tags, read from its first IFD in
+ * whichever byte order the file's own header declares.
+ *
+ * @param {Buffer} bytes
+ * @returns {{width: number, height: number}|undefined}
+ */
+function tiffDimensions(bytes) {
+    if (bytes.length < 8) return undefined;
+    const order = bytes.toString("ascii", 0, 2);
+    let little;
+    if (order === "II") little = true;
+    else if (order === "MM") little = false;
+    else return undefined;
+    const u16 = (offset) => (little ? bytes.readUInt16LE(offset) : bytes.readUInt16BE(offset));
+    const u32 = (offset) => (little ? bytes.readUInt32LE(offset) : bytes.readUInt32BE(offset));
+    if (u16(2) !== 42) return undefined;
+    const ifd = u32(4);
+    if (ifd + 2 > bytes.length) return undefined;
+    const entryCount = u16(ifd);
+    let width;
+    let height;
+    for (let i = 0; i < entryCount && (width === undefined || height === undefined); i++) {
+        const entry = ifd + 2 + i * 12;
+        if (entry + 12 > bytes.length) break;
+        const tag = u16(entry);
+        if (tag !== 256 && tag !== 257) continue;
+        // SHORT (type 3) values sit in the first two bytes of the value
+        // field; LONG (type 4) occupies all four, so only the width in that
+        // field differs by type.
+        const type = u16(entry + 2);
+        const value = type === 3 ? u16(entry + 8) : u32(entry + 8);
+        if (tag === 256) width = value;
+        else height = value;
+    }
+    return width !== undefined && height !== undefined ? { width, height } : undefined;
+}
+
+/**
+ * An AVIF's declared size, read from the first `ispe` (Image Spatial
+ * Extents) property its ISOBMFF container carries, by walking box headers
+ * down through `meta` → `iprp` → `ipco` rather than assuming a fixed layout.
+ *
+ * @param {Buffer} bytes
+ * @returns {{width: number, height: number}|undefined}
+ */
+function avifDimensions(bytes) {
+    /** @type {{width: number, height: number}|undefined} */
+    let found;
+    const walk = (start, end) => {
+        let pos = start;
+        while (!found && pos + 8 <= end) {
+            const size = bytes.readUInt32BE(pos);
+            if (size < 8) return;
+            const type = bytes.toString("ascii", pos + 4, pos + 8);
+            const dataStart = pos + 8;
+            const dataEnd = Math.min(pos + size, end);
+            if (type === "meta") {
+                // `meta` is a full box: four bytes of version and flags
+                // precede its own nested boxes.
+                walk(dataStart + 4, dataEnd);
+            } else if (type === "iprp" || type === "ipco") {
+                walk(dataStart, dataEnd);
+            } else if (type === "ispe" && dataEnd - dataStart >= 12) {
+                found = {
+                    width: bytes.readUInt32BE(dataStart + 4),
+                    height: bytes.readUInt32BE(dataStart + 8),
+                };
+            }
+            pos += size;
+        }
+    };
+    walk(0, bytes.length);
+    return found;
+}
+
+/**
+ * The pixel dimensions a raster image's own header states.
+ *
+ * Read from the file's bytes directly rather than through a decoder, so a
+ * corrupt or partial file fails closed — the same `undefined` answer as a
+ * format this carries no reader for — instead of throwing out of the asset
+ * walk. An SVG has no pixel dimensions to read; stating one would be a
+ * fabricated viewBox reading rather than a fact about the file.
+ *
+ * @param {string} absPath - The file's absolute path.
+ * @param {string} ext - Its extension, lowercase and dot-led.
+ * @returns {{width: number, height: number}|undefined} The declared size, or
+ *   `undefined` when the format carries none, or the header cannot be read.
+ */
+export function imageDimensions(absPath, ext) {
+    if (ext === ".svg") return undefined;
+    const reader = IMAGE_DIMENSION_READERS[ext];
+    if (!reader) return undefined;
+    let bytes;
+    try {
+        bytes = fs.readFileSync(absPath);
+    } catch {
+        return undefined;
+    }
+    try {
+        return reader(bytes);
+    } catch {
+        // A header this short or this malformed to parse is the same answer
+        // as one this reads no format for: the dimensions stay blank.
+        return undefined;
+    }
+}
+
+/**
+ * The dimension reader for each raster extension {@link IMAGE_EXTENSIONS}
+ * declares, `.svg` excepted — it has no pixel dimensions, handled above
+ * rather than entered here.
+ *
+ * @type {Readonly<Record<string, (bytes: Buffer) => ({width: number, height: number}|undefined)>>}
+ */
+const IMAGE_DIMENSION_READERS = Object.freeze({
+    ".png": pngDimensions,
+    ".apng": pngDimensions,
+    ".gif": gifDimensions,
+    ".bmp": bmpDimensions,
+    ".jpg": jpegDimensions,
+    ".jpeg": jpegDimensions,
+    ".webp": webpDimensions,
+    ".tiff": tiffDimensions,
+    ".avif": avifDimensions,
+});

package/engine/base-compiler.mjs

@@ -64,8 +64,9 @@
 import { authoredFrontmatter } from "./index-records.mjs";
 import { scanBlocks } from "./content-blocks.mjs";
 import { scanHeadingAttributes, withheldSections } from "./heading-attributes.mjs";
-import { scanCaptions } from "./content-captions.mjs";
+import { scanFigures } from "./content-figures.mjs";
 import { footnoteFindings } from "./content-footnotes.mjs";
+import { checkImages } from "./content-images.mjs";
 import { renderMarkdownExpressions } from "./markdown-expressions.mjs";
 import { isGmNote } from "./note-vocabulary.mjs";
 import { cloneAddressState } from "./address-values.mjs";
@@ -125,6 +126,25 @@ import { reckoningContext } from "./reckoning-markers.mjs";
  *   says nothing about. Counted as errors, never as skips.
  */
 
+/**
+ * A `ref` call's Foundry rendering: a same-page wikilink rather than a
+ * Markdown link, so the wikilink pass that runs after expressions render
+ * addresses it exactly as an authored `[[#anchor|Text]]` is — by the
+ * JournalEntryPage the figure's own fence became, whether that page holds
+ * only the figure or carries it alongside other prose. A Markdown link's
+ * `#anchor` fragment resolves nowhere in Foundry, which addresses a page by
+ * UUID and an anchor within a page by that page's own anchor; this is why the
+ * two surfaces do not share a renderer.
+ *
+ * @param {{anchor: string}} target - The figure's own anchor.
+ * @param {string} label - The link's text, which may itself carry Markdown.
+ * @returns {string} `[[#anchor|label]]`, with a literal `|` in the label
+ *   escaped so it cannot be read as the wikilink's own separator.
+ */
+function foundryRefLink({ anchor }, label) {
+    return `[[#${anchor}|${label.replace(/\|/g, "\\|")}]]`;
+}
+
 /**
  * The shared walk → filter → expand → convert → build → write → count loop.
  *
@@ -699,6 +719,22 @@ export class BasePackCompiler {
                     :   footnoteError.column,
             });
         }
+        // An image sharing its paragraph with other text, a bad address or a
+        // title with nowhere to draw it — the same findings `lint` reports,
+        // asked here too so a build run on its own refuses what the lint
+        // already names rather than rendering the directive as though it were
+        // absent. `checkImages` already resolves `bodyLine` and `bodyColumn`
+        // internally, so its findings need no further adjustment.
+        for (const imageError of checkImages(body, "", {
+            bodyLine: this.currentNote?.bodyLine ?? 1,
+            bodyColumn: this.currentNote?.bodyColumn ?? 1,
+        })) {
+            findings.push({
+                message: imageError.message,
+                line: imageError.line,
+                column: imageError.column,
+            });
+        }
         if (!this.constructor.convertsWikilinks) {
             this.reportConvertBodyFindings(findings);
             return body;
@@ -711,7 +747,8 @@ export class BasePackCompiler {
             sqlTables: absPath ? this.sqlTables?.get(absPath) : undefined,
             pageLists: absPath ? this.sqlTables?.pageLists?.get(absPath) : undefined,
         });
-        for (const captionError of scanCaptions(tabulated).errors) {
+        const figureScan = scanFigures(tabulated);
+        for (const captionError of figureScan.errors) {
             findings.push({
                 message: captionError.message,
                 line:
@@ -720,12 +757,27 @@ export class BasePackCompiler {
                 column: captionError.column,
             });
         }
+        // What the `ref` expression helper needs: this note's own figures, by
+        // id, and how a reference renders — a same-page wikilink rather than
+        // a Markdown link, so the wikilink pass below addresses it exactly as
+        // an authored `[[#anchor|Text]]` is, by the page the figure's own
+        // fence became. Cross-note resolution is omitted: a journal addresses
+        // a page by UUID, which this pass has none of for another note.
+        const figuresById = new Map(
+            figureScan.figures
+                .filter((figure) => figure.id)
+                .map((figure) => [
+                    figure.id,
+                    { label: figure.label, caption: figure.caption, hasCaption: figure.hasCaption },
+                ]),
+        );
         const expressions = renderMarkdownExpressions(tabulated, {
             fm,
             dates: reckoningContext(this.linkIndex),
             sqlResults: absPath ? this.sqlTables?.inline?.get(absPath) : undefined,
             file: absPath,
             bodyLine,
+            figures: { get: (id) => figuresById.get(id), link: foundryRefLink },
         });
         for (const finding of expressions.findings) {
             findings.push({ message: finding.message, line: finding.line, column: finding.column });

package/engine/bundles.mjs

@@ -75,6 +75,7 @@ import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { folderField, renderFoundryMarkdown, resolveName } from "./helpers.mjs";
 import { packForType } from "./ids.mjs";
 import { readQualifier } from "./wikilinks.mjs";
+import { pathnameRoles } from "./art-fields.mjs";
 
 /**
  * Load every compiled document a bundle may hold, keyed `<docType>/<id>`.
@@ -311,6 +312,12 @@ export class Bundles extends BasePackCompiler {
             contents.push({ docType: member.docType, document });
         }
 
+        // The markdown this pass reads has already had its embeds rewritten
+        // into ordinary images, each `src` the pathname `pathnameRoles` keys
+        // its roles by — so a `:::figure` of a map names itself `Map 1` here
+        // exactly as the website and the book name the same picture.
+        const roles = pathnameRoles(this.linkIndex);
+
         return buildAdventure({
             id: fm.id,
             name,
@@ -323,7 +330,12 @@ export class Bundles extends BasePackCompiler {
             // Foundry renders on the import card. That is why a bundle earns no
             // separate documentation journal the way an item does: the document
             // it compiles into already has somewhere to put the prose.
-            description: markdown.trim() ? renderFoundryMarkdown(markdown) : "",
+            description:
+                markdown.trim() ?
+                    renderFoundryMarkdown(markdown, undefined, undefined, undefined, (pathname) =>
+                        roles.get(pathname),
+                    )
+                :   "",
             folder: this.folderResolver(authoredFolder, { isAddress: folderIsAddress }),
             stats: this.stats,
             contents,

package/engine/content-blocks.mjs

@@ -27,7 +27,7 @@
 
  * **One pass reads all three names.** Reading them in two passes made the first
  * one meet the second's closers with nothing open, and report a block the author
- * had not written. A construct this pass does not own — `:::caption` — is
+ * had not written. A construct this pass does not own — `:::figure` — is
  * counted rather than claimed, so its closer is attributed to it and the pass
  * that owns it still finds it in the markdown this one passes through.
  *
@@ -87,13 +87,13 @@ export const BLOCK_NAMES = Object.freeze({
 export const BLOCK_CONTAINERS = Object.freeze(["secret"]);
 
 /**
- * Constructs another pass owns. A `:::caption` is read by the caption pass, so
+ * Constructs another pass owns. A `:::figure` is read by the figure pass, so
  * this one **counts it and does not claim it**: the opener and its closer pass
  * through untouched, and the count is what lets a closer be attributed to the
  * innermost block actually open. Claiming one would report a block that does not
- * exist and take the caption out of the note.
+ * exist and take the figure out of the note.
  */
-const FOREIGN = Object.freeze(["caption"]);
+const FOREIGN = Object.freeze(["figure"]);
 
 /** `title` is the heading. Everything else an author writes becomes an attribute. */
 const TITLE = "title";

package/engine/content-embeds.mjs

@@ -173,6 +173,25 @@ export function resolveEmbed(index, embed) {
     return { reason: read.reason, target: embed.written, type: read.type };
 }
 
+/**
+ * The role an address's asset declares, read through the same resolution an
+ * embed's address takes.
+ *
+ * This is the lookup a `:::figure` fence's `map` counter reaches through —
+ * see {@link module:engine/content-figures.scanFigures}'s `resolveRole` — for
+ * an address still in its authored form, before {@link resolveEmbeds} has
+ * rewritten it into the ordinary image every surface renders.
+ *
+ * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex},
+ *   or the equivalent the site and the book build.
+ * @param {string} address - The address as authored, inside `![[...]]`.
+ * @returns {string|undefined} The role, or `undefined` for a note's address,
+ *   one that resolves nowhere, or a picture that declares none.
+ */
+export function embedRole(index, address) {
+    return readAssetAddress(index, address, EMBED_DEFAULT_TYPE).record?.asset?.role || undefined;
+}
+
 /**
  * What is wrong with one embed's directive or placement, if anything.
  *