@heroiclands/package-build 20.2.1 → 20.3.1

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # @heroiclands/package-build
 
+## 20.3.1
+
+### Patch Changes
+
+- 43188f2: A registry entry can now name an icon family, so a package that draws from two
+  of them can say so.
+  
+  The SoHL icon legend states in its own prose that it uses Font Awesome plus
+  Game-Icons.net "for the arms, gear, and condition glyphs that Font Awesome does
+  not cover" — eighteen `ginf-*` classes the registry had no way to express. They
+  differ in more than a prefix: Game-Icons has no weights, so a `style` on such an
+  entry names something that does not exist, and it resolves to a different font,
+  which a PDF has to embed separately.
+  
+  `family` defaults to `fontawesome`, so every existing entry is unchanged. A
+  style on an unstyled family is reported rather than silently ignored, because it
+  means the author expected a filled and hollow pair the family cannot spell.
+  
+  Also adds `gem` and `gem-outline`, and repoints `diamond` at them. `fa-diamond`
+  is Font Awesome's playing-card suit and ships in solid only, so it could not
+  spell the hollow half of the Success Value scale it was being used for.
+
+## 20.3.0
+
+### Minor Changes
+
+- 6be4a7e: An icon can now carry attributes, and `affiliation` joins the registry.
+  
+  `:icon-affiliation:{size: 2x}` — `key: value` pairs in a trailing brace, the
+  shape `markdown-it-attrs` and remark-directive already use. Attributes rather
+  than a bare size because `size` is only the first one anybody needed: a
+  fixed-width flag, a rotation, a title override are the same shape of thing, and
+  a syntax that could only express size would have to be replaced to gain any of
+  them.
+  
+  Size is a closed vocabulary — `lg`, `xl`, `2x`, `3x` — mapping to Font Awesome's
+  own classes on the web and the same multiples in a PDF. It exists because the
+  icon legend enlarges its glyphs so a reader can tell them apart, which makes the
+  size part of what that page says rather than styling applied to it. A free-form
+  `font-size` would have been CSS, which reaches two surfaces of three.
+  
+  An attribute that cannot be honoured is reported rather than ignored, and the
+  icon still renders: hiding a good icon over a bad size would be the worse answer.
+  
+  `affiliation` is `fa-certificate` — a charter under seal. It replaces a
+  `fa-duotone fa-handshake` that was reaching for Font Awesome Pro because the
+  interlocking hands washed out at small sizes; the fix for a silhouette problem
+  is a bolder silhouette, not a paid tier.
+- e209110: Add `close` and `run` to the icon registry, and correct `delete`.
+  
+  Converting the SoHL user guide turned up two controls with no name to convert
+  to. A `✕` there means three different things — "not applicable" in a Healing
+  Rate column, "remove" on a control, and **close** on a dialog's corner — and a
+  `▶` **runs** an action, where the nearest existing entry was `expand`, whose
+  accessible label would have told a screen reader the wrong thing. Both now have
+  their own name and their own label; that Font Awesome draws the three `xmark`
+  senses identically is this table's business rather than the reader's.
+  
+  `delete` was written as `fa-trash-can` and is now `fa-trash`, which is what the
+  system's templates actually draw — twenty-five times, against no `fa-trash-can`
+  at all. A registry checked against the interface is the whole point of having
+  one; unchecked, it is just a second place to be wrong.
+
+### Patch Changes
+
+- 1d8e289: The charset and icon checks now report warnings rather than errors, so neither
+  can fail a build.
+  
+  Both emitted `severity: "error"`, and `reportFindings` fails a run on an error —
+  so adopting the charset check turned consumers' builds red for content that was
+  already correct. A character outside the charset does not make a note wrong: it
+  compiles to the same document and publishes the same page, and only a book that
+  does not exist yet cares. An undeclared icon name is the same shape of thing,
+  visible on the page as literal text.
+  
+  The NFC rule is a warning too, despite having the best claim to being an error,
+  because a lint that fails a build for one of its rules and not the others is one
+  nobody can predict.
+
 ## 20.2.1
 
 ### Patch Changes

package/engine/content-charset.mjs

@@ -64,8 +64,21 @@
  *   embeds: it carries the box-drawing, geometric and arrow repertoire that no
  *   candidate serif reliably has.
  *
- * **This module reports and does not exit**, as every gate in this engine does.
- * The command decides what a finding is worth.
+ * **Every finding here is a `warning`, and that is deliberate.** `reportFindings`
+ * fails a run on an error and not on a warning, so nothing this module says can
+ * break a build.
+ *
+ * A character outside the charset does not make a note wrong. It compiles to
+ * the same document, publishes the same page, and reads correctly everywhere
+ * except a book that does not exist yet — so failing a consumer's build over it
+ * would stop work that is already correct in order to serve a renderer that is
+ * still being written. The trees this shipped against had 112 findings between
+ * them on the day it landed, all of them real and none of them urgent.
+ *
+ * The NFC rule is the one with a claim to being an error, since a decomposed
+ * name is silently invisible to an exact-match filter. It is a warning too,
+ * because a lint that fails a build for one of its rules and not the others is
+ * a lint nobody can predict.
  *
  * @module
  */
