@jasy/pdf 1.0.0-beta.3 → 1.0.0-beta.4

package/dist/elements/pdf-document-element.js

@@ -17,6 +17,13 @@ export class PDFDocumentElement extends PDFElement {
         this.children.forEach((child) => child.calculateLayout(new BoxConstraints(), origin, ctx));
         return { width: 0, height: 0 };
     }
+    /** The root has no size of its own. */
+    computeSize() {
+        return { width: 0, height: 0 };
+    }
+    layoutChildren() {
+        return this.children;
+    }
     getProps() {
         return { children: this.children, defaultTextStyle: this.defaultTextStyle };
     }

package/dist/elements/pdf-element.d.ts

@@ -2,6 +2,7 @@ import type { FontMetrics } from "../utils/font-metrics.js";
 import type { PDFPageConfig } from "./page-element.js";
 import type { ResolvedTextStyle } from "../text/text-style.js";
 import type { OverflowPolicy } from "../layout/fragmentation.js";
+import type { Diagnostics } from "../common/diagnostics.js";
 import type { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
 import type { CrossAlign } from "../layout/alignment.js";
 /**
@@ -11,18 +12,14 @@ import type { CrossAlign } from "../layout/alignment.js";
  * height. The PDF byte writer is deliberately absent - layout must not touch it.
  */
 /**
- * A positioning frame - the CSS "containing block" that `Positioned` children resolve their
- * offsets against. A `relative` Box (later the page) creates one and threads it to its subtree;
- * `Positioned` descendants register a placement closure in `place`, which the frame drains once it
- * has finished sizing itself (so `right`/`bottom` can resolve against the final box).
+ * A positioning frame - the CSS "containing block" that `Positioned` children resolve their offsets
+ * against: the page's content box, or a `relative` Box. Threaded to the subtree so a `Positioned`
+ * can tell it has one. The frame's owner finds its `Positioned` descendants by walking the tree
+ * after sizing itself, and lays them out against its own box - layout itself registers nothing.
  */
 export interface PositioningFrame {
     origin: Offset;
     size: Size;
-    place: Array<(frame: {
-        origin: Offset;
-        size: Size;
-    }, ctx: LayoutContext) => void>;
 }
 /**
  * What a `PageBuilder` learns about the page it landed on. `pageNumber` is 1-based and counts PHYSICAL
@@ -62,24 +59,86 @@ export interface LayoutContext {
     /** What to do when an element overflows a page region and cannot break (set from the render option;
      *  absent = clip silently). Evaluated in `packChildren` where the forced placement happens. */
     onOverflow?: OverflowPolicy;
-    /** The FULL body height of the current page (between header and footer), set by the page driver. A
-     *  `keepTogether` group reads it to decide the degrade rule: veto splitting only when the group would
-     *  fit on a fresh page; a group taller than a whole page drops the veto and splits. */
+    /** The render's diagnostics channel. Never part of a size, so never part of the layout-cache key;
+     *  absent when an element is laid out on its own, which then warns as before. */
+    diagnostics?: Diagnostics;
+    /** The physical page (1-based) pagination is filling - only so a diagnostic can name it; the render
+     *  pass knows it as `pageInfo`. Never part of a size. */
+    paginatingPage?: number;
+    /** The height a FRESH page gives this region: the page body (between header and footer, set by the
+     *  page driver) minus what encloses the region on every page - a border, padding, a repeated table
+     *  header (`insetContext`). A `keepTogether` group reads it to decide the degrade rule: veto splitting
+     *  only when the group would fit on a fresh page; a group taller than that drops the veto and splits. */
     pageBodyHeight?: number;
+    /** Something already sits above this element in the current page region. Then "does not fit"
+     *  means "move to the next page", never an overflow - only content at the top of a fresh page is
+     *  forced on and reported. Set by `packChildren`; absent = top of the page. */
+    belowContent?: boolean;
+    /** What a `Box`'s percentage padding resolves against: the width the Box itself was offered (CSS:
+     *  the containing block), not its inner width. Set by the Box for its own padding only. */
+    boxPaddingBase?: number;
 }
 export declare abstract class PDFElement {
     private _structId;
     get structId(): number;
     /** Make this element share `from`'s tagging identity - used by fragmentation clones. Returns this. */
     adoptStructId(from: PDFElement): this;
+    /**
+     * Marks this element as a piece of `original`, split across pages: it is the same element to a
+     * reader of the tagged PDF (one structure element) and to the Row or Column it sits in (its flex
+     * properties). Every fragmentation clone ends in this call, so a property added to the base is
+     * carried in ONE place. Returns this.
+     */
+    asPieceOf(original: PDFElement): this;
+    /** Takes the flex properties `original` set (CSS `align-self`, `order`, `flex-shrink`). Returns this. */
+    takeFlexItemFrom(original: PDFElement): this;
     abstract getProps(): unknown;
     /**
      * Lays the element out: `constraints` bound its size (flows DOWN), `offset` is the
-     * absolute top-left position the parent assigns it, and the returned `Size` is the
+     * top-left position the parent assigns it, relative to the parent's own top-left (absolute
+     * coordinates exist only in the render pass), and the returned `Size` is the
      * space it actually took (flows UP). Layout works in a top-left origin; the Y-flip
      * happens once at the IR -> backend seam.
      */
     abstract calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    /**
+     * The size `calculateLayout` would return under these constraints - with NO side effects: no
+     * position, no stored size, nothing registered with a frame. A parent asks this to decide, and lays
+     * a child out once afterwards; asking with a full layout doubled the work at every nesting level.
+     * Do not override it - implement `computeSize` (as Flutter's `getDryLayout` / `computeDryLayout`).
+     * The same question twice is answered from the layout cache (`layout/layout-cache.ts`).
+     */
+    measure(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    /**
+     * The part of the constraints this element's size actually reads - what the layout cache keys on.
+     * All of it by default. An element whose size ignores a bound returns it opened up, so two questions
+     * that differ only there share one answer. It must be TRUE for `computeSize`: reading a bound that
+     * is dropped here makes the cache hand back a wrong size.
+     */
+    protected sizeInputs(constraints: BoxConstraints): BoxConstraints;
+    private sizeCache?;
+    /**
+     * Whether this element's size can depend on the page it lands on (`pageConfig`, `pageInfo`): a
+     * `PageBuilder`, a `Page`, and everything holding one. Only those key a cached size on the page, so
+     * every other size is reused across pages and across the pagination and render passes. Remembered:
+     * the tree does not change, and an answer that was `false` can never become `true`.
+     */
+    dependsOnPage(): boolean;
+    private pageDependent?;
+    /**
+     * How this element sizes itself for `measure`. It must come from the SAME sizing computation as
+     * `calculateLayout`, or a measured size and a laid-out one can differ.
+     */
+    protected abstract computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    /** The elements this one lays out, for walks that must see the whole tree. Leaves have none. */
+    layoutChildren(): readonly PDFElement[];
+    /**
+     * The element this one is transparent for, if any: a `ProxyElement` returns its child. A surrounding
+     * Row or Column looks through it for the flex item (`layout/flex-item.ts`).
+     */
+    proxied(): PDFElement | undefined;
+    /** Lays out its own `Positioned` descendants (a page, a `relative` Box); a walk for them stops here. */
+    isPositioningFrame(): boolean;
     /**
      * The relative-size fraction (0..1) this element asked for on the given axis, if any (`horizontal` =
      * width). A flex parent reads it to resolve a percentage child against its OWN main size - e.g. a
@@ -141,9 +200,9 @@ export declare abstract class PDFElement {
     /**
      * Where this child sits among its siblings (CSS `order`), lowest first, source order deciding ties.
      * It moves the child in the LAYOUT only - the element tree, and therefore the reading order a tagged
-     * PDF exposes, is untouched. Default 0.
+     * PDF exposes, is untouched. Unset means 0; a stack reads it through `layout/flex-item.ts`.
      */
-    order: number;
+    order?: number;
     /**
      * How willingly this child gives up main-axis space when the line overflows (CSS `flex-shrink`),
      * weighted by its own size as CSS does. Default 1, as in CSS: an overflowing line squeezes its
@@ -154,8 +213,9 @@ export declare abstract class PDFElement {
      * caution outlived its use: four of the gallery cases turned out to be overflowing their page
      * margin without anyone noticing, because nothing ever pulled them back. Shrinking is bounded from
      * below by `minIntrinsicMain`, so a child is never squeezed past what it can actually hold.
+     * Unset means 1; a stack reads it through `layout/flex-item.ts`.
      */
-    flexShrink: number;
+    flexShrink?: number;
     /** Sets `flexShrink` and returns the element. */
     withFlexShrink(shrink: number | undefined): this;
     /** Sets `order` and returns the element, so a factory can thread it through in one expression. */

package/dist/elements/pdf-element.js

@@ -1,3 +1,4 @@
+import { SizeCache } from "../layout/layout-cache.js";
 let _nextStructId = 0;
 export class PDFElement {
     constructor() {
@@ -5,24 +6,6 @@ export class PDFElement {
         // fragmentation copies (adoptStructId), so a paragraph or table split across pages stays ONE structure
         // element. Only the elements that actually tag (Text, Image, StructGroup) read it.
         this._structId = _nextStructId++;
-        /**
-         * Where this child sits among its siblings (CSS `order`), lowest first, source order deciding ties.
-         * It moves the child in the LAYOUT only - the element tree, and therefore the reading order a tagged
-         * PDF exposes, is untouched. Default 0.
-         */
-        this.order = 0;
-        /**
-         * How willingly this child gives up main-axis space when the line overflows (CSS `flex-shrink`),
-         * weighted by its own size as CSS does. Default 1, as in CSS: an overflowing line squeezes its
-         * children back inside instead of letting them run past the edge of the box. `0` opts out and keeps
-         * a child at its natural size.
-         *
-         * This was 0 until the alpha, so that adding flexShrink could not move an existing layout. That
-         * caution outlived its use: four of the gallery cases turned out to be overflowing their page
-         * margin without anyone noticing, because nothing ever pulled them back. Shrinking is bounded from
-         * below by `minIntrinsicMain`, so a child is never squeezed past what it can actually hold.
-         */
-        this.flexShrink = 1;
     }
     get structId() {
         return this._structId;
@@ -32,6 +15,73 @@ export class PDFElement {
         this._structId = from._structId;
         return this;
     }
+    /**
+     * Marks this element as a piece of `original`, split across pages: it is the same element to a
+     * reader of the tagged PDF (one structure element) and to the Row or Column it sits in (its flex
+     * properties). Every fragmentation clone ends in this call, so a property added to the base is
+     * carried in ONE place. Returns this.
+     */
+    asPieceOf(original) {
+        return this.adoptStructId(original).takeFlexItemFrom(original);
+    }
+    /** Takes the flex properties `original` set (CSS `align-self`, `order`, `flex-shrink`). Returns this. */
+    takeFlexItemFrom(original) {
+        this.alignSelf = original.alignSelf ?? this.alignSelf;
+        this.order = original.order ?? this.order;
+        this.flexShrink = original.flexShrink ?? this.flexShrink;
+        return this;
+    }
+    /**
+     * The size `calculateLayout` would return under these constraints - with NO side effects: no
+     * position, no stored size, nothing registered with a frame. A parent asks this to decide, and lays
+     * a child out once afterwards; asking with a full layout doubled the work at every nesting level.
+     * Do not override it - implement `computeSize` (as Flutter's `getDryLayout` / `computeDryLayout`).
+     * The same question twice is answered from the layout cache (`layout/layout-cache.ts`).
+     */
+    measure(constraints, ctx) {
+        const cache = (this.sizeCache ?? (this.sizeCache = new SizeCache()));
+        const asked = this.sizeInputs(constraints);
+        const onPage = this.dependsOnPage();
+        const known = cache.get(asked, ctx, onPage);
+        if (known)
+            return known;
+        const size = this.computeSize(constraints, ctx);
+        cache.set(asked, ctx, onPage, size);
+        return size;
+    }
+    /**
+     * The part of the constraints this element's size actually reads - what the layout cache keys on.
+     * All of it by default. An element whose size ignores a bound returns it opened up, so two questions
+     * that differ only there share one answer. It must be TRUE for `computeSize`: reading a bound that
+     * is dropped here makes the cache hand back a wrong size.
+     */
+    sizeInputs(constraints) {
+        return constraints;
+    }
+    /**
+     * Whether this element's size can depend on the page it lands on (`pageConfig`, `pageInfo`): a
+     * `PageBuilder`, a `Page`, and everything holding one. Only those key a cached size on the page, so
+     * every other size is reused across pages and across the pagination and render passes. Remembered:
+     * the tree does not change, and an answer that was `false` can never become `true`.
+     */
+    dependsOnPage() {
+        return (this.pageDependent ?? (this.pageDependent = this.layoutChildren().some((child) => child.dependsOnPage())));
+    }
+    /** The elements this one lays out, for walks that must see the whole tree. Leaves have none. */
+    layoutChildren() {
+        return [];
+    }
+    /**
+     * The element this one is transparent for, if any: a `ProxyElement` returns its child. A surrounding
+     * Row or Column looks through it for the flex item (`layout/flex-item.ts`).
+     */
+    proxied() {
+        return undefined;
+    }
+    /** Lays out its own `Positioned` descendants (a page, a `relative` Box); a walk for them stops here. */
+    isPositioningFrame() {
+        return false;
+    }
     /**
      * The relative-size fraction (0..1) this element asked for on the given axis, if any (`horizontal` =
      * width). A flex parent reads it to resolve a percentage child against its OWN main size - e.g. a

package/dist/elements/rectangle-element.d.ts

@@ -78,9 +78,22 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
      *  `Spacer` in a box can only resolve if the box itself was given a bounded extent to pass down. With an
      *  explicit size on an axis the box already knows its extent there and asks for nothing. */
     needsBoundedMain(horizontal: boolean): boolean;
+    /** A Box's own padding resolves a percentage against what the Box was OFFERED (CSS: the containing
+     *  block), not against the inner width it hands its children - so it is told. Only a bounded offer:
+     *  in a Row a child is offered no width at all, and there the padding keeps resolving against the
+     *  Box's own width, as it always did. */
+    private paddingContext;
     /** A Box stacks its children vertically inside its border, which is on both sides of the axis. */
     minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    /**
+     * The one sizing path. With an `offset` it lays the children out and keeps its geometry; with
+     * `null` it only measures - no field written, no child placed, no frame drained.
+     */
+    private sizeWith;
+    isPositioningFrame(): boolean;
+    layoutChildren(): readonly PDFElement[];
     getProps(): {
         x: number;
         y: number;
@@ -93,6 +106,7 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
         radius: number | Radii;
         sideBorders: SideBorders | undefined;
         overflow: "hidden" | "visible";
+        relative: boolean;
     };
 }
 export {};

package/dist/elements/rectangle-element.js

@@ -1,7 +1,10 @@
+import { widthRules } from "../layout/box-constraints.js";
 import { Color } from "../common/color.js";
 import { BoxConstraints, extentSpecs, resolveSize, } from "../layout/box-constraints.js";
 import { stackMinIntrinsic, withDeclaredExtent } from "../layout/min-intrinsic.js";
-import { childrenForceBreak, packChildren, } from "../layout/fragmentation.js";
+import { positionedIn } from "./layout/positioned-element.js";
+import { PaddingElement } from "./layout/padding-element.js";
+import { childrenForceBreak, insetContext, packChildren, } from "../layout/fragmentation.js";
 import { SizedPDFElement, } from "./pdf-element.js";
 export class RectangleElement extends SizedPDFElement {
     constructor({ children = [], color = new Color(0, 0, 0), backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, breakBefore, breakAfter, ...sizing }) {
@@ -20,8 +23,10 @@ export class RectangleElement extends SizedPDFElement {
         this.breakAfter = breakAfter ?? false;
         this.sizeMemory = { ...sizing, x: 0, y: 0, width, height };
     }
+    // A break before the FIRST child is a break before this stack (CSS propagates it): the whole stack
+    // moves to the next page, instead of leaving an empty piece - or an empty border - behind.
     breaksBefore() {
-        return this.breakBefore;
+        return this.breakBefore || (this.children[0]?.breaksBefore() ?? false);
     }
     breaksAfter() {
         return this.breakAfter;
@@ -35,23 +40,29 @@ export class RectangleElement extends SizedPDFElement {
      * box is sized by what it actually holds on each page.
      */
     fragment(maxHeight, width, ctx) {
-        // A percentage width resolves against the region width the page driver hands us, so a
-        // paginating %-box keeps its fraction on every page.
-        const boxWidth = this.sizeMemory.width ??
-            (this.sizeMemory.widthFactor !== undefined ? width * this.sizeMemory.widthFactor : width);
+        // The box's own width rules (fixed, %, min/max) resolved against the region - the same sizing
+        // path as `measure`, so the content is packed at the width it will be drawn at.
+        const boxWidth = this.measure(BoxConstraints.loose(width, Infinity), ctx).width;
         const innerWidth = Math.max(0, boxWidth - 2 * this.borderWidth);
         // Border-box: the content is inset by the border on top and bottom, so a fragment
         // holding `c` of content is `c + 2*border` tall. (Derived, not a fudge factor.)
         const innerMaxHeight = maxHeight - 2 * this.borderWidth;
-        const { fitted, remainder, forceBreak } = packChildren(this.children, innerMaxHeight, innerWidth, ctx);
+        const { fitted, remainder, forceBreak } = packChildren(this.children, innerMaxHeight, innerWidth, insetContext(this.paddingContext(ctx, width), 2 * this.borderWidth));
         // Fits with no forced cut: return the whole box unchanged. A trailing forced break is the
         // exception - fall through so the box is rebuilt from the packed children (without the consumed
         // break marker), rather than handing back the original that still holds it.
-        if (remainder.length === 0 && !forceBreak)
-            return { fitted: this, remainder: null };
-        const contentHeight = (kids) => kids.reduce((sum, child) => sum +
-            child.calculateLayout(BoxConstraints.loose(innerWidth, Infinity), { x: 0, y: 0 }, ctx)
-                .height, 0);
+        if (remainder.length === 0 && !forceBreak) {
+            // The content fits, but a fixed height may not - such a box cannot shrink, so it moves on whole.
+            const own = this.measure(BoxConstraints.loose(width, Infinity), ctx).height;
+            return own <= maxHeight
+                ? { fitted: this, remainder: null }
+                : { fitted: null, remainder: this };
+        }
+        // Nothing fit below the content above: move on whole, not as an empty bordered box.
+        if (fitted.length === 0 && !forceBreak)
+            return { fitted: null, remainder: this };
+        const childCtx = this.paddingContext(ctx, width);
+        const contentHeight = (kids) => kids.reduce((sum, child) => sum + child.measure(BoxConstraints.loose(innerWidth, Infinity), childCtx).height, 0);
         return {
             fitted: this.cloneWithChildren(fitted, contentHeight(fitted) + 2 * this.borderWidth),
             // A trailing forced break leaves nothing to carry over: no remainder box, no extra page.
@@ -70,10 +81,9 @@ export class RectangleElement extends SizedPDFElement {
         return new RectangleElement({
             x: 0,
             y: 0,
-            width: this.sizeMemory.width,
-            widthFactor: this.sizeMemory.widthFactor,
-            // A split box is sized by its per-page content (height passed in), so the height factor
-            // is intentionally dropped here - box-decoration-break, same as an explicit height.
+            ...widthRules(this.sizeMemory),
+            // A split box is sized by its per-page content (height passed in), so the height rules are
+            // intentionally dropped here - box-decoration-break, same as an explicit height.
             height,
             children,
             color: this.color,
@@ -84,7 +94,7 @@ export class RectangleElement extends SizedPDFElement {
             relative: this.relative,
             overflow: this.overflow,
             breakAfter,
-        });
+        }).asPieceOf(this);
     }
     relativeSizeFactor(horizontal) {
         return horizontal ? this.sizeMemory.widthFactor : this.sizeMemory.heightFactor;
@@ -100,12 +110,32 @@ export class RectangleElement extends SizedPDFElement {
             return false;
         return this.children.some((c) => c.needsBoundedMain(horizontal));
     }
+    /** A Box's own padding resolves a percentage against what the Box was OFFERED (CSS: the containing
+     *  block), not against the inner width it hands its children - so it is told. Only a bounded offer:
+     *  in a Row a child is offered no width at all, and there the padding keeps resolving against the
+     *  Box's own width, as it always did. */
+    paddingContext(ctx, offered) {
+        const own = this.children[0];
+        return own instanceof PaddingElement && own.ofBox && Number.isFinite(offered)
+            ? { ...ctx, boxPaddingBase: offered }
+            : ctx;
+    }
     /** A Box stacks its children vertically inside its border, which is on both sides of the axis. */
     minIntrinsicMain(horizontal, ctx) {
         const content = stackMinIntrinsic(this.children, 0, !horizontal, horizontal, ctx) + 2 * this.borderWidth;
         return withDeclaredExtent(content, horizontal ? this.sizeMemory.width : this.sizeMemory.height, horizontal ? this.sizeMemory.minWidth : this.sizeMemory.minHeight);
     }
     calculateLayout(constraints, offset, ctx) {
+        return this.sizeWith(constraints, ctx, offset);
+    }
+    computeSize(constraints, ctx) {
+        return this.sizeWith(constraints, ctx, null);
+    }
+    /**
+     * The one sizing path. With an `offset` it lays the children out and keeps its geometry; with
+     * `null` it only measures - no field written, no child placed, no frame drained.
+     */
+    sizeWith(constraints, ctx, offset) {
         // An explicit extent is a fixed point size or a fraction of the offered box (relative sizing);
         // the fraction only resolves in a bounded region. `undefined` = fill / shrink-wrap below.
         const specs = extentSpecs(this.sizeMemory);
@@ -118,12 +148,11 @@ export class RectangleElement extends SizedPDFElement {
         // fixed box would balloon to the parent's size.)
         // Whether there is a region to fill is decided by the constraints we were GIVEN: a `maxWidth` caps
         // a box, it does not turn a shrink-wrapping one into a filling one (CSS `max-width` does not either).
-        this.width =
-            explicitWidth !== undefined
-                ? bounds.constrainWidth(explicitWidth)
-                : constraints.hasBoundedWidth
-                    ? bounds.maxWidth
-                    : this.width;
+        let width = explicitWidth !== undefined
+            ? bounds.constrainWidth(explicitWidth)
+            : constraints.hasBoundedWidth
+                ? bounds.maxWidth
+                : undefined;
         // Width shrink-wrap: no explicit width AND an unbounded region (e.g. a `Box` badge inside a
         // `Positioned`). Resolved after the children are measured, just below.
         const shrinkWrapWidth = explicitWidth === undefined && !constraints.hasBoundedWidth;
@@ -131,43 +160,46 @@ export class RectangleElement extends SizedPDFElement {
         // SHRINK-WRAP the content in an unbounded one (a note box in a stack). Shrink-wrap is
         // resolved after the children are measured, just below.
         const shrinkWrapHeight = explicitHeight === undefined && !constraints.hasBoundedHeight;
-        this.height =
-            explicitHeight !== undefined
-                ? bounds.constrainHeight(explicitHeight)
-                : constraints.hasBoundedHeight
-                    ? bounds.maxHeight
-                    : this.height;
-        this.x = this.sizeMemory.x + offset.x;
-        this.y = this.sizeMemory.y + offset.y;
-        // A `relative` box is a positioning frame: thread a fresh frame to the subtree so any
-        // `Positioned` descendant registers against it (out of flow), then drain it below once the
-        // box is sized. A plain box leaves `ctx` untouched -> byte-identical.
-        const frame = this.relative
-            ? { origin: { x: 0, y: 0 }, size: { width: 0, height: 0 }, place: [] }
+        let height = explicitHeight !== undefined
+            ? bounds.constrainHeight(explicitHeight)
+            : constraints.hasBoundedHeight
+                ? bounds.maxHeight
+                : undefined;
+        const x = this.sizeMemory.x + (offset?.x ?? 0);
+        const y = this.sizeMemory.y + (offset?.y ?? 0);
+        // A `relative` box is a positioning frame: its subtree is told it has one, and once the box is
+        // sized it lays out the `Positioned` descendants against itself (below). Measuring places
+        // nothing, so it needs no frame. A plain box leaves `ctx` untouched.
+        const frame = this.relative && offset
+            ? { origin: { x: 0, y: 0 }, size: { width: 0, height: 0 } }
             : undefined;
-        const childCtx = frame ? { ...ctx, frame } : ctx;
+        const childCtx = this.paddingContext(frame ? { ...ctx, frame } : ctx, constraints.maxWidth);
         // Lay out children stacked inside the border (inset by the border width). Width is finalized here;
         // height is left unbounded so each child sizes to its own content - EXCEPT for a child that cannot
         // lay itself out without a bound (a stack holding an `Expanded`/`Spacer`). That one gets the height
         // still free inside the box, so its flex child has real leftover space instead of an infinite one.
         const innerWidth = shrinkWrapWidth
             ? Infinity
-            : Math.max(0, (this.width ?? 0) - 2 * this.borderWidth);
+            : Math.max(0, (width ?? 0) - 2 * this.borderWidth);
         const innerHeight = shrinkWrapHeight
             ? Infinity
-            : Math.max(0, (this.height ?? 0) - 2 * this.borderWidth);
+            : Math.max(0, (height ?? 0) - 2 * this.borderWidth);
         let contentWidth = 0;
         let contentHeight = 0;
-        let yCursor = this.y + this.borderWidth;
+        // Children are placed relative to this box's top-left, inside the border.
+        let yCursor = this.borderWidth;
         for (const child of this.children) {
-            const consumed = yCursor - (this.y + this.borderWidth);
+            const consumed = yCursor - this.borderWidth;
             // Same rule the flex helper applies: a child gets a finite main extent when it cannot lay itself
             // out without one - a stack holding an `Expanded`/`Spacer`, or a child sized as a percentage of us.
             const needsBound = child.needsBoundedMain(false) || child.relativeSizeFactor(false) !== undefined;
             const childHeight = needsBound
                 ? Math.max(0, innerHeight - consumed) // Infinity - consumed stays Infinity, as it should
                 : Infinity;
-            const childSize = child.calculateLayout(BoxConstraints.loose(innerWidth, childHeight), { x: this.x + this.borderWidth, y: yCursor }, childCtx);
+            const childConstraints = BoxConstraints.loose(innerWidth, childHeight);
+            const childSize = offset
+                ? child.calculateLayout(childConstraints, { x: this.borderWidth, y: yCursor }, childCtx)
+                : child.measure(childConstraints, childCtx);
             yCursor += childSize.height;
             contentHeight += childSize.height;
             contentWidth = Math.max(contentWidth, childSize.width);
@@ -175,32 +207,44 @@ export class RectangleElement extends SizedPDFElement {
         // No explicit width and no bounded region: shrink-wrap to the widest child.
         // Clamped, so a min/max still applies to a box that sized itself to its content.
         if (shrinkWrapWidth)
-            this.width = bounds.constrainWidth(contentWidth + 2 * this.borderWidth);
+            width = bounds.constrainWidth(contentWidth + 2 * this.borderWidth);
         // A ratio on a shrink-wrapping box can only be applied HERE: before the children were measured
         // there was no width to derive the height from.
         const ratio = this.sizeMemory.aspectRatio;
         const ratioSizesHeight = ratio !== undefined && ratio > 0 && shrinkWrapWidth && shrinkWrapHeight;
         // No explicit height and no bounded region: the border hugs its content.
         if (ratioSizesHeight)
-            this.height = bounds.constrainHeight((this.width ?? 0) / ratio);
+            height = bounds.constrainHeight((width ?? 0) / ratio);
         else if (shrinkWrapHeight)
-            this.height = bounds.constrainHeight(contentHeight + 2 * this.borderWidth);
-        // The box is sized now: place any out-of-flow `Positioned` descendants against its box.
+            height = bounds.constrainHeight(contentHeight + 2 * this.borderWidth);
+        if (offset) {
+            this.x = x;
+            this.y = y;
+            this.width = width;
+            this.height = height;
+        }
+        // The box is sized now: place its out-of-flow `Positioned` descendants, relative to its own
+        // top-left. Each is drawn at its own place in the tree (tree order).
         if (frame) {
-            frame.origin = { x: this.x, y: this.y };
-            frame.size = { width: this.width ?? 0, height: this.height ?? 0 };
-            for (const place of frame.place)
-                place(frame, ctx);
+            const box = { width: width ?? 0, height: height ?? 0 };
+            for (const p of positionedIn(this.children))
+                p.placeIn(box, childCtx);
         }
         // Border-box model: width/height ARE the outer box (the rect we draw); the content
         // is inset by the border on every side. Report the honest box size - no phantom
         // border added on (that asymmetric "+border" was the source of the magic-3 fudge in
         // fragment). Top-left coordinates; the Y-flip happens at the IR -> backend seam.
         return {
-            width: this.width ?? 0,
-            height: this.height ?? 0,
+            width: width ?? 0,
+            height: height ?? 0,
         };
     }
+    isPositioningFrame() {
+        return this.relative;
+    }
+    layoutChildren() {
+        return this.children ?? [];
+    }
     getProps() {
         return {
             x: this.x,
@@ -214,6 +258,7 @@ export class RectangleElement extends SizedPDFElement {
             radius: this.radius,
             sideBorders: this.sideBorders,
             overflow: this.overflow,
+            relative: this.relative,
         };
     }
 }

package/dist/elements/row-element.d.ts

@@ -68,6 +68,17 @@ export declare class RowElement extends SizedPDFElement {
     /** A Row lays out side by side, so widths add up (gaps included) and heights overlap. */
     minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    /** The first element inside this row that asks for a page break by flag, once found (or `null`). */
+    private declaredBreak?;
+    /**
+     * A row is one line: nothing inside it starts a new page. A `breakBefore` / `breakAfter` in a cell
+     * (a table row is a Row too) is therefore ignored - say so. A `PageBreak` reports itself.
+     */
+    private reportIgnoredBreak;
+    /** The one sizing path: `layout` places the children (relative to this box), `measure` only sizes them. */
+    private sizeWith;
+    layoutChildren(): readonly PDFElement[];
     getProps(): {
         x: number;
         y: number;