@heroiclands/package-build 22.14.3 → 22.14.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @heroiclands/package-build
 
+## 22.14.4
+
+### Patch Changes
+
+**Illustrations** — Named image sizes set the display width on pages and in books. Images without a size use their natural dimensions within the available space.
+
 ## 22.14.3
 
 ### Patch Changes

package/docs/api.md

@@ -965,12 +965,12 @@ Raw HTML in a note's prose, reported. **A note is markdown.** What markdown cann
 
 ### `engine.contentImages`
 
-An image saying how wide it is and where it sits. A markdown image carries no indication of either, so each of the three surfaces decides for itself and the author — who is the one who knows — has no way to say. A directive in the curly-attribute convention Pandoc and Kramdown use closes that, in three closed vocabularies: a width class, a named `size:`, and a `float:` position. The named size is accepted without affecting display.
+An image saying how wide it is and where it sits. A directive in the curly-attribute convention Pandoc and Kramdown use supplies a width class, a named `size:`, and a `float:` position. The named size sets a maximum display width for each surface.
 
 | Export                | Signature                                       | Returns                                                                                                                                        | Use it when                                                                  |
 | --------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
 | `IMAGE_CLASSES`       | `const IMAGE_CLASSES`                           | —                                                                                                                                              | The width classes an image may carry, and what each means to a renderer.     |
-| `IMAGE_SIZES`         | `const IMAGE_SIZES`                             | —                                                                                                                                              | The named sizes an image directive accepts without applying a display size.  |
+| `IMAGE_SIZES`         | `const IMAGE_SIZES`                             | —                                                                                                                                              | The named sizes an image directive accepts.                                  |
 | `IMAGE_FLOATS`        | `const IMAGE_FLOATS`                            | —                                                                                                                                              | The `float:` positions an image may take, and where each puts it.            |
 | `IMAGE_FIGURE_CLASS`  | `const IMAGE_FIGURE_CLASS`                      | —                                                                                                                                              | The class every figure carries, whatever its width or position.              |
 | `IMAGE_PATTERN`       | `const IMAGE_PATTERN`                           | —                                                                                                                                              | A markdown image, with the directive it may carry.                           |
@@ -1167,6 +1167,7 @@ A note's markdown, and a document plan, rendered as Typst source. **This module
 | `renderBook`            | `renderBook({ plan, bodies, title, subtitle, front, fonts, version, preamble, banners })` | {string} A complete `.typ` document.                         | The whole book, as one Typst document.                                   |
 | `resolveDanglingLabels` | `function resolveDanglingLabels(source, findings`                                         | {string} The same document, with no reference left dangling. | Point every internal link at a label the document actually declares.     |
 | `iconNamesIn`           | `function iconNamesIn(markdown)`                                                          | {string[]} The names, in order of appearance, with repeats.  | Every icon name a body uses, so a build can resolve them once.           |
+| `BOOK_IMAGE_WIDTHS`     | `const BOOK_IMAGE_WIDTHS`                                                                 | —                                                            | The book measure requested by each named image size.                     |
 | `bookTypstPreamble`     | `function bookTypstPreamble()`                                                            | {string} Typst markup.                                       | The Typst definitions the book's page furniture is drawn with.           |
 
 ### `engine.pdfFonts`

package/docs/content-format.md

@@ -2066,10 +2066,10 @@ place for those words and this is it.
 
 ##### Width is a class, and the ordinary width carries no marker
 
-| `class` value | book          | website            | Foundry journal  |
-| ------------- | ------------- | ------------------ | ---------------- |
-| _(none)_      | one column    | the text measure   | the page measure |
-| `.full-width` | the full page | full content width | full page width  |
+| `class` value | book                          | website            | Foundry journal |
+| ------------- | ----------------------------- | ------------------ | --------------- |
+| _(none)_      | natural width within a column | natural width      | natural width   |
+| `.full-width` | page measure                  | full content width | full page width |
 
 The simple case needs no spelling, which is why the ordinary width has no name.
 
@@ -2080,21 +2080,24 @@ refused.
 
 ##### Named size is `size:`
 
