@docx4j/core-ts 0.1.0 → 0.1.1

package/dist/model/fonts/Mapper.mjs

@@ -0,0 +1,481 @@
+import { DEFAULT_FONT_REGISTRY } from './registry.mjs';
+import { SUBSTITUTE_ROWS } from './substitutions.generated.mjs';
+import { MS_FONT_NAMES, MS_FONTS_WITH_BOLD, LINE_METRIC_FAMILIES, EAST_ASIAN_FAMILIES } from './families.generated.mjs';
+import { leftToTheDocumentDefault, selectByClass, substitutionClass } from './FontFallback.mjs';
+/** What the report says where nothing was measured. */
+export const UNKNOWN_ERROR = 'unknown';
+/** Word's own fallback where a document font resolves to nothing at all. */
+export const FONT_FALLBACK = 'Times New Roman';
+const MS_FONT_NAME_SET = new Set(MS_FONT_NAMES);
+const MS_FONTS_WITH_BOLD_SET = new Set(MS_FONTS_WITH_BOLD);
+const LINE_METRIC_FAMILY_SET = new Set(LINE_METRIC_FAMILIES);
+/** docx4j `WordLineMetrics.ALIASES`: families the table reaches through a built-in alias. */
+const LINE_METRIC_ALIASES = new Map([
+    ['helvetica', 'arial'], ['helvetica neue', 'arial'], ['helveticaneue', 'arial'],
+    ['helv', 'arial'], ['arialmt', 'arial'], ['timesnewromanpsmt', 'times new roman'],
+]);
+const EAST_ASIAN_FAMILY_SET = new Set(EAST_ASIAN_FAMILIES);
+/** docx4j `WordLineMetrics.isEastAsianFamily`: the table's optional field 7. */
+export function isEastAsianFamily(documentFont) {
+    if (documentFont === undefined)
+        return false;
+    const key = documentFont.trim().toLowerCase();
+    const alias = LINE_METRIC_ALIASES.get(key);
+    return EAST_ASIAN_FAMILY_SET.has(key) || (alias !== undefined && EAST_ASIAN_FAMILY_SET.has(alias));
+}
+/** docx4j `WordLineMetrics.isTableFamily`: the table's own families and its built-in aliases. */
+function isLineMetricFamily(documentFontName) {
+    if (documentFontName === undefined)
+        return false;
+    const key = documentFontName.trim().toLowerCase();
+    if (LINE_METRIC_FAMILY_SET.has(key))
+        return true;
+    const alias = LINE_METRIC_ALIASES.get(key);
+    return alias !== undefined && LINE_METRIC_FAMILY_SET.has(alias);
+}
+/**
+ * Whether docx4j's tables know this family: `MicrosoftFonts.xml`, `word-line-metrics` (512
+ * Microsoft and Office cloud families) or `FontSubstitutions.xml`.
+ *
+ * A known family the environment merely lacks is substituted for its widths (the passes before
+ * `addWordDefaultSubstitutes`), since Word on the author's machine had the font; an unknown one
+ * is what Word itself could not find either.  "Known" is `substitutionClass`, **not** `classOf`,
+ * which will also guess a class from a name that merely ends in "Sans": docx4j measured a
+ * corporate face that fell between the two and was drawn in the document default's serif
+ * throughout.  A family deliberately left to the document default is "known" for this purpose
+ * too, the measurement that put it there being that the default beat a stand-in.
+ */
+export function isKnownFamily(documentFontName) {
+    if (documentFontName === undefined || documentFontName === null)
+        return false;
+    const name = documentFontName.trim();
+    if (MS_FONT_NAME_SET.has(name))
+        return true;
+    if (isLineMetricFamily(name))
+        return true;
+    if (substitutionClass(name) !== 'UNKNOWN')
+        return true;
+    return leftToTheDocumentDefault(name);
+}
+const WEIGHT_WORDS = ['light', 'semilight', 'semibold', 'demibold', 'medium', 'black', 'thin',
+    'extralight', 'ultralight', 'heavy'];
+/**
+ * Whether this document font has a bold face of its own: the `MicrosoftFonts.xml` entry where
+ * there is one (Franklin Gothic Book has none), else a family whose name ends in a weight word
+ * (Calibri Light, Segoe UI Semibold, Arial Black) is a single weight in Windows' font model and
+ * has none; any other family is taken to have one.
+ */
+export function hasBoldFace(documentFontName) {
+    if (documentFontName === undefined || documentFontName === null)
+        return true;
+    const name = documentFontName.trim();
+    if (MS_FONT_NAME_SET.has(name))
+        return MS_FONTS_WITH_BOLD_SET.has(name);
+    let last = name.toLowerCase();
+    const sp = last.lastIndexOf(' ');
+    if (sp > 0)
+        last = last.slice(sp + 1);
+    return !WEIGHT_WORDS.includes(last);
+}
+/** The source a table row's quality word says. */
+function sourceOf(substitute) {
+    if (substitute === undefined)
+        return 'CLASS';
+    if (substitute.quality === 'metric')
+        return 'METRIC_CLONE';
+    if (substitute.quality === 'measured')
+        return 'MEASURED_STAND_IN';
+    return 'CLASS';
+}
+/** The font table keyed by lower-cased name. */
+export function fontTableOf(fonts) {
+    var _a;
+    const table = new Map();
+    for (const font of (_a = fonts === null || fonts === void 0 ? void 0 : fonts.font) !== null && _a !== void 0 ? _a : []) {
+        if ((font === null || font === void 0 ? void 0 : font.name) !== undefined)
+            table.set(font.name.trim().toLowerCase(), font);
+    }
+    return table;
+}
+/**
+ * The font Word draws an unknown font in, by its fontTable entry: measured (docx4j CR-016
+ * probe `fonts-unresolvable`, Word 365) a face whose entry says `w:family="roman"` is drawn in
+ * **Cambria**, one saying `swiss` in **Calibri**, one with an entry that names no family in
+ * Calibri, one with no fontTable entry at all in Cambria; an exact panose does not change that
+ * (Arial's gave Calibri), and the document's default font is never used.
+ */
+export function wordDefaultFor(documentFontName, table) {
+    var _a, _b;
+    let entry = table.get(documentFontName.trim().toLowerCase());
+    if (entry === undefined)
+        return 'Cambria';
+    // the family: the entry's own, else the first along its altName chain
+    const seen = new Set();
+    while (entry !== undefined && entry.name !== undefined && !seen.has(entry.name.trim().toLowerCase())) {
+        seen.add(entry.name.trim().toLowerCase());
+        const family = (_a = entry.family) === null || _a === void 0 ? void 0 : _a.val;
+        if (family !== undefined) {
+            const f = family.trim().toLowerCase();
+            if (f === 'roman')
+                return 'Cambria';
+            if (f === 'modern')
+                return 'Courier New';
+            return 'Calibri'; // swiss, script, decorative, auto
+        }
+        const alt = (_b = entry.altName) === null || _b === void 0 ? void 0 : _b.val;
+        entry = alt === undefined ? undefined : table.get(alt.trim().toLowerCase());
+    }
+    return 'Calibri';
+}
+/**
+ * Maps the document's font names to physical fonts, over a {@link FontRegistry} the caller
+ * supplies.  One per package, as in docx4j.
+ */
+export class Mapper {
+    constructor(
+    /** The fonts the consumer has; the docx4j font jars' faces where nothing is given, which
+     *  is the environment the parity goldens were made in. */
+    registry = DEFAULT_FONT_REGISTRY) {
+        this.registry = registry;
+        /** The mapping, keyed by the lower-cased document font name. */
+        this.fontMappings = new Map();
+        /** The document's embedded faces, keyed by the name the font table part uses. */
+        this.regularForms = new Map();
+        this.boldForms = new Map();
+        this.italicForms = new Map();
+        this.boldItalicForms = new Map();
+        this.decisions = new Map();
+        /** The document fonts `addWordDefaultSubstitutes` mapped: Word substitutes such a font whole,
+         *  bold face included, so `addNoBoldFaceAliases` leaves them alone. */
+        this.wordDefaulted = new Set();
+        this.lineMetricsAliases = new Map();
+    }
+    /** The physical font a document font maps to, by case-insensitive name; undefined for a slot
+     *  nothing names (docx4j `Mapper.get`, which tolerates null since 17.1.1). */
+    get(key) {
+        if (key === undefined || key === null)
+            return undefined;
+        return this.fontMappings.get(key.toLowerCase());
+    }
+    put(key, pf) {
+        this.fontMappings.set(key.toLowerCase(), pf);
+    }
+    get size() {
+        return this.fontMappings.size;
+    }
+    /** What was decided for this document font, or undefined where no pass met it. */
+    getDecision(documentFont) {
+        var _a;
+        if (documentFont === undefined || documentFont === null)
+            return undefined;
+        const record = this.decisions.get(documentFont.trim().toLowerCase());
+        if (record === undefined)
+            return undefined;
+        return { ...record, physicalFont: (_a = this.get(record.documentFont)) !== null && _a !== void 0 ? _a : null };
+    }
+    /** Every decision, ordered by the document font's name (case-insensitively), so that two
+     *  runs over the same document give the same list. */
+    getDecisions() {
+        return [...this.decisions.values()]
+            .map((r) => { var _a; return ({ ...r, physicalFont: (_a = this.get(r.documentFont)) !== null && _a !== void 0 ? _a : null }); })
+            .sort((a, b) => a.documentFont.toLowerCase().localeCompare(b.documentFont.toLowerCase()));
+    }
+    /** Whose Word line metrics a document font takes, where a pass resolved it through another
+     *  family; undefined where it takes its own.  Per mapper, i.e. per package: docx4j's was a
+     *  JVM-wide map until 17.1.1, and one document's `w:altName` answered for every later one. */
+    lineMetricsFamily(documentFont) {
+        if (documentFont === undefined)
+            return undefined;
+        return this.lineMetricsAliases.get(documentFont.trim().toLowerCase());
+    }
+    registerLineMetricsAlias(documentFont, family) {
+        if (documentFont === undefined || family === undefined)
+            return;
+        const key = documentFont.trim().toLowerCase();
+        // a font with metrics of its own takes them; there is nothing to alias
+        if (isLineMetricFamily(documentFont))
+            return;
+        this.lineMetricsAliases.set(key, family.trim());
+    }
+    decide(documentFont, source, via = null, widthError = null) {
+        this.decisions.set(documentFont.trim().toLowerCase(), { documentFont: documentFont.trim(), source, via, widthError });
+    }
+    // --- embedded faces ----------------------------------------------------------------
+    registerRegularForm(name, pf) { set(this.regularForms, name, pf); }
+    registerBoldForm(name, pf) { set(this.boldForms, name, pf); }
+    registerItalicForm(name, pf) { set(this.italicForms, name, pf); }
+    registerBoldItalicForm(name, pf) { set(this.boldItalicForms, name, pf); }
+    /** Whether the document embeds this font. */
+    isEmbedded(name) {
+        return this.regularForms.has(name) || this.boldForms.has(name)
+            || this.italicForms.has(name) || this.boldItalicForms.has(name);
+    }
+    /** The installed font of this name, else the document's embedded form of it (docx4j
+     *  CR-016 Decisions 2: the installed font wins, for all four faces and in both mappers). */
+    installedOrEmbedded(name) {
+        var _a, _b, _c, _d;
+        return (_d = (_c = (_b = (_a = this.registry.get(name)) !== null && _a !== void 0 ? _a : this.regularForms.get(name)) !== null && _b !== void 0 ? _b : this.boldForms.get(name)) !== null && _c !== void 0 ? _c : this.italicForms.get(name)) !== null && _d !== void 0 ? _d : this.boldItalicForms.get(name);
+    }
+    // --- the passes --------------------------------------------------------------------
+    /**
+     * The mapper's own answer for a document font the environment has neither under that name
+     * nor embedded; undefined where it has none.  {@link resolvedVia} says how it was reached.
+     */
+    resolveDocumentFont(_documentFontName, _fontTableEntry) {
+        return undefined;
+    }
+    /** An entry for each of the document's fonts: steps 1 to 3 of the precedence. */
+    populateFontMappings(documentFontNames, fonts) {
+        var _a;
+        const table = fontTableOf(fonts);
+        for (const documentFontName of documentFontNames) {
+            if (documentFontName === undefined || documentFontName.trim().length === 0)
+                continue;
+            if (this.get(documentFontName) !== undefined)
+                continue; // already mapped; its decision stands
+            let pf = this.installedOrEmbedded(documentFontName);
+            let source = pf === undefined ? undefined
+                : (this.registry.get(documentFontName) !== undefined ? 'INSTALLED' : 'EMBEDDED');
+            if (pf === undefined) {
+                this.resolvedVia = undefined;
+                pf = this.resolveDocumentFont(documentFontName, table.get(documentFontName.trim().toLowerCase()));
+                if (pf !== undefined)
+                    source = 'MAPPER_OWN';
+            }
+            if (pf === undefined) {
+                // recorded, not merely logged: a later pass overwrites this where it maps the font,
+                // and what is left says which fonts reached the consumer with nothing
+                this.decide(documentFontName, 'UNMAPPED');
+            }
+            else {
+                this.put(documentFontName, pf);
+                this.decide(documentFontName, source, source === 'MAPPER_OWN'
+                    ? ((_a = this.resolvedVia) !== null && _a !== void 0 ? _a : `the mapper's own answer: ${pf.name}`)
+                    : null);
+            }
+        }
+    }
+    /**
+     * `font-substitutes.xml`: for each document font the table knows, the first of its open
+     * substitutes this environment has.  The measurements that chose each substitute are in
+     * docx4j's `Mapper.addMetricallyCompatibleSubstitutes` javadoc, and the table's `error`
+     * attributes quote them.
+     */
+    addMetricallyCompatibleSubstitutes() {
+        var _a;
+        for (const row of SUBSTITUTE_ROWS) {
+            const before = this.get(row.documentFont);
+            let taken;
+            for (const candidate of row.substitutes) {
+                if (this.registry.get(candidate.font) !== undefined) {
+                    taken = candidate;
+                    break;
+                }
+            }
+            if (taken === undefined)
+                continue;
+            this.addMetricallyCompatibleSubstitute(row.documentFont, taken.font);
+            const after = this.get(row.documentFont);
+            if (after !== undefined && after !== before) {
+                this.decide(row.documentFont, sourceOf(taken), null, (_a = taken.error) !== null && _a !== void 0 ? _a : (taken.quality === 'class' ? UNKNOWN_ERROR : null));
+            }
+        }
+    }
+    /** Map this document font to an open substitute, unless the environment has the font itself
+     *  or the document embeds it (the embedded font is what the author intended, and it is the
+     *  only thing certain to be available). */
+    addMetricallyCompatibleSubstitute(documentFont, substitute) {
+        if (this.isEmbedded(documentFont))
+            return;
+        if (this.registry.get(documentFont) !== undefined)
+            return;
+        const pf = this.registry.get(substitute);
+        if (pf !== undefined)
+            this.put(documentFont, pf);
+    }
+    /**
+     * `w:altName` in `word/fontTable.xml` (ECMA-376 17.8.3.1): "the name of an alternate font
+     * which shall be used if the font specified is not available".  That is the document author's
+     * own answer to a missing font, and Word takes it.
+     *
+     * After the metric clones - a clone of the document's own font is a better answer than any
+     * alias - and before the class pass, which is only a guess from the name.  The chain is
+     * followed: the alternate may itself be absent and name an alternate (CR-016 probe
+     * `fonts-unresolvable` (e), (f)); a few hops, never a cycle.
+     */
+    addAltNameSubstitutes(documentFontNames, fonts) {
+        var _a, _b, _c, _d;
+        const altNames = new Map();
+        for (const font of (_a = fonts === null || fonts === void 0 ? void 0 : fonts.font) !== null && _a !== void 0 ? _a : []) {
+            const alt = (_b = font === null || font === void 0 ? void 0 : font.altName) === null || _b === void 0 ? void 0 : _b.val;
+            if ((font === null || font === void 0 ? void 0 : font.name) === undefined || alt === undefined || alt.trim().length === 0)
+                continue;
+            altNames.set(font.name.trim().toLowerCase(), alt.trim());
+        }
+        if (altNames.size === 0)
+            return;
+        const names = documentFontNames !== null && documentFontNames !== void 0 ? documentFontNames : altNames.keys();
+        for (const documentFontName of names) {
+            if (documentFontName === undefined || documentFontName.trim().length === 0)
+                continue;
+            if (this.get(documentFontName) !== undefined)
+                continue; // already mapped
+            if (this.isEmbedded(documentFontName))
+                continue;
+            if (this.registry.get(documentFontName) !== undefined)
+                continue; // installed; identity
+            const first = altNames.get(documentFontName.trim().toLowerCase());
+            let alt = first;
+            const seen = new Set([documentFontName.trim().toLowerCase()]);
+            let pf;
+            let resolvedAlt;
+            let eastAsianHop;
+            const chain = [];
+            while (alt !== undefined && !seen.has(alt.trim().toLowerCase())) {
+                seen.add(alt.trim().toLowerCase());
+                chain.push(alt);
+                /* A hop this environment lacks but whose family the line-metrics table flags East
+                 * Asian: Word had that font and drew it, and its line is 1.3 x its usWin box, which no
+                 * substitute comes near.  The chain goes on for the *width* substitution; only the line
+                 * box is taken here. */
+                if (eastAsianHop === undefined && isEastAsianFamily(alt) && this.registry.get(alt) === undefined) {
+                    eastAsianHop = alt;
+                }
+                pf = (_d = (_c = this.registry.get(alt)) !== null && _c !== void 0 ? _c : this.registry.get(`${alt} Regular`)) !== null && _d !== void 0 ? _d : this.get(alt);
+                if (pf !== undefined) {
+                    resolvedAlt = alt;
+                    break;
+                }
+                alt = altNames.get(alt.trim().toLowerCase());
+            }
+            /* The line box is registered even where the chain found no face: Word had the alternate
+             * and drew it, so the line is its whatever renders the glyphs. */
+            if (eastAsianHop !== undefined)
+                this.registerLineMetricsAlias(documentFontName, eastAsianHop);
+            if (pf === undefined)
+                continue;
+            this.put(documentFontName, pf);
+            if (eastAsianHop === undefined)
+                this.registerLineMetricsAlias(documentFontName, resolvedAlt);
+            this.decide(documentFontName, 'ALT_NAME', `w:altName ${chain.join(' -> ')}`);
+        }
+    }
+    /** Whether {@link addClassBasedSubstitutes} applies to this mapper.  True for every mapper
+     *  since docx4j 17.1.1. */
+    wantsClassBasedSubstitutes() {
+        return true;
+    }
+    /**
+     * Map whatever is still unmapped to a font of the same class.  Without it an unmapped font
+     * falls back to whatever the document's *default* font maps to, which is a Times clone
+     * standing in for a sans as often as not.  Deliberately conservative: a condensed face is
+     * left unmapped, its widths being further from an ordinary condensed face's than the
+     * default's are.
+     */
+    addClassBasedSubstitutes(documentFontNames) {
+        if (documentFontNames === undefined)
+            return;
+        for (const documentFontName of documentFontNames) {
+            if (documentFontName === undefined || documentFontName.trim().length === 0)
+                continue;
+            if (this.get(documentFontName) !== undefined)
+                continue;
+            if (this.isEmbedded(documentFontName))
+                continue;
+            if (this.registry.get(documentFontName) !== undefined)
+                continue;
+            const pf = selectByClass(this.registry, documentFontName);
+            if (pf !== undefined) {
+                this.put(documentFontName, pf);
+                this.decide(documentFontName, 'CLASS', `a face of the same class: ${substitutionClass(documentFontName)}`, UNKNOWN_ERROR);
+            }
+        }
+    }
+    /** The mapper's own guesses for what the measured passes left (`BestMatchingMapper`'s panose
+     *  match and `FontSubstitutions.xml`).  Nothing here: that mapper needs font files. */
+    addMapperSubstitutes(_documentFontNames, _fonts) {
+    }
+    /**
+     * Word's own answer for a font it cannot find, for whatever is still unmapped: Cambria or
+     * Calibri (or Courier New) by the fontTable entry's family ({@link wordDefaultFor}), mapped
+     * to whatever this mapper maps that font to.  Applied only to a family none of docx4j's
+     * tables know ({@link isKnownFamily}).
+     */
+    addWordDefaultSubstitutes(documentFontNames, fonts) {
+        var _a, _b;
+        if (documentFontNames === undefined)
+            return;
+        const table = fontTableOf(fonts);
+        for (const documentFontName of documentFontNames) {
+            if (documentFontName === undefined || documentFontName.trim().length === 0)
+                continue;
+            if (this.get(documentFontName) !== undefined)
+                continue;
+            if (this.isEmbedded(documentFontName))
+                continue;
+            if (this.registry.get(documentFontName) !== undefined)
+                continue;
+            if (isKnownFamily(documentFontName))
+                continue;
+            const wordFont = wordDefaultFor(documentFontName, table);
+            const pf = (_b = (_a = this.get(wordFont)) !== null && _a !== void 0 ? _a : this.registry.get(wordFont)) !== null && _b !== void 0 ? _b : selectByClass(this.registry, wordFont);
+            if (pf === undefined)
+                continue;
+            this.put(documentFontName, pf);
+            this.wordDefaulted.add(documentFontName.trim().toLowerCase());
+            this.registerLineMetricsAlias(documentFontName, wordFont);
+            this.decide(documentFontName, 'WORD_DEFAULT', `Word's own default for a font it cannot find: ${wordFont}`, UNKNOWN_ERROR);
+        }
+    }
+    /**
+     * For each document font with no bold face of its own, an alias of its mapped physical font
+     * reporting none, so that the consumer synthesises bold at the regular advances as Word does.
+     * Last of the passes: it re-maps, and it is not a source of its own - the decision says so by
+     * reporting a synthetic bold face.
+     */
+    addNoBoldFaceAliases(documentFontNames) {
+        if (documentFontNames === undefined)
+            return;
+        for (const documentFontName of documentFontNames) {
+            if (documentFontName === undefined || documentFontName.trim().length === 0)
+                continue;
+            if (hasBoldFace(documentFontName))
+                continue;
+            if (this.isEmbedded(documentFontName))
+                continue; // the embedded forms say what the document has
+            /* A font Word itself could not find is substituted whole - Calibri's real bold for its
+             * w:b - however its name reads: "EnBW DIN Pro Light" is Calibri Bold in Word, not a
+             * synthesised Calibri.  Measured (CR-016 phase 4 gate): with the alias that document
+             * scored 0.8441, without it 0.8783. */
+            if (this.wordDefaulted.has(documentFontName.trim().toLowerCase()))
+                continue;
+            const pf = this.get(documentFontName);
+            if (pf === undefined || pf.noBoldFace)
+                continue;
+            this.fontMappings.set(documentFontName.toLowerCase(), pf.noBoldFaceAlias());
+        }
+    }
+    /**
+     * Every pass in order, as docx4j's `WordprocessingMLPackage.setFontMapper` runs them.
+     *
+     * @param documentFontNames the document's font names (`MainDocumentPart.fontsInUse()`)
+     * @param fonts the font table part's content, for `w:altName` and `w:family`
+     */
+    populate(documentFontNames, fonts) {
+        const names = [...documentFontNames];
+        this.populateFontMappings(names, fonts);
+        this.addMetricallyCompatibleSubstitutes();
+        this.addAltNameSubstitutes(names, fonts);
+        if (this.wantsClassBasedSubstitutes())
+            this.addClassBasedSubstitutes(names);
+        this.addMapperSubstitutes(names, fonts);
+        this.addWordDefaultSubstitutes(names, fonts);
+        this.addNoBoldFaceAliases(names);
+    }
+}
+function set(map, name, pf) {
+    if (pf === undefined)
+        map.delete(name);
+    else
+        map.set(name, pf);
+}

package/dist/model/fonts/PhysicalFont.d.mts

@@ -0,0 +1,34 @@
+/** The suffix of a no-bold-face alias; a registry lookup strips it (docx4j `PhysicalFonts.get`). */
+export declare const NOBOLD_SUFFIX = "+nobold";
+/**
+ * A font available to the consumer: the full name a font registry keys it by (docx4j registers
+ * the first of FOP's triplets, the name table's id 4 - "Carlito Regular", "Arimo Bold"), and
+ * the family a `font-family` names ("Carlito").
+ */
+export declare class PhysicalFont {
+    /** The face's full name, as a registry keys it. */
+    readonly name: string;
+    /** True for a {@link noBoldFaceAlias}. */
+    readonly noBoldFace: boolean;
+    constructor(
+    /** The face's full name, as a registry keys it. */
+    name: string, 
+    /** The family name, as CSS would use it; the name with its twin suffixes stripped when the
+     *  registry does not say. */
+    familyName?: string, 
+    /** True for a {@link noBoldFaceAlias}. */
+    noBoldFace?: boolean);
+    readonly familyName: string;
+    /**
+     * This font again under `name + '+nobold'`, reporting no bold face of its own, so that a
+     * consumer synthesises bold from this file at its own advances rather than taking the
+     * family's real bold - which is what Word does for a family that has none (docx4j CR-016
+     * probe `fonts-light-bold`: Word draws a `w:b` run in Calibri Light with the Calibri Light
+     * font object, 378.55pt for a sentence its regular sets in 377.50, where Carlito Bold set it
+     * in 388.70).  Held by the mapper, never put in a registry - it stands for one document's font.
+     */
+    noBoldFaceAlias(): PhysicalFont;
+    toString(): string;
+}
+/** The physical font name without the suffixes a FO layer adds; they stack, so all are stripped. */
+export declare function stripSuffixes(name: string): string;

package/dist/model/fonts/PhysicalFont.mjs

@@ -0,0 +1,62 @@
+// docx4j `org.docx4j.fonts.PhysicalFont`, without the files.
+//
+// docx4j's class wraps FOP's `EmbedFontInfo` and carries the font's panose and its file URI, so
+// that FOP can be told where to read the outlines.  CR-001 Phase B step 4 ports the *decision*
+// half of `org.docx4j.fonts` and not the rendering half (CR-001 section 14.2), so a physical
+// font here is a name, the family a CSS `font-family` would use, and the no-bold-face flag -
+// everything a `Mapper` answer means to a consumer that draws with a browser, measures with
+// `fontkit`, or only reports.  Reading font files (`PhysicalFonts.discover`) is a later CR.
+/** The suffix of a no-bold-face alias; a registry lookup strips it (docx4j `PhysicalFonts.get`). */
+export const NOBOLD_SUFFIX = '+nobold';
+/** The suffixes the docx4j FO layer stacks on a font-family for a twin declared from the same
+ *  file: the kerned twin, the twin with no OpenType features, and the no-bold-face alias.
+ *  Nothing here produces the first two; they are stripped so that a name written by docx4j's
+ *  FO output resolves against a registry built here. */
+const SUFFIXES = ['+kerned', '+noliga', NOBOLD_SUFFIX];
+/**
+ * A font available to the consumer: the full name a font registry keys it by (docx4j registers
+ * the first of FOP's triplets, the name table's id 4 - "Carlito Regular", "Arimo Bold"), and
+ * the family a `font-family` names ("Carlito").
+ */
+export class PhysicalFont {
+    constructor(
+    /** The face's full name, as a registry keys it. */
+    name, 
+    /** The family name, as CSS would use it; the name with its twin suffixes stripped when the
+     *  registry does not say. */
+    familyName, 
+    /** True for a {@link noBoldFaceAlias}. */
+    noBoldFace = false) {
+        this.name = name;
+        this.noBoldFace = noBoldFace;
+        this.familyName = familyName !== null && familyName !== void 0 ? familyName : stripSuffixes(name);
+    }
+    /**
+     * This font again under `name + '+nobold'`, reporting no bold face of its own, so that a
+     * consumer synthesises bold from this file at its own advances rather than taking the
+     * family's real bold - which is what Word does for a family that has none (docx4j CR-016
+     * probe `fonts-light-bold`: Word draws a `w:b` run in Calibri Light with the Calibri Light
+     * font object, 378.55pt for a sentence its regular sets in 377.50, where Carlito Bold set it
+     * in 388.70).  Held by the mapper, never put in a registry - it stands for one document's font.
+     */
+    noBoldFaceAlias() {
+        return new PhysicalFont(this.name + NOBOLD_SUFFIX, this.familyName, true);
+    }
+    toString() {
+        return this.name;
+    }
+}
+/** The physical font name without the suffixes a FO layer adds; they stack, so all are stripped. */
+export function stripSuffixes(name) {
+    let key = name;
+    for (let stripped = true; stripped;) {
+        stripped = false;
+        for (const suffix of SUFFIXES) {
+            if (key.endsWith(suffix)) {
+                key = key.slice(0, -suffix.length);
+                stripped = true;
+            }
+        }
+    }
+    return key;
+}