@stll/folio-core 0.48.0 → 0.50.0

package/dist/display-list/build/unsupported.d.ts

@@ -7,8 +7,6 @@ import { DisplayUnsupported } from "../types.js";
 declare const UNSUPPORTED_CONSTRUCT: {
   /** `w:effect` animations (blinkBackground, shimmer, …). */
   readonly textEffect: "textEffect";
-  /** `w:smallCaps`: advances are correct, the small-cap glyph choice is not expressible. */
-  readonly smallCaps: "smallCaps";
   /** `w:w` horizontal scale: folded into advances, but the glyphs are not narrowed. */
   readonly horizontalScale: "horizontalScale";
   /** `w:em` emphasis marks. */
@@ -39,6 +37,8 @@ declare const UNSUPPORTED_CONSTRUCT: {
   readonly headerFooterContent: "headerFooterContent";
   /** `a:bodyPr` middle/bottom anchoring inside a text box. */
   readonly textBoxVerticalAlign: "textBoxVerticalAlign";
+  /** A text box's `a:gradFill`: the primitives carry no gradient. */
+  readonly textBoxGradientFill: "textBoxGradientFill";
   /** A fragment kind with no builder. */
   readonly fragmentKind: "fragmentKind";
   /** A fragment whose block or measure is missing from the block lookup. */

package/dist/display-list/dom/renderDisplayListToDom.d.ts

@@ -1,10 +1,19 @@
 import { DisplayColor, DisplayFontFace, DisplayImageSource, DisplayList, DisplayPage } from "../types.js";
 //#region src/display-list/dom/renderDisplayListToDom.d.ts
+/**
+ * How the backend addresses image and embedded-font bytes: `objectUrl` mints
+ * a `blob:` URL where the runtime can (a live page, which revokes them), and
+ * `dataUrl` always inlines the bytes (markup that leaves the process, such as
+ * a serialized page, where a `blob:` URL would resolve to nothing).
+ */
+type DisplayBinaryUrls = "objectUrl" | "dataUrl";
 type RenderDisplayListOptions = {
   /** Document to create elements in. */
   readonly doc: Document;
   /** Page background, painted before any primitive. */
   readonly pageBackground?: DisplayColor;
+  /** Defaults to `objectUrl`. */
+  readonly binaryUrls?: DisplayBinaryUrls;
 };
 /**
  * A page's glyph runs and images index tables that live on the list, and an
@@ -23,4 +32,4 @@ declare const renderDisplayPageToDom: (page: DisplayPage, options: RenderDisplay
 /** One `div.layout-page` per display page, in page order. */
 declare const renderDisplayListToDom: (list: DisplayList, options: RenderDisplayListOptions) => HTMLElement[];
 //#endregion
-export { RenderDisplayListOptions, RenderDisplayPageOptions, renderDisplayListToDom, renderDisplayPageToDom };
+export { DisplayBinaryUrls, RenderDisplayListOptions, RenderDisplayPageOptions, renderDisplayListToDom, renderDisplayPageToDom };

package/dist/display-list/dom/renderDisplayListToDom.js

@@ -103,8 +103,8 @@ const resolveImage = (ref, images) => {
 };
 /** A `Blob` part cannot be backed by shared memory, so prove it is not. */
 const isBlobPart = (bytes) => bytes.buffer instanceof ArrayBuffer;
-const binarySrc = (bytes, mimeType) => {
-	if (isBlobPart(bytes) && typeof Blob === "function" && typeof URL !== "undefined" && typeof URL.createObjectURL === "function") return URL.createObjectURL(new Blob([bytes], { type: mimeType }));
+const binarySrc = (bytes, mimeType, urls) => {
+	if (urls === "objectUrl" && isBlobPart(bytes) && typeof Blob === "function" && typeof URL !== "undefined" && typeof URL.createObjectURL === "function") return URL.createObjectURL(new Blob([bytes], { type: mimeType }));
 	return bytesToDataUrl(bytes, mimeType);
 };
 const fontFaceRule = (face, embedded, src) => `@font-face { font-family: ${quoteFontFamily(embedded.id)}; src: url("${src}"); font-weight: ${face.weight}; font-style: ${face.italic ? "italic" : "normal"}; }`;
@@ -113,14 +113,14 @@ const fontFaceRule = (face, embedded, src) => `@font-face { font-family: ${quote
 * once per render and shared by every page: an id maps to one blob, so the
 * bytes are held once and one revoke releases them.
 */
-const embeddedFontFaceCss = (fonts) => {
+const embeddedFontFaceCss = (fonts, urls) => {
 	const srcById = /* @__PURE__ */ new Map();
 	const rules = [];
 	for (const face of fonts) {
 		const embedded = face.embedded;
 		if (embedded === void 0) continue;
 		const cached = srcById.get(embedded.id);
-		const src = cached ?? binarySrc(embedded.bytes, FONT_MIME_TYPE);
+		const src = cached ?? binarySrc(embedded.bytes, FONT_MIME_TYPE, urls);
 		if (cached === void 0) srcById.set(embedded.id, src);
 		rules.push(fontFaceRule(face, embedded, src));
 	}
@@ -297,7 +297,6 @@ const paintGlyphRun = (run, context) => {
 	if (run.unicodeBidi !== void 0) span.style.unicodeBidi = run.unicodeBidi;
 	if (run.stroke !== void 0) span.style.webkitTextStroke = `${px(run.stroke.thicknessPx)} ${cssColor(run.stroke.color)}`;
 	span.style.fontKerning = run.kerning ? "normal" : "none";
-	if (run.smallCaps) span.style.fontVariant = "small-caps";
 	applyAdjustments(span, run.adjustments);
 	span.dataset["advanceSum"] = String(advanceSum);
 	applyModelRange(span, run.pmRange);
@@ -400,7 +399,7 @@ const paintImage = ({ image, rect, crop, opacity, brightness, contrast }, contex
 		element.style.height = px(fullHeight);
 	}
 	element.alt = "";
-	element.src = binarySrc(source.bytes, IMAGE_MIME_TYPES[source.format]);
+	element.src = binarySrc(source.bytes, IMAGE_MIME_TYPES[source.format], context.binaryUrls);
 	clip.append(element);
 	context.parent.append(clip);
 };
@@ -498,6 +497,7 @@ const renderPage = (page, options) => {
 	}
 	const context = {
 		doc: options.doc,
+		binaryUrls: options.binaryUrls ?? "objectUrl",
 		fonts: options.fonts,
 		images: options.images,
 		parent: element,
@@ -596,11 +596,11 @@ const paintRegionTree = ({ primitives, regions }, context) => {
 };
 const renderDisplayPageToDom = (page, options) => renderPage(page, {
 	...options,
-	fontFaceCss: embeddedFontFaceCss(options.fonts)
+	fontFaceCss: embeddedFontFaceCss(options.fonts, options.binaryUrls ?? "objectUrl")
 });
 /** One `div.layout-page` per display page, in page order. */
 const renderDisplayListToDom = (list, options) => {
-	const fontFaceCss = embeddedFontFaceCss(list.fonts);
+	const fontFaceCss = embeddedFontFaceCss(list.fonts, options.binaryUrls ?? "objectUrl");
 	return list.pages.map((page, pageIndex) => renderPage(page, {
 		...options,
 		fonts: list.fonts,

package/dist/display-list/html/renderDisplayListToHtml.d.ts

@@ -0,0 +1,21 @@
+import { DisplayColor, DisplayList } from "../types.js";
+//#region src/display-list/html/renderDisplayListToHtml.d.ts
+declare const escapeHtmlText: (value: string) => string;
+type RenderDisplayListToHtmlOptions = {
+  /** `@font-face` rules for the families the list names, placed in the head. */
+  readonly fontFaceCss?: string;
+  /** The document title. */
+  readonly title?: string;
+  /** Space between pages. Defaults to 0: pages stack flush. */
+  readonly pageGapPx?: number;
+  /** CSS color behind the pages. Defaults to white. */
+  readonly canvasColor?: string;
+  /** Page background, painted before any primitive. */
+  readonly pageBackground?: DisplayColor;
+};
+/** The pages' markup, one slot per display page, in page order. */
+declare const renderDisplayListPagesToHtml: (list: DisplayList, options?: Pick<RenderDisplayListToHtmlOptions, "pageBackground">) => string[];
+/** A complete HTML document showing every page of the list. */
+declare const renderDisplayListToHtml: (list: DisplayList, options?: RenderDisplayListToHtmlOptions) => string;
+//#endregion
+export { RenderDisplayListToHtmlOptions, escapeHtmlText, renderDisplayListPagesToHtml, renderDisplayListToHtml };

package/dist/display-list/html/renderDisplayListToHtml.js

@@ -0,0 +1,126 @@
+import { renderDisplayListToDom } from "../dom/renderDisplayListToDom.js";
+//#region src/display-list/html/renderDisplayListToHtml.ts
+/**
+* A display list as one HTML document, with no browser and no DOM.
+*
+* The DOM backend paints into whatever `Document` it is handed. This module
+* hands it a document with only what the backend reaches for and serializes
+* the result, so a server, a CLI or a harness can produce the page a browser
+* would show from the same painter the editor uses. Binary data (images,
+* embedded faces) is inlined as `data:` URLs, because a `blob:` URL minted in
+* this process resolves to nothing once the markup leaves it.
+*/
+const VOID_TAGS = /* @__PURE__ */ new Set([
+	"img",
+	"br",
+	"hr"
+]);
+const createStubElement = (tagName) => {
+	const children = [];
+	const attributes = {};
+	return {
+		tagName,
+		style: {},
+		dataset: {},
+		attributes,
+		children,
+		className: "",
+		id: "",
+		textContent: "",
+		alt: "",
+		src: "",
+		href: "",
+		title: "",
+		append: (...nodes) => {
+			children.push(...nodes);
+		},
+		appendChild: (node) => {
+			children.push(node);
+			return node;
+		},
+		setAttribute: (name, value) => {
+			attributes[name] = value;
+		}
+	};
+};
+/**
+* A `Document` with only what the DOM backend reaches for. A backend that
+* grows a new requirement throws on the missing property here rather than
+* silently serializing less than it painted.
+*/
+const stubDocument = () => {
+	return { createElement: createStubElement };
+};
+const asStub = (element) => element;
+/** A vendor property is camelCase with no leading capital, so its leading dash is explicit. */
+const VENDOR_PREFIXES = [
+	"webkit-",
+	"moz-",
+	"ms-",
+	"o-"
+];
+const toKebabCase = (name) => {
+	const hyphenated = name.replaceAll(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`);
+	return VENDOR_PREFIXES.some((prefix) => hyphenated.startsWith(prefix)) ? `-${hyphenated}` : hyphenated;
+};
+const escapeHtmlText = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+const escapeAttribute = (value) => escapeHtmlText(value).replaceAll("\"", "&quot;");
+const serializeStyle = (style) => Object.entries(style).map(([property, value]) => `${toKebabCase(property)}: ${value}`).join("; ");
+/**
+* Serialized without one character of added whitespace: the backend sets
+* `white-space: pre` on every run, so an indentation newline would be painted.
+*/
+const RAW_TEXT_TAGS = /* @__PURE__ */ new Set(["style", "script"]);
+/** Text placed inside a `<style>` or `<script>`: a `</` cannot close the element early. */
+const rawElementText = (text) => text.replaceAll("</", "<\\/");
+const serializeElement = (element) => {
+	const attributes = [];
+	if (element.className !== "") attributes.push(`class="${escapeAttribute(element.className)}"`);
+	if (element.id !== "") attributes.push(`id="${escapeAttribute(element.id)}"`);
+	if (element.href !== "") attributes.push(`href="${escapeAttribute(element.href)}"`);
+	if (element.src !== "") attributes.push(`src="${escapeAttribute(element.src)}"`);
+	if (element.title !== "") attributes.push(`title="${escapeAttribute(element.title)}"`);
+	if (element.tagName === "img") attributes.push(`alt="${escapeAttribute(element.alt)}"`);
+	for (const [name, value] of Object.entries(element.attributes)) attributes.push(`${name}="${escapeAttribute(value)}"`);
+	for (const [key, value] of Object.entries(element.dataset)) attributes.push(`data-${toKebabCase(key)}="${escapeAttribute(value)}"`);
+	const style = serializeStyle(element.style);
+	if (style !== "") attributes.push(`style="${escapeAttribute(style)}"`);
+	const open = [element.tagName, ...attributes].join(" ");
+	if (VOID_TAGS.has(element.tagName)) return `<${open} />`;
+	if (element.children.length > 0) return `<${open}>${element.children.map(serializeElement).join("")}</${element.tagName}>`;
+	return `<${open}>${RAW_TEXT_TAGS.has(element.tagName) ? rawElementText(element.textContent) : escapeHtmlText(element.textContent)}</${element.tagName}>`;
+};
+/**
+* Each page sits in a slot of whole pixels. A page height is fractional (A4 is
+* 1122.52 px), so pages stacked in normal flow would start at fractional
+* offsets; the slot rounds the offset while the page keeps its exact size.
+*/
+const pageSlot = (markup, page) => `<div class="layout-page-slot" style="position: relative; overflow: hidden; width: ${String(Math.ceil(page.widthPx))}px; height: ${String(Math.ceil(page.heightPx))}px">${markup}</div>`;
+/** The pages' markup, one slot per display page, in page order. */
+const renderDisplayListPagesToHtml = (list, options = {}) => renderDisplayListToDom(list, {
+	doc: stubDocument(),
+	binaryUrls: "dataUrl",
+	...options.pageBackground !== void 0 && { pageBackground: options.pageBackground }
+}).map((element, index) => {
+	const markup = serializeElement(asStub(element));
+	const page = list.pages.at(index);
+	return page === void 0 ? markup : pageSlot(markup, page);
+});
+/** A complete HTML document showing every page of the list. */
+const renderDisplayListToHtml = (list, options = {}) => {
+	const gap = options.pageGapPx ?? 0;
+	const canvas = rawElementText(options.canvasColor ?? "#fff");
+	const layout = gap > 0 ? `body { display: flex; flex-direction: column; align-items: center; gap: ${String(gap)}px; padding: ${String(gap)}px 0; }` : "";
+	return [
+		"<!doctype html>",
+		`<html><head><meta charset="utf-8"><title>${escapeHtmlText(options.title ?? "")}</title><style>`,
+		rawElementText(options.fontFaceCss ?? ""),
+		`html, body { margin: 0; padding: 0; background: ${canvas}; }`,
+		layout,
+		"</style></head><body>",
+		renderDisplayListPagesToHtml(list, options).join(""),
+		"</body></html>"
+	].join("\n");
+};
+//#endregion
+export { escapeHtmlText, renderDisplayListPagesToHtml, renderDisplayListToHtml };

package/dist/display-list/selectDisplayPages.d.ts

@@ -0,0 +1,6 @@
+import { DisplayList } from "./types.js";
+//#region src/display-list/selectDisplayPages.d.ts
+/** Keep `pageIndices` (0-based, in the order given; duplicates are dropped). */
+declare const selectDisplayPages: (list: DisplayList, pageIndices: readonly number[]) => DisplayList;
+//#endregion
+export { selectDisplayPages };

package/dist/display-list/selectDisplayPages.js

@@ -0,0 +1,44 @@
+//#region src/display-list/selectDisplayPages.ts
+/** Keep `pageIndices` (0-based, in the order given; duplicates are dropped). */
+const selectDisplayPages = (list, pageIndices) => {
+	const kept = [...new Set(pageIndices)].filter((index) => Number.isInteger(index) && index >= 0 && index < list.pages.length);
+	const remap = new Map(kept.map((original, next) => [original, next]));
+	const relink = (link) => {
+		if (link.target.kind !== "page") return [link];
+		const pageIndex = remap.get(link.target.pageIndex);
+		return pageIndex === void 0 ? [] : [{
+			...link,
+			target: {
+				...link.target,
+				pageIndex
+			}
+		}];
+	};
+	const pages = kept.flatMap((index) => {
+		const page = list.pages[index];
+		return page === void 0 ? [] : [{
+			...page,
+			links: page.links.flatMap(relink)
+		}];
+	});
+	return {
+		...list,
+		pages,
+		outline: list.outline.flatMap((entry) => {
+			const pageIndex = remap.get(entry.pageIndex);
+			return pageIndex === void 0 ? [] : [{
+				...entry,
+				pageIndex
+			}];
+		}),
+		unsupported: list.unsupported.flatMap((entry) => {
+			const pageIndex = remap.get(entry.pageIndex);
+			return pageIndex === void 0 ? [] : [{
+				...entry,
+				pageIndex
+			}];
+		})
+	};
+};
+//#endregion
+export { selectDisplayPages };

package/dist/docx/blockContentParser.js

@@ -1,5 +1,5 @@
 import { parseBookmarkEnd, parseBookmarkStart } from "./bookmarkParser.js";
-import { convertBulletToUnicode } from "./bulletMarkers.js";
+import { bulletMarkerFontName, convertBulletToUnicode } from "./bulletMarkers.js";
 import { CAPTURE, dispatchChildrenWithContext, ownedElsewhere, withPreservedChildren } from "./containerChildren.js";
 import { isNumberingReference } from "./numberingReference.js";
 import { formatOoxmlCounter } from "./ooxmlCounterFormatter.js";
@@ -62,7 +62,7 @@ const computeListMarker = (paragraph, { numbering, listCounters, abstractCounter
 	previousList.numId = numId;
 	const pattern = listRendering.marker;
 	if (listRendering.isBullet) {
-		listRendering.marker = convertBulletToUnicode(pattern || "");
+		listRendering.marker = convertBulletToUnicode(pattern || "", bulletMarkerFontName(listRendering.markerFormatting));
 		previousList.abstractNumId = null;
 		previousList.fromStyle = false;
 		previousList.numId = null;

package/dist/docx/bulletMarkers.d.ts

@@ -1,4 +1,20 @@
 //#region src/docx/bulletMarkers.d.ts
-declare const convertBulletToUnicode: (bulletChar: string) => string;
+type MarkerFontFamily = {
+  ascii?: string | undefined;
+  hAnsi?: string | undefined;
+};
+/** The face a bullet level's `w:rFonts` names for its (Latin-range) marker character. */
+declare const bulletMarkerFontName: (formatting: {
+  fontFamily?: MarkerFontFamily | undefined;
+} | null | undefined) => string | undefined;
+/**
+ * Map a bullet level's `w:lvlText` to the character painted for it.
+ *
+ * `fontName` is the level's own `w:rFonts` face. When it is an ordinary text
+ * font, a Latin-range character is the letter itself (the common `o` bullet
+ * in a monospace face); without a named face the character is read as a
+ * symbol-font code.
+ */
+declare const convertBulletToUnicode: (bulletChar: string, fontName?: string) => string;
 //#endregion
-export { convertBulletToUnicode };
+export { bulletMarkerFontName, convertBulletToUnicode };

package/dist/docx/bulletMarkers.js

@@ -28,10 +28,35 @@ const SYMBOL_BULLET_MAP = {
 	62: ">",
 	45: "-"
 };
-const convertBulletToUnicode = (bulletChar) => {
+/**
+* Fonts whose single-byte codes name pictographs rather than Latin letters.
+* A `w:lvlText` character below U+0100 only means a symbol glyph when the
+* numbering level's `w:rFonts` selects one of these faces.
+*/
+const SYMBOL_ENCODED_FONTS = /* @__PURE__ */ new Set([
+	"symbol",
+	"wingdings",
+	"wingdings 2",
+	"wingdings 3",
+	"webdings"
+]);
+/** The face a bullet level's `w:rFonts` names for its (Latin-range) marker character. */
+const bulletMarkerFontName = (formatting) => formatting?.fontFamily?.ascii ?? formatting?.fontFamily?.hAnsi;
+/** A printable Latin-1 character in a named, non-symbol face paints as itself. */
+const isTextFontCharacter = (charCode, fontName) => fontName !== void 0 && (charCode >= 32 && charCode < 127 || charCode >= 160 && charCode < 256) && !SYMBOL_ENCODED_FONTS.has(fontName.trim().toLowerCase());
+/**
+* Map a bullet level's `w:lvlText` to the character painted for it.
+*
+* `fontName` is the level's own `w:rFonts` face. When it is an ordinary text
+* font, a Latin-range character is the letter itself (the common `o` bullet
+* in a monospace face); without a named face the character is read as a
+* symbol-font code.
+*/
+const convertBulletToUnicode = (bulletChar, fontName) => {
 	if (!bulletChar || bulletChar.trim() === "") return "•";
 	const charCode = bulletChar.codePointAt(0);
 	if (charCode === void 0) return "•";
+	if (isTextFontCharacter(charCode, fontName)) return bulletChar;
 	const mapped = SYMBOL_BULLET_MAP[charCode];
 	if (mapped !== void 0) return mapped;
 	if (charCode >= 57344 && charCode <= 63743) return "•";
@@ -39,4 +64,4 @@ const convertBulletToUnicode = (bulletChar) => {
 	return bulletChar;
 };
 //#endregion
-export { convertBulletToUnicode };
+export { bulletMarkerFontName, convertBulletToUnicode };

package/dist/docx/drawingGroupChildren.d.ts

@@ -0,0 +1,60 @@
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/drawingGroupChildren.d.ts
+type GroupTextBoxFrame = {
+  /** Element indices from the `wpg:wgp` down to the `wps:wsp`. */
+  path: number[];
+  wsp: XmlElement;
+  /** EMUs from the group's top-left corner. */
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** Degrees clockwise. */
+  rotation: number;
+  flipH: boolean;
+  flipV: boolean;
+};
+type Transform2D = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  childX: number;
+  childY: number;
+  childWidth: number;
+  childHeight: number;
+  rotation: number;
+  flipH: boolean;
+  flipV: boolean;
+};
+/** A `CT_GroupTransform2D` or `CT_Transform2D`; absent children read as zero. */
+declare const readTransform: (xfrm: XmlElement | null) => Transform2D;
+/**
+ * Every `wps:wsp` with a text box in the group, nested groups included, with
+ * its frame in EMUs from the group's top-left corner.
+ *
+ * A nested group that is rotated or flipped turns its children's frames into
+ * something other than a rectangle in the drawing's axes, so its text boxes
+ * are left out and stay with the preview.
+ */
+declare const collectGroupTextBoxes: (group: XmlElement, width: number, height: number) => GroupTextBoxFrame[];
+/** Identity of a group drawing's authored XML. */
+declare const groupXmlFingerprint: (rawXml: string) => string;
+/** Identity of a text box's content, compared on save to tell an edit. */
+declare const groupTextContentFingerprint: (content: unknown) => string;
+type GroupTextBoxEdit = {
+  path: readonly number[];
+  /** Serialized `w:txbxContent` children. */
+  contentXml: string;
+};
+/**
+ * The captured group XML with each edited text box's content replaced, or
+ * undefined when an edit names no text box in it.
+ *
+ * The replacement is written as a placeholder element and substituted after
+ * the tree is serialized, so the new content is never reparsed and the rest
+ * of the capture is written exactly as it was read.
+ */
+declare const replaceGroupTextBoxContent: (rawXml: string, edits: readonly GroupTextBoxEdit[]) => string | undefined;
+//#endregion
+export { GroupTextBoxEdit, GroupTextBoxFrame, collectGroupTextBoxes, groupTextContentFingerprint, groupXmlFingerprint, readTransform, replaceGroupTextBoxContent };

package/dist/docx/drawingGroupChildren.js

@@ -0,0 +1,176 @@
+import { canonicalJson } from "../utils/canonicalJson.js";
+import { captureVerbatimXml } from "./verbatimCapture.js";
+import { findChildByLocalName, findDeep, getAttribute, getChildElements, getLocalName, parseNumericAttribute, parseXml } from "./xmlParser.js";
+//#region src/docx/drawingGroupChildren.ts
+/**
+* The text boxes of a DrawingML group (`wpg:wgp`), read as frames folio can lay
+* out, and written back into the group's authored XML.
+*
+* A group states a child coordinate space (`a:chOff` / `a:chExt`) that its
+* own frame (`a:off` / `a:ext`) maps onto, and every child's `a:xfrm` is in
+* that space; a nested `wpg:grpSp` repeats the mapping one level down
+* (ECMA-376 §20.1.7.5). Composing the mappings gives each `wps:wsp` a frame
+* in EMUs relative to the group's own top-left corner. Only the frame is
+* mapped: the text inside keeps its authored size and the body insets stay in
+* EMUs.
+*/
+/** `a:xfrm@rot` is in 60,000ths of a degree. */
+const ROTATION_UNITS_PER_DEGREE = 6e4;
+/** Deeper nesting than this is not a drawing anyone authored. */
+const MAX_GROUP_DEPTH = 16;
+const MAX_GROUP_TEXT_BOXES = 256;
+const numberAttribute = (element, name) => parseNumericAttribute(element, null, name) ?? 0;
+const onOffAttribute = (element, name) => {
+	const value = getAttribute(element, null, name);
+	return value === "1" || value === "true" || value === "on";
+};
+/** A `CT_GroupTransform2D` or `CT_Transform2D`; absent children read as zero. */
+const readTransform = (xfrm) => {
+	const offset = findChildByLocalName(xfrm, "off");
+	const extent = findChildByLocalName(xfrm, "ext");
+	const childOffset = findChildByLocalName(xfrm, "chOff");
+	const childExtent = findChildByLocalName(xfrm, "chExt");
+	return {
+		x: numberAttribute(offset, "x"),
+		y: numberAttribute(offset, "y"),
+		width: numberAttribute(extent, "cx"),
+		height: numberAttribute(extent, "cy"),
+		childX: numberAttribute(childOffset, "x"),
+		childY: numberAttribute(childOffset, "y"),
+		childWidth: numberAttribute(childExtent, "cx"),
+		childHeight: numberAttribute(childExtent, "cy"),
+		rotation: numberAttribute(xfrm, "rot") / ROTATION_UNITS_PER_DEGREE,
+		flipH: onOffAttribute(xfrm, "flipH"),
+		flipV: onOffAttribute(xfrm, "flipV")
+	};
+};
+const groupTransform = (group) => readTransform(findChildByLocalName(findChildByLocalName(group, "grpSpPr"), "xfrm"));
+const shapeTransform = (shape) => readTransform(findChildByLocalName(findChildByLocalName(shape, "spPr"), "xfrm"));
+/**
+* The top-level mapping: the group's child space stretched over the drawing's
+* extent. A missing or empty child extent means the child space is the
+* drawing's own.
+*/
+const rootMap = (group, width, height) => {
+	const transform = groupTransform(group);
+	const scaleX = transform.childWidth > 0 ? width / transform.childWidth : 1;
+	const scaleY = transform.childHeight > 0 ? height / transform.childHeight : 1;
+	return {
+		scaleX,
+		scaleY,
+		offsetX: -transform.childX * scaleX,
+		offsetY: -transform.childY * scaleY
+	};
+};
+/** A nested group's child space, mapped through its frame in the parent's space. */
+const nestedMap = (parent, transform) => {
+	const scaleX = transform.childWidth > 0 ? transform.width / transform.childWidth : 1;
+	const scaleY = transform.childHeight > 0 ? transform.height / transform.childHeight : 1;
+	return {
+		scaleX: parent.scaleX * scaleX,
+		scaleY: parent.scaleY * scaleY,
+		offsetX: parent.scaleX * (transform.x - transform.childX * scaleX) + parent.offsetX,
+		offsetY: parent.scaleY * (transform.y - transform.childY * scaleY) + parent.offsetY
+	};
+};
+const hasTextBox = (wsp) => findChildByLocalName(findChildByLocalName(wsp, "txbx"), "txbxContent") !== null;
+/**
+* Every `wps:wsp` with a text box in the group, nested groups included, with
+* its frame in EMUs from the group's top-left corner.
+*
+* A nested group that is rotated or flipped turns its children's frames into
+* something other than a rectangle in the drawing's axes, so its text boxes
+* are left out and stay with the preview.
+*/
+const collectGroupTextBoxes = (group, width, height) => {
+	const frames = [];
+	const visit = (container, map, path, depth) => {
+		for (const [index, child] of getChildElements(container).entries()) {
+			if (frames.length >= MAX_GROUP_TEXT_BOXES) return;
+			const localName = getLocalName(child.name ?? "");
+			if (localName === "grpSp" && depth < MAX_GROUP_DEPTH) {
+				const transform = groupTransform(child);
+				if (transform.rotation === 0 && !transform.flipH && !transform.flipV) visit(child, nestedMap(map, transform), [...path, index], depth + 1);
+				continue;
+			}
+			if (localName !== "wsp" || !hasTextBox(child)) continue;
+			const transform = shapeTransform(child);
+			const frameWidth = transform.width * map.scaleX;
+			const frameHeight = transform.height * map.scaleY;
+			if (!(frameWidth > 0 && frameHeight > 0)) continue;
+			frames.push({
+				path: [...path, index],
+				wsp: child,
+				x: transform.x * map.scaleX + map.offsetX,
+				y: transform.y * map.scaleY + map.offsetY,
+				width: frameWidth,
+				height: frameHeight,
+				rotation: transform.rotation,
+				flipH: transform.flipH,
+				flipV: transform.flipV
+			});
+		}
+	};
+	visit(group, rootMap(group, width, height), [], 0);
+	return frames;
+};
+/** Two FNV-1a passes with different offsets: a short, stable identity. */
+const fingerprint = (text) => {
+	let first = 2166136261;
+	let second = 16777619;
+	for (let index = 0; index < text.length; index += 1) {
+		const code = text.charCodeAt(index);
+		first = Math.imul(first ^ code, 16777619);
+		second = Math.imul(second ^ code, 96280213);
+	}
+	return `${(first >>> 0).toString(16).padStart(8, "0")}${(second >>> 0).toString(16).padStart(8, "0")}`;
+};
+/** Identity of a group drawing's authored XML. */
+const groupXmlFingerprint = (rawXml) => fingerprint(rawXml);
+/** Identity of a text box's content, compared on save to tell an edit. */
+const groupTextContentFingerprint = (content) => fingerprint(canonicalJson(content));
+/** The group a captured drawing carries; a Fallback branch holds none. */
+const findGroup = (root) => findDeep(root, "wpg", "wgp") ?? void 0;
+const childAtPath = (group, path) => {
+	let current = group;
+	for (const index of path) current = current ? getChildElements(current)[index] : void 0;
+	return current;
+};
+/**
+* The text box content element a path names, or undefined when the path does
+* not lead to a `wps:wsp` holding one.
+*/
+const textBoxContentAt = (group, path) => {
+	const wsp = childAtPath(group, path);
+	if (!wsp || getLocalName(wsp.name ?? "") !== "wsp") return;
+	return findChildByLocalName(findChildByLocalName(wsp, "txbx"), "txbxContent") ?? void 0;
+};
+/**
+* The captured group XML with each edited text box's content replaced, or
+* undefined when an edit names no text box in it.
+*
+* The replacement is written as a placeholder element and substituted after
+* the tree is serialized, so the new content is never reparsed and the rest
+* of the capture is written exactly as it was read.
+*/
+const replaceGroupTextBoxContent = (rawXml, edits) => {
+	const root = parseXml(rawXml);
+	const group = findGroup(root);
+	if (!group) return;
+	const replacements = /* @__PURE__ */ new Map();
+	for (const [index, edit] of edits.entries()) {
+		const content = textBoxContentAt(group, edit.path);
+		if (!content) return;
+		const placeholder = `folio-group-text-${index}-${fingerprint(rawXml)}`;
+		content.elements = [{
+			type: "element",
+			name: placeholder
+		}];
+		replacements.set(`<${placeholder}/>`, edit.contentXml || "<w:p/>");
+	}
+	let xml = (root.elements ?? []).map((element) => captureVerbatimXml(element)).join("");
+	for (const [placeholder, contentXml] of replacements) xml = xml.replace(placeholder, () => contentXml);
+	return xml;
+};
+//#endregion
+export { collectGroupTextBoxes, groupTextContentFingerprint, groupXmlFingerprint, readTransform, replaceGroupTextBoxContent };

package/dist/docx/drawingUtils.js

@@ -107,6 +107,7 @@ function parseFill(spPr) {
 function parseGradientFill(gradientFill) {
 	let type = "linear";
 	let angle;
+	let scaled;
 	const linear = findChildByLocalName(gradientFill, "lin");
 	if (linear) {
 		const authoredAngle = getAttribute(linear, null, "ang");
@@ -114,6 +115,7 @@ function parseGradientFill(gradientFill) {
 			const parsedAngle = Number.parseInt(authoredAngle, 10);
 			angle = Number.isNaN(parsedAngle) ? void 0 : parsedAngle / 6e4;
 		}
+		scaled = parseOnOffValue(getAttribute(linear, null, "scaled"), void 0, "a:lin@scaled");
 	}
 	const path = findChildByLocalName(gradientFill, "path");
 	if (path) {
@@ -139,6 +141,7 @@ function parseGradientFill(gradientFill) {
 		gradient: {
 			type,
 			...angle !== void 0 ? { angle } : {},
+			...scaled !== void 0 ? { scaled } : {},
 			stops
 		}
 	};