postext 0.3.19 → 0.3.21

package/dist/parse/types.d.ts

@@ -1,11 +1,19 @@
-export type ContentBlockType = 'heading' | 'paragraph' | 'blockquote' | 'listItem' | 'mathDisplay' | 'resourceBlock' | 'directive';
+export type ContentBlockType = 'heading' | 'paragraph' | 'blockquote' | 'listItem' | 'mathDisplay' | 'resourceBlock' | 'directive' | 'containerStart' | 'containerEnd';
 /** Attributes parsed from a `:::name{key="v" other=bare flag}` directive.
  *  Values are kept as strings; directive consumers validate/coerce. A bare
  *  `flag` becomes `{ flag: '' }`. */
 export type DirectiveAttrs = Record<string, string>;
 /** Recognized directive names. Unknown names are not parsed as directives —
  *  they fall through to the paragraph branch and surface via warnings. */
-export type DirectiveName = 'pagebreak' | 'numbering';
+export type DirectiveName = 'pagebreak' | 'numbering' | 'columnbreak';
+/** Recognized fenced-container names. A container opens with a
+ *  `:::name{attrs}` line and closes with a bare `:::` line; the blocks in
+ *  between are parsed as usual and bracketed by a `containerStart` /
+ *  `containerEnd` marker pair sharing a `containerId`. */
+export type ContainerName = 'callout' | 'paragraphs' | 'part';
+/** Letter-case transform applied to the computed label of an inline `:ref`
+ *  (never to the number, never to a `text=` override). */
+export type RefCase = 'lower' | 'upper' | 'capitalize';
 /** Metadata attached to an `InlineSpan` when it represents a math formula.
  *  The span's `text` is a single `\uFFFC` (object replacement character)
  *  acting as a one-char-wide atomic placeholder in the plain text. */
@@ -42,6 +50,9 @@ export interface InlineSpan {
         style?: 'default' | 'number' | 'full';
         /** Optional override text to display instead of the computed label. */
         text?: string;
+        /** Optional letter-case transform for the label part (`Fig.` /
+         *  `Figure`) of the computed label. Ignored when `text` is set. */
+        case?: RefCase;
     };
 }
 /** Convenience discriminants for inline span iteration. */
@@ -52,23 +63,51 @@ export type MathSpan = InlineSpan & {
     math: MathMeta;
 };
 export type ListKind = 'unordered' | 'ordered' | 'task';
-export type ParseIssueKind = 'unclosedMath' | 'unclosedMathBlock';
-export interface ParseIssue {
+export type ParseIssueKind = 'unclosedMath' | 'unclosedMathBlock' | 'unclosedContainer';
+interface ParseIssueBase {
     kind: ParseIssueKind;
-    delimiter: '$' | '$$';
+    delimiter: '$' | '$$' | ':::';
     /** Absolute source offset of the unmatched opening delimiter. */
     sourceStart: number;
     /** End of the scanned region (usually the line or block end). */
     sourceEnd: number;
+}
+/** An inline `$…` or display `$$…` formula whose closing delimiter is
+ *  missing. */
+export interface UnclosedMathIssue extends ParseIssueBase {
+    kind: 'unclosedMath' | 'unclosedMathBlock';
+    delimiter: '$' | '$$';
     /** Raw TeX captured up to the end of the scanned region, for warning
      *  messages — may be empty. */
     tex: string;
 }
+/** A `:::name` container fence that was still open at end of input. The
+ *  parser auto-closes it; `sourceStart`/`sourceEnd` cover the opening line. */
+export interface UnclosedContainerIssue extends ParseIssueBase {
+    kind: 'unclosedContainer';
+    delimiter: ':::';
+    containerName: ContainerName;
+    containerId: number;
+}
+export type ParseIssue = UnclosedMathIssue | UnclosedContainerIssue;
 export interface ContentBlock {
     type: ContentBlockType;
     text: string;
     spans: InlineSpan[];
     level?: number;
+    /** For `heading` blocks: attributes parsed from a trailing
+     *  `{key="value" other=bare}` on the heading line (e.g.
+     *  `# Title {author="I. Zango"}`). The braces and their content are
+     *  removed from `text`. Absent when the heading carries no attributes. */
+    attrs?: DirectiveAttrs;
+    /** Absolute source range of each quoted attribute value, so editors can
+     *  map text rendered from `{attr.<key>}` back to the markdown. */
+    attrSources?: Record<string, {
+        start: number;
+        end: number;
+    }>;
+    /** Plain-text indices of forced title breaks (`\\` in the source). */
+    titleBreaks?: number[];
     /** Depth (1-based) for listItem blocks. Level 1 = outermost. */
     depth?: number;
     /** Discriminator for listItem blocks. Defaults to 'unordered' when absent. */
@@ -85,6 +124,16 @@ export interface ContentBlock {
     directiveAttrs?: DirectiveAttrs;
     /** For `resourceBlock` blocks: the referenced `Resource.id`. */
     resourceId?: string;
+    /** For `containerStart` / `containerEnd` marker blocks: the container
+     *  name (`'callout'`, `'paragraphs'`, `'part'`). */
+    containerName?: ContainerName;
+    /** For `containerStart` blocks: attributes parsed from the opening fence.
+     *  Always present on a start marker (empty object when the fence carries
+     *  no `{…}`). */
+    containerAttrs?: DirectiveAttrs;
+    /** For container marker blocks: identifier shared by the matching
+     *  start/end pair. Ids start at 1 and increase per parse. */
+    containerId?: number;
     /** Character offset of the first source character of this block in the original markdown */
     sourceStart: number;
     /** Character offset just past the last source character of this block */
@@ -96,4 +145,5 @@ export interface ContentBlock {
      */
     sourceMap: number[];
 }
+export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/parse/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/parse/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,WAAW,GACX,YAAY,GACZ,UAAU,GACV,aAAa,GACb,eAAe,GACf,WAAW,CAAC;AAEhB;;qCAEqC;AACrC,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEpD;0EAC0E;AAC1E,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,WAAW,CAAC;AAEtD;;sEAEsE;AACtE,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB;;kDAE8C;IAC9C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;uEACmE;IACnE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;8DAC0D;IAC1D,UAAU,CAAC,EAAE,OAAO,eAAe,EAAE,UAAU,CAAC;IAChD;;kDAE8C;IAC9C,GAAG,CAAC,EAAE;QACJ,oCAAoC;QACpC,UAAU,EAAE,MAAM,CAAC;QACnB;;sBAEc;QACd,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;QACtC,uEAAuE;QACvE,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED,2DAA2D;AAC3D,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC;AACzD,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEvD,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;AAExD,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,mBAAmB,CAAC;AAElE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,GAAG,GAAG,IAAI,CAAC;IACtB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB;mCAC+B;IAC/B,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,iDAAiD;IACjD,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4FAA4F;IAC5F,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/parse/types.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/bandCaps.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Band caps — page-span blocks, stage 2 (mid-page bands).
+ *
+ * Stage 1 (`placement.ts`) only inserts a page-span block where the current
+ * column band is *level*; a block arriving with the columns uneven moves to
+ * the top of the next page. Stage 2 lets it land mid-page the way a
+ * compositor would set it: the text above the box is cut level across all
+ * columns, the box spans the page, and the columns resume below it.
+ *
+ * Rather than redistributing already-placed blocks in place (which would
+ * bypass orphan / widow / keep-with-next), the engine re-runs the placement
+ * pass with a **band cap**: the columns of the band that opens with a given
+ * content block are shortened to `lines` grid lines, so they fill and
+ * overflow into each other naturally — every placement rule keeps applying
+ * — and end level at `bandTop + lines·grid`, where the span block then cuts
+ * the band. A cap is proposed by the pass that saw the block arrive in an
+ * uneven band with room below (`lines = ceil(Σ used px / N / grid)`), and
+ * consumed by the next pass. When the capped band overflows differently
+ * (e.g. keep-with-next moved a heading and the text no longer fits above
+ * the cut), the cap is retried one line taller a bounded number of times,
+ * then dropped — the block falls back to stage 1.
+ */
+import type { VDTColumn } from '../vdt';
+/** Cap on the band that opens with content block `startContentIndex`
+ *  (part `startPart` — a split paragraph's continuation can open a band
+ *  too), keyed in `bandCaps` by the span block's own content index. */
+export interface BandCap {
+    startContentIndex: number;
+    /** Part index of the band's opening block (`0` unless it is the
+     *  continuation of a paragraph split across columns / pages). */
+    startPart: number;
+    /** Height of the capped band in baseline-grid lines. */
+    lines: number;
+    /** Times the cap has been grown by one line after an overflow. */
+    retries: number;
+}
+/** Maximum number of extra placement passes the band-cap driver may run on
+ *  top of the initial pass (proposals + retries). */
+export declare const MAX_BAND_PASSES = 4;
+/** Maximum number of `lines + 1` retries for a cap whose band overflowed. */
+export declare const MAX_BAND_CAP_RETRIES = 3;
+/** What a placement pass reports back to the band-cap driver. */
+export interface BandPassReport {
+    /** New caps, keyed by the proposing span block's content index. */
+    bandCapProposals: ReadonlyMap<number, BandCap>;
+    /** Span blocks inserted in the band their cap was applied to. */
+    spanPlacedInBand: ReadonlySet<number>;
+    /** Caps whose opening block did open a band in this pass. */
+    bandCapsApplied: ReadonlySet<number>;
+}
+/** Shorten every column of a (still empty) band to `capPx`, remembering
+ *  each column's true bottom in `uncappedBottoms` so the band can be
+ *  restored (`uncapBand`) when the span block cuts it. Idempotent; a column
+ *  already shorter than the cap (bottom float) is left alone. A column that
+ *  already holds content keeps its used height — the cap then only trims
+ *  what is left. */
+export declare function applyBandCap(cols: readonly VDTColumn[], capPx: number, uncappedBottoms: Map<VDTColumn, number>): void;
+/** Give capped columns their true bottom back (the slack below the cap
+ *  returns to `availableHeight`). */
+export declare function uncapBand(cols: readonly VDTColumn[], uncappedBottoms: Map<VDTColumn, number>): void;
+/** True bottom of a column — the remembered one while it is capped. */
+export declare function columnBottom(col: VDTColumn, uncappedBottoms: ReadonlyMap<VDTColumn, number>): number;
+/** Grid lines a level cut of the band would need: the content spread over
+ *  the band's columns evenly, rounded up to whole lines. */
+export declare function bandCapLines(cols: readonly VDTColumn[], gridPx: number): number;
+/**
+ * Drive the band-cap passes. `initial` is the plain first pass; `runPass`
+ * re-places the document with the given caps. Returns the layout to carry
+ * into column balancing, the caps it was built with, and the number of
+ * passes run (including the initial one).
+ *
+ * Each round first settles the caps of the previous pass — a cap whose
+ * block was not inserted in its band is retried one line taller (while it
+ * did apply and `retries` allows), otherwise dropped — then adopts the new
+ * proposals (never one already tried). Rounds stop when nothing changes or
+ * `MAX_BAND_PASSES` extra passes were run. The layout returned never carries
+ * an undelivered cap: failing caps are removed and, when none survive, the
+ * initial pass is returned untouched — a document whose span blocks all
+ * fit stage 1 costs no extra pass at all.
+ */
+export declare function resolveBandCaps<T extends BandPassReport>(initial: T, runPass: (bandCaps: ReadonlyMap<number, BandCap>) => T): {
+    result: T;
+    bandCaps: Map<number, BandCap>;
+    passCount: number;
+};
+//# sourceMappingURL=bandCaps.d.ts.map

package/dist/pipeline/bandCaps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bandCaps.d.ts","sourceRoot":"","sources":["../../src/pipeline/bandCaps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAExC;;uEAEuE;AACvE,MAAM,WAAW,OAAO;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B;qEACiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;qDACqD;AACrD,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/C,iEAAiE;IACjE,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtC,6DAA6D;IAC7D,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACtC;AAED;;;;;oBAKoB;AACpB,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,SAAS,EAAE,EAC1B,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,GACtC,IAAI,CAQN;AAED;qCACqC;AACrC,wBAAgB,SAAS,CACvB,IAAI,EAAE,SAAS,SAAS,EAAE,EAC1B,eAAe,EAAE,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,GACtC,IAAI,CASN;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,CAAC,SAAS,EAAE,MAAM,CAAC,GAAG,MAAM,CAEpG;AAED;4DAC4D;AAC5D,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAI/E;AAKD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,cAAc,EACtD,OAAO,EAAE,CAAC,EACV,OAAO,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,GACrD;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAiDlE"}

package/dist/pipeline/bandCaps.js

@@ -0,0 +1,142 @@
+/**
+ * Band caps — page-span blocks, stage 2 (mid-page bands).
+ *
+ * Stage 1 (`placement.ts`) only inserts a page-span block where the current
+ * column band is *level*; a block arriving with the columns uneven moves to
+ * the top of the next page. Stage 2 lets it land mid-page the way a
+ * compositor would set it: the text above the box is cut level across all
+ * columns, the box spans the page, and the columns resume below it.
+ *
+ * Rather than redistributing already-placed blocks in place (which would
+ * bypass orphan / widow / keep-with-next), the engine re-runs the placement
+ * pass with a **band cap**: the columns of the band that opens with a given
+ * content block are shortened to `lines` grid lines, so they fill and
+ * overflow into each other naturally — every placement rule keeps applying
+ * — and end level at `bandTop + lines·grid`, where the span block then cuts
+ * the band. A cap is proposed by the pass that saw the block arrive in an
+ * uneven band with room below (`lines = ceil(Σ used px / N / grid)`), and
+ * consumed by the next pass. When the capped band overflows differently
+ * (e.g. keep-with-next moved a heading and the text no longer fits above
+ * the cut), the cap is retried one line taller a bounded number of times,
+ * then dropped — the block falls back to stage 1.
+ */
+/** Maximum number of extra placement passes the band-cap driver may run on
+ *  top of the initial pass (proposals + retries). */
+export const MAX_BAND_PASSES = 4;
+/** Maximum number of `lines + 1` retries for a cap whose band overflowed. */
+export const MAX_BAND_CAP_RETRIES = 3;
+/** Shorten every column of a (still empty) band to `capPx`, remembering
+ *  each column's true bottom in `uncappedBottoms` so the band can be
+ *  restored (`uncapBand`) when the span block cuts it. Idempotent; a column
+ *  already shorter than the cap (bottom float) is left alone. A column that
+ *  already holds content keeps its used height — the cap then only trims
+ *  what is left. */
+export function applyBandCap(cols, capPx, uncappedBottoms) {
+    for (const c of cols) {
+        if (c.bbox.height <= capPx + 0.01)
+            continue;
+        if (!uncappedBottoms.has(c))
+            uncappedBottoms.set(c, c.bbox.y + c.bbox.height);
+        const trimmed = c.bbox.height - capPx;
+        c.bbox.height = capPx;
+        c.availableHeight = Math.max(0, c.availableHeight - trimmed);
+    }
+}
+/** Give capped columns their true bottom back (the slack below the cap
+ *  returns to `availableHeight`). */
+export function uncapBand(cols, uncappedBottoms) {
+    for (const c of cols) {
+        const bottom = uncappedBottoms.get(c);
+        if (bottom === undefined)
+            continue;
+        const height = bottom - c.bbox.y;
+        c.availableHeight += height - c.bbox.height;
+        c.bbox.height = height;
+        uncappedBottoms.delete(c);
+    }
+}
+/** True bottom of a column — the remembered one while it is capped. */
+export function columnBottom(col, uncappedBottoms) {
+    return uncappedBottoms.get(col) ?? col.bbox.y + col.bbox.height;
+}
+/** Grid lines a level cut of the band would need: the content spread over
+ *  the band's columns evenly, rounded up to whole lines. */
+export function bandCapLines(cols, gridPx) {
+    let total = 0;
+    for (const c of cols)
+        total += c.bbox.height - c.availableHeight;
+    return Math.max(1, Math.ceil((total / cols.length - 0.01) / gridPx));
+}
+const capKey = (spanIndex, cap) => `${spanIndex}:${cap.startContentIndex}:${cap.startPart}:${cap.lines}`;
+/**
+ * Drive the band-cap passes. `initial` is the plain first pass; `runPass`
+ * re-places the document with the given caps. Returns the layout to carry
+ * into column balancing, the caps it was built with, and the number of
+ * passes run (including the initial one).
+ *
+ * Each round first settles the caps of the previous pass — a cap whose
+ * block was not inserted in its band is retried one line taller (while it
+ * did apply and `retries` allows), otherwise dropped — then adopts the new
+ * proposals (never one already tried). Rounds stop when nothing changes or
+ * `MAX_BAND_PASSES` extra passes were run. The layout returned never carries
+ * an undelivered cap: failing caps are removed and, when none survive, the
+ * initial pass is returned untouched — a document whose span blocks all
+ * fit stage 1 costs no extra pass at all.
+ */
+export function resolveBandCaps(initial, runPass) {
+    const caps = new Map();
+    let result = initial;
+    let passCount = 1;
+    if (initial.bandCapProposals.size === 0)
+        return { result, bandCaps: caps, passCount };
+    const tried = new Set();
+    for (let extra = 0; extra < MAX_BAND_PASSES; extra++) {
+        let changed = false;
+        for (const [spanIndex, cap] of [...caps]) {
+            if (result.spanPlacedInBand.has(spanIndex))
+                continue;
+            changed = true;
+            if (result.bandCapsApplied.has(spanIndex) && cap.retries < MAX_BAND_CAP_RETRIES) {
+                caps.set(spanIndex, { ...cap, lines: cap.lines + 1, retries: cap.retries + 1 });
+            }
+            else {
+                caps.delete(spanIndex);
+            }
+        }
+        for (const [spanIndex, cap] of result.bandCapProposals) {
+            if (caps.has(spanIndex) || tried.has(capKey(spanIndex, cap)))
+                continue;
+            caps.set(spanIndex, { ...cap });
+            changed = true;
+        }
+        if (!changed)
+            break;
+        if (caps.size === 0) {
+            // Every cap was dropped and nothing new came up: the plain layout.
+            result = initial;
+            break;
+        }
+        for (const [spanIndex, cap] of caps)
+            tried.add(capKey(spanIndex, cap));
+        result = runPass(caps);
+        passCount++;
+    }
+    // Never hand back a layout whose columns were capped for a box that did
+    // not arrive: strip the failing caps (dropping an earlier cap can unsettle
+    // a later one, hence the loop — each round removes at least one).
+    while (caps.size > 0) {
+        const failing = [...caps.keys()].filter((i) => !result.spanPlacedInBand.has(i));
+        if (failing.length === 0)
+            break;
+        for (const i of failing)
+            caps.delete(i);
+        if (caps.size === 0) {
+            result = initial;
+            break;
+        }
+        result = runPass(caps);
+        passCount++;
+    }
+    return { result, bandCaps: caps, passCount };
+}
+//# sourceMappingURL=bandCaps.js.map

package/dist/pipeline/bandCaps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bandCaps.js","sourceRoot":"","sources":["../../src/pipeline/bandCaps.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/build.d.ts

@@ -1,6 +1,8 @@
 import type { PostextContent, PostextConfig } from '../types';
 import { type VDTDocument } from '../vdt';
 import type { MeasurementCache } from '../measure';
+import { type LooseBudget } from './columnBalancing';
+import { type BandCap, type BandPassReport } from './bandCaps';
 export interface BuildDocumentOptions {
     /**
      * Cooperative cancellation hook. Called once per top-level content block
@@ -13,5 +15,44 @@ export interface BuildDocumentOptions {
 export declare class BuildCancelledError extends Error {
     constructor();
 }
+/** Cross-pass hints a placement pass consumes. All keyed by content-block
+ *  index; every map is optional so the plain first pass carries none. */
+export interface PassHints {
+    /** Column balancing: extra top spacing (px) per heading / list-end target. */
+    balanceExtraPx?: ReadonlyMap<number, number>;
+    /** Column balancing: K-P looseness per paragraph re-broken one line longer. */
+    balanceLooseness?: ReadonlyMap<number, number>;
+    /** Column balancing: shared budget of the loose candidates offered together
+     *  (the pass stops loosening a column once it gained what it needs). */
+    balanceLooseBudget?: ReadonlyMap<number, LooseBudget>;
+    /** Band caps keyed by the span block's content index (see `bandCaps.ts`). */
+    bandCaps?: ReadonlyMap<number, BandCap>;
+}
+export interface PassResult extends BandPassReport {
+    doc: VDTDocument;
+    /** Pages whose break into the next page was explicit (`:::pagebreak`,
+     *  heading `breakBefore`, chapter opener) rather than natural content
+     *  overflow — those pages keep their short last column. */
+    forcedBreakPages: Set<number>;
+    bandCapProposals: Map<number, BandCap>;
+    spanPlacedInBand: Set<number>;
+    bandCapsApplied: Set<number>;
+    /** Column balancing: per loose paragraph tried in this pass, the tracking
+     *  (thousandths of an em) that gained its extra line — `null` when no rung
+     *  of the ladder did, so the driver can blacklist it. Candidates left
+     *  untried because their column's budget was already met are absent. */
+    looseOutcome: Map<number, number | null>;
+}
+/**
+ * Single placement pass. `hints` carries the cross-pass adjustments: the
+ * column-balancing spacing / looseness and the band caps of page-span
+ * blocks. Besides the document it reports `forcedBreakPages` (for
+ * balancing) and the band-cap bookkeeping the driver in `buildDocument`
+ * needs — new cap proposals, the span blocks that landed in their capped
+ * band, and the caps that were actually applied.
+ *
+ * @internal Exposed for tests only; use `buildDocument`.
+ */
+export declare function buildDocumentPass(content: PostextContent, config?: PostextConfig, cache?: MeasurementCache, options?: BuildDocumentOptions, hints?: PassHints): PassResult;
 export declare function buildDocument(content: PostextContent, config?: PostextConfig, cache?: MeasurementCache, options?: BuildDocumentOptions): VDTDocument;
 //# sourceMappingURL=build.d.ts.map

package/dist/pipeline/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/pipeline/build.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAA0B,MAAM,UAAU,CAAC;AAGtF,OAAO,EAIL,KAAK,WAAW,EAIjB,MAAM,QAAQ,CAAC;AAWhB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAkDnD,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC;CAC9B;AAED,qBAAa,mBAAoB,SAAQ,KAAK;;CAK7C;AAmjCD,wBAAgB,aAAa,CAC3B,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,aAAa,EACtB,KAAK,CAAC,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,WAAW,CA8Db"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/pipeline/build.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAA8C,MAAM,UAAU,CAAC;AAG1G,OAAO,EAIL,KAAK,WAAW,EAKjB,MAAM,QAAQ,CAAC;AAWhB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA2DnD,OAAO,EAGL,KAAK,WAAW,EAGjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAML,KAAK,OAAO,EACZ,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC;CAC9B;AAED,qBAAa,mBAAoB,SAAQ,KAAK;;CAK7C;AAWD;yEACyE;AACzE,MAAM,WAAW,SAAS;IACxB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C;4EACwE;IACxE,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACtD,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,UAAW,SAAQ,cAAc;IAChD,GAAG,EAAE,WAAW,CAAC;IACjB;;+DAE2D;IAC3D,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B;;;4EAGwE;IACxE,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1C;AAuCD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,aAAa,EACtB,KAAK,CAAC,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE,oBAAoB,EAC9B,KAAK,GAAE,SAAc,GACpB,UAAU,CAu9CZ;AAED,wBAAgB,aAAa,CAC3B,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,aAAa,EACtB,KAAK,CAAC,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,WAAW,CA6Fb"}