@@ -295,7 +308,7 @@ export function decomposedRuns(text) {
  * @param {string} text - The file's contents.
  * @param {string} file - Path to report, relative to the tree.
  * @returns {Array<{file: string, line: number, column: number,
- *   severity: "error", message: string}>} What is wrong, in file order.
+ *   severity: "warning", message: string}>} What is wrong, in file order.
  */
 export function checkText(text, file) {
     const findings = [];
@@ -347,7 +360,7 @@ export function checkText(text, file) {
                 file,
                 line: i + 1,
                 column,
-                severity: /** @type {const} */ ("error"),
+                severity: /** @type {const} */ ("warning"),
                 message: `\`${ch}\` ${hex(cp)} is ${refusalFor(cp)}`,
             });
         }
@@ -364,7 +377,7 @@ export function checkText(text, file) {
             file,
             line,
             column,
-            severity: /** @type {const} */ ("error"),
+            severity: /** @type {const} */ ("warning"),
             message:
                 `\`${run.sequence}\` is written decomposed as ${points}; write the ` +
                 `precomposed \`${run.composed}\` (${[...run.composed]
@@ -391,13 +404,13 @@ export function checkText(text, file) {
  *   in addition to the dot-directories always skipped.
  * @param {readonly string[]} [opts.extensions] - File extensions to read.
  * @returns {{findings: Array<{file: string, line: number, column: number,
- *   severity: "error", message: string}>, files: number}} The findings, and how
+ *   severity: "warning", message: string}>, files: number}} The findings, and how
  *   many files produced them.
  */
 export function lintContentCharset(contentBase, { skipDirectories = [], extensions } = {}) {
     const exts = new Set(extensions ?? [".md", ".markdown", ".yaml", ".yml", ".json"]);
     const skip = new Set(skipDirectories);
-    /** @type {Array<{file: string, line: number, column: number, severity: "error", message: string}>} */
+    /** @type {Array<{file: string, line: number, column: number, severity: "warning", message: string}>} */
     const findings = [];
     let files = 0;
 

package/engine/content-icons.mjs

@@ -56,6 +56,12 @@
  * 1.1, so a distributed PDF may embed the subset it uses. Attribution belongs
  * in the book's colophon, not in every note.
  *
+ * **Every finding here is a `warning`**, so nothing this module says can fail a
+ * build — `reportFindings` fails on an error and not on a warning. An
+ * undeclared name renders as its own literal text, which is visible on the page
+ * and wrong in a way a reader will notice; that deserves to be reported and
+ * does not deserve to stop a build that is otherwise correct.
+ *
  * @module
  */
 
@@ -73,28 +79,201 @@ import path from "node:path";
  */
 export const ICON_STYLES = Object.freeze(["solid", "regular", "brands"]);
 
+/**
+ * The icon families a registry entry may draw from.
+ *
+ * **Two, because the interface uses two.** The SoHL icon legend says so in its
+ * own prose: Font Awesome for most things, and Game-Icons.net *"for the arms,
+ * gear, and condition glyphs that Font Awesome does not cover"* — eighteen of
+ * them, `ginf-broadsword` and its kin (#391).
+ *
+ * They differ in more than a class prefix, which is why this is a family rather
+ * than a naming convention:
+ *
+ * - Font Awesome has **weights**, so an entry names a `style` and a filled and
+ *   hollow pair is one icon twice. Game-Icons has none, so a `style` on such an
+ *   entry names something that does not exist.
+ * - They resolve to **different fonts**. A PDF has to embed both, and find each
+ *   codepoint in its own table — Font Awesome's from the file it ships,
+ *   Game-Icons' from the `game-icons-codepoints.json` the consumer's own
+ *   `build-icon-font.mjs` writes.
+ *
+ * `class` is the prefix the web surfaces use. `styled` says whether a `style`
+ * belongs on the entry at all, which is what lets a mistake be reported rather
+ * than rendered as a class nobody defined.
+ *
+ * @type {Readonly<Record<string, {class: string, styled: boolean, describe: string}>>}
+ */
+export const ICON_FAMILIES = Object.freeze({
+    fontawesome: {
+        class: "fa",
+        styled: true,
+        describe: "Font Awesome Free",
+    },
+    "game-icons": {
+        class: "ginf",
+        styled: false,
+        describe: "the Game-Icons.net webfont a package builds for itself",
+    },
+});
+
+/** The family an entry that does not name one belongs to. */
+export const DEFAULT_ICON_FAMILY = "fontawesome";
+
+/**
+ * The family an entry draws from, named or defaulted.
+ *
+ * @param {{family?: string}} entry - A registry entry.
+ * @returns {string} The family name.
+ */
+export function familyOf(entry) {
+    return entry?.family ?? DEFAULT_ICON_FAMILY;
+}
+
+/**
+ * The sizes a note may ask for, and what each means on a page.
+ *
+ * **A closed set, because size is content here rather than styling.** The icon
+ * legend exists to let a reader tell one glyph from another, and several of
+ * them genuinely cannot be told apart at the size of running text — so the
+ * enlargement is part of what that page *says*, not decoration applied to it.
+ * That is the one case worth a size at all.
+ *
+ * Closed rather than free-form for the usual reason: `font-size: 2em` in a note
+ * is CSS, which reaches two of the three surfaces and means nothing to the
+ * third. A name means the same thing everywhere, and the multiples below are
+ * Font Awesome's own, so the web class and the PDF scale cannot drift.
+ *
+ * @type {Readonly<Record<string, {class: string, scale: number}>>}
+ */
+export const ICON_SIZES = Object.freeze({
+    lg: { class: "fa-lg", scale: 1.25 },
+    xl: { class: "fa-xl", scale: 1.5 },
+    "2x": { class: "fa-2x", scale: 2 },
+    "3x": { class: "fa-3x", scale: 3 },
+});
+
+/**
+ * The attribute names a note may write, and how each is validated.
+ *
+ * One entry today. It is a table rather than an `if (key === "size")` because
+ * the next attribute — a fixed-width flag, a rotation, a title override — should
+ * cost a line here and nothing else, and because an unknown key has to be
+ * *reported*: silently ignoring `{sixe: 2x}` would leave the author looking at a
+ * page that is not what they asked for, with nothing to say why.
+ *
+ * @type {Readonly<Record<string, {values: readonly string[], describe: string}>>}
+ */
+export const ICON_ATTRIBUTES = Object.freeze({
+    size: {
+        values: Object.freeze(Object.keys(ICON_SIZES)),
+        describe: "how much larger than running text to draw the icon",
+    },
+});
+
+/**
+ * Read the brace of an icon token.
+ *
+ * Values are validated against {@link ICON_ATTRIBUTES} here rather than at the
+ * point of rendering, so a mistake is one finding with a position rather than a
+ * silently different page.
+ *
+ * @param {string} [raw] - The text between the braces, without them.
+ * @returns {{attrs: Record<string, string>, problems: string[]}} What was
+ *   written, and what cannot be honoured.
+ */
+export function parseIconAttributes(raw) {
+    /** @type {Record<string, string>} */
+    const attrs = {};
+    const problems = [];
+    if (!raw || !raw.trim()) return { attrs, problems };
+
+    // Split on commas, not whitespace: `size: 2x` is one pair with a space in
+    // it, and the space after the colon is the whole point of the spelling.
+    for (const part of raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)) {
+        const colon = part.indexOf(":");
+        if (colon === -1) {
+            problems.push(
+                `\`${part}\` is not a \`key: value\` attribute — an icon takes ` +
+                    `${Object.keys(ICON_ATTRIBUTES).join(", ")}`,
+            );
+            continue;
+        }
+        const key = part.slice(0, colon).trim();
+        const value = part.slice(colon + 1).trim();
+        const spec =
+            Object.prototype.hasOwnProperty.call(ICON_ATTRIBUTES, key) ?
+                ICON_ATTRIBUTES[key]
+            :   undefined;
+        if (!spec) {
+            problems.push(
+                `\`${key}\` is not an icon attribute — the ones there are: ` +
+                    `${Object.keys(ICON_ATTRIBUTES).join(", ")}`,
+            );
+            continue;
+        }
+        if (!spec.values.includes(value)) {
+            problems.push(
+                `\`${key}: ${value}\` is not one of ${spec.values.join(", ")} — ` +
+                    `${key} says ${spec.describe}`,
+            );
+            continue;
+        }
+        attrs[key] = value;
+    }
+    return { attrs, problems };
+}
+
 /**
  * The icons the user guide already depicts, under the names it should call them.
  *
- * Each entry was read off the interface it describes rather than invented: the
- * `star`/`star-outline` pair is the filled and hollow star the mastery row and
- * the improve flag draw, and `edit` is the pencil the formula editor opens
- * from. The names are what a *writer* would reach for — `delete`, not
- * `trash-can` — because the writer is the one typing them; the Font Awesome
- * spelling is this table's business, not theirs.
+ * Each entry is read off the interface it describes rather than invented, and
+ * that is meant literally — the table was checked against the system's own
+ * templates, which is how `delete` came to be `fa-trash` rather than the
+ * `fa-trash-can` first written here. The sheets draw `fa-trash` twenty-five
+ * times and `fa-trash-can` never, so the first spelling would have printed an
+ * icon the reader has never seen on screen. A registry that is not checked
+ * against the interface is just a second place to be wrong.
+ *
+ * The names are what a *writer* would reach for — `delete`, not `trash` —
+ * because the writer is the one typing them; the Font Awesome spelling is this
+ * table's business, not theirs.
+ *
+ * **Three entries share `xmark`, and that is the point of naming rather than
+ * drawing.** A `✕` in the guide means "not applicable" in a Healing Rate
+ * column, "remove this row" on a control, and "close" on a dialog's corner. One
+ * glyph, three sentences, three different things for a reader who cannot see
+ * it — so they are three names with three labels, and the fact that Font
+ * Awesome happens to draw them identically stays in this table.
+ *
+ * `run` and `expand` are likewise distinct: `▶` runs an action, and its label
+ * should say so. `fa-play` is what the sheets use for it.
  *
  * @type {Readonly<Record<string, {style: string, icon: string, label: string}>>}
  */
 export const DEFAULT_ICONS = Object.freeze({
+    affiliation: { style: "solid", icon: "certificate", label: "affiliation" },
     star: { style: "solid", icon: "star", label: "star" },
     "star-outline": { style: "regular", icon: "star", label: "hollow star" },
-    diamond: { style: "solid", icon: "diamond", label: "diamond" },
+    // The Success Value scale. `fa-diamond` is Font Awesome's playing-card
+    // suit and ships in solid only, so it can spell no hollow half of a
+    // filled/hollow pair; `fa-gem` is a gemstone, has both weights, and is what
+    // a quality scale actually means. `diamond` stays as an alias of it so a
+    // note that already says `:icon-diamond:` keeps working.
+    gem: { style: "solid", icon: "gem", label: "value gem" },
+    "gem-outline": { style: "regular", icon: "gem", label: "unearned value gem" },
+    diamond: { style: "solid", icon: "gem", label: "value gem" },
     edit: { style: "solid", icon: "pen-to-square", label: "edit" },
-    delete: { style: "solid", icon: "trash-can", label: "delete" },
+    delete: { style: "solid", icon: "trash", label: "delete" },
     add: { style: "solid", icon: "plus", label: "add" },
     remove: { style: "solid", icon: "xmark", label: "remove" },
     "not-applicable": { style: "solid", icon: "xmark", label: "not applicable" },
+    close: { style: "solid", icon: "xmark", label: "close" },
     menu: { style: "solid", icon: "ellipsis-vertical", label: "actions menu" },
+    run: { style: "solid", icon: "play", label: "run this action" },
     expand: { style: "solid", icon: "caret-right", label: "expand" },
     shield: { style: "solid", icon: "shield-halved", label: "armour" },
     compass: { style: "solid", icon: "compass", label: "guided tour" },
@@ -113,9 +292,24 @@ export const DEFAULT_ICONS = Object.freeze({
  * Not `:name[content]`. That is remark-directive syntax, and this toolchain
  * parses with markdown-it; a directive would render as its own literal text.
  *
+ * An optional trailing brace carries **attributes**:
+ *
+ *     :icon-affiliation:{size: 2x}
+ *
+ * `key: value` pairs, comma-separated, in the shape `markdown-it-attrs` and
+ * remark-directive already use — so it is a convention a reader may recognise
+ * rather than one this module invented. Attributes rather than a bare value
+ * because `size` is merely the first one anybody needed: a fixed-width flag, a
+ * rotation, a title override are the same shape of thing, and a syntax that
+ * could only ever express size would have to be replaced to gain any of them.
+ *
+ * One inline rule consumes the token **and** its brace, so there is no state in
+ * which the icon resolves and the brace is left stranded on the page. An
+ * unhandled token degrades whole, exactly as the bare form does.
+ *
  * @type {RegExp}
  */
-export const ICON_PATTERN = /:icon-([a-z0-9]+(?:-[a-z0-9]+)*):/g;
+export const ICON_PATTERN = /:icon-([a-z0-9]+(?:-[a-z0-9]+)*):(?:\{([^}]*)\})?/g;
 
 /**
  * Look one name up.
@@ -144,11 +338,24 @@ const attr = (value) =>
  * @param {{style: string, icon: string, label: string}} entry - A registry entry.
  * @returns {string} An `<i>` element.
  */
-export function iconHtml(entry) {
-    return (
-        `<i class="fa-${attr(entry.style)} fa-${attr(entry.icon)}" ` +
-        `role="img" aria-label="${attr(entry.label)}"></i>`
-    );
+export function iconHtml(entry, attrs = {}) {
+    const family = ICON_FAMILIES[familyOf(entry)] ?? ICON_FAMILIES[DEFAULT_ICON_FAMILY];
+    const prefix = family.class;
+
+    // A styled family spells the weight and the name as two classes; an
+    // unstyled one has a single class and no weight to spell.
+    const classes =
+        family.styled ?
+            [`${prefix}-${attr(entry.style)}`, `${prefix}-${attr(entry.icon)}`]
+        :   [`${prefix}-${attr(entry.icon)}`];
+
+    // The size classes are Font Awesome's, and the Game-Icons stylesheet this
+    // toolchain's consumers generate mirrors its box metrics deliberately, so
+    // they apply to both families.
+    const sized = attrs.size ? ICON_SIZES[attrs.size] : undefined;
+    if (sized) classes.push(sized.class);
+
+    return `<i class="${classes.join(" ")}" role="img" aria-label="${attr(entry.label)}"></i>`;
 }
 
 /**
@@ -160,7 +367,8 @@ export function iconHtml(entry) {
 export function iconsIn(text) {
     const out = [];
     for (const m of text.matchAll(ICON_PATTERN)) {
-        out.push({ name: m[1], index: m.index ?? 0, raw: m[0] });
+        const { attrs, problems } = parseIconAttributes(m[2]);
+        out.push({ name: m[1], index: m.index ?? 0, raw: m[0], attrs, problems });
     }
     return out;
 }
@@ -176,28 +384,38 @@ export function iconsIn(text) {
  * @param {string} file - Path to report.
  * @param {Record<string, object>} [registry] - Defaults to {@link DEFAULT_ICONS}.
  * @returns {Array<{file: string, line: number, column: number,
- *   severity: "error", message: string}>} The unknown names.
+ *   severity: "warning", message: string}>} The unknown names.
  */
 export function lintIcons(text, file, registry = DEFAULT_ICONS) {
     const findings = [];
-    for (const { name, index, raw } of iconsIn(text)) {
-        if (resolveIcon(name, registry)) continue;
+    for (const { name, index, raw, problems } of iconsIn(text)) {
         const before = text.slice(0, index);
         const line = before.split("\n").length;
         const column = index - (before.lastIndexOf("\n") + 1) + 1;
-        // Nearest declared name, when there is an obvious one: a typo is the
-        // common case and the registry is short enough to say what was meant.
-        const suggestion = nearestName(name, Object.keys(registry));
-        findings.push({
-            file,
-            line,
-            column,
-            severity: /** @type {const} */ ("error"),
-            message:
-                `\`${raw}\` names an icon the registry does not declare` +
-                (suggestion ? `; did you mean \`:icon-${suggestion}:\`?` : "") +
-                ` — an undeclared name renders as its own literal text`,
-        });
+        const at = { file, line, column, severity: /** @type {const} */ ("warning") };
+
+        if (!resolveIcon(name, registry)) {
+            // Nearest declared name, when there is an obvious one: a typo is the
+            // common case and the registry is short enough to say what was meant.
+            const suggestion = nearestName(name, Object.keys(registry));
+            findings.push({
+                ...at,
+                message:
+                    `\`${raw}\` names an icon the registry does not declare` +
+                    (suggestion ? `; did you mean \`:icon-${suggestion}:\`?` : "") +
+                    ` — an undeclared name renders as its own literal text`,
+            });
+            // The name is the bigger fault; reporting its attributes as well
+            // would be two findings for one token the author has to rewrite.
+            continue;
+        }
+
+        // A bad attribute on a good name is its own finding: the icon renders,
+        // and renders differently from what was asked for, which is the case
+        // nobody notices without being told.
+        for (const problem of problems) {
+            findings.push({ ...at, message: `\`${raw}\`: ${problem}` });
+        }
     }
     return findings;
 }
@@ -250,7 +468,7 @@ function editDistance(a, b) {
  *
  * @param {Record<string, object>} registry - A package's icon table.
  * @param {string} [where="icons"] - Where to say the fault is.
- * @returns {Array<{severity: "error", message: string}>} What is wrong with it.
+ * @returns {Array<{severity: "warning", message: string}>} What is wrong with it.
  */
 export function checkIconRegistry(registry, where = "icons") {
     const findings = [];
@@ -258,29 +476,54 @@ export function checkIconRegistry(registry, where = "icons") {
         const at = `\`${where}.${name}\``;
         if (!entry || typeof entry !== "object") {
             findings.push({
-                severity: /** @type {const} */ ("error"),
+                severity: /** @type {const} */ ("warning"),
                 message: `${at} is not an icon entry — it takes \`style\`, \`icon\` and \`label\``,
             });
             continue;
         }
-        if (!ICON_STYLES.includes(entry.style)) {
+        const familyName = familyOf(entry);
+        const family = ICON_FAMILIES[familyName];
+        if (!family) {
             findings.push({
-                severity: /** @type {const} */ ("error"),
+                severity: /** @type {const} */ ("warning"),
+                message:
+                    `${at} names family \`${familyName}\`, and the families there ` +
+                    `are: ${Object.keys(ICON_FAMILIES).join(", ")}`,
+            });
+            continue;
+        }
+
+        if (family.styled && !ICON_STYLES.includes(entry.style)) {
+            findings.push({
+                severity: /** @type {const} */ ("warning"),
                 message:
                     `${at} names style \`${entry.style}\`, and Font Awesome Free ships ` +
                     `only ${ICON_STYLES.join(", ")} — a glyph in any other style is ` +
                     `absent from the font a book would embed`,
             });
         }
+
+        // A style on an unstyled family is not a harmless extra key: it says
+        // the author expected a weight, and the family has none, so what they
+        // get is not what they asked for.
+        if (!family.styled && entry.style !== undefined) {
+            findings.push({
+                severity: /** @type {const} */ ("warning"),
+                message:
+                    `${at} names style \`${entry.style}\`, and ${family.describe} has ` +
+                    `no weights — the style is ignored, so a filled and hollow pair ` +
+                    `cannot be spelled this way`,
+            });
+        }
         if (typeof entry.icon !== "string" || !entry.icon) {
             findings.push({
-                severity: /** @type {const} */ ("error"),
+                severity: /** @type {const} */ ("warning"),
                 message: `${at} declares no \`icon\`, so nothing names the glyph to draw`,
             });
         }
         if (typeof entry.label !== "string" || !entry.label) {
             findings.push({
-                severity: /** @type {const} */ ("error"),
+                severity: /** @type {const} */ ("warning"),
                 message:
                     `${at} declares no \`label\`, and an icon with no accessible name ` +
                     `is read aloud as a gap in the sentence`,
@@ -302,7 +545,7 @@ export function checkIconRegistry(registry, where = "icons") {
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
  * @param {Record<string, object>} [opts.registry] - The package's icon table.
  * @returns {{findings: Array<{file: string, line: number, column: number,
- *   severity: "error", message: string}>, files: number}} What it found.
+ *   severity: "warning", message: string}>, files: number}} What it found.
  */
 export function lintContentIcons(contentBase, { skipDirectories = [], registry } = {}) {
     const skip = new Set(skipDirectories);
@@ -355,7 +598,7 @@ export function iconPlugin(registry = DEFAULT_ICONS) {
     return (md) => {
         /** @type {any} */ (md).inline.ruler.before("emphasis", "heroiclands_icon", iconRule);
         /** @type {any} */ (md).renderer.rules.heroiclands_icon = (tokens, idx) =>
-            iconHtml(tokens[idx].meta.entry);
+            iconHtml(tokens[idx].meta.entry, tokens[idx].meta.attrs);
 
         /**
          * @param {any} state - markdown-it inline state.
@@ -367,7 +610,7 @@ export function iconPlugin(registry = DEFAULT_ICONS) {
             if (state.src.charCodeAt(start) !== 0x3a /* : */) return false;
             // Anchored at the cursor, so the scan is O(token) rather than a
             // search of the remaining source at every colon in the paragraph.
-            const re = /^:icon-([a-z0-9]+(?:-[a-z0-9]+)*):/;
+            const re = /^:icon-([a-z0-9]+(?:-[a-z0-9]+)*):(?:\{([^}]*)\})?/;
             const m = re.exec(state.src.slice(start));
             if (!m) return false;
 
@@ -376,9 +619,14 @@ export function iconPlugin(registry = DEFAULT_ICONS) {
             // unrecognised name visible on the page instead of vanishing.
             if (!entry) return false;
 
+            // An attribute that cannot be honoured is reported by the lint, not
+            // enforced here: refusing to render would hide a good icon over a
+            // bad size, and the page is the place the author is looking.
+            const { attrs } = parseIconAttributes(m[2]);
+
             if (!silent) {
                 const token = state.push("heroiclands_icon", "", 0);
-                token.meta = { name: m[1], entry };
+                token.meta = { name: m[1], entry, attrs };
                 token.markup = m[0];
             }
             state.pos += m[0].length;

package/package.json

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

@@ -61,13 +61,13 @@ export function decomposedRuns(text: string): Array<{
  * @param {string} text - The file's contents.
  * @param {string} file - Path to report, relative to the tree.
  * @returns {Array<{file: string, line: number, column: number,
- *   severity: "error", message: string}>} What is wrong, in file order.
+ *   severity: "warning", message: string}>} What is wrong, in file order.
  */
 export function checkText(text: string, file: string): Array<{
     file: string;
     line: number;
     column: number;
-    severity: "error";
+    severity: "warning";
     message: string;
 }>;
 /**
@@ -84,7 +84,7 @@ export function checkText(text: string, file: string): Array<{
  *   in addition to the dot-directories always skipped.
  * @param {readonly string[]} [opts.extensions] - File extensions to read.
  * @returns {{findings: Array<{file: string, line: number, column: number,
- *   severity: "error", message: string}>, files: number}} The findings, and how
+ *   severity: "warning", message: string}>, files: number}} The findings, and how
  *   many files produced them.
  */
 export function lintContentCharset(contentBase: string, { skipDirectories, extensions }?: {
@@ -95,7 +95,7 @@ export function lintContentCharset(contentBase: string, { skipDirectories, exten
         file: string;
         line: number;
         column: number;
-        severity: "error";
+        severity: "warning";
         message: string;
     }>;
     files: number;

package/types/engine/content-icons.d.mts

@@ -1,3 +1,27 @@
+/**
+ * The family an entry draws from, named or defaulted.
+ *
+ * @param {{family?: string}} entry - A registry entry.
+ * @returns {string} The family name.
+ */
+export function familyOf(entry: {
+    family?: string;
+}): string;
+/**
+ * Read the brace of an icon token.
+ *
+ * Values are validated against {@link ICON_ATTRIBUTES} here rather than at the
+ * point of rendering, so a mistake is one finding with a position rather than a
+ * silently different page.
+ *
+ * @param {string} [raw] - The text between the braces, without them.
+ * @returns {{attrs: Record<string, string>, problems: string[]}} What was
+ *   written, and what cannot be honoured.
+ */
+export function parseIconAttributes(raw?: string): {
+    attrs: Record<string, string>;
+    problems: string[];
+};
 /**
  * Look one name up.
  *
@@ -26,7 +50,7 @@ export function iconHtml(entry: {
     style: string;
     icon: string;
     label: string;
-}): string;
+}, attrs?: {}): string;
 /**
  * Every icon a string names, in the order written.
  *
@@ -49,13 +73,13 @@ export function iconsIn(text: string): Array<{
  * @param {string} file - Path to report.
  * @param {Record<string, object>} [registry] - Defaults to {@link DEFAULT_ICONS}.
  * @returns {Array<{file: string, line: number, column: number,
- *   severity: "error", message: string}>} The unknown names.
+ *   severity: "warning", message: string}>} The unknown names.
  */
 export function lintIcons(text: string, file: string, registry?: Record<string, object>): Array<{
     file: string;
     line: number;
     column: number;
-    severity: "error";
+    severity: "warning";
     message: string;
 }>;
 /**
@@ -63,10 +87,10 @@ export function lintIcons(text: string, file: string, registry?: Record<string,
  *
  * @param {Record<string, object>} registry - A package's icon table.
  * @param {string} [where="icons"] - Where to say the fault is.
- * @returns {Array<{severity: "error", message: string}>} What is wrong with it.
+ * @returns {Array<{severity: "warning", message: string}>} What is wrong with it.
  */
 export function checkIconRegistry(registry: Record<string, object>, where?: string): Array<{
-    severity: "error";
+    severity: "warning";
     message: string;
 }>;
 /**
@@ -81,7 +105,7 @@ export function checkIconRegistry(registry: Record<string, object>, where?: stri
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
  * @param {Record<string, object>} [opts.registry] - The package's icon table.
  * @returns {{findings: Array<{file: string, line: number, column: number,
- *   severity: "error", message: string}>, files: number}} What it found.
+ *   severity: "warning", message: string}>, files: number}} What it found.
  */
 export function lintContentIcons(contentBase: string, { skipDirectories, registry }?: {
     skipDirectories?: readonly string[] | undefined;
@@ -91,7 +115,7 @@ export function lintContentIcons(contentBase: string, { skipDirectories, registr
         file: string;
         line: number;
         column: number;
-        severity: "error";
+        severity: "warning";
         message: string;
     }>;
     files: number;
@@ -117,15 +141,97 @@ export function iconPlugin(registry?: Record<string, object>): (md: object) => v
  * @type {readonly string[]}
  */
 export const ICON_STYLES: readonly string[];
+/**
+ * The icon families a registry entry may draw from.
+ *
+ * **Two, because the interface uses two.** The SoHL icon legend says so in its
+ * own prose: Font Awesome for most things, and Game-Icons.net *"for the arms,
+ * gear, and condition glyphs that Font Awesome does not cover"* — eighteen of
+ * them, `ginf-broadsword` and its kin (#391).
+ *
+ * They differ in more than a class prefix, which is why this is a family rather
+ * than a naming convention:
+ *
+ * - Font Awesome has **weights**, so an entry names a `style` and a filled and
+ *   hollow pair is one icon twice. Game-Icons has none, so a `style` on such an
+ *   entry names something that does not exist.
+ * - They resolve to **different fonts**. A PDF has to embed both, and find each
+ *   codepoint in its own table — Font Awesome's from the file it ships,
+ *   Game-Icons' from the `game-icons-codepoints.json` the consumer's own
+ *   `build-icon-font.mjs` writes.
+ *
+ * `class` is the prefix the web surfaces use. `styled` says whether a `style`
+ * belongs on the entry at all, which is what lets a mistake be reported rather
+ * than rendered as a class nobody defined.
+ *
+ * @type {Readonly<Record<string, {class: string, styled: boolean, describe: string}>>}
+ */
+export const ICON_FAMILIES: Readonly<Record<string, {
+    class: string;
+    styled: boolean;
+    describe: string;
+}>>;
+/** The family an entry that does not name one belongs to. */
+export const DEFAULT_ICON_FAMILY: "fontawesome";
+/**
+ * The sizes a note may ask for, and what each means on a page.
+ *
+ * **A closed set, because size is content here rather than styling.** The icon
+ * legend exists to let a reader tell one glyph from another, and several of
+ * them genuinely cannot be told apart at the size of running text — so the
+ * enlargement is part of what that page *says*, not decoration applied to it.
+ * That is the one case worth a size at all.
+ *
+ * Closed rather than free-form for the usual reason: `font-size: 2em` in a note
+ * is CSS, which reaches two of the three surfaces and means nothing to the
+ * third. A name means the same thing everywhere, and the multiples below are
+ * Font Awesome's own, so the web class and the PDF scale cannot drift.
+ *
+ * @type {Readonly<Record<string, {class: string, scale: number}>>}
+ */
+export const ICON_SIZES: Readonly<Record<string, {
+    class: string;
+    scale: number;
+}>>;
+/**
+ * The attribute names a note may write, and how each is validated.
+ *
+ * One entry today. It is a table rather than an `if (key === "size")` because
+ * the next attribute — a fixed-width flag, a rotation, a title override — should
+ * cost a line here and nothing else, and because an unknown key has to be
+ * *reported*: silently ignoring `{sixe: 2x}` would leave the author looking at a
+ * page that is not what they asked for, with nothing to say why.
+ *
+ * @type {Readonly<Record<string, {values: readonly string[], describe: string}>>}
+ */
+export const ICON_ATTRIBUTES: Readonly<Record<string, {
+    values: readonly string[];
+    describe: string;
+}>>;
 /**
  * The icons the user guide already depicts, under the names it should call them.
  *
- * Each entry was read off the interface it describes rather than invented: the
- * `star`/`star-outline` pair is the filled and hollow star the mastery row and
- * the improve flag draw, and `edit` is the pencil the formula editor opens
- * from. The names are what a *writer* would reach for — `delete`, not
- * `trash-can` — because the writer is the one typing them; the Font Awesome
- * spelling is this table's business, not theirs.
+ * Each entry is read off the interface it describes rather than invented, and
+ * that is meant literally — the table was checked against the system's own
+ * templates, which is how `delete` came to be `fa-trash` rather than the
+ * `fa-trash-can` first written here. The sheets draw `fa-trash` twenty-five
+ * times and `fa-trash-can` never, so the first spelling would have printed an
+ * icon the reader has never seen on screen. A registry that is not checked
+ * against the interface is just a second place to be wrong.
+ *
+ * The names are what a *writer* would reach for — `delete`, not `trash` —
+ * because the writer is the one typing them; the Font Awesome spelling is this
+ * table's business, not theirs.
+ *
+ * **Three entries share `xmark`, and that is the point of naming rather than
+ * drawing.** A `✕` in the guide means "not applicable" in a Healing Rate
+ * column, "remove this row" on a control, and "close" on a dialog's corner. One
+ * glyph, three sentences, three different things for a reader who cannot see
+ * it — so they are three names with three labels, and the fact that Font
+ * Awesome happens to draw them identically stays in this table.
+ *
+ * `run` and `expand` are likewise distinct: `▶` runs an action, and its label
+ * should say so. `fa-play` is what the sheets use for it.
  *
  * @type {Readonly<Record<string, {style: string, icon: string, label: string}>>}
  */
@@ -146,6 +252,21 @@ export const DEFAULT_ICONS: Readonly<Record<string, {
  * Not `:name[content]`. That is remark-directive syntax, and this toolchain
  * parses with markdown-it; a directive would render as its own literal text.
  *
+ * An optional trailing brace carries **attributes**:
+ *
+ *     :icon-affiliation:{size: 2x}
+ *
+ * `key: value` pairs, comma-separated, in the shape `markdown-it-attrs` and
+ * remark-directive already use — so it is a convention a reader may recognise
+ * rather than one this module invented. Attributes rather than a bare value
+ * because `size` is merely the first one anybody needed: a fixed-width flag, a
+ * rotation, a title override are the same shape of thing, and a syntax that
+ * could only ever express size would have to be replaced to gain any of them.
+ *
+ * One inline rule consumes the token **and** its brace, so there is no state in
+ * which the icon resolves and the brace is left stranded on the page. An
+ * unhandled token degrades whole, exactly as the bare form does.
+ *
  * @type {RegExp}
  */
 export const ICON_PATTERN: RegExp;