@heroiclands/package-build 20.2.0 → 20.3.0

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # @heroiclands/package-build
 
+## 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
+
+- f39c7e8: Restore the lockfile refresh to the release, and re-sync the lockfile 20.2.0
+  shipped without.
+  
+  `changeset version` rewrites `package.json` and the CHANGELOG and never touches
+  `package-lock.json`, so the lockfile's root `version` keeps the previous
+  release's number. The `version-script` input is the only seam the changesets
+  action offers between versioning and committing, which is where the refresh has
+  to happen for it to land in the same commit.
+  
+  That input was removed for one release on the theory that it was why `changeset
+  version` could not find its own binary. It was not: `node_modules` had been
+  committed as a symlink to an absolute path, and the action's `git reset --hard`
+  restored it over the install, so nothing resolved by any mechanism. With the
+  symlink gone the seam works again, and it is back.
+
 ## 20.2.0
 
 ### Minor 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,143 @@ import path from "node:path";
  */
 export const ICON_STYLES = Object.freeze(["solid", "regular", "brands"]);
 
+/**
+ * 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" },
     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 +234,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 +280,11 @@ 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 classes = [`fa-${attr(entry.style)}`, `fa-${attr(entry.icon)}`];
+    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 +296,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 +313,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 +397,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,14 +405,14 @@ 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)) {
             findings.push({
-                severity: /** @type {const} */ ("error"),
+                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 ` +
@@ -274,13 +421,13 @@ export function checkIconRegistry(registry, where = "icons") {
         }
         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 +449,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 +502,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 +514,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 +523,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.0",
+    "version": "20.3.0",
     "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,18 @@
+/**
+ * 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 +41,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 +64,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 +78,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 +96,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 +106,7 @@ export function lintContentIcons(contentBase: string, { skipDirectories, registr
         file: string;
         line: number;
         column: number;
-        severity: "error";
+        severity: "warning";
         message: string;
     }>;
     files: number;
@@ -117,15 +132,65 @@ export function iconPlugin(registry?: Record<string, object>): (md: object) => v
  * @type {readonly string[]}
  */
 export const ICON_STYLES: readonly string[];
+/**
+ * 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 +211,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;