-| `size` value | display                  |
-| ------------ | ------------------------ |
-| `auto`       | same as omitting `size:` |
-| `small`      | same as omitting `size:` |
-| `medium`     | same as omitting `size:` |
-| `large`      | same as omitting `size:` |
-| `xlarge`     | same as omitting `size:` |
-| `full-width` | same as omitting `size:` |
-
-The parser accepts and records these names for Markdown images and embedded
-assets. **A `size:` value does not change the displayed dimensions** on the
-website, in Foundry, or in the book. With no `size:`, the parser records `auto`;
-the existing rendering rules apply. In particular, book images occupy a column
-unless they carry `.full-width`. A `size:` may sit before or after `float:` in
-the same directive, and neither changes the other's behavior.
+| `size` value | website and Foundry | book         |
+| ------------ | ------------------- | ------------ |
+| `auto`       | natural size        | natural size |
+| `small`      | 64 CSS pixels       | 1.6 cm       |
+| `medium`     | 128 CSS pixels      | 3.2 cm       |
+| `large`      | 256 CSS pixels      | 5.6 cm       |
+| `xlarge`     | 512 CSS pixels      | 8 cm         |
+| `full-width` | content measure     | page measure |
+
+These are maximum display widths for Markdown images and embedded assets;
+height follows the file's aspect ratio. The available column, page, or browser
+measure caps every size, and print also caps image height within the page.
+Omitting `size:` means `auto`, which uses the file's natural dimensions within
+those bounds. `full-width` spans the book's page rather than one column. The
+`.full-width` class also grants page scope in print; when it accompanies a
+bounded `size:`, the image keeps that bounded width inside the page figure.
+A `size:` may sit before or after `float:` in the same directive, and neither
+changes the other's behavior.
 
 ##### Position is `float:`
 

package/docs/getting-started.md

@@ -370,9 +370,10 @@ position together:
 ```
 
 The accepted sizes are `auto`, `small`, `medium`, `large`, `xlarge`, and
-`full-width`. Omitting `size:` means `auto`. The build checks the name, but
-`size:` does not change the displayed dimensions on the website, in Foundry, or
-in the book. See [Images](content-format.md#images) for the rendering rules.
+`full-width`. Omitting `size:` means `auto`, which uses the image's natural
+dimensions within the available measure. The other names set maximum display
+widths for the website, Foundry, and book. See
+[Images](content-format.md#images) for the surface sizes and layout rules.
 
 ## Step 6 — check the tree
 

package/engine/content-images.mjs

@@ -25,7 +25,8 @@
  * simple case needs no spelling. {@link IMAGE_CLASSES} holds the one class
  * there is. **Position is `float:`**, and {@link IMAGE_FLOATS} holds the five
  * values it takes. **Named size is `size:`**, and {@link IMAGE_SIZES} holds its
- * values. Size is parsed but does not change the figure's current presentation.
+ * values. The HTML surfaces receive a size class; the book receives a print
+ * measure.
  *
  * All three are closed, and an unrecognised value is **refused with a located
  * diagnostic** rather than ignored. Ignoring is the failure worth preventing:
@@ -105,7 +106,7 @@ export const IMAGE_CLASSES = Object.freeze({
     },
 });
 
-/** The named sizes an image directive accepts without applying a display size. */
+/** The named sizes an image directive accepts. */
 export const IMAGE_SIZES = Object.freeze([
     "auto",
     "small",
@@ -326,16 +327,17 @@ export function parseImageDirective(raw) {
 /**
  * The classes a figure carries, from a parsed directive.
  *
- * @param {{classes?: string[], float?: string}} [directive] - As parsed.
+ * @param {{classes?: string[], size?: string, float?: string}} [directive] - As parsed.
  * @returns {string} A space-separated class list, always naming
  *   {@link IMAGE_FIGURE_CLASS} first.
  */
-export function figureClasses({ classes = [], float = "" } = {}) {
+export function figureClasses({ classes = [], size = "auto", float = "" } = {}) {
     const names = [IMAGE_FIGURE_CLASS];
     for (const name of classes) {
         const spec = IMAGE_CLASSES[/** @type {keyof typeof IMAGE_CLASSES} */ (name)];
         if (spec) names.push(spec.class);
     }
+    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);
     return names.join(" ");
@@ -367,13 +369,14 @@ export function escapeHtml(text) {
  * @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.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.
  * @returns {string} The figure, as one HTML block.
  */
-export function imageFigureHtml({ src, alt = "", classes = [], float = "" }) {
+export function imageFigureHtml({ src, alt = "", classes = [], size = "auto", float = "" }) {
     const caption = alt ? `\n<figcaption>${escapeHtml(alt)}</figcaption>` : "";
     return (
-        `<figure class="${figureClasses({ classes, float })}">\n` +
+        `<figure class="${figureClasses({ classes, size, float })}">\n` +
         `<img src="${escapeHtml(src)}" alt="${escapeHtml(alt)}">${caption}\n` +
         `</figure>`
     );
@@ -644,10 +647,16 @@ export function renderImageFigures(body, resolveSrc = (src) => src) {
     let last = 0;
     for (const image of imagesIn(text)) {
         if (!image.block || imageSourceProblem(image.src) || image.title) continue;
-        const { classes, float, problems } = parseImageDirective(image.directive);
+        const { classes, size, float, problems } = parseImageDirective(image.directive);
         if (problems.length) continue;
         out += text.slice(last, image.index);
-        out += imageFigureHtml({ src: resolveSrc(image.src), alt: image.alt, classes, float });
+        out += imageFigureHtml({
+            src: resolveSrc(image.src),
+            alt: image.alt,
+            classes,
+            size,
+            float,
+        });
         last = image.index + image.length;
     }
     return out + text.slice(last);
@@ -696,6 +705,7 @@ export function imagePlugin(resolveSrc = (src) => src) {
                 src: resolveSrc(token.attrGet("src") ?? ""),
                 alt: token.content ?? "",
                 classes: token.meta.classes,
+                size: token.meta.size,
                 float: token.meta.float,
             })}\n`;
         };
@@ -733,12 +743,12 @@ function attachImageDirectives(tokens) {
             directive = brace[0];
         }
 
-        const { classes, float, problems } = parseImageDirective(directive);
+        const { classes, size, float, problems } = parseImageDirective(directive);
         // Not ours to consume: leaving the braces in place is what makes an
         // unrecognised value visible on the page instead of passing as ordinary.
         if (problems.length) continue;
 
-        image.meta = { ...(image.meta ?? {}), block: true, classes, float };
+        image.meta = { ...(image.meta ?? {}), block: true, classes, size, float };
         if (trailing) trailing.content = trailing.content.slice(directive.length);
         // The figure is a block, so the paragraph that held it renders nothing.
         tokens[i].hidden = true;

package/engine/pdf-render.mjs

@@ -66,6 +66,16 @@ import MarkdownIt from "markdown-it";
 import { bookDraftNoticePreamble } from "./draft-notice.mjs";
 import { iconPlugin, ICON_PATTERN } from "./content-icons.mjs";
 import { IMAGE_CLASSES, IMAGE_FLOATS, imagePlugin } from "./content-images.mjs";
+
+/** Requested print width for every named image size. */
+export const BOOK_IMAGE_WIDTHS = Object.freeze({
+    auto: "auto",
+    small: "1.6cm",
+    medium: "3.2cm",
+    large: "5.6cm",
+    xlarge: "8cm",
+    "full-width": '"full-width"',
+});
 import { slugify } from "./content-slug.mjs";
 
 /**
@@ -706,17 +716,19 @@ function renderLink(href, inner, ctx) {
  */
 function renderImage(token, ctx) {
     const alt = token.content || token.attrGet?.("alt") || "";
-    const caption =
-        alt ? `\n  #text(size: 7.6pt, style: "italic", fill: luma(45%))[${escapeTypst(alt)}]` : "";
+    const caption = alt ? `[${escapeTypst(alt)}]` : "none";
     const staged = ctx.images.get(token.attrGet?.("src") ?? "");
-    if (!staged) return caption ? `\n#block(below: 0.6em)[${caption}\n]\n\n` : "";
+    if (!staged)
+        return alt ?
+                `\n#block(below: 0.6em)[#text(size: 7.6pt, style: "italic", fill: luma(45%))${caption}]\n\n`
+            :   "";
 
-    const figure =
-        `#block(width: 100%, below: 0.6em)[\n` +
-        `  #image("${escapeTypstString(staged)}", width: 100%)${caption}\n]`;
+    const size = BOOK_IMAGE_WIDTHS[token.meta?.size] ?? BOOK_IMAGE_WIDTHS.auto;
+    const figure = `#book-image("${escapeTypstString(staged)}", requested: ${size}, caption: ${caption})`;
 
     const width = token.meta?.classes?.[0];
-    const scope = IMAGE_CLASSES[width]?.scope ?? "column";
+    const scope =
+        token.meta?.size === "full-width" ? "parent" : (IMAGE_CLASSES[width]?.scope ?? "column");
     const float = IMAGE_FLOATS[token.meta?.float];
     // In the flow where it was written: no class asking for the page, and no
     // position asking for the top or the bottom of the column.
@@ -804,6 +816,17 @@ export function bookTypstPreamble() {
         "#let book-page-height = 11in",
         "#let book-text-width = book-page-width - 2 * book-margin",
         "#let book-text-height = book-page-height - 2 * book-margin",
+        // Use the file's natural measure for auto. Every requested width is
+        // bounded by the available measure and by the height of a page.
+        "#let book-image(path, requested: auto, caption: none) = layout(size => {\n" +
+            "  let natural = measure(image(path))\n" +
+            '  let target = if requested == auto { natural.width } else if requested == "full-width" { size.width } else { requested }\n' +
+            "  let width = calc.min(target, size.width, book-text-height * 0.8 * (natural.width / natural.height))\n" +
+            "  block(width: width, below: 0.6em)[\n" +
+            '    #image(path, width: 100%, fit: "contain")\n' +
+            '    #if caption != none { text(size: 7.6pt, style: "italic", fill: luma(45%))[#caption] }\n' +
+            "  ]\n" +
+            "})",
         // The title sets short of the measure, so a plate's last line does not
         // run to the trimmed edge of the paper.
         "#let book-title-measure = book-text-width - 2.5cm",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.14.3",
+    "version": "22.14.4",
     "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/content-images.d.mts

@@ -32,12 +32,13 @@ export function parseImageDirective(raw?: string): {
 /**
  * The classes a figure carries, from a parsed directive.
  *
- * @param {{classes?: string[], float?: string}} [directive] - As parsed.
+ * @param {{classes?: string[], size?: string, float?: string}} [directive] - As parsed.
  * @returns {string} A space-separated class list, always naming
  *   {@link IMAGE_FIGURE_CLASS} first.
  */
-export function figureClasses({ classes, float }?: {
+export function figureClasses({ classes, size, float }?: {
     classes?: string[];
+    size?: string;
     float?: string;
 }): string;
 /**
@@ -58,13 +59,15 @@ export function escapeHtml(text: string): string;
  * @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.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.
  * @returns {string} The figure, as one HTML block.
  */
-export function imageFigureHtml({ src, alt, classes, float }: {
+export function imageFigureHtml({ src, alt, classes, size, float }: {
     src: string;
     alt?: string | undefined;
     classes?: string[] | undefined;
+    size?: string | undefined;
     float?: string | undefined;
 }): string;
 /**
@@ -249,7 +252,7 @@ export const IMAGE_CLASSES: Readonly<Record<string, {
     scope: string;
     describe: string;
 }>>;
-/** The named sizes an image directive accepts without applying a display size. */
+/** The named sizes an image directive accepts. */
 export const IMAGE_SIZES: readonly string[];
 /**
  * The `float:` positions an image may take, and where each puts it.

package/types/engine/pdf-render.d.mts

@@ -252,3 +252,12 @@ export function resolveDanglingLabels(source: string, findings?: object[]): stri
  * @returns {string[]} The names, in order of appearance, with repeats.
  */
 export function iconNamesIn(markdown: string): string[];
+/** Requested print width for every named image size. */
+export const BOOK_IMAGE_WIDTHS: Readonly<{
+    auto: "auto";
+    small: "1.6cm";
+    medium: "3.2cm";
+    large: "5.6cm";
+    xlarge: "8cm";
+    "full-width": "\"full-width\"";
+}>;