postext 0.3.39 → 0.3.41

package/dist/pipeline/build.js

@@ -26,7 +26,7 @@ import { computeHeadingContext, computeResourceNumbering, } from './resourceNumb
 import { defaultResourceTypes } from '../defaults/resourceTypes';
 import { buildHeadersAndFooters, measureHeadingAdvancedDesignHeight } from './headerFooter';
 import { proposeBalanceLines, collectColumnGaps, firstDivergentColumn, gapLinesIn, pageSegments, MAX_BALANCING_PASSES, MAX_BALANCING_PASSES_PER_DOCUMENT, balanceKey } from './columnBalancing';
-import { applyBandCap, uncapBand, columnBottom, bandCapLines, bandTop, resolveBandCaps, resolveTrailingCaps, bandCapLinesAroundZone, } from './bandCaps';
+import { applyBandCap, uncapBand, columnBottom, bandCapLines, bandTop, resolveBandCapsGen, drainPasses, resolveTrailingCapsGen, bandCapLinesAroundZone, } from './bandCaps';
 import { raggedLooseLines } from './raggedLines';
 /** Tolerance for "does this block fit" checks against a column's free
  *  height, absorbing floating-point drift between grid multiples. */
@@ -2923,6 +2923,48 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
  *  first, for the page labels it prints to settle. */
 const MAX_TOC_ROUNDS = 3;
 export function buildDocument(content, config, cache, options) {
+    return drainPasses(buildDocumentGen(content, config, cache, options));
+}
+/** Let the event loop turn: `scheduler.yield()` where it exists, else a
+ *  message-channel hop (a `setTimeout(0)` is clamped to 4 ms once nested). */
+export function yieldToEventLoop() {
+    const scheduler = globalThis.scheduler;
+    if (scheduler?.yield)
+        return scheduler.yield();
+    if (typeof MessageChannel !== 'undefined') {
+        return new Promise((resolve) => {
+            const channel = new MessageChannel();
+            channel.port1.onmessage = () => {
+                channel.port1.close();
+                resolve();
+            };
+            channel.port2.postMessage(null);
+        });
+    }
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+/**
+ * {@link buildDocument}, yielding to the event loop between placement
+ * passes. A build is several passes (band caps, column balancing, contents
+ * rounds), each a synchronous re-placement of the document; in a worker
+ * this lets a `cancel` posted mid-build be observed at the next pass
+ * boundary — `shouldCancel` is polled there as well as inside a pass —
+ * instead of after the whole build.
+ */
+export async function buildDocumentAsync(content, config, cache, options) {
+    const gen = buildDocumentGen(content, config, cache, options);
+    const pause = options?.yieldBetweenPasses ?? yieldToEventLoop;
+    for (;;) {
+        const step = gen.next();
+        if (step.done)
+            return step.value;
+        await pause();
+        if (options?.shouldCancel?.())
+            throw new BuildCancelledError();
+    }
+}
+/** The build as a generator: one `yield` after every placement pass. */
+export function* buildDocumentGen(content, config, cache, options) {
     // A document printing its own table of contents (`:::toc` with no
     // host-supplied outline) is laid out with the page labels of the previous
     // build until they no longer change: the contents' own length moves what
@@ -2932,36 +2974,44 @@ export function buildDocument(content, config, cache, options) {
         const parsed = parseMarkdownMemo(extractFrontmatter(content.markdown).content);
         if (hasTocDirective(parsed)) {
             let outline = computeOutline(parsed, resolveAllConfig(config), content.continuation?.headings);
-            let doc = buildDocumentBalanced({ ...content, outline }, config, cache, options);
+            let doc = yield* buildDocumentBalanced({ ...content, outline }, config, cache, options, 0);
             for (let round = 0; round < MAX_TOC_ROUNDS; round++) {
                 const after = outlineFromDoc(doc, outline);
                 if (sameOutline(after, outline))
                     break;
                 outline = after;
-                doc = buildDocumentBalanced({ ...content, outline }, config, cache, options);
+                doc = yield* buildDocumentBalanced({ ...content, outline }, config, cache, options, round + 1);
             }
             return doc;
         }
     }
-    return buildDocumentBalanced(content, config, cache, options);
+    return yield* buildDocumentBalanced(content, config, cache, options);
 }
-function buildDocumentBalanced(content, config, cache, options) {
+const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+function* buildDocumentBalanced(content, config, cache, options, tocRound = 0) {
     // Each pass reports its own progress, numbered in build order.
     let passIndex = 0;
     const onProgress = options?.onProgress;
+    const onPass = options?.onPass;
     const passOptions = onProgress
         ? { ...options, onProgress: (p) => onProgress({ ...p, pass: passIndex }) }
         : options;
     const runPass = (hints) => {
         passIndex++;
-        return buildDocumentPass(content, config, cache, passOptions, hints);
+        const started = onPass ? now() : 0;
+        const result = buildDocumentPass(content, config, cache, passOptions, hints);
+        onPass?.({ pass: passIndex, tocRound, ms: now() - started, pages: result.doc.pages.length });
+        return result;
     };
+    // The first pass is a pass too: let a cancel land before the caps run.
+    const initial = runPass();
+    yield;
     // --- Band caps (page-span blocks mid-page) -----------------------------
     // A span block that arrived in an uneven band proposes a cap; the driver
     // re-places the document with it (and grows / drops caps whose band
     // overflowed) before balancing runs. Documents without such blocks get
     // their first pass back untouched — no extra pass.
-    const bands = resolveBandCaps(runPass(), (bandCaps) => runPass({ bandCaps }));
+    const bands = yield* resolveBandCapsGen(initial, (bandCaps) => runPass({ bandCaps }));
     let best = bands.result;
     const bandCaps = bands.bandCaps;
     let passCount = bands.passCount;
@@ -3154,7 +3204,7 @@ function buildDocumentBalanced(content, config, cache, options) {
         return blacklist(null);
     };
     let balancingPasses = 0;
-    const balance = () => {
+    function* balance() {
         while (balancingPasses < MAX_BALANCING_PASSES_PER_DOCUMENT) {
             const active = segments.filter((s) => !s.done);
             if (active.length === 0)
@@ -3224,6 +3274,7 @@ function buildDocumentBalanced(content, config, cache, options) {
             const next = runPass(hintsFrom(proposal.lines, proposal.loose, proposal.looseBudget));
             passCount++;
             balancingPasses++;
+            yield;
             const nextGaps = collectColumnGaps(next.doc, next.forcedBreakPages);
             const capPage = pageOfContent(best.doc);
             const accepted = [];
@@ -3287,9 +3338,9 @@ function buildDocumentBalanced(content, config, cache, options) {
             if (accepted.length > 0)
                 best = spliceSegments(next, accepted);
         }
-    };
+    }
     resetSegments();
-    balance();
+    yield* balance();
     // --- Trailing bands (closing columns cut level) -------------------------
     // Once the balancing levers have settled the earlier pages, level the
     // closing band of every chapter / the document with a trailing cap. It is
@@ -3300,14 +3351,14 @@ function buildDocumentBalanced(content, config, cache, options) {
     // fill what the cut left short (a column ending a line under the cap).
     if (balancing.trailing) {
         const frozen = hintsFrom(applied.lines, applied.loose);
-        const trailing = resolveTrailingCaps(best, bandCaps, (caps) => runPass({ ...frozen, bandCaps: caps }));
+        const trailing = yield* resolveTrailingCapsGen(best, bandCaps, (caps) => runPass({ ...frozen, bandCaps: caps }));
         passCount += trailing.passCount;
         if (trailing.result !== best) {
             best = trailing.result;
             for (const [i, cap] of trailing.caps)
                 bandCaps.set(i, cap);
             resetSegments();
-            balance();
+            yield* balance();
         }
     }
     best.doc.iterationCount = passCount;