Bibliography: how pdf.js lays out XFA, and what a Go layout engine inherits

[tannevaled]

Reading of Mozilla pdf.js's XFA layout implementation (src/core/xfa/), before we write ours.

No code, no design. The full reading is in the first comment, with file and line for every claim.

Read at pdf.js 9785821 (2026-08-30), local read-only clone at /Users/Shared/biblio/pdf.js.

[tannevaled]

[2026-09-03 10:49:17 CEST]

Read at pdf.js 9785821 (2026-08-30). Paths below are relative to src/core/xfa/ unless said otherwise. Every claim carries a file and a line; where I could not determine something I say so.

---

1. The shape of the problem, in its own terms

Three phases, not two

XFAFactory (factory.js:32-43) does parse, then bind, then — separately, and asynchronously — pages:

this.root = new XFAParser().parse(XFAFactory._createDocument(data));
const binder = new Binder(this.root);
this.form = binder.bind();

and later _createPagesHelper (factory.js:53-70) drives a generator one page at a time through setTimeout, because pagination is slow enough to block the event loop.

The phase we underestimated is the middle one. Binding does not annotate the template; it builds a second tree.

// bind.js:61
this.root.form = this.form = root.template[$clone]();

bind() returns that clone (bind.js:72-75), and _bindOccurrences (bind.js:385-417) inserts one clone of the container per matched data node:

const clone = baseClone[$clone]();
parent[name].push(clone);
parent[$insertAt](pos + i, clone);

with a second path, _createOccurrences (bind.js:421-462), that clones up to occur.initial when the data supplies no matches at all (if (!this.emptyMerge) return;, bind.js:422-424). Layout never sees the template. It sees an expanded form.

layout.js is not the engine

It is 387 lines holding four functions — addHTML, checkDimensions, flushHTML, getAvailableSpace (layout.js:387) — and its own header says who uses them:

// layout.js:27
// Subform and ExclGroup have a layout so they share these functions.

The engine is three things in template.js and xfa_object.js:

• Template[$toPages] (template.js:5418-5658) — the page loop.
• Subform[$toHTML] (template.js:4977-5247) and ExclGroup[$toHTML] (template.js:2443-2602) — the container algorithm, essentially duplicated.
• XFAObject[$childrenToHTML] (xfa_object.js:393-428) — the resumable child walk.

So it is the other way round from what the filename suggests: layout.js holds the predicates and accumulators, template.js holds the control flow, per element.

The control flow is failure-driven, and resumable

HTMLResult (utils.js:171-198) has three outcomes, not two: success, FAILURE, and breakNode. The header comment of layout.js:29-54 is the clearest statement of the whole algorithm and worth quoting in full:

 * A container has an initial space (with a width and a height) to fit in,
 * ... So if the container has known dimensions and these ones are ok with the
 * space then continue else we return HTMLResult.FAILURE: it's up to the
 * parent to deal with this failure (e.g. if parent layout is lr-tb and
 * we fail to add a child at end of line (lr) then we try to add it on the
 * next line).
 ...
 * Before a failure some children may have been layed out: they've been saved in
 * [$extra].children and [$extra] has properties generator and failingNode
 * in order to save the state where we were before a failure.
 * This [$extra].children property is useful when a container has to be splited.
 * So if a container is unbreakable, we must delete its [$extra] property before
 * returning.

There is no "split a box" routine. Splitting is the saved generator: $childrenToHTML stashes the iterator in this[$extra].generator and the child that failed in this[$extra].failingNode, and on re-entry retries that child first in the new space (xfa_object.js:393-409).

What surprised me — three things

(a) pdf.js does not compute a geometric page. It emits HTML and lets CSS flexbox place things.

This is the finding that changes the estimate. converters.position refuses to emit coordinates unless the parent is a positioned layout:

// html_utils.js:112-118
position(node, style) {
  const parent = node[$getSubformParent]();
  if (parent?.layout && parent.layout !== "position") {
    // IRL, we've some x/y in tb layout.
    // Specs say x/y is only used in positioned layout.
    return;
  }

and fixDimensions actively throws the coordinates away:

// html_utils.js:347-350
if (parent.layout && parent.layout !== "position") {
  // Useless in this context.
  node.x = node.y = 0;
}

The lines built by createLine (layout.js:56-64) carry class xfaLr/xfaRl, and in web/xfa_layer_builder.css:

/* web/xfa_layer_builder.css:255-273 */
.xfaLrTb, .xfaRlTb, .xfaTb { display: flex; flex-direction: column; align-items: stretch; }
.xfaLr { display: flex; flex-direction: row; align-items: stretch; }
.xfaRl { display: flex; flex-direction: row-reverse; align-items: stretch; }

hAlign becomes alignSelf (html_utils.js:158-168); vAlign becomes xfaValignMiddle, i.e. align-items: center (css:287-290); table rows are display:flex; flex-direction:row (css:298-309).

A Go engine that must draw on a PDF page has to write, in addition to everything pdf.js writes, the flexbox subset pdf.js delegates to the browser. That work is invisible in pdf.js's line count and I have no way to size it from this reading.

(b) The page loop is a while(true) with a heuristic bail-out.

// template.js:5502-5509
while (true) {
  if (!hasSomething) {
    mainHtml.children.pop();
    if (++hasSomethingCounter === MAX_EMPTY_PAGES) {
      warn("XFA - Something goes wrong: please file a bug.");

MAX_EMPTY_PAGES = 3 (template.js:123). Pagination is not proven to terminate; it is bounded and then complained about.

(c) Fit checking is not a pure function. checkDimensions (layout.js:266-385) consults a global on the template root in five of its six branches — node[$getTemplateRoot]()[$extra].noLayoutFailure — which is switched on around unsplittable subtrees (setFirstUnsplittable, template.js:313-319) and around leader/trailer/overflow injection (handleOverflow, template.js:404-418). It also has a hard-coded slop:

// layout.js:275
const ERROR = 2;

used in every comparison, e.g. Math.round(h - space.height) > ERROR.

---

2. The pieces, with sizes

src/core/xfa/ is 16 358 lines across 27 files. For layout, the ones that matter:

File	Lines	Load-bearing	Mechanical
template.js	6 603	~2 400	~4 200
xfa_object.js	1 091	~60 (370-428)	rest is the object model, $clone, proto
html_utils.js	653	~200	~450 CSS emission
layout.js	387	~360	header only
text.js	300	~280	—
utils.js	212	~50	table + validators
fonts.js	193	~110	name-sniffing tables
bind.js	673	(we have most of this)

template.js is not 6 603 lines of layout. 742 of its lines are attribute parsing (grep -c 'attributes\.'), 225 are new XFAObjectArray() declarations, and TemplateNamespace (template.js:6131-6592) is 472 lines of static foo(attrs) { return new Foo(attrs); } and nothing else. The classes that actually lay out, with sizes:

Subform    461  (4789-5249)
Field      426  (2649-3074)
ExclGroup  308  (2297-2604)
Template   286  (5375-5660)
Draw       180  (1823-2002)
PageArea   140  (3996-4135)
Caption    123  (1144-1266)
Area       115  ( 544- 658)
PageSet    103  (4136-4238)

plus ~280 lines of module helpers at template.js:155-418 (getBorderDims, setTabIndex, setFirstUnsplittable, handleBreak, handleOverflow, …).

Is "8-12k lines" the right order of magnitude? For a faithful port of parse + bind + layout: yes. For layout alone: no, it is high by about 2-3x. The layout proper — everything after binding — is about 3 500-4 000 lines in pdf.js, of which perhaps 1 200 are genuinely hard: Subform/ExclGroup/Field/Template $toHTML, all of layout.js, layoutNode/computeBbox/fixDimensions, and TextMeasure. The remaining ~4 000 in template.js are the element vocabulary — long, repetitive, and safe.

But add back: (i) the ~1 000-line typed object model we do not have, (ii) the flexbox-substitute layer pdf.js never writes, whose size I could not determine. So our total is plausibly larger than pdf.js's, not smaller.

---

3. The order it has to be built in

Each step below is blocked by the one above it, and the citation says why.

(a) The expanded form tree. bind.js:61 — layout runs over a clone, never over the template. _bindOccurrences (bind.js:385-417) inserts one clone per matched data node. Occur defaults are asymmetric and are computed in Occur[$clean] (template.js:3918-3942): min defaults to 0 under a pageArea/pageSet and 1 elsewhere; max defaults to min if min was written and to 1 (or -1 under a page container) if it was not. Without this, a dynamic form's table has exactly one row and the whole exercise is pointless.

(b) A typed element model with per-element defaults, and resolved geometry. getTransformedBBox (layout.js:202-259) needs anchorType and rotate; getBorderDims (template.js:155-177) needs the border's four widths and four insets; converters.dimensions (html_utils.js:81-111) needs colSpan against the parent's columnWidths. Note that $getSubformParent is not the parent — it skips SubformSet (template.js:4901-4907) — and $getContainedChildren flattens SubformSet into its parent (template.js:198-206, 4922-4926).

(c) Text measurement. layoutNode (html_utils.js:207-288) is called from exactly three places — Caption[$getExtra] (template.js:1190), Draw[$toHTML] (template.js:1908), Field[$toHTML] (template.js:2816) — and it is what supplies w/h when the template leaves them empty. There is no fallback: a Draw with no h has no height until text is measured. This cannot be deferred.

(d) layout.js — checkDimensions, getAvailableSpace, addHTML, flushHTML. Meaningless without (b) and (c).

(e) The resumable child walk — $childrenToHTML + [$extra].generator + [$extra].failingNode (xfa_object.js:393-428) and flushHTML (layout.js:66-94). Splitting is entirely this.

(f) Page machinery — PageArea[$toHTML] (template.js:4081-4133, including medium.short/medium.long and the landscape swap at 4098-4106), ContentArea[$toHTML] (template.js:1570-1597), and $getNextPage on both PageArea (4061-4075) and PageSet (4176-4236, with the odd/even/first/rest matching at 4210-4235).

(g) Breaks and overflow, last. handleBreak (template.js:328-402), Overflow[$getExtra] (template.js:3977), leaders and trailers (template.js:5519-5529, 5553-5561), handleOverflow (template.js:404-418). These steer the loop that (f) drives, so they come after it.

---

4. What we already have — and it is less than it looks

template.go (185 lines) — a parser, not a model

Node{Kind, Attr map[string]string, Text, Kids} (template.go:21-33) is a generic XML tree. pdf.js's equivalent is xfa_object.js (1 091 lines) plus the 6 603-line typed vocabulary of template.js. What that vocabulary supplies and we do not:

• Per-element attribute defaults. getStringOption(data, options) returns options[0] when the attribute is absent or invalid (utils.js:70-76). The defaults are encoded in the order of the option list, several hundred times over. Node.Get("layout") returning "" is not the same as "position".
• $getSubformParent (template.js:4901-4907) — layout asks this, not "parent".
• $getContainedChildren (template.js:198-206) — SubformSet children are yielded as if they were the parent's.
• proto / use / usehref resolution, and $clone.

Verdict: not met. What we have is the right foundation to build a model on, not a model.

data.go (189 lines) — fine, and not a layout prerequisite

ParseDatasets, Values, Value, FieldNames. pdf.js's data.js is 82 lines and is only the round-trip serializer; nothing in layout reads it. No gap here.

bind.go (708) + som.go (220) — the largest gap, and it is structural

The binder is our best-covered piece and the SOM support is genuinely ahead of where I expected. But its output shape is wrong for layout. It returns a flat []Binding of (Name, Path, Kind, Node, Data, DataPath, Value, Bound) (bind.go:23-44). pdf.js's binder returns a tree with containers duplicated per record.

We say so ourselves, honestly, at bind.go:153-156:

It does not repeat a container to satisfy occur's initial count. pdf.js, merging into empty data, clones a subform until there are as many as the template asks for. Those clones carry no data; they change the layout, not the values, and this returns values.

That was the right call for a value reader. It is precisely the thing a layout engine needs. Half met, and the missing half is the half layout depends on.

Encouragingly, the information is already in hand: occurInfo (bind.go:631-658) reads min/max with the asymmetric defaults, and bindOccurrences (bind.go:529-536) already iterates matches. What is missing is emitting a cloned subtree per occurrence rather than a path with an index in it. That, plus $clone and proto resolution, is step (a).

measure.go (83 lines) — sound, unused, and divergent in one place

Better than pdf.js in two respects:

• We have pc (pica = 12pt, measure.go:36). dimConverters (utils.js:19-25) has only pt, cm, mm, in, px — no pica.
• We error on an unknown unit (measure.go:63). pdf.js silently returns the bare number as points (utils.js:97-102), so "10em" reads as 10 points and "10 pt" (with a space — the unit group is (.*), untrimmed) also reads as 10 points by accident.

One divergence to settle before it bites: we map px = 72/96 (measure.go:37), pdf.js maps px = 1pt (utils.js:24). Whichever is right per spec, we and the reference implementation will disagree on real files, and nobody will notice until a form is off by a third.

Honest note: ParseMeasure and measureOr have no caller in the package outside measure_test.go and template_test.go:57. It is a correct leaf utility wired to nothing.

Summary

Met	XML parsing; datasets; SOM; explicit and implicit binding; unit parsing
Half met	the form tree (values yes, occurrence expansion no); the element vocabulary (untyped, no defaults)
Not met	typed geometry; $extra state; HTMLResult; any fit check; content-area/page model; text measurement; any font stack (go.mod has zero dependencies)

---

5. The hard parts, named

Roughly in order of expected cost.

(i) Text measurement is the floor, and pdf.js's is admittedly approximate

An unexplained blanket 2% inflation on every measured width:

// text.js:18
const WIDTH_FACTOR = 1.02;

// text.js:296
return { width: WIDTH_FACTOR * width, height, isBroken };

No comment justifies it anywhere in the file.

Six independent copies of 1.2 as a default line height, in three files, with no shared constant: text.js:180, text.js:182, text.js:214, fonts.js:183, fonts.js:184, html_utils.js:625. Worse, two of them are in different units: text.js:182 computes an absolute Math.max(1.2, fontLineHeight) * fontSize, while html_utils.js:625 emits a unitless CSS Math.max(1.2, pdfFont.lineHeight).

The no-font path assumes every character is one em wide:

// text.js:211-215
// When we have no font in the pdf, just use the font size as default width.
for (const line of str.split(/[\u2029\n]/)) {
  for (const char of line.split("")) {
    this.glyphs.push([fontSize, 1.2 * fontSize, fontSize, char, false]);
  }

and getMetrics with no font returns three literals:

// fonts.js:173-179
if (!pdfFont) {
  return { lineHeight: 12, lineGap: 2, lineNoGap: 10 };
}

The real path is honest work: glyph advances from pdfFont.charsToGlyphs, scaled by fontSize / 1000 (text.js:186-200), with pdfFont.defaultWidth || pdfFont.charsToGlyphs(" ")[0].width as the per-glyph fallback (text.js:187-188).

(ii) Line breaking is greedy and space-only

TextMeasure.compute (text.js:222-297) breaks only on a literal " ". On overflow it rewinds the loop counter and re-walks glyphs already counted (text.js:273, i = lastSpacePos;). No UAX #14, no hyphenation:

// text.js:279
// Just break in the middle of the word

// text.js:250
// We can break here but the space is not taken into account.

No CJK handling, no zero-width space, no non-breaking-space case. For French government forms full of non-breaking spaces before punctuation, this is a place we will differ from Adobe and will need our own judgement.

(iii) A live defect in pdf.js's rich-text measurement

xhtml.js:377 and xhtml.js:467 call

measure.pushFont({ weight: "bold" });    // xhtml.js:377  (<b>)
measure.pushFont({ posture: "italic" }); // xhtml.js:467  (<i>)

but TextMeasure defines only pushData (text.js:157). Grepping all of src/core/xfa/ finds pushFont at exactly those two call sites and nowhere as a definition. Measuring rich text containing <b> or <i> throws a TypeError. So pdf.js's rich-text measurement is not a reference we can copy or check ourselves against.

(iv) The retry protocol is subtle, and pdf.js documents a bug it had to guard

The nine-line comment at template.js:5161-5168 is the one to read twice:

// The goal is not only to avoid some useless checks but to avoid
// bugs too: if a descendant managed to put a node and failed
// on the next one, going to the next step here will imply to
// visit the descendant again, clear [$extra].children and restart
// on the failing node, consequently the first node just disappears
// because it has never been flushed.

That is a defect found in the field, not a design. Any reimplementation with the same architecture will hit it. ExclGroup carries the same guard by reference: // See comment in Subform::[$toHTML]. (template.js:2554).

(v) $isSplittable cannot be cached, and knows why

// template.js:4940-4942
[$isSplittable]() {
  // We cannot cache the result here because the contentArea
  // can change.

and the -tb branch (template.js:4962-4970) deliberately returns false without memoizing, with a comment explaining a specific case about a sixth element of width 20 on a line of width 100.

(vi) Nothing guarantees termination

MAX_EMPTY_PAGES = 3 (template.js:123), MAX_ATTEMPTS_FOR_LRTB_LAYOUT = 2 (template.js:117), ERROR = 2 (layout.js:275), DEFAULT_TAB_INDEX = 5000 (template.js:126). lr-tb has exactly two passes — attempt 0 puts the child on the current line, attempt 1 starts a new one, and there is no third option.

(vii) The spec is admitted to be wrong or unclear, and the code follows real files

// html_utils.js:115-116
// IRL, we've some x/y in tb layout.
// Specs say x/y is only used in positioned layout.

// template.js:5384-5387
// Spec is unclear:
//  A container element that describes a single subform capable of
//  enclosing other containers.
// Can we have more than one subform ?

There are 28 TODO comments in template.js, 10 of them the bare // TODO: incomplete. on a $toHTML method — including the two that matter most: Subform[$toHTML] (template.js:5046) and PageArea[$toHTML] (template.js:4082). Others: Area (597), Caption (1196), ChoiceList (1417), ContentArea (1571), DateTimeEdit (1704), NumericEdit (3854), TextEdit (5802). SubformSet carries // TODO: need to handle break stuff and relation. (template.js:5274).

(viii) hAlign: "radix" — decimal-point alignment — is not implemented at all

// html_utils.js:150-152
case "radix":
  // TODO: implement this correctly !
  style.textAlign = "left";

(ix) Font matching is a heuristic cascade that admits guessing

FontFinder.find (fonts.js:82-152) normalizes names with /[,\-_ ]|bolditalic|bold|italic|regular|it/gi (fonts.js:88), then strips PostScript suffixes with name.replaceAll(/psmt|mt/gi, "") (fonts.js:118), and when several candidates survive:

// fonts.js:141-144
warn(`XFA - Too many choices to guess the correct font: ${fontName}`);
this.cache.set(fontName, maybe[0]);
return maybe[0];

The substitution ladder is hard-coded: Helvetica, then Myriad Pro, then Arial, then a stub with size: 10 and typeface: "Courier" (text.js:55-83), with // TODO: Add a default font based on Liberation. at text.js:56.

(x) The flexbox we have to write and pdf.js does not

Named in §1(a). Two concrete instances of pdf.js getting placement for free:

• Row height equalization. addHTML for row/rl-row rewrites every sibling's CSS height as each new child lands:

  // layout.js:137-141
  extra.height = Math.max(extra.height, h);
  const height = measureToString(extra.height);
  for (const child of extra.children) {
    child.attributes.style.height = height;
  }

  In a geometric engine this becomes a genuine second pass over the row.

• Border geometry is expressed as CSS calc() with half-widths (html_utils.js:426-443), e.g. width = `calc(100% + ${(widths[1] + widths[3]) / 2 - insetsW}px)`, and the wrapper/border pair is built by createWrapper (html_utils.js:404-511), which hoists a hand-maintained list of 13 CSS property names onto the wrapper (html_utils.js:480-494). All of that is ours to resolve numerically.

(xi) A unit trap worth writing down now

measureToString (html_utils.js:35-41) silently collapses any string to "0px":

function measureToString(m) {
  if (typeof m === "string") {
    return "0px";
  }
  return Number.isInteger(m) ? `${m}px` : `${m.toFixed(2)}px`;
}

It relies on every caller having already run getMeasurement. XFA's "" (meaning "unspecified") is a string and lands here as 0px by design; a real "3in" that slipped through lands here as 0px by accident. In Go with a Measure float64 we do not have the sentinel "", so we need an explicit "unspecified" — an (Measure, bool) or a *Measure. Getting this wrong is silent.

---

6. What a first useful slice would be

Static geometry, one page, position layout only, no splitting, no measurement.

1. Expand the form tree by occurrence — step 3(a). Unavoidable, and it is the piece we are closest to (occurInfo and bindOccurrences already exist in bind.go). Output a cloned *Node tree rather than []Binding; keep Bind as it is for callers that want values.
2. Read the page box from pageArea/medium (template.js:4091-4109, including the landscape swap) and the content area from contentArea x/y/w/h (template.js:1554-1568). Both are literal measurements; measureOr already reads them, and template_test.go:57 already proves it on a real file.
3. Walk only position subforms, emitting absolute boxes for draw and field from their literal x/y/w/h, through getTransformedBBox (layout.js:202-259) for anchorType and rotate.
4. Draw borders and static draw text; place bound field values as plain text in the field box.
5. Output []Page of positioned boxes — something go-pdfkit/render can already draw.

What it deliberately excludes: every flow layout (tb, lr-tb, rl-tb, table, row), and therefore all of layout.js; all splitting and $extra/generator resumption; all breaks, leaders, trailers and overflow; the $toPages loop beyond one pageArea and one contentArea; text measurement, and hence any element with an empty w or h (skip it and count it); captions with reserve <= 0 (template.js:1209-1223); rich text; and every ui widget appearance.

Why it earns its place anyway. It makes the fourteen dynamic forms produce something visible and diffable against Adobe, and it forces us to build the expanded form tree — the true prerequisite, and the thing our binder currently and deliberately declines to build.

The first number it should produce is a measurement, not a picture: of the fields in those fourteen forms, how many sit under a position subform with a literal w and h? If that number is small, we learn early — for the price of a week rather than a quarter — that text measurement (§3(c), §5(i)) is not deferrable and that the flexbox layer (§5(x)) is the real project.

---

What I could not determine

• How large the flexbox-substitute layer is. pdf.js never writes it, so there is no evidence in this codebase to size it from. It is the one figure in §2 with nothing behind it.
• Whether px should be 1pt (pdf.js) or 72/96 (ours). Both are assertions; neither codebase cites the spec.
• Whether WIDTH_FACTOR = 1.02 compensates for something specific (kerning? the dropped break space?) or is a fitted constant. No comment, no commit message reachable from the line.

[tannevaled]

Correction, read directly rather than delegated

[2026-09-03 16:54:30 CEST], against pdf.js 9785821.

I re-read the load-bearing claims above myself. Three hold exactly. One is too strong, and the nuance decides the plan.

fixDimensions does not discard coordinates unconditionally

The reading above says "fixDimensions literally discards coordinates". The line is conditional — html_utils.js:347:

if (parent.layout && parent.layout !== "position") {
  // Useless in this context.
  node.x = node.y = 0;
}

Coordinates are discarded only under a flow layout. Under position they survive.

And under position, pdf.js does compute geometry

html_utils.js:112-123, the position converter:

position(node, style) {
    const parent = node[$getSubformParent]();
    if (parent?.layout && parent.layout !== "position") {
      // IRL, we've some x/y in tb layout.
      // Specs say x/y is only used in positioned layout.
      return;
    }
    style.position = "absolute";
    style.left = measureToString(node.x);
    style.top = measureToString(node.y);
}

It emits an absolute placement from node.x/node.y. Flexbox is the delegate for flow layouts (tb, lr-tb, table) only.

Why this changes the risk, not just the wording

The reading above states the main unsized risk as: a Go engine drawing to a PDF page must additionally write the flexbox subset pdf.js never writes — invisible in pdf.js's line count, and it could not be sized.

That is true for flow layouts. It is not true for position, where pdf.js writes the placement and is therefore a complete reference to follow rather than a gap to invent. So the recommended first slice — position-only — is on much better footing than the paragraph implies: the part with no reference is precisely the part the first slice excludes.

The corollary is less comfortable and worth stating: the unsized work has not gone away, it has been located. It is the flow layouts, and it arrives in full the moment the slice widens past position.

Confirmed as written

• layout.js is not the engine. layout.js:27 — "Subform and ExclGroup have a layout so they share these functions." 387 lines against template.js's 6603.
• measure.pushFont is called and never defined. xhtml.js:377 and :467 call it; src/core/xfa/ defines only pushData (text.js:104, :157). Rich-text measurement with <b> or <i> throws. Worth not copying.
• The file sizes: layout.js 387, template.js 6603, html_utils.js 653, xfa_object.js 1091.

One note on method, since it applies to this issue as much as to the code: the delegated reading was good and the correction is small, but it was found only by opening the two cited lines instead of trusting the sentence that cited them. The citation was accurate; the summary built on it was not.

[tannevaled]

The measurement: how far a position-only engine reaches

[2026-09-03 17:06:00 CEST]. Counted over the 560 template+datasets pairs, 0 unparsed. Counter at /Users/Shared/xfacount/count.py, outside every work tree — it is a measuring instrument, not something this library should carry.

	fields	position + literal w/h	flow layout	needs measurement
whole corpus (560 forms)	82 386	70 297 — 85.3%	11 643 — 14.1%	446 — 0.5%
repeating-occur forms (64)	26 659	21 977 — 82.4%	4 493 — 16.9%	189 — 0.7%

The defaults I assumed, each read from pdf.js rather than guessed

• A subform with no layout attribute counts as position. template.js:2333 and :4833 pass the option list to getStringOption beginning with "position", and an absent attribute yields the first entry.
• The discriminator is the enclosing subform's layout, not the field's. html_utils.js:112-123 — position(node, style) consults node[$getSubformParent]().layout and returns without emitting a placement unless it is position.
• "Literal w/h" means a number with an optional unit (in|mm|cm|pt|pc|px). A percentage, an expression, or an absent value counts as needs measurement.
• The template root is treated as position.
• I did not use /NeedsRendering to pick the dynamic set — these are extracted templates with no document around them. The second row is forms carrying an occur that can repeat, which is the shape that actually forces a layout engine to duplicate containers. That is my definition, not the earlier "fourteen dynamic forms", and the two are not the same set.

What it means for the plan

A position-only slice reaches 85.3% of the corpus, and 82.4% of the forms that genuinely need an engine. The two populations agree, which is the reassuring part — the repeating forms are not a different world, they are the same world with 3 points more flow.

So the slice is worth shipping on its own, and — with the correction above — it has a complete reference to follow: under position, pdf.js emits absolute left/top from node.x/node.y rather than delegating to flexbox.

Text measurement is not the project. 446 fields corpus-wide, 0.5%, need it. That was the suspicion this measurement existed to test, and it is wrong by two orders of magnitude.

The real remainder is flow layout: 11 643 fields, 14.1% — and it is concentrated rather than spread. us-irs__f3800 alone accounts for 1 872 of them, 16% of all flow fields in one form; the top three forms hold 27%. A dozen large tabular IRS forms, not a diffuse tail. That concentration is worth knowing before the second slice is scoped: it may be cheaper to make a handful of table-heavy forms work than to make flow layout general.

[tannevaled]

The first slice is in #8, and its number is not the one predicted

[2026-09-03 18:36:28 CEST]

13 331 of the 82 386 corpus fields placed, against the 70 297 the measurement predicted. The disagreement is the finding, so it goes first.

What the measurement did not model

The count above asked: is the field's immediately enclosing subform positioned? That is exactly what converters.position asks before it emits style.left/style.top (html_utils.js:112-123), so the count was right about what it counted. It is a different question from can a position-only engine say where this is on the page, because a field's place is the sum of its ancestors' places, and the chain has to be positioned all the way up.

556 of the 560 outermost subforms are laid out tb. Counted strictly — every container from the content area down to the field imposing position — only 120 of 82 386 fields have an unbroken chain. Almost every positioned subform hangs below a flow one, and where a flow layout puts its second child is the height of its first, which is the flow layout itself.

The two counts reconcile exactly: 70 297 − 56 966 that turn out to have a flow ancestor after all + the 8 fields binding drops where occur allows nought and no data arrives = 13 331 placed, 69 047 reported unplaced.

Why 13 331 and not 120

One part of the flow rule is exact rather than approximate, and it is worth writing down because it is what makes the slice reach a real form at all:

pdf.js accumulates from nought. extra.height starts at 0 and the first child is pushed before anything is added to it (layout.js:145-160), and fixDimensions zeroes the child's own coordinates (html_utils.js:347-350). So the first child of a tb, table, lr-tb or row container sits at the container's own origin — the flow algorithm's own answer for one child, not an approximation.

rl-tb and rl-row fill from the right, which needs a width, so they are excluded.

The check, and what it is blind to

judge.mjs (at /Users/Shared/xfajudge/, outside every work tree) drives pdf.js's own XFAFactory over each template+datasets pair and walks the HTML it emits, accumulating left/top down the chain of positioned ancestors and resolving the CSS transforms pdf.js writes for anchorType and rotate. TestPlacementAgainstPdfjs pairs its boxes with ours by kind and name.

boxes paired	21 933
agree to within 1/100 pt	21 881	99.76%
differ only by pdf.js's own two-decimal rounding	47	0.21%
disagree	5	0.02%

All five differ in width only, never in place, and all five are colSpan cells taking their width from the parent table's columnWidths rather than their own w (html_utils.js:81-111).

anchorType and rotate are the strongest part: pdf.js emits them as a CSS transform with percentage translations, we port getTransformedBBox. The two agree on their arithmetic rather than on a shared formula.

The check's largest hole is the same as the slice's: pdf.js hands flow layouts to the browser's flexbox and emits no coordinates for them, so it and we are blind in the same place. Where we report a field unplaced under a flow layout, pdf.js has nothing to compare it with. This cannot be closed with pdf.js as the judge.

It also could not run on 77 of the 560 forms. 70 fail at fonts.js:159, where selectFont dereferences a null typeface — on the very path getMetrics at :173-179 says it handles. 7 fail with RangeError: Maximum call stack size exceeded, recursing between PageSet[$getNextPage] (template.js:4176-4236) and PageArea[$getNextPage] (:4061-4075). The second is a genuine defect on real files, and it is the page machinery step (f) of the plan above.

What the next slice is worth, measured

The reading called flow layout "the real remainder, 11 643 fields, 14.1%, concentrated in a dozen tabular IRS forms". That was right about the concentration of table, and wrong about the size: flow is where 68 891 of our unplaced fields are, and it is tb on the outermost subform of nearly every form, not a tail.

The cheap part of it is measurable without building it. Stacking tb and table children over literal heights — arithmetic on numbers already in the template, no text measurement — takes the reach from 13 331 to 62 973 of 82 304. So:

• ~49 600 fields are behind nothing harder than adding up heights that are already written down;
• the remaining ~19 300 are where a container's height is genuinely absent, and that is where text measurement stops being 0.5% of the problem.

Two decisions settled

px is not an XFA unit. The authority is pdfium's CXFA_Measurement (xfa/fxfa/parser/cxfa_measurement.cpp, GetUnitFromString) — Foxit's implementation, the one closest to Adobe's own. Its list is mm, pt, in, cm, pc, mp, em, %, and px is not on it. pdf.js's 1pt and our 72/96 were both HTML habits; choosing between two inventions is not a decision. A length in px is now refused and the element reported unplaced. No x/y/w/h in the corpus is written in it. The same reading added mp, a real XFA unit neither implementation had.

measureOr did not survive contact with a real caller. It answers two ways where layout needs three, so it is gone: Node.Measure(name) (Measure, bool, error) says absent, or a length, or written and unreadable. A field with no width has no width until its text is measured, which is not the same as a field nought wide. ParseMeasure survived unchanged.

[tannevaled]

Correction: my measurement above was wrong, and here is the mistake

[2026-09-03 18:38:30 CEST]

I published "a position-only slice reaches 85.3% of the corpus" two comments up. The slice reaches 13 331 of 82 386 fields, not 70 297. The implementation found it, and the fault is in my counting, not in the implementation.

What I counted: is the field's immediately enclosing subform positioned? That question is exactly what converters.position asks (html_utils.js:112-123), so it was a faithful reading of the reference.

What I should have counted: can a position-only engine say where this is on the page? A place is the sum of its ancestors' places, and the chain has to be positioned all the way up. 556 of the 560 outermost subforms are tb. Counted strictly, only 120 fields of 82 386 have an unbroken position chain.

The two reconcile exactly: 70 297 − 56 966 with a flow ancestor after all + 8 dropped by binding (occur min 0, no data) = 13 331 placed, 69 047 reported unplaced with reasons.

It reaches 13 331 rather than 120 because one part of the flow rule turns out to be exact rather than approximate: extra.height starts at nought and the first child is pushed before anything is added to it (layout.js:145-160), so the first child of a tb/table/lr-tb/row container sits at the container's own origin. That is arithmetic, not a guess. rl-* fill from the right and are excluded.

Why I got it wrong, since the shape of the error is the useful part

I asked a question about one node where the plan needed a question about a chain. The reading it came from was accurate — I verified the two cited lines myself — and the count faithfully implemented what I read. A correct answer to the wrong question survives every check you can make on the answer, and no amount of re-reading html_utils.js would have caught it. Only building the thing did.

It is the same failure this project has now met a dozen times in instruments: a measure that is blind in the direction it is trusted for. This is the first time it appeared in a measure I wrote and published myself, and it shaped the plan for a day.

What it changes for slice 2, which is better news than the correction

Stacking tb/table children over literal heights — adding up numbers already written in the template, no text measurement — takes the reach from 13 331 to 62 973. So roughly 49 600 fields sit behind nothing harder than arithmetic on written-down heights.

The ~19 300 after that are where a container's height is genuinely absent, and that is where text measurement stops being 0.5% of the problem. My earlier "flow is 14.1%, a dozen tabular IRS forms" was right about table's concentration and wrong about the size: flow is tb on nearly every form's outermost subform.

[tannevaled]

Slice 2 is in #9, and its number is 15 400 rather than 62 973

[2026-09-03 19:16:05 CEST]

15 400 of the 82 378 expanded corpus fields placed, against the 62 973 the last comment predicted. Slice 1 placed 13 331. The disagreement is the finding, so it goes first — and it is the same shape of error as the one corrected two comments up, in a different place.

Text measurement is not half of one per cent. It gates half the corpus.

The measurement above found 446 fields — 0.5% — whose own w or h only text measurement could give, and concluded "text measurement is not the project". Counted over the leaves, that number holds: of the corpus's ~234 000 fields and draws, only 8 466 draws and 598 fields write no height, plus 955 draws writing h="=0mm", which is not a length. Under four per cent.

A stack is a chain. Where the second child of a tb begins is the height of the first, so one child whose height cannot be said leaves every sibling below it in that container with nowhere to begin. Under four per cent of the leaves hold up 40 435 fields — half of them. Each carries the reason:

40 247  a tb layout stacks its children, and the height of the one above it is
        not computed: the template does not write its height, which only
        measuring its text would give

The earlier count asked whether a field needs its text measured. What decides a stack is whether anything above it in the same container does — and most of what is in a stack is draw, which the count did not look at. 142 566 draws write a literal height and 8 466 do not, and the 8 466 are enough.

Pagination is the other wall

21 094 fields have a place computed for them and fall past the bottom of the one content area this slice lays out. Placed plus those is 36 494, which is how far the arithmetic reaches on the heights available. pdf.js does not refuse them — it fails the container and carries what is left onto the next page (template.js:5502-5600). That is step (f) of the plan, and it is now the biggest thing between here and a whole form.

The rule that would have reached 62 973, measured and rejected

Taking a container's written height as its height, rather than the taller of that and its contents, computes a place for 80 821 of the 82 378 fields. That is plausibly the rule behind the estimate, and it was measured rather than argued about.

It is not pdf.js's rule. Subform[$toHTML] ends

const height = Math.max(this[$extra].height + marginV, this.h || 0);   // template.js:5222

A container is as tall as what it holds even where the template writes a height. Over the 2 323 containers where both quantities can be had, the written height is the wrong one 63 times, by 14 pt on average. Reaching further by guessing is not reaching further. It would not even have reached further on one page: under that rule only 14 410 fields land, fewer than the 15 400, because more of the stack advances and so more of it runs off the bottom.

The check, and why slice 1's could not be it

judge.mjs is blind to exactly what this slice computes. pdf.js emits no coordinates for a child of a flow layout: it writes them into a display: flex; flex-direction: column div (web/xfa_layer_builder.css:255-263) and lets the browser stack them. Slice 1's 21 933-box comparison worked only because slice 1 placed nothing but first children, which sit at the container's origin. It does not carry over.

pdf.js does emit the accumulation itself, as a number, in one place: a subform's style.height is Math.max(extra.height + marginV, this.h || 0), hoisted onto the wrapper by createWrapper (html_utils.js:480-494), and extra.height is the sum this slice computes. So the judge now dumps container heights too:

container heights this package computes, paired with pdf.js's	7 072
agree to within 1/100 pt	7 072	100.00%
disagree	0	0.00%
more paired but written outright in the template — no check in agreeing	3 736
this package cannot measure, so has no number to compare	2 264

Thirteen disagreed before the check accounted for one rule, and the rule was pdf.js's rather than a defect of ours: a row writes its own height back over every cell already placed (layout.js:135-143), so what pdf.js emits for a cell is the row's height and not the cell's. Comparing our row height with it checks the stretch instead.

The dump now flags each box flowed, so the placement check cannot mistake a container's origin for an element's place. Of the 23 540 boxes pdf.js placed by flexbox, what can be said is one-sided and worth saying: none came out above or to the left of the container it belongs to, and 21 459 sit exactly at that container's origin. 199 boxes remain where pdf.js emits a real place; all 199 agree.

What it does not cover. Where inside a container the children ended up: two orderings of the same children come to the same total, and a height cannot tell them apart. So the ORDER of a stack is unchecked, and pdf.js cannot check it. Nor borders and insets on positioned layouts; nor text measurement; nor anything under a rotated ancestor. Still 77 of the 560 forms it cannot run on, for the two pdf.js defects named above.

One thing settled along the way

presence is not decoration. A hidden or inactive child takes no room at all — pdf.js returns HTMLResult.EMPTY and $childrenToHTML never reaches the accumulator (xfa_object.js:410-418), so the child after one moves up into its place. invisible keeps its room. 1 187 containers and leaves in the corpus carry one of the three; a stack that ignored them would put everything below one in the wrong place. The box is still reported, carrying a new Box.Hidden, because nothing is dropped.

What the next slice is worth

Not a guess this time, but the two reasons above, counted:

• Text measurement: 40 435 fields wait on it, and it needs a font stack this module does not have (go.mod has no dependencies).
• Pagination: 21 094 fields wait on it, and it needs only the page loop over content areas — PageSet[$getNextPage] (template.js:4176-4236), where one of the two pdf.js defects also lives.

Pagination is the cheaper of the two and does not need a single glyph.

[tannevaled]

I made the same mistake twice, and it is worth naming as a pattern

[2026-09-03 19:18:00 CEST]

Slice 2 places 15 400 fields against the 62 973 I predicted. Slice 1 placed 13 331 against 70 297. Both predictions were mine, both were wrong, and both failed the same way.

Slice 1. I counted is the field's enclosing subform positioned? The answer needed was can we say where this is on the page? — and a place is the sum of its ancestors' places.

Slice 2. I counted how many fields write no height? — 446, 0.5%, and I concluded text measurement was not the project. The answer needed was how many fields sit in a stack where something above them writes no height? — because where a tb's second child begins is the height of the first. Only ~4% of leaves write no height, and those leaves hold up 40 435 fields, half the corpus.

Worse, my count looked only at field. Most of what sits in a stack is draw, and I never counted those at all: 8 466 draws write no height, against 598 fields.

The pattern, in one sentence: I asked a question about a node where the structure is a chain. Twice. The reading behind each count was accurate and I verified the citations myself both times. A correct answer to the wrong question survives every check you can make on the answer — which is exactly why it took building the thing to find it, twice.

What actually blocks the remaining fields, now counted properly

	fields
placed	15 400
place computed, falls past the bottom of the content area — pagination	21 094
held up by a leaf above them with no written height — text measurement	40 435

Arithmetic alone reaches 36 494. Pagination needs no glyphs; text measurement needs a font stack this module does not have. That is the real fork, and it was invisible in my 0.5%.

The rejected hypothesis, measured rather than argued

Where did 62 973 come from? Taking a container's written height instead of max(contents + margin, written) computes a place for 80 821 fields — close to my figure. It is not pdf.js's rule (template.js:5222), and over the 2 323 containers where both quantities exist the written height is wrong 63 times, by 14 pt on average. It would not even place more on one page — 14 410 against 15 400 — because more of the stack advances, so more of it runs off the bottom.

A judge where I said there was none

I told slice 2 that its external control could not see it: pdf.js delegates flow layouts to flexbox and emits no coordinates. That was true of positions and I stopped there.

pdf.js does emit the accumulation as a number — a subform's style.height is Math.max(extra.height + marginV, this.h || 0). So the check became container heights rather than box positions: 7 072 computed, 7 072 agreeing to within 1/100 pt, 0 disagreeing. Thirteen disagreed until the check accounted for pdf.js's row-stretch (layout.js:135-143) — its rule, not our defect.

Uncovered, and stated: the order within a container (two orderings sum alike, and no height distinguishes them — pdf.js cannot check this either), borders and insets, text measurement, rotated ancestors, and the 77 of 560 forms pdf.js itself crashes on.

[tannevaled]

Slice 3 is in #10, and its number is 29 123 rather than 36 494

[2026-09-03 21:54:41 CEST]

29 123 of the 81 750 body fields placed, on 1 237 sheets, against the 36 494 the last comment's arithmetic predicted. Slice 2 placed 15 400. The disagreement goes first.

The one-page bound was masking text measurement

Slice 2 reported 21 094 fields with a place computed that fell past the bottom of the one content area it laid out, and concluded the arithmetic reaches 36 494 once the page turns. It reaches 29 123. Counted field by field against slice 2's own dispositions, of those 21 094 (20 736 by distinct path):

what became of a field that fell past the bottom
placed, once the sheet turned	14 077 — 68%
held up by a leaf above it with no written height, further down the same stack	5 156
taller than a whole content area, and cannot be broken	885
the form ran out of pages	405
no room inside a container that moves whole	167
other	46

A field reported "past the bottom" was one whose place had been computed on the assumption that everything above it on that page had a height. Once the page turns and the stack goes on past the cutoff, a quarter of them turn out to sit below a leaf that writes none. The 40 435 waiting on text measurement are now 44 246.

It is the same shape as the two errors above: a question asked about one node — does this one's place fall past the bottom? — where the structure is a chain. Third time, in a third place. The first two were counts over the templates; this one was a count over the output of a working implementation, which is why I did not expect it to be the same mistake.

What blocks the rest, counted properly

	fields
placed	29 123
waiting on a height only measuring text would give	44 246
a height written as =0mm, which is not a length	3 649
under lr-tb, which wraps onto lines	3 124
a place computed and nowhere left to put it	1 608

Pagination is spent. Text measurement is now 84% of what is left, and it needs the font stack go.mod still has no dependency for.

A judge that can see pagination, as asked

pdf.js emits one <div class="xfaPage"> per sheet with every element inside the one it belongs to. That is said outright in the structure of its output rather than in a style, so page count and per-page membership are comparable even where a coordinate is not. It has to be narrowed to the forms where every element of the body was placed — pdf.js measures text and this does not, and more elements need more sheets — and the direction of the disagreement is reported for the rest, because needing MORE sheets while placing FEWER elements would be a defect and not a shortfall.

forms where this package placed every element of the body	199
of those, agreeing with pdf.js on the number of sheets	198	99.5%
boxes paired on those forms	23 006
on the same sheet as pdf.js put them	23 006	100.00%
on another sheet	0	0.00%
forms where fewer elements were placed, and so fewer sheets	221
... the same number of sheets	63
... MORE sheets, which would be a defect	0	0.00%

Slice 1's and slice 2's checks still hold on the much larger box population this places: 7 072 of 7 072 container heights agree to 1/100 pt, 450 of 450 boxes where pdf.js emits a real place agree exactly, and of the 51 312 it placed by flexbox, none came out above or to the left of its container.

The one disagreement is not pagination. us-opm__sf813's outermost subform is positioned, and pdf.js's checkDimensions position arm (layout.js:355-364) sends children reaching past the bottom of the content area onto a second sheet. This package does not fit-check a positioned layout at all — it did not in slice 1 either — so it draws them off the bottom of the one sheet.

What the judge does not cover: where inside a container the children ended up; borders, insets and margins on positioned layouts; text measurement; anything under a rotated ancestor; breaking one container in two; and the 77 of 560 forms pdf.js cannot lay out.

The recursion pdf.js dies on is not in the branch it looks to be in

The issue above says pdf.js exhausts its stack on 7 forms recursing between PageSet[$getNextPage] and PageArea[$getNextPage], and names the branch:

this[$cleanPage]();
return this[$getNextPage]();

$cleanPage (template.js:4160-4167) clears the [$extra] of every page area and page set below the set and not the set's own, so the call returns to state no different from the state it left. I ported the machine with a guard on exactly that branch, and it overflowed the stack on the corpus anyway, at ca-cra__t183corp-fill-24e.

The branch above it does the same thing. A page set whose <occur> still allows another run resets its own indices and calls itself (:4193-4198), and comes back to the same place when every page area below it has spent its own <occur>. So the shape to guard is every way a page set can start itself again, not the one named after cleaning. Three rules, and the machine terminates on the seven forms pdf.js dies on:

• a page set may restart at most once per request for a page;
• cleaning resets the set's own place in its list as well as its children's, which is what the name says;
• a page set holding neither a page area nor a page set says there is no next page rather than looping.

Reading the branch named in the issue was not enough to find the second one. Only running the port over the corpus was, and it announced itself as a one-gigabyte stack in this package's own test binary.

A second crash of my own in the same area, worth recording because it is a shape rather than a typo: first() dereferenced a nil page set when a break named, by id, a page area of a second page set. #id searches the whole form; p.index had walked only the first page set, so the chosen page area had no parent recorded. Every page set under the outermost subform is indexed now, and a page area outside every page set is a sheet the form can start on with nothing after it.

Two smaller things settled by measurement

A sheet is empty when the BODY did not reach it, and a container with nothing drawn in it counts as reaching it. pdf.js's test is hasSomething ||= html.children?.length > 0 on what the body returned for a content area (:5545, :5568), so a subform holding only more subforms keeps the sheet. My first rule counted drawn boxes. Thirty-eight fr-cerfa forms carry a break onto a last sheet whose only content is an empty subform; matching pdf.js's rule moved sheet-count agreement from 161/199 to 198/199 in one change.

Nineteen fields across five forms are now unplaced that slice 2 placed. Each is after a <breakBefore startNew="1"> on a form whose one page area has <occur max="1"/>: the template says "start a new sheet here" and the page set says there is no second sheet. Slice 2 did not read breaks and stacked them on sheet one, contradicting the template without saying so; this reports them. Four of the five forms are among the seven pdf.js crashes on, which is the same contradiction reaching pdf.js as an infinite loop.

What the next slice is worth

• Text measurement: 44 246 fields, and a font stack this module does not have.
• Breaking one container across a sheet: pdf.js keeps [$extra].children, a generator and a failingNode for it (layout.js:38-53). Worth 1 052 fields — the 885 taller than any content area plus the 167 with no room inside one that moves whole.
• Fit-checking a positioned layout, which slice 1 never did: one form of 199, and the only sheet-count disagreement left.

[tannevaled]

Slice 4 is in #11, and 44 246 fields waiting on text measurement is not 44 246 fields that measuring it places

[2026-09-03 22:58:27 CEST]

54 708 of the 81 750 body fields placed, on 2 268 sheets. Slice 3 placed 29 123. The disagreement goes first, and this time it reconciles to the field.

Measuring the text places 25 585 of the 44 246, and the other 18 661 were behind it

The last comment said text measurement was 84% of what was left — 44 246 fields — which was a faithful statement of what was blocking them at that moment. It is not the same statement as "measuring the text places 44 246", and the gap is exact:

where a field that was waiting on text measurement ended up
placed	25 585
below a height written as =0mm, which is not a length	13 287
a place computed and nowhere left to put it	4 186
under lr-tb, which wraps its children onto lines	1 179
anchored by a corner, with no size of its own	9

25 585 + 18 661 = 44 246, to the field. Every blocker that grew, grew because it was behind the wall: a field below an unmeasurable leaf was reported for the leaf, and is now reported for whatever is genuinely in its way.

It is the node-versus-chain shape a fourth time, in a fourth place. The first two were counts over templates, the third a count over an implementation's output, and this one is a count of dispositions — which is the closest thing to ground truth this project has, and it still says less than it looks like it says. "N fields wait on X" is a statement about the FIRST blocker in each chain. It is not a prediction of what fixing X places, and no amount of care in producing it would make it one.

The regime has no font stack, and that is not a simplification

go.mod still has no dependencies. pdf.js's no-font fallback is written down, exact, and — because judge.mjs calls setFonts([]) — the regime the reference itself runs in over the whole judged corpus, so the two sets of numbers are the same numbers rather than merely comparable ones.

• TextMeasure.addString with no font (text.js:211-219): one em per character, a line 1.2 ems tall, a first line one em. So n lines is 10 + 12(n−1).
• getMetrics with no font (fonts.js:173-179): { lineHeight: 12, lineGap: 2, lineNoGap: 10 }, and a field with nothing to measure takes lineNoGap for its widget (template.js:2821).

The template's font size is discarded, and that is pdf.js's doing rather than a shortcut of ours. FontInfo asks the finder for the typeface (text.js:42) and, not having it, replaces the whole of xfaFont with the default's (:43-46, 55-83) — Courier, size 10, letter spacing 0. So <font size="8pt"> on a draw, font-size:14pt in a span's style, and line-height are all inert here. A measurement that honoured them would disagree with the reference on nearly every leaf, and the disagreement would look like a defect of ours.

Real advances are glyph.w filled from a face, and they belong in go-opentype/opentype. Nothing above that line moves.

Two things decided the agreement, and neither is about fonts

The last no-break space of a run becomes an ordinary one — in ALL text, not only rich text. XFAParser.onText (parser.js:60-73) is every text node of an XFA document, and its comment says why: "normally by definition a &nbsp is unbreakable but in real life Acrobat can break strings on &nbsp". Line 2 of Form AB(S11) in a 63-point column is four lines with the space and three without. Applied only inside rich text it left 31 container heights disagreeing, every one of them a table cell of a ca-cra or us-irs form; applied everywhere the check went to 7 758 of 7 758.

A leaf whose text gives no height is not left unmeasured. computeBbox (html_utils.js:290-324) runs on every draw and every field before it returns and fills the height in from minH — or from nought under a positioned parent that writes a height of its own — and the container above stacks that. 7 475 of the 8 466 unsized draws write a minH. The one case refused here is maxH above nought, where pdf.js answers with the ROOM the leaf has: a height is arrived at before the room it will go in is known, and no corpus leaf that needs it writes one.

Rich text needed the markup kept in order — 32 109 of the corpus's <p> elements hold text both before and after a <span> — and its whitespace normalised run by run the way pdf.js normalises it: newline removed, spaces collapsed unless xfa-spacerun:yes, which 44 099 spans write.

Two defects of the reference, not copied. selectFont (fonts.js:155-163) dereferences the typeface before the test that would have returned the constants getMetrics documents at :173-179 — the line this slice needed is the one pdf.js dies on, on 70 of 560 forms. And <b>/<i> call measure.pushFont (xhtml.js:377, 467), which TextMeasure does not have, so a rich text carrying either throws; no unsized leaf of the corpus writes one.

The judge, extended — and one thing it had been doing wrong

It was pairing boxes by the element's own name. That holds only while the two sides list the same names in the same order, and it stopped holding here: us-irs__fw9 has six subforms called Bullet1, in three lists on three sheets. While most of them had no height they were never compared; once they all had one they became six entries of one list with nothing making pdf.js's order and ours line up. Pairing on the whole chain of names turns a mispairing into an unpaired box rather than into a disagreement.

It is not a cosmetic change. Unpairable fell from 8 090 to 5 133, and 2 139 boxes moved out of the "pdf.js emits a real place" column into the "pdf.js placed it by flexbox" one, where they belong — which is to say the older checks were reporting agreement on 2 139 comparisons that were not comparisons.

container heights
heights this package computes, paired with pdf.js's	7 758
agree to within 1/100 pt	7 758	100.00%
disagree	0	0.00%
more paired but written outright in the template — no check in agreeing	5 136
this package cannot measure, so has no number to compare	192

where the boxes went
boxes where pdf.js emits a real place	176
agree exactly	176	100.00%
boxes pdf.js placed by flexbox	117 813
... at the flow container's own origin, where a first child goes	115 498
... below or to the right of it, where the rest go	2 315
... above or to the left of it, which would be outside it	0	0.00%

which sheet they went on
forms where this package placed every element of the body	357
of those, agreeing with pdf.js on the number of sheets	354	99.2%
boxes paired on those forms	89 334
on the same sheet as pdf.js put them	89 334	100.00%
on another sheet	0	0.00%
forms placing fewer elements, and so using MORE sheets — a defect	0	0.00%

The comparable subset is the whole judged corpus, because judge.mjs calls setFonts([]) and pdf.js therefore takes the same one-em fallback we do. The three sheet-count disagreements are not text and not pagination: two have a positioned outermost subform, whose fit-check this package has never done (layout.js:355-364).

What it does not cover. Where inside a container the children ended up — two orderings sum alike, and pdf.js cannot check this either. Borders, margins and insets on positioned layouts. Anything under a rotated ancestor. Breaking one container in two across a sheet. And real per-glyph advances: neither side has them, so the check is blind to them in both directions, and a form whose fonts a caller does supply is not checked at all by this. Still 77 of the 560 forms it cannot run on.

What is left, and it is not text

	slice 3	slice 4
placed	29 123	54 708
waiting on a height only measuring text would give	44 246	0
below a height written as =0mm	3 649	16 936
a place computed and nowhere left to put it	1 608	5 794
under lr-tb	3 124	4 303
anchored by a corner, with no size of its own	0	9

h="=0mm" is now the largest single thing between here and a whole corpus. pdf.js reads it as nought — getMeasurement's pattern /([+-]?\d+\.?\d*)(.*)/ is unanchored and finds the 0mm inside it (utils.js:83-87) — so the reference places every one of these. Whether that is Adobe's rule or an accident of a regular expression is a reading of pdfium's CXFA_Measurement, the way px was settled, and not a guess for this slice.

After it: the 5 794 with nowhere to put them, most of which want a container broken across a sheet; lr-tb, which wants a real line-breaking layout and now has the text measurement it would need; and fit-checking a positioned layout, which is the last two sheet-count disagreements.

[tannevaled]

Slice 5 is in #12, and its number is 71 230 — 16 936 was not the prediction, 16 522 is the answer

[2026-09-03 23:24:24 CEST]

71 230 of the 81 750 body fields placed, on 2 737 sheets. Slice 4 placed 54 708. The disagreement goes first, and it reconciles to the field.

=0mm blocked 16 936 and removing it places 16 522

You said it: 16 936 is the count of fields whose first blocker was =0mm, not a prediction of what removing it places. Counted field by field against slice 4's own dispositions:

what became of a field whose first blocker was =0mm
placed	16 687
taller than a whole content area, and cannot be broken	249

189 fields that slice 4 placed are now reported unplaced. Each sits in a container whose height slice 4 could not compute, so the stack placed the child it had reached and stopped there — part of the container went onto the sheet. Now the container measures, and measures taller than a whole content area, which cannot be placed without splitting it across a sheet. 128 of the 189 are one form, us-opm__sf144a; the others are ca-cra__rc325-fill-26e (41) and ca-cra__rc343-fill-26e (20). This is the fourth slice in a row where the honest count went down somewhere as a wall came out from behind another one, and it is the first time the loss is of fields that were on the paper.

16 687 placed + 24 freed elsewhere − 189 reported = 16 522, and 54 708 + 16 522 = 71 230.

The rule is pdfium's, and pdf.js agreeing is worth little here

pdf.js places all 16 936 by accident — the unanchored pattern finds 0mm inside =0mm (utils.js:83-87). pdfium strips the = deliberately and parses the rest leniently (cxfa_measurement.cpp, SetString). Reading past SetString as you asked, the surrounding behaviour that had to be matched:

• FXSYS_wcstof skips ' ' and nothing else (fx_extension.cpp:41-45), so a tab stops the number before it starts;
• fast_float in general | allow_leading_plus: a number needs a digit but not one before the point, and an e with no digits after it rolls back to the mantissa rather than failing, because general is fixed|scientific — which is why ="5em" is five ems and not a syntax error;
• non-finite forced to nought;
• the unit is the whole tail, matched exactly and with its case (EqualsASCII; the unit tests assert CM, Cm, cM are unknown).

inf/nan need no case, and the doc comment says why rather than leaving it to be found: pdfium forces a non-finite value to nought, so it is nought points whatever unit follows, and not reading it leaves nought in an unknown unit — nought points as well. The two readings cannot differ.

An expression is not evaluated, and the doc comment says it is deliberate. ="Foo.h * 2" is nought under pdfium's rule, and nought is the reference's answer rather than a shortfall standing in for one.

Two answers part company with the ordinary reading and are named in the doc comment: a calculated number with no unit is nought (="5" is not five points, where "5" is), and the unit is case-sensitive. Both are pdfium's. Neither is written in the corpus — which writes exactly one calculated shape, h="=0mm", 955 times on 101 of the 560 forms, and nothing else with a leading = at all.

Checked against pdfium's unit tests rather than by agreement count

TestPdfiumsOwnMeasurementTests is cxfa_measurement_unittest.cpp run against this package — EqualsPrefix, NoPrefix, InvalidValues, and every GetUnitFromString case including the three that differ only in case. Where pdfium states a value and a unit and this reports points, the points are what the same measurement comes to inside pdfium, because TryMeasureAsFloat converts with ToUnit(XFA_Unit::Pt) (cjx_object.cpp:429-436). The single line that is not a port is marked as such.

The judge had a fault of its own, and it is slice 4's shape in a new place

Four draws of us-ssa__ss-5-ar-inst are written w="-0.106in" — a negative width — and became reachable for the first time here. The check called all four defects: boxes outside the container holding them.

They are not. A negative extent is not a box reaching left of where it was put: pdfium normalises a widget's rectangle before using it (CFX_RectF::Normalize, called at cxfa_fffield.cpp:293 and cxfa_ffwidget.cpp:288) and so does this package; pdf.js does not, because CSS cannot — it emits width:-0.11px, which a browser ignores. The judge was comparing our normalised left edge against pdf.js's unnormalised origin: the same box, counted two ways. Both sides are normalised now, in the flowed branch and in apart, and the count is 0.

Same lesson as the Bullet1 pairing: the fault was in the comparison and it announced itself as a disagreement about the subject.

The judges, on a population a third larger

container heights
heights this package computes, paired with pdf.js's	7 764
agree to within 1/100 pt	7 764	100.00%
disagree	0	0.00%
more paired but written outright in the template — no check in agreeing	5 289

where the boxes went
boxes where pdf.js emits a real place	176
agree exactly	176	100.00%
boxes pdf.js placed by flexbox	152 446
... at the flow container's own origin	149 488
... below or to the right of it	2 958
... above or to the left of it, which would be outside it	0	0.00%

which sheet they went on
forms where this package placed every element of the body	431
of those, agreeing with pdf.js on the number of sheets	428	99.3%
boxes paired on those forms	117 378
on the same sheet as pdf.js put them	117 378	100.00%
forms placing fewer elements and using MORE sheets — a defect	0	0.00%

The three sheet-count disagreements are the same three as slice 4 and are not this slice's: two have a positioned outermost subform, whose fit-check has never been done (layout.js:355-364).

What none of it covers, unchanged: where inside a container the children ended up; borders, margins and insets on positioned layouts; anything under a rotated ancestor; breaking one container in two across a sheet; real per-glyph advances, which neither side has. Still 77 of 560 forms pdf.js cannot lay out.

What is left

	slice 4	slice 5
placed	54 708	71 230
below a height written as =0mm	16 936	0
a place computed and nowhere left to put it	5 794	6 208
under lr-tb	4 303	4 303
anchored by a corner, with no size of its own	9	9

Breaking one container across a sheet is now the largest thing left — most of the 6 208 want it, and 4 214 of them are containers taller than a whole content area. lr-tb is next, and it has had the text measurement it needs since slice 4. Fit-checking a positioned layout is still the last two sheet-count disagreements.

Five test files used ="0mm" as their canonical "written and unreadable" fixture, because it was the corpus's real one; they use 96px now — a length this package refuses on purpose, settled in slice 1.

[tannevaled]

Slice 6 is in #13, and the largest thing left was never a splitting problem

[2026-09-04 08:34:17 CEST]

75 490 of the 81 750 body fields placed, on 2 864 sheets. Slice 5 placed
71 230 on 2 737. The disagreement goes first, and this time it is about the
diagnosis rather than about the size.

All 4 214 are positioned subforms, and no rule would ever have split one

"Most of the 6 208 want a container broken across a sheet" is not what they
wanted. I classified the bucket before writing anything, and every one of the
4 214 has layout=position — which fails clause 2 of $isSplittable. Not one
carries a <keep>; not one is a row.

They are whole-page subforms — form1.Page1, topmostSubform.Page5,
form1.Page04 — six to thirty points taller than the content area they are
drawn for, one per printed sheet. That is how LiveCycle writes a multi-page
form, and it is why the bucket is so large and so uniform.

What was refusing them was not the absence of a splitter. It was a fit-check
this package applied and pdf.js does not, and I found it by reading
checkDimensions rather than by reasoning about splitting:

// layout.js:266-268
function checkDimensions(node, space) {
  if (node[$getTemplateRoot]()[$extra].firstUnsplittable === null) {
    return true;
  }

The first node of a sheet that moves in one piece is not measured against
anything. And the node that claims that pass switches noLayoutFailure on
before its own check runs (setFirstUnsplittable, template.js:313-319,
called from Subform at :5079, ExclGroup at :2484, Draw at :1927 and Field
at :2878), so it cannot fail either — and neither can anything inside it,
because unsetFirstUnsplittable clears the flag only on the way out of that
same node and leaves firstUnsplittable set. So the rule is exactly: the
first leaf or unsplittable container laid out on a sheet goes down whatever its
height, its whole subtree unchecked; everything after it on that sheet is
checked.

firstUnsplittable is reset once per sheet, in the page loop before the
loop over that sheet's content areas (template.js:5536-5538) — not per
content area, which I had assumed until I read it.

Because this package rejected the first whole-page subform, the flow never
turned the page at all, and every later one was measured against the same
sheet. us-irs__fw9 came out on one sheet with 321 fields unplaced;
pdf.js's own dump for it is six sheets. us-uscis__i-600a: one against
fourteen.

Splitting is where those rejections go, which is why this is still the slice

The two halves are one mechanism. What does not fit and is not first sends the
whole chain to the next content area — and that is what splitting the
containers above it means: the children they placed stay where they are and the
rest of them begin again at the top of the new area. There the failing node is
first in its turn. pdf.js has no "split a box" routine for the same reason; the
split IS the resumed generator.

So the code that changed is small. The chain machinery (push/pop/rebase)
was already there from slice 3; what it lacked was the rule for what to do when
the thing that does not fit cannot be split, and it was short-circuiting into a
rejection instead of using the machinery.

The predicate, asked of the chain rather than assumed

flowable(n) became (*placer).splittable(n) and recurses upward as pdf.js
does. Four clauses, each read:

1. the container above must be splittable. The recursion ends at
   <template>, which answers yes (template.js:5401-5403); everything else
   inherits the base answer, no (xfa_object.js:214-216). The one that
   matters is <area> — it holds body content, it is not a subform, and
   $getSubformParent does not skip it (template.js:4901-4907), so nothing
   inside an area is ever split. I had not seen that stated anywhere.
2. layout neither position nor containing row.
3. <keep intact> is none — and ExclGroup[$isSplittable]
   (template.js:2405-2429) has the same predicate without this clause,
   which I checked rather than assumed, as you asked. That difference is kept.
4. parent layout ending in -tb with numberInLine !== 0. This one is not
   code, and that is a measurement rather than an omission. No container this
   package flows through has a layout ending in -tb — only tb and table,
   and "tb".endsWith("-tb") is false — so the clause cannot change an answer
   here. It needs numberInLine, which nothing here computes and which the
   lr-tb slice will bring. The quote is in the doc comment verbatim rather
   than paraphrased.

On the chain being the fifth appearance of that shape: clause 1 turns out
to be unreachable from the flow, because the flow only ever descends through
containers that already passed. I kept the recursion anyway and wrote its
witness — TestSplittabilityIsAskedOfTheWholeChainAndNotOfOneNode pins all
nine answers, <area> and the exclGroup's missing keep clause included — so
that the invariant is asked rather than assumed, and so that a flow which one
day descends somewhere else is caught rather than silently wrong.

The reconciliation, field by field

Every field's disposition dumped from origin/main and from this branch and
paired on (form, path), 81 750 of them, no length mismatch:

taller than a whole content area → placed	4 214
no room inside a container that moves whole → placed	46
no room inside … → still no room inside	61
placed → unplaced	0
net	+4 260

71 230 + 4 260 = 75 490. This is the first slice where the honest count
did not go down anywhere. The 46 are inside the first container of a sheet,
where pdf.js checks nothing either. 9 430 fields placed both times are on a
different sheet now, which is what turning pages that were never turned looks
like.

	slice 5	slice 6
placed	71 230	75 490
taller than a whole content area, and cannot be broken	4 214	0
past the last sheet the page set gives	1 887	1 887
no room inside a container that moves in one piece	107	61
under lr-tb	4 303	4 303
anchored by a corner, with no size of its own	9	9

1 887 past the last sheet did not move. Turning many more pages exhausted no
page set that was not exhausted before, which was not obvious in advance.

The judge, and the pairing re-audited rather than the rate

container heights
heights this package computes, paired with pdf.js's	7 764
agree to within 1/100 pt	7 764	100.00%

where the boxes went
boxes where pdf.js emits a real place	176
agree exactly	176	100.00%
boxes pdf.js placed by flexbox	161 820
… above or to the left of their container, which would be outside it	0	0.00%

which sheet they went on	slice 5	slice 6
forms where this package placed every element	431	473
of those, agreeing with pdf.js on the sheet count	428	469	99.2%
boxes paired on those forms	117 378	149 433
on the same sheet as pdf.js put them	117 378	149 433	100.00%
forms placing fewer elements and using MORE sheets — a defect	0	0	0.00%

The pairing itself, since splitting is exactly what alters which boxes are
comparable. Of 156 574 body boxes on the 469 agreeing forms:

paired	149 433
unnamed, so never keyed	6 680
keyed but absent from pdf.js's dump	461
… of which presence="hidden", which pdf.js emits as display:none	460
dropped because the two sides counted a key differently	0

That last zero is the one worth having: the failure mode this change could
produce — a container split in two yielding a different number of boxes on one
side — did not occur once. Both known faults stay fixed: the whole chain of
names, and rectangles normalised on both sides.

Four sheet-count disagreements, and two are new

us-opm__sf813 and us-opm__sf39a are the same two as slice 5 and are not
this slice's: a positioned outermost subform, whose fit-check
(layout.js:355-364) has never been done here.

us-uscis__i-600a and us-uscis__i-821 are newly visible, and only because
they became fully placed — i-600a was on one sheet before this change
against pdf.js's fourteen, and is on thirteen now. In both, every box agrees up
to a <breakBefore targetType="pageArea" startNew="1"/> and is exactly one
sheet behind after it. That is a question about breaks, not about splitting,
and I have not diagnosed it to the line. Naming it without a witness would be
guessing.

What is left

under lr-tb — the next slice, and it has its text measurement	4 303
past the last sheet the page set gives	1 887
no room inside a container that moves in one piece	61
anchored by a corner, with no size of their own	9

lr-tb is now the largest by a wide margin, and clause 4 of $isSplittable is
waiting for it.