reamkit 1.22.0 → 1.24.0

package/dist/esm/core/drawingml/text-warp.js

@@ -0,0 +1,355 @@
+//#region src/core/drawingml/text-warp.ts
+/** Distance from the box's centre line, `0` at the middle and `1` at either edge. */
+var fromCentre = (u) => Math.abs(2 * u - 1);
+/** A band of constant height `1 - drop` whose top edge is `top`. */
+var band = (top, drop) => ({
+	top,
+	bottom: top + (1 - drop)
+});
+/**
+* §20.1.10.76 ST_TextShapeType — the warp each preset applies, keyed by its
+* name. `adj` arrives as the `a:avLst` adjustment in hundred-thousandths, or
+* the preset's own default when the file states none.
+*/
+var ENVELOPES = new Map([
+	["textPlain", {
+		defaultAdj: 0,
+		at: () => ({
+			top: 0,
+			bottom: 1
+		})
+	}],
+	["textStop", {
+		defaultAdj: 12500,
+		at: (u, adj) => {
+			const t = adj * Math.max(0, (fromCentre(u) - .375) / .625);
+			return {
+				top: t,
+				bottom: 1 - t
+			};
+		}
+	}],
+	["textTriangle", {
+		defaultAdj: 5e4,
+		at: (u, adj) => ({
+			top: adj * fromCentre(u),
+			bottom: 1
+		})
+	}],
+	["textTriangleInverted", {
+		defaultAdj: 5e4,
+		at: (u, adj) => ({
+			top: 0,
+			bottom: 1 - adj * fromCentre(u)
+		})
+	}],
+	["textChevron", {
+		defaultAdj: 25e3,
+		at: (u, adj) => band(adj * fromCentre(u), adj)
+	}],
+	["textChevronInverted", {
+		defaultAdj: 25e3,
+		at: (u, adj) => band(adj * (1 - fromCentre(u)), adj)
+	}],
+	["textCanUp", {
+		defaultAdj: 14e3,
+		at: (u, adj) => band(adj * fromCentre(u) ** 4, adj)
+	}],
+	["textCanDown", {
+		defaultAdj: 14e3,
+		at: (u, adj) => band(adj * (1 - fromCentre(u) ** 4), adj)
+	}],
+	["textWave1", {
+		defaultAdj: 6250,
+		at: (u, adj) => band(adj * (1 - Math.sin(2 * Math.PI * u)), 2 * adj)
+	}],
+	["textWave2", {
+		defaultAdj: 6250,
+		at: (u, adj) => band(adj * (1 + Math.sin(2 * Math.PI * u)), 2 * adj)
+	}],
+	["textDoubleWave1", {
+		defaultAdj: 6250,
+		at: (u, adj) => band(adj * (1 - Math.sin(4 * Math.PI * u)), 2 * adj)
+	}],
+	["textWave4", {
+		defaultAdj: 6250,
+		at: (u, adj) => band(adj * (1 + Math.sin(4 * Math.PI * u)), 2 * adj)
+	}],
+	["textInflate", {
+		defaultAdj: 13600,
+		at: (u, adj) => {
+			const t = adj * fromCentre(u) ** 2;
+			return {
+				top: t,
+				bottom: 1 - t
+			};
+		}
+	}],
+	["textDeflate", {
+		defaultAdj: 37500,
+		at: (u, adj) => {
+			const t = adj * (1 - fromCentre(u) ** 2.23);
+			return {
+				top: t,
+				bottom: 1 - t
+			};
+		}
+	}],
+	["textInflateTop", {
+		defaultAdj: 31800,
+		at: (u, adj) => ({
+			top: adj * fromCentre(u) ** 2,
+			bottom: 1
+		})
+	}],
+	["textDeflateTop", {
+		defaultAdj: 47e3,
+		at: (u, adj) => ({
+			top: adj * (1 - fromCentre(u) ** 2),
+			bottom: 1
+		})
+	}],
+	["textInflateBottom", {
+		defaultAdj: 31800,
+		at: (u, adj) => ({
+			top: 0,
+			bottom: 1 - adj * fromCentre(u) ** 2
+		})
+	}],
+	["textDeflateBottom", {
+		defaultAdj: 47e3,
+		at: (u, adj) => ({
+			top: 0,
+			bottom: 1 - adj * (1 - fromCentre(u) ** 2)
+		})
+	}],
+	["textDeflateInflate", {
+		defaultAdj: 19800,
+		at: (u, adj) => ({
+			top: 0,
+			bottom: .268 + adj * fromCentre(u) ** 2
+		})
+	}],
+	["textDeflateInflateDeflate", {
+		defaultAdj: 4600,
+		at: (u, adj) => ({
+			top: 0,
+			bottom: .258 + adj * fromCentre(u) ** 2
+		})
+	}],
+	["textFadeRight", {
+		defaultAdj: 33333,
+		at: (u, adj) => ({
+			top: adj * u,
+			bottom: 1 - adj * u
+		})
+	}],
+	["textFadeLeft", {
+		defaultAdj: 33333,
+		at: (u, adj) => ({
+			top: adj * (1 - u),
+			bottom: 1 - adj * (1 - u)
+		})
+	}],
+	["textFadeUp", {
+		defaultAdj: 1e5,
+		at: (u, adj) => ({
+			top: adj * fromCentre(u) ** 2,
+			bottom: 1
+		})
+	}],
+	["textFadeDown", {
+		defaultAdj: 1e5,
+		at: (u, adj) => ({
+			top: 0,
+			bottom: 1 - adj * fromCentre(u) ** 2
+		})
+	}],
+	["textSlantUp", {
+		defaultAdj: 55500,
+		at: (u, adj) => band(adj * (1 - u), adj)
+	}],
+	["textSlantDown", {
+		defaultAdj: 44400,
+		at: (u, adj) => band(adj * u, adj)
+	}],
+	["textCascadeUp", {
+		defaultAdj: 55500,
+		at: (u, adj) => ({
+			top: .138 * (1 - u),
+			bottom: 1 - adj + adj * (1 - u)
+		})
+	}],
+	["textCascadeDown", {
+		defaultAdj: 55500,
+		at: (u, adj) => ({
+			top: .138 * u,
+			bottom: 1 - adj + adj * u
+		})
+	}],
+	["textCurveUp", {
+		defaultAdj: 45600,
+		at: (u, adj) => curve(1 - u, adj)
+	}],
+	["textCurveDown", {
+		defaultAdj: 45600,
+		at: (u, adj) => curve(u, adj)
+	}]
+]);
+/**
+* The ring presets, which do not hang text between two edges at all: they wind
+* it once round an ellipse inscribed in the box. Both start at the box's left
+* edge; `Inside` climbs over the top with each letter's head pointing out of
+* the ring, `Outside` dips under the bottom with each letter's head pointing
+* into it — which is why half of either one reads upside down.
+*
+* The band the letters occupy is a fixed share of the ring whatever the text:
+* eight letters and thirty-two fill exactly the same annulus, so it is the
+* preset and not the string that fixes the inner radius.
+*/
+var RING_INNER = .34;
+var RINGS = new Map([["textRingInside", {
+	clockwise: true,
+	headOut: true
+}], ["textRingOutside", {
+	clockwise: false,
+	headOut: false
+}]]);
+/**
+* The `textCurve*` pair: the baseline is an arc over the box and the band
+* narrows towards the end the text runs to.
+*
+* @param u   Position across the box, already turned the way the preset runs.
+* @param adj How much of the band's height the taper takes by the far end.
+* @returns   The two edges at `u`.
+*/
+function curve(u, adj) {
+	const bottom = 1 - .24 * (2 * u - 1) ** 2;
+	return {
+		top: bottom - (.758 - adj * u ** 1.7),
+		bottom
+	};
+}
+/**
+* Whether a preset bends text at all. `textNoShape` is the "no warp" member of
+* the enumeration and by far its most common value — two thirds of the decks
+* that mention a warp state only this one — and a body carrying it is an
+* ordinary text box, NOT WordArt stretched to its shape.
+*
+* @param preset The `a:prstTxWarp @prst` value.
+* @returns Whether {@link textWarpEdges} can bend text through this preset.
+*/
+function isTextWarp(preset) {
+	return ENVELOPES.has(preset) || RINGS.has(preset);
+}
+/**
+* The matrix that places one glyph of a warped body.
+*
+* Maps the glyph's own text space — x along its advance, y UP from its
+* baseline — into the page's top-left frame, as `[a, b, c, d, e, f]` with
+* `px = a·x + c·y + e` and `py = b·x + d·y + f`. Upright text therefore has a
+* negative `d`: the glyph's y runs against the page's.
+*
+* @param frame     The two frames, from the laid-out line.
+* @param glyphX    The glyph's left edge in the un-warped block.
+* @param advance   How wide the glyph is there.
+* @param baselineY The line's baseline in the un-warped block.
+* @returns The six numbers, or `undefined` where the warp leaves no room to
+*          draw — the pinched end of a fade, or a preset this file cannot bend.
+*/
+function warpGlyphMatrix(frame, glyphX, advance, baselineY) {
+	const u = (glyphX + advance / 2 - frame.srcX) / frame.srcWidth;
+	const v = (baselineY - frame.srcTop) / frame.srcHeight;
+	const ring = RINGS.get(frame.preset);
+	if (ring) return ringMatrix(frame, ring, u, v, glyphX);
+	return envelopeMatrix(frame, u, v, glyphX, advance);
+}
+/** The glyph matrix for a warp that hangs text between a top and a bottom edge. */
+function envelopeMatrix(frame, u, v, glyphX, advance) {
+	const edges = textWarpEdges(frame.preset, u, frame.adjust);
+	if (!edges) return void 0;
+	const height = edges.bottom - edges.top;
+	if (!(height > 0)) return void 0;
+	const sx = frame.boxWidth / frame.srcWidth;
+	const sy = height * frame.boxHeight / frame.srcHeight;
+	const step = .004;
+	const lo = Math.max(0, u - step);
+	const hi = Math.min(1, u + step);
+	const at = (q) => {
+		const e = textWarpEdges(frame.preset, q, frame.adjust);
+		return e ? e.top + v * (e.bottom - e.top) : void 0;
+	};
+	const before = at(lo);
+	const after = at(hi);
+	const slope = before !== void 0 && after !== void 0 && hi > lo ? (after - before) * frame.boxHeight / ((hi - lo) * frame.boxWidth) : 0;
+	const x0 = frame.boxX + (glyphX - frame.srcX) / frame.srcWidth * frame.boxWidth;
+	const mid = edges.top + v * height;
+	const y0 = frame.boxY + mid * frame.boxHeight - slope * advance * sx / 2;
+	return [
+		sx,
+		slope * sx,
+		0,
+		-sy,
+		x0,
+		y0
+	];
+}
+/**
+* The glyph matrix for a ring: one turn round the ellipse inscribed in the box.
+*
+* The band is a CONSTANT inset from that ellipse, not a scaled copy of it. A
+* scaled copy would be the natural reading — a circular annulus squashed to the
+* box's proportions — but it makes the band four times deeper at the ring's
+* sides than at its top on a box four times wider than tall, and the letters
+* there come out as spikes radiating from the centre. Held at a constant depth
+* the ring's outer edge still touches the box all the way round, which is what
+* both references draw and what a box of capitals measures.
+*/
+function ringMatrix(frame, ring, _u, v, glyphX) {
+	const a = frame.boxWidth / 2;
+	const b = frame.boxHeight / 2;
+	if (!(a > 0 && b > 0 && frame.srcWidth > 0 && frame.srcHeight > 0)) return void 0;
+	const uLeft = (glyphX - frame.srcX) / frame.srcWidth;
+	const turn = ring.clockwise ? -1 : 1;
+	const psi = Math.PI + turn * 2 * Math.PI * uLeft;
+	const cos = Math.cos(psi);
+	const sin = Math.sin(psi);
+	const rawX = -turn * a * sin;
+	const rawY = -turn * b * cos;
+	const speed = Math.hypot(rawX, rawY);
+	if (!(speed > 0)) return void 0;
+	const tx = rawX / speed;
+	const ty = rawY / speed;
+	const inX = -turn * -ty;
+	const inY = -turn * tx;
+	const head = ring.headOut ? -1 : 1;
+	const depth = (1 - RING_INNER) * b;
+	const sT = 2 * Math.PI * speed / frame.srcWidth;
+	const sN = depth / frame.srcHeight;
+	const inset = (ring.headOut ? v : 1 - v) * depth;
+	return [
+		sT * tx,
+		sT * ty,
+		sN * head * inX,
+		sN * head * inY,
+		frame.boxX + a + a * cos + inX * inset,
+		frame.boxY + b - b * sin + inY * inset
+	];
+}
+/**
+* The two edges of a warp at one position across its box.
+*
+* @param preset The `a:prstTxWarp @prst` value.
+* @param u      Position across the box, `0` at its left edge and `1` at its right.
+* @param adj    The `a:avLst` `adj` guide in hundred-thousandths, when the file states one.
+* @returns The top and bottom edges, `0`…`1` down the box, or `undefined` for a
+*          preset this file does not bend (an unknown name, or `textNoShape`).
+*/
+function textWarpEdges(preset, u, adj) {
+	const env = ENVELOPES.get(preset);
+	if (!env) return void 0;
+	const a = (adj ?? env.defaultAdj) / 1e5;
+	return env.at(Math.min(1, Math.max(0, u)), a);
+}
+//#endregion
+export { isTextWarp, warpGlyphMatrix };

package/dist/esm/core/drawingml/theme-parser.d.ts

@@ -1,4 +1,42 @@
 import { PoNode } from '../po-helpers.js';
+/**
+ * §20.1.4.1.16 `a:fontScheme` — the two typefaces a theme names, each in three
+ * scripts. A document does not repeat them: it refers to them by TOKEN
+ * (`+mj-lt`, `+mn-ea`, …), which every reader is expected to resolve.
+ */
+export interface ThemeFonts {
+    /** `a:majorFont` — headings. */
+    readonly major: ThemeFontSlots;
+    /** `a:minorFont` — body text. */
+    readonly minor: ThemeFontSlots;
+}
+/** One font of a scheme, in the three scripts a run may pick from. */
+export interface ThemeFontSlots {
+    readonly latin?: string;
+    readonly ea?: string;
+    readonly cs?: string;
+}
+/**
+ * Parse a theme's font scheme (§20.1.4.1.16).
+ *
+ * @param themeXml The raw theme part bytes, UTF-8.
+ * @returns The two fonts; slots the theme leaves empty are absent.
+ */
+export declare function parseThemeFonts(themeXml: Uint8Array): ThemeFonts;
+/**
+ * Resolve a typeface written as a theme TOKEN to the name it stands for.
+ *
+ * A slide states its fonts as `+mn-lt` far more often than by name, and left
+ * unresolved that string travels into the model as if it WERE a typeface: no
+ * substitution table knows it, so a deck whose theme is Times came out in a
+ * grotesque (45541_Header).
+ *
+ * @param typeface The `@typeface` as the file writes it.
+ * @param fonts    The theme's font scheme, when the part was read.
+ * @returns The resolved name; the input unchanged when it is not a token, and
+ *          `undefined` when it is a token the theme leaves empty.
+ */
+export declare function resolveThemeFont(typeface: string | undefined, fonts: ThemeFonts | undefined): string | undefined;
 /**
  * Parse a DrawingML theme part (ECMA-376 §20.1.6.2, `a:clrScheme`) into a
  * `name → hex` colour map. Reads the twelve scheme slots — `dk1`/`lt1`/`dk2`/

package/dist/esm/core/drawingml/theme-parser.js

@@ -26,6 +26,69 @@ var SCHEME_SLOTS = new Set([
 	"folHlink"
 ]);
 /**
+* Parse a theme's font scheme (§20.1.4.1.16).
+*
+* @param themeXml The raw theme part bytes, UTF-8.
+* @returns The two fonts; slots the theme leaves empty are absent.
+*/
+function parseThemeFonts(themeXml) {
+	const scheme = poFindByPath(parser.parse(decoder.decode(themeXml)), [
+		"a:theme",
+		"a:themeElements",
+		"a:fontScheme"
+	]);
+	const read = (tag) => {
+		const font = scheme ? poChildren(scheme).find((c) => poIs(c, tag)) : void 0;
+		const slot = (name) => {
+			const node = font ? poChildren(font).find((c) => poIs(c, name)) : void 0;
+			const face = node ? poAttr(node, "typeface")?.trim() : void 0;
+			return face === void 0 || face === "" ? void 0 : face;
+		};
+		const [latin, ea, cs] = [
+			slot("a:latin"),
+			slot("a:ea"),
+			slot("a:cs")
+		];
+		return {
+			...latin !== void 0 ? { latin } : {},
+			...ea !== void 0 ? { ea } : {},
+			...cs !== void 0 ? { cs } : {}
+		};
+	};
+	return {
+		major: read("a:majorFont"),
+		minor: read("a:minorFont")
+	};
+}
+var THEME_FONT_TOKENS = new Map([
+	["+mj-lt", ["major", "latin"]],
+	["+mn-lt", ["minor", "latin"]],
+	["+mj-ea", ["major", "ea"]],
+	["+mn-ea", ["minor", "ea"]],
+	["+mj-cs", ["major", "cs"]],
+	["+mn-cs", ["minor", "cs"]]
+]);
+/**
+* Resolve a typeface written as a theme TOKEN to the name it stands for.
+*
+* A slide states its fonts as `+mn-lt` far more often than by name, and left
+* unresolved that string travels into the model as if it WERE a typeface: no
+* substitution table knows it, so a deck whose theme is Times came out in a
+* grotesque (45541_Header).
+*
+* @param typeface The `@typeface` as the file writes it.
+* @param fonts    The theme's font scheme, when the part was read.
+* @returns The resolved name; the input unchanged when it is not a token, and
+*          `undefined` when it is a token the theme leaves empty.
+*/
+function resolveThemeFont(typeface, fonts) {
+	if (typeface === void 0 || !typeface.startsWith("+")) return typeface;
+	const slot = THEME_FONT_TOKENS.get(typeface.toLowerCase());
+	if (!slot || !fonts) return void 0;
+	const [which, script] = slot;
+	return fonts[which][script];
+}
+/**
 * Parse a DrawingML theme part (ECMA-376 §20.1.6.2, `a:clrScheme`) into a
 * `name → hex` colour map. Reads the twelve scheme slots — `dk1`/`lt1`/`dk2`/
 * `lt2`, `accent1`–`accent6`, `hlink`/`folHlink` — taking each slot's
@@ -105,7 +168,13 @@ function parseThemeFillStyles(themeXml) {
 		"a:fmtScheme",
 		"a:fillStyleLst"
 	]);
-	return list ? [...poChildren(list)] : [];
+	return list ? fillsOf(list) : [];
+}
+function fillsOf(list) {
+	return poChildren(list).filter((c) => {
+		const tag = poTag(c);
+		return tag !== void 0 && tag !== "#text";
+	});
 }
 /**
 * Parse a theme's BACKGROUND fill styles (§20.1.4.1.7 `a:bgFillStyleLst`), as
@@ -123,7 +192,7 @@ function parseThemeBgFillStyles(themeXml) {
 		"a:fmtScheme",
 		"a:bgFillStyleLst"
 	]);
-	return list ? [...poChildren(list)] : [];
+	return list ? fillsOf(list) : [];
 }
 /**
 * Parse a theme's effect styles (§20.1.4.1.15 `a:effectStyleLst`), as the raw
@@ -141,7 +210,7 @@ function parseThemeEffectStyles(themeXml) {
 		"a:fmtScheme",
 		"a:effectStyleLst"
 	]);
-	return list ? [...poChildren(list)] : [];
+	return list ? fillsOf(list) : [];
 }
 var EMU_PER_POINT = 12700;
 function colorOf(slot) {
@@ -154,4 +223,4 @@ function colorOf(slot) {
 	}
 }
 //#endregion
-export { parseTheme, parseThemeBgFillStyles, parseThemeEffectStyles, parseThemeFillStyles, parseThemeLineWidths };
+export { parseTheme, parseThemeBgFillStyles, parseThemeEffectStyles, parseThemeFillStyles, parseThemeFonts, parseThemeLineWidths, resolveThemeFont };

package/dist/esm/core/font/measure.d.ts

@@ -10,6 +10,18 @@ export interface FontMeasure {
     readonly pdfWidthForGid: (gid: number) => number;
     /** Shaped width of `text` at `fontSize`, in points. */
     readonly textWidthPt: (text: string, fontSize: number) => number;
+    /**
+     * How far this text's INK actually reaches from its baseline, in points:
+     * `above` up to its highest glyph edge, `below` down to its lowest. Not the
+     * font's line box — "HHH" reaches a cap height and no further, and only a
+     * string carrying a descender reaches under the baseline at all. WordArt
+     * stretches the ink it draws to fill its shape (§20.1.9.10), so it is the
+     * ink and not the line box that has to be measured.
+     */
+    readonly textInkPt: (text: string, fontSize: number) => {
+        above: number;
+        below: number;
+    };
     /** Encode `text` as a hex string of 4-digit glyph ids (Identity-H addressing). */
     readonly encodeTextAsCidHex: (text: string) => string;
     /**

package/dist/esm/core/font/measure.js

@@ -52,9 +52,45 @@ function createFontMeasure(parsed, kern = true) {
 		if (hex !== "") parts.push(`<${hex}>`);
 		return `[${parts.join(" ")}] TJ`;
 	};
+	const glyf = parsed.tables.get("glyf");
+	const glyphInk = (gid) => {
+		if (!glyf || gid < 0 || gid >= parsed.numGlyphs) return void 0;
+		const start = parsed.glyphOffsets[gid] ?? 0;
+		if ((parsed.glyphOffsets[gid + 1] ?? 0) - start < 10) return void 0;
+		const at = glyf.offset + start;
+		const i16 = (o) => {
+			const v = (parsed.raw[at + o] ?? 0) << 8 | (parsed.raw[at + o + 1] ?? 0);
+			return v >= 32768 ? v - 65536 : v;
+		};
+		return {
+			yMin: i16(4),
+			yMax: i16(8)
+		};
+	};
+	const textInkPt = (text, fontSize) => {
+		const shaped = shapeText(text, parsed.glyphForCodepoint, parsed.advanceWidths, parsed.ligatures, kerning, parsed.joiningForms);
+		let yMax = -Infinity;
+		let yMin = Infinity;
+		for (const gid of shaped.gids) {
+			const ink = glyphInk(gid);
+			if (!ink) continue;
+			if (ink.yMax > yMax) yMax = ink.yMax;
+			if (ink.yMin < yMin) yMin = ink.yMin;
+		}
+		if (!Number.isFinite(yMax) || !Number.isFinite(yMin)) {
+			yMax = parsed.capHeight || parsed.ascender;
+			yMin = 0;
+		}
+		const k = fontSize / parsed.unitsPerEm;
+		return {
+			above: yMax * k,
+			below: -yMin * k
+		};
+	};
 	return {
 		pdfWidthForGid,
 		textWidthPt,
+		textInkPt,
 		encodeTextAsCidHex,
 		showText
 	};

package/dist/esm/core/fonts/families.d.ts

@@ -0,0 +1,10 @@
+import { FamilyKey } from './remote-fonts.js';
+import { FlowDoc } from '../ir/flow.js';
+/**
+ * The curated substitute families a document's text needs, always including the
+ * sans default as the fallback for unstyled runs, math and chart labels.
+ *
+ * @param flow The parsed document.
+ * @returns One {@link FamilyKey} per distinct family the document names.
+ */
+export declare function familiesInFlow(flow: FlowDoc): Set<FamilyKey>;

package/dist/esm/core/fonts/families.js

@@ -0,0 +1,44 @@
+import { resolveFamilyKey } from "./remote-fonts.js";
+//#region src/core/fonts/families.ts
+/**
+* The curated substitute families a document's text needs, always including the
+* sans default as the fallback for unstyled runs, math and chart labels.
+*
+* @param flow The parsed document.
+* @returns One {@link FamilyKey} per distinct family the document names.
+*/
+function familiesInFlow(flow) {
+	const names = /* @__PURE__ */ new Set();
+	const add = (name) => {
+		if (name !== void 0 && name.trim() !== "") names.add(name.trim().toLowerCase());
+	};
+	add(flow.styles.defaultRunProperties.fontFamily?.ascii);
+	for (const style of flow.styles.styles.values()) {
+		add(style.runProperties.fontFamily?.ascii);
+		add(style.paragraphProperties.runProperties?.fontFamily?.ascii);
+		add(style.tableLayer?.runProperties?.fontFamily?.ascii);
+		for (const c of style.tableConditions ?? []) add(c.layer.runProperties?.fontFamily?.ascii);
+	}
+	for (const abstract of flow.numbering?.abstractNums.values() ?? []) for (const level of abstract.levels.values()) add(level.runProperties.fontFamily?.ascii);
+	const shapeText = (shape) => {
+		if (shape.text) visit(shape.text.content);
+		for (const child of shape.children ?? []) shapeText(child.shape);
+	};
+	const visit = (elements) => {
+		for (const el of elements) if (el.kind === "paragraph") {
+			add(el.paragraph.properties.runProperties?.fontFamily?.ascii);
+			for (const run of el.paragraph.runs) add(run.properties.fontFamily?.ascii);
+		} else if (el.kind === "table") for (const row of el.table.rows) for (const cell of row.cells) visit(cell.content);
+		else if (el.kind === "shape") shapeText(el.shape);
+	};
+	visit(flow.body);
+	for (const band of flow.headersFooters?.values() ?? []) visit(band);
+	for (const note of flow.footnotes?.values() ?? []) visit(note);
+	for (const note of flow.endnotes?.values() ?? []) visit(note);
+	for (const comment of flow.comments?.values() ?? []) visit(comment.content);
+	const keys = new Set(["arimo"]);
+	for (const name of names) keys.add(resolveFamilyKey(name));
+	return keys;
+}
+//#endregion
+export { familiesInFlow };

package/dist/esm/core/fonts/index.d.ts

@@ -1,2 +1,3 @@
-export { fetchFontSet, resolveFamilyKey, clearFontCache } from './remote-fonts.js';
-export type { FamilyKey, FetchFontSetOptions, FetchLike } from './remote-fonts.js';
+export { fetchFontSet, fetchScriptFont, isScriptKey, resolveFamilyKey, resolveFamilyStyle, clearFontCache, } from './remote-fonts.js';
+export { scriptForCodepoint, scriptsInFlow } from './scripts.js';
+export type { FamilyKey, FamilyStyle, FetchFontSetOptions, FetchLike, ScriptKey, SubstituteKey, } from './remote-fonts.js';

package/dist/esm/core/fonts/remote-fonts.d.ts

@@ -1,11 +1,61 @@
 import { FontBytesByVariant } from '../font/index.js';
 /** A curated open substitute family (the Croscore + Carlito/Caladea set, like LibreOffice). */
 export type FamilyKey = 'arimo' | 'tinos' | 'cousine' | 'carlito' | 'caladea';
+/**
+ * A WRITING SYSTEM the curated five cannot draw at all. They are Latin families
+ * — Greek, Cyrillic and Hebrew ride along, everything else is a notdef box —
+ * and 2145 characters of the corpus fall outside them: Han, Kana, Hangul,
+ * Arabic, the geometric symbols a form's checkbox is made of.
+ *
+ * These are fetched only when a document actually holds such a character, and
+ * only in the regular weight: Noto Sans SC is ten megabytes, and a bold run in
+ * it is better stroked (see `SyntheticFace`) than downloaded four times over.
+ */
+export type ScriptKey = 'jp' | 'kr' | 'sc' | 'arabic' | 'hebrew' | 'thai' | 'symbols';
+/** Either kind of substitute — a Latin family or a per-script face. */
+export type SubstituteKey = FamilyKey | ScriptKey;
+/** Whether a substitute key names a writing system rather than a Latin family. */
+export declare function isScriptKey(key: SubstituteKey): key is ScriptKey;
+/**
+ * Fetch the ONE face a writing system is drawn with.
+ *
+ * @param script The writing system.
+ * @param fetchImpl Injectable `fetch` (defaults to the global one).
+ * @returns The regular face, or `undefined` when the download fails.
+ */
+export declare function fetchScriptFont(script: ScriptKey, fetchImpl?: FetchLike): Promise<FontBytesByVariant | undefined>;
+/** A family name, read: which substitute it maps to and what it says about the face. */
+export interface FamilyStyle {
+    readonly key: FamilyKey;
+    /** The NAME asks for a heavy face (`Arial Black`, `DIN-Bold`). */
+    readonly bold?: boolean;
+    /** …or a slanted one (`Frutiger Oblique`). */
+    readonly italic?: boolean;
+    /**
+     * …or a narrow one (`Arial Narrow`), as the fraction of the normal advance it
+     * sets at. No curated family ships a condensed cut, so the substitute is
+     * squeezed instead — Arial Narrow's own widths are 82 % of Arial's, which is
+     * also what LibreOffice's Liberation Sans Narrow reproduces.
+     */
+    readonly widthScale?: number;
+}
 /**
  * Map a document-referenced font family to a curated open substitute: an exact
  * metric twin when one is known (e.g. Calibri → Carlito), otherwise a
  * serif/mono/sans style fallback.
  *
+ * The name may also carry the FACE — `Times New Roman Bold` is the Times
+ * family, and read whole it matches no twin at all and fell through to the
+ * generic sans, which is how a Times heading came out in a grotesque.
+ *
+ * @param name The referenced family name (case-insensitive); empty ⇒ Arimo.
+ * @returns The chosen family and what the name said about the face.
+ */
+export declare function resolveFamilyStyle(name: string | undefined): FamilyStyle;
+/**
+ * The curated substitute for a family name — {@link resolveFamilyStyle} without
+ * the face it also carries.
+ *
  * @param name The referenced family name (case-insensitive); empty ⇒ Arimo.
  * @returns The chosen {@link FamilyKey}.
  */