@cj-tech-master/excelts 9.6.1 → 10.0.0

package/dist/esm/modules/excel/xlsx/xform/drawing/shape-xform.js

@@ -0,0 +1,109 @@
+import { BaseXform } from "../base-xform.js";
+const EMU_PER_POINT = 12700;
+/**
+ * Normalize a user-supplied colour to the bare 6-digit RGB hex that OOXML's
+ * `<a:srgbClr val="...">` requires:
+ * - strips a leading `#`
+ * - accepts 8-digit ARGB (the form excelts uses for cell fills) and drops the
+ *   leading alpha byte, since `srgbClr` carries no alpha channel
+ * - upper-cases
+ *
+ * Anything that isn't a 6- or 8-digit hex string is passed through unchanged so
+ * a caller using a less common form is not silently broken.
+ */
+function normalizeColor(color) {
+    const hex = color.startsWith("#") ? color.slice(1) : color;
+    if (/^[0-9a-fA-F]{8}$/.test(hex)) {
+        // ARGB → RGB: drop the alpha byte (srgbClr has no alpha component).
+        return hex.slice(2).toUpperCase();
+    }
+    if (/^[0-9a-fA-F]{6}$/.test(hex)) {
+        return hex.toUpperCase();
+    }
+    return hex;
+}
+/**
+ * Renders a user-visible drawing shape. Geometry/position is governed by the
+ * enclosing anchor (`xfrm` is written as zero, matching how Excel anchors a
+ * shape to a cell range), while preset geometry, fill, outline and text are
+ * taken from the model. Write-only: shapes are not parsed back on read (the
+ * same limitation that already applies to all non-chart drawing content).
+ */
+class ShapeXform extends BaseXform {
+    get tag() {
+        return "xdr:sp";
+    }
+    render(xmlStream, model) {
+        xmlStream.openNode("xdr:sp", { macro: "", textlink: "" });
+        // --- Non-visual shape properties ---
+        xmlStream.openNode("xdr:nvSpPr");
+        xmlStream.leafNode("xdr:cNvPr", { id: model.cNvPrId, name: model.name });
+        xmlStream.leafNode("xdr:cNvSpPr", {});
+        xmlStream.closeNode(); // xdr:nvSpPr
+        // --- Shape properties ---
+        xmlStream.openNode("xdr:spPr");
+        // Position/size is driven by the anchor; emit a zero xfrm placeholder.
+        xmlStream.openNode("a:xfrm");
+        xmlStream.leafNode("a:off", { x: 0, y: 0 });
+        xmlStream.leafNode("a:ext", { cx: 0, cy: 0 });
+        xmlStream.closeNode(); // a:xfrm
+        xmlStream.openNode("a:prstGeom", { prst: model.shapeType });
+        xmlStream.leafNode("a:avLst");
+        xmlStream.closeNode(); // a:prstGeom
+        // Fill: a colour produces a solidFill, otherwise an explicit noFill.
+        if (model.fill && model.fill.color) {
+            xmlStream.openNode("a:solidFill");
+            xmlStream.leafNode("a:srgbClr", { val: normalizeColor(model.fill.color) });
+            xmlStream.closeNode(); // a:solidFill
+        }
+        else {
+            xmlStream.leafNode("a:noFill");
+        }
+        // Line: an `a:ln` with width (pt → EMU) and/or a solid colour. When width
+        // is given without a colour, Excel applies its default outline colour at
+        // that width. When neither colour nor width is supplied, emit an explicit
+        // noFill line (no visible outline).
+        if (model.line && (model.line.color || model.line.width !== undefined)) {
+            const lnAttrs = {};
+            if (model.line.width !== undefined) {
+                lnAttrs.w = Math.round(model.line.width * EMU_PER_POINT);
+            }
+            xmlStream.openNode("a:ln", lnAttrs);
+            if (model.line.color) {
+                xmlStream.openNode("a:solidFill");
+                xmlStream.leafNode("a:srgbClr", { val: normalizeColor(model.line.color) });
+                xmlStream.closeNode(); // a:solidFill
+            }
+            xmlStream.closeNode(); // a:ln
+        }
+        else {
+            xmlStream.openNode("a:ln");
+            xmlStream.leafNode("a:noFill");
+            xmlStream.closeNode(); // a:ln
+        }
+        xmlStream.closeNode(); // xdr:spPr
+        // --- Text body ---
+        xmlStream.openNode("xdr:txBody");
+        xmlStream.leafNode("a:bodyPr", { vertOverflow: "clip", wrap: "square", anchor: "ctr" });
+        xmlStream.leafNode("a:lstStyle");
+        xmlStream.openNode("a:p");
+        xmlStream.openNode("a:pPr", { algn: "ctr" });
+        xmlStream.closeNode(); // a:pPr
+        if (model.text) {
+            xmlStream.openNode("a:r");
+            xmlStream.openNode("a:rPr", { lang: "en-US" });
+            xmlStream.closeNode(); // a:rPr
+            xmlStream.openNode("a:t");
+            xmlStream.writeText(model.text);
+            xmlStream.closeNode(); // a:t
+            xmlStream.closeNode(); // a:r
+        }
+        else {
+            xmlStream.leafNode("a:endParaRPr", { lang: "en-US" });
+        }
+        xmlStream.closeNode(); // a:p
+        xmlStream.closeNode(); // xdr:txBody
+        xmlStream.closeNode(); // xdr:sp
+    }
+}
+export { ShapeXform };

package/dist/esm/modules/excel/xlsx/xform/drawing/two-cell-anchor-xform.js

@@ -2,6 +2,7 @@ import { BaseCellAnchorXform } from "./base-cell-anchor-xform.js";
 import { CellPositionXform } from "./cell-position-xform.js";
 import { GraphicFrameXform } from "./graphic-frame-xform.js";
 import { PicXform } from "./pic-xform.js";
+import { ShapeXform } from "./shape-xform.js";
 import { SpXform } from "./sp-xform.js";
 import { StaticXform } from "../static-xform.js";
 class TwoCellAnchorXform extends BaseCellAnchorXform {
@@ -24,6 +25,7 @@ class TwoCellAnchorXform extends BaseCellAnchorXform {
             "xdr:to": new CellPositionXform({ tag: "xdr:to" }),
             "xdr:pic": new PicXform(),
             "xdr:sp": new SpXform(),
+            "xdr:userShape": new ShapeXform(),
             "xdr:graphicFrame": new GraphicFrameXform(),
             "xdr:clientData": new StaticXform({ tag: "xdr:clientData" })
         };
@@ -125,7 +127,14 @@ class TwoCellAnchorXform extends BaseCellAnchorXform {
             this.map["xdr:graphicFrame"].render(xmlStream, model.graphicFrame);
         }
         else if (model.shape) {
-            this.map["xdr:sp"].render(xmlStream, model.shape);
+            // A user-visible shape routes to the dedicated ShapeXform; the legacy
+            // form-control shape (no `kind`) stays on the SpXform path.
+            if (model.shape.kind === "userShape") {
+                this.map["xdr:userShape"].render(xmlStream, model.shape);
+            }
+            else {
+                this.map["xdr:sp"].render(xmlStream, model.shape);
+            }
         }
         this.map["xdr:clientData"].render(xmlStream, {});
         xmlStream.closeNode(); // xdr:twoCellAnchor

package/dist/esm/modules/excel/xlsx/xform/sheet/worksheet-xform.js

@@ -498,7 +498,70 @@ class WorkSheetXform extends BaseXform {
                 });
             }
         }
-        // Handle header watermark images — VML header/footer image
+        // Handle user-drawn shapes — anchored drawing parts with no media/rel.
+        const shapes = model.shapes ?? [];
+        if (shapes.length > 0) {
+            let { drawing } = model;
+            if (!drawing) {
+                drawing = model.drawing = {
+                    rId: nextRid(rels),
+                    name: `drawing${++options.drawingsCount}`,
+                    anchors: [],
+                    rels: []
+                };
+                options.drawings.push(drawing);
+                rels.push({
+                    Id: drawing.rId,
+                    Type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing",
+                    Target: drawingRelTargetFromWorksheet(drawing.name)
+                });
+            }
+            for (const shape of shapes) {
+                const anchorRange = shape.anchorRange;
+                if (!anchorRange) {
+                    continue;
+                }
+                // Mirror the three image anchoring modes. `getAnchorType` (drawing
+                // xform) dispatches on `pos`/`br`: absolute when `pos` is present,
+                // two-cell when `br` is present, one-cell otherwise (needs `ext`).
+                let range;
+                if (anchorRange.pos) {
+                    range = { pos: anchorRange.pos, ext: anchorRange.ext, editAs: "absolute" };
+                }
+                else if (anchorRange.br) {
+                    range = {
+                        tl: anchorRange.tl,
+                        br: anchorRange.br,
+                        editAs: anchorRange.editAs ?? "oneCell"
+                    };
+                }
+                else {
+                    range = {
+                        tl: anchorRange.tl,
+                        ext: anchorRange.ext,
+                        editAs: anchorRange.editAs ?? "oneCell"
+                    };
+                }
+                // Allocate a cNvPr id from the same monotonic space as the anchor's
+                // position in the drawing so it never collides with image/chart ids
+                // (which derive from the anchor index).
+                const cNvPrId = drawing.anchors.length + 1;
+                drawing.anchors.push({
+                    range,
+                    shape: {
+                        kind: "userShape",
+                        cNvPrId,
+                        name: shape.name ?? `Shape ${cNvPrId}`,
+                        shapeType: shape.shapeType,
+                        fill: shape.fillColor ? { color: shape.fillColor } : undefined,
+                        line: shape.lineColor !== undefined || shape.lineWidth !== undefined
+                            ? { color: shape.lineColor, width: shape.lineWidth }
+                            : undefined,
+                        text: shape.text
+                    }
+                });
+            }
+        }
         if (headerImageMedia.length > 0) {
             const medium = headerImageMedia[0]; // Only one header image per sheet
             const bookImage = options.media[medium.imageId];

package/dist/esm/modules/pdf/builder/document-builder.js

@@ -26,7 +26,7 @@ import { writePdfAMetadata, writePdfAOutputIntent } from "../core/pdfa.js";
 import { FontManager } from "../font/font-manager.js";
 import { iterateSystemFontCandidates } from "../font/system-fonts.js";
 import { parseTtf } from "../font/ttf-parser.js";
-import { wrapTextLines, emitTextWithMatrix, alphaGsName } from "../render/page-renderer.js";
+import { emitTextBlock, alphaGsName } from "../render/page-renderer.js";
 import { writeImageXObject } from "./image-utils.js";
 // =============================================================================
 // Constants
@@ -95,56 +95,29 @@ export class PdfPageBuilder {
         const bold = options.bold ?? false;
         const italic = options.italic ?? false;
         const fontFamily = options.fontFamily ?? "Helvetica";
-        // Resolve font
+        // Resolve the provisional Type1 resource and record the run's code
+        // points. The text is emitted as a deferred block so anchor alignment,
+        // word wrapping, and glyph encoding are all computed at build time —
+        // after fonts are finalised (a non-WinAnsi run may trigger a build-time
+        // auto-embed of a system CIDFont). Measuring against the provisional
+        // metrics here would misplace anchored text and break lines wrongly.
         const resourceName = this._fontManager.resolveFont(fontFamily, bold, italic);
         this._fontManager.trackText(text);
-        const useType3 = this._fontManager.hasType3Fonts() && !this._fontManager.hasEmbeddedFont();
-        // Resolve anchor into an adjusted x before any matrix math. We use the
-        // same font/size combination the stream will render with, so the
-        // alignment is correct for the actual glyphs (not a fallback
-        // estimate). Single-line drawing only — wrapped text ignores anchor
-        // because the wrapper re-splits by the caller's supplied x.
-        const anchor = options.anchor ?? "start";
-        const resolvedX = anchor === "start" || options.maxWidth
-            ? options.x
-            : options.x -
-                this._fontManager.measureText(text, resourceName, fontSize) *
-                    (anchor === "middle" ? 0.5 : 1);
-        if (options.maxWidth) {
-            // Word-wrap (reuses the shared wrapTextLines from page-renderer)
-            const measure = (s) => this._fontManager.measureText(s, resourceName, fontSize);
-            const lines = wrapTextLines(text, measure, options.maxWidth);
-            const leading = fontSize * lineHeightFactor;
-            this._stream.save();
-            this._applyAlpha(color.a);
-            this._stream.setFillColor(color);
-            for (let i = 0; i < lines.length; i++) {
-                const lineY = options.y - i * leading;
-                emitTextWithMatrix(this._stream, lines[i], 1, 0, 0, 1, options.x, lineY, resourceName, fontSize, this._fontManager, useType3);
-            }
-            this._stream.restore();
-        }
-        else {
-            // Single line
-            this._stream.save();
-            this._applyAlpha(color.a);
-            this._stream.setFillColor(color);
-            const rotation = options.rotation ?? 0;
-            if (rotation === 0) {
-                emitTextWithMatrix(this._stream, text, 1, 0, 0, 1, resolvedX, options.y, resourceName, fontSize, this._fontManager, useType3);
-            }
-            else {
-                // Build the rotation matrix around (x, y). `emitTextWithMatrix`
-                // accepts the full 2×3 text matrix, so we pre-multiply the
-                // rotation with the translation so one call positions and
-                // rotates the glyph sequence in a single Tm op.
-                const theta = (rotation * Math.PI) / 180;
-                const cos = Math.cos(theta);
-                const sin = Math.sin(theta);
-                emitTextWithMatrix(this._stream, text, cos, sin, -sin, cos, resolvedX, options.y, resourceName, fontSize, this._fontManager, useType3);
-            }
-            this._stream.restore();
-        }
+        this._stream.save();
+        this._applyAlpha(color.a);
+        this._stream.setFillColor(color);
+        emitTextBlock(this._stream, {
+            text,
+            x: options.x,
+            y: options.y,
+            type1ResourceName: resourceName,
+            fontSize,
+            anchor: options.anchor ?? "start",
+            maxWidth: options.maxWidth,
+            lineHeightFactor,
+            rotation: options.rotation ?? 0
+        }, this._fontManager);
+        this._stream.restore();
         return this;
     }
     /**

package/dist/esm/modules/pdf/builder/pdf-editor.js

@@ -144,7 +144,7 @@ export class PdfEditorPage {
     }
     /** @internal */
     _hasOverlay() {
-        return (this._overlay._stream.toString().length > 0 ||
+        return (this._overlay._stream.hasContent() ||
             this._overlay._images.length > 0 ||
             this._overlay._builderAnnotations.length > 0 ||
             this._overlay._formFields.length > 0);

package/dist/esm/modules/pdf/core/pdf-stream.js

@@ -23,6 +23,16 @@ import { pdfNumber } from "./pdf-object.js";
  */
 export class PdfContentStream {
     constructor() {
+        /**
+         * Content stream fragments in draw order. Most entries are plain operator
+         * strings produced eagerly. A function entry is a *deferred* fragment:
+         * its body is only evaluated at serialization time. This is required for
+         * text whose final byte encoding depends on font decisions (embedded
+         * CIDFont vs. Type1/WinAnsi vs. Type3 fallback) that are not finalised
+         * until `PdfDocumentBuilder.build()`. Deferring keeps the fragment at its
+         * exact draw-order position (preserving z-order) while letting the actual
+         * encoding run after the font manager's state is settled.
+         */
         this.parts = [];
     }
     // ===========================================================================
@@ -36,6 +46,17 @@ export class PdfContentStream {
         this.parts.push(operator);
         return this;
     }
+    /**
+     * Append a deferred fragment whose body is evaluated only at serialization
+     * time. Used by text drawing so the final byte encoding can be chosen after
+     * the document's fonts are resolved at build time. The fragment occupies its
+     * draw-order slot immediately, so z-order relative to other operators is
+     * preserved.
+     */
+    deferred(produce) {
+        this.parts.push(produce);
+        return this;
+    }
     // ===========================================================================
     // Graphics State
     // ===========================================================================
@@ -435,10 +456,25 @@ export class PdfContentStream {
     // Serialization
     // ===========================================================================
     /**
-     * Get the content stream as a string.
+     * Whether any fragment has been appended. Unlike `toString().length > 0`,
+     * this does NOT evaluate deferred fragments, so it is safe to call before
+     * fonts are resolved (e.g. when probing for overlay content during an
+     * editor save, prior to `writeFontResources`). A deferred text fragment
+     * counts as content even though its bytes are not produced yet.
+     */
+    hasContent() {
+        return this.parts.length > 0;
+    }
+    /**
+     * Get the content stream as a string. Deferred fragments (see `deferred`)
+     * are evaluated here, after font resolution has completed at build time.
      */
     toString() {
-        return this.parts.join("\n");
+        const out = [];
+        for (const part of this.parts) {
+            out.push(typeof part === "function" ? part() : part);
+        }
+        return out.join("\n");
     }
     /**
      * Get the content stream as a Uint8Array (UTF-8 encoded).

package/dist/esm/modules/pdf/font/font-manager.js

@@ -182,30 +182,47 @@ export class FontManager {
     getEmbeddedResourceName() {
         return this.embeddedResourceName;
     }
+    /**
+     * Resolve the resource name a draw-time-resolved Type1 resource should
+     * actually render (and be measured) with, given the font manager's
+     * *current* state. If an embedded font exists (possibly auto-discovered
+     * at build time, after the text was drawn against a Type1 resource), the
+     * embedded resource name is returned so both measurement and encoding go
+     * through the CIDFont. Otherwise the original Type1 resource name is kept;
+     * `measureText` handles Type3-fallback widths internally from that name.
+     *
+     * Centralises the routing rule shared by the deferred text renderer and
+     * any deferred measurement (anchor alignment, word wrapping) so the two
+     * never disagree.
+     */
+    resolveRenderResourceName(type1ResourceName) {
+        return this.embeddedFont ? this.embeddedResourceName : type1ResourceName;
+    }
     /**
      * Record that a text string will be rendered, tracking its code points.
      * Must be called for every text string before writing the PDF.
+     *
+     * Two sets are maintained because font selection may be decided *after*
+     * drawing (e.g. `PdfDocumentBuilder.build()` auto-discovers and embeds a
+     * system font once it sees the accumulated non-WinAnsi code points):
+     *
+     *   - `usedCodePoints` — every code point seen, always. If an embedded
+     *     font ends up being used (whether registered up front or
+     *     auto-discovered at build time), the subset must cover all of these,
+     *     including plain ASCII, so the CIDFont can encode the full run.
+     *   - `type3CodePoints` — non-WinAnsi code points only. Drives the
+     *     build-time decision to auto-embed a system font, and the Type3
+     *     fallback when none is available.
      */
     trackText(text) {
-        if (this.embeddedFont) {
-            for (let i = 0; i < text.length; i++) {
-                const cp = text.codePointAt(i);
-                this.usedCodePoints.add(cp);
-                if (cp > 0xffff) {
-                    i++; // skip low surrogate
-                }
+        for (let i = 0; i < text.length; i++) {
+            const cp = text.codePointAt(i);
+            if (cp > 0xffff) {
+                i++; // skip low surrogate
             }
-        }
-        else {
-            // No embedded font — track non-WinAnsi chars for Type3 fallback
-            for (let i = 0; i < text.length; i++) {
-                const cp = text.codePointAt(i);
-                if (cp > 0xffff) {
-                    i++;
-                }
-                if (!isWinAnsiCodePoint(cp)) {
-                    this.type3CodePoints.add(cp);
-                }
+            this.usedCodePoints.add(cp);
+            if (!isWinAnsiCodePoint(cp)) {
+                this.type3CodePoints.add(cp);
             }
         }
     }

package/dist/esm/modules/pdf/render/page-renderer.js

@@ -675,7 +675,7 @@ function drawRotatedGeneral(stream, cell, lines, fontManager, resourceName, font
         emitTextWithMatrix(stream, line, cos, sin, -sin, cos, tx, ty, resourceName, fontSize, fontManager, useType3);
     }
 }
-/** Emit a text string with hex encoding if available. */
+/** Emit a text string with hex encoding if available, onto a sink stream. */
 function emitText(stream, fontManager, text, resourceName) {
     const hex = fontManager.encodeText(text, resourceName);
     if (hex) {
@@ -690,40 +690,133 @@ function emitText(stream, fontManager, text, resourceName) {
  * when needed.  For each sub-run the matrix origin is advanced along the
  * text direction (cos, sin) by the rendered width.
  *
- * When `useType3` is false this collapses to a single BT/ET pair — identical
- * to the old `emitText()` path but wrapped in begin/end for convenience.
+ * The emitted operators are written as a *deferred* fragment (see
+ * `PdfContentStream.deferred`). The fragment is only evaluated at
+ * serialization time, by which point `PdfDocumentBuilder.build()` has
+ * finalised the document's fonts (auto-discovered embedded CIDFont,
+ * Type3 fallback, or plain Type1). This is essential: at draw time the
+ * font manager has not yet decided whether a non-WinAnsi code point (e.g.
+ * U+2192 →) will be served by an embedded font or a Type3 glyph, so eager
+ * encoding would irreversibly degrade those characters to spaces via the
+ * WinAnsi fallback. Deferring the encode keeps the fragment at its exact
+ * draw-order slot (preserving z-order) while choosing the correct bytes
+ * once fonts are known.
+ *
+ * The `useType3` argument is the caller's *draw-time* guess and is ignored;
+ * the deferred body recomputes the routing from the now-settled font
+ * manager state.
+ */
+export function emitTextWithMatrix(stream, text, a, b, c, d, tx, ty, type1ResourceName, fontSize, fontManager, _useType3) {
+    stream.deferred(() => renderTextBlock(text, a, b, c, d, tx, ty, type1ResourceName, fontSize, fontManager));
+}
+/**
+ * Emit a text block as a single *deferred* fragment so that anchor
+ * alignment, word wrapping, and glyph encoding are all computed at
+ * serialization time — after `PdfDocumentBuilder.build()` has finalised the
+ * document's fonts.
+ *
+ * This matters because text measurement (anchor offset, line breaking) must
+ * use the *same* font that ultimately renders the glyphs. At draw time the
+ * font may still be unresolved (a non-WinAnsi run can trigger a build-time
+ * auto-embed of a system CIDFont), so measuring against the provisional
+ * Type1/Helvetica metrics would misplace centred/right-aligned text and
+ * break lines at the wrong points. Deferring keeps measurement and encoding
+ * consistent while preserving the fragment's draw-order slot (z-order).
+ */
+export function emitTextBlock(stream, options, fontManager) {
+    stream.deferred(() => renderTextBlockLayout(options, fontManager));
+}
+/**
+ * Lay out and render a text block from the font manager's *current*
+ * (build-time) state. Resolves the render resource name once and uses it for
+ * both measurement and encoding so the two never disagree.
+ *
+ * Layout is computed in the text's *local* coordinate frame — x grows along
+ * the baseline, y grows upward — then mapped to page space through the
+ * rotation matrix. This makes anchor alignment, multi-line word wrapping, and
+ * rotation compose correctly together: each line is offset by its anchor
+ * shift (along local x) and its line index (down local y), and a single
+ * rotation maps the whole block into place. Upright text (rotation 0) reduces
+ * to the identity mapping.
+ */
+function renderTextBlockLayout(options, fontManager) {
+    const { text, x, y, type1ResourceName, fontSize, anchor, maxWidth, lineHeightFactor, rotation } = options;
+    // Resolve the resource name once; measurement and rendering share it so a
+    // build-time auto-embedded CIDFont (or Type3 fallback) is measured with the
+    // metrics that will actually render the glyphs.
+    const measureResource = fontManager.resolveRenderResourceName(type1ResourceName);
+    const measure = (s) => fontManager.measureText(s, measureResource, fontSize);
+    const lines = maxWidth ? wrapTextLines(text, measure, maxWidth) : [text];
+    const leading = fontSize * lineHeightFactor;
+    // Rotation matrix [a b; c d] = [cos sin; -sin cos]; identity when upright.
+    const theta = (rotation * Math.PI) / 180;
+    const cos = rotation === 0 ? 1 : Math.cos(theta);
+    const sin = rotation === 0 ? 0 : Math.sin(theta);
+    const anchorFactor = anchor === "middle" ? 0.5 : anchor === "end" ? 1 : 0;
+    const parts = [];
+    for (let i = 0; i < lines.length; i++) {
+        // Local-frame origin of this line: anchor shift along x, line index down y.
+        const localX = anchorFactor === 0 ? 0 : -measure(lines[i]) * anchorFactor;
+        const localY = -i * leading;
+        // Map local origin into page space through the rotation matrix.
+        const tx = x + localX * cos + localY * -sin;
+        const ty = y + localX * sin + localY * cos;
+        parts.push(renderTextBlock(lines[i], cos, sin, -sin, cos, tx, ty, type1ResourceName, fontSize, fontManager));
+    }
+    return parts.join("\n");
+}
+/**
+ * Produce the PDF operator string for a positioned text run, choosing the
+ * encoding from the font manager's *current* (build-time) state:
+ *   - embedded font  → single BT/ET with CIDFont hex encoding
+ *   - Type3 fallback → split into WinAnsi (Type1) and per-glyph Type3 runs
+ *   - neither        → single BT/ET with Type1/WinAnsi encoding
+ *
+ * Must only be called after font resolution (i.e. from a deferred fragment).
  */
-export function emitTextWithMatrix(stream, text, a, b, c, d, tx, ty, type1ResourceName, fontSize, fontManager, useType3) {
+function renderTextBlock(text, a, b, c, d, tx, ty, type1ResourceName, fontSize, fontManager) {
+    const sink = new PdfContentStream();
+    // Type3 splitting only applies when there is no embedded font but Type3
+    // fallback glyphs were generated. Otherwise the run renders as a single
+    // BT/ET pair, choosing the resource name from the now-settled state:
+    // if an embedded font exists (possibly auto-discovered at build time,
+    // after this run was drawn against a Type1 resource), the run must use it
+    // so `emitText` → `encodeText` produces CIDFont hex; without that switch
+    // the stale Type1 resource name would make `encodeText` return null and
+    // non-WinAnsi characters would degrade to spaces via the WinAnsi fallback.
+    const useType3 = fontManager.hasType3Fonts() && !fontManager.hasEmbeddedFont();
     if (!useType3) {
-        stream.beginText();
-        stream.setFont(type1ResourceName, fontSize);
-        stream.setTextMatrix(a, b, c, d, tx, ty);
-        emitText(stream, fontManager, text, type1ResourceName);
-        stream.endText();
-        return;
+        const resourceName = fontManager.resolveRenderResourceName(type1ResourceName);
+        sink.beginText();
+        sink.setFont(resourceName, fontSize);
+        sink.setTextMatrix(a, b, c, d, tx, ty);
+        emitText(sink, fontManager, text, resourceName);
+        sink.endText();
+        return sink.toString();
     }
     // Type3 path: split into runs and advance origin along text direction
     const runs = splitTextRuns(text, fontManager);
     let curTx = tx;
     let curTy = ty;
     for (const run of runs) {
-        stream.beginText();
+        sink.beginText();
         if (run.type3) {
-            stream.setFont(run.type3.resourceName, fontSize);
-            stream.setTextMatrix(a, b, c, d, curTx, curTy);
-            stream.showTextHex(run.type3.hex);
+            sink.setFont(run.type3.resourceName, fontSize);
+            sink.setTextMatrix(a, b, c, d, curTx, curTy);
+            sink.showTextHex(run.type3.hex);
         }
         else {
-            stream.setFont(type1ResourceName, fontSize);
-            stream.setTextMatrix(a, b, c, d, curTx, curTy);
-            emitText(stream, fontManager, run.text, type1ResourceName);
+            sink.setFont(type1ResourceName, fontSize);
+            sink.setTextMatrix(a, b, c, d, curTx, curTy);
+            emitText(sink, fontManager, run.text, type1ResourceName);
         }
-        stream.endText();
+        sink.endText();
         const w = fontManager.measureText(run.text, run.type3?.resourceName ?? type1ResourceName, fontSize);
         // Advance along the text direction (first column of the matrix)
         curTx += a * w;
         curTy += b * w;
     }
+    return sink.toString();
 }
 /**
  * Split a line of text into runs of consecutive WinAnsi and non-WinAnsi