@jasy/pdf 1.0.0-alpha.8 → 1.0.0-beta.1

package/dist/elements/container-element.js

@@ -1,15 +1,19 @@
 import { FlexLayoutHelper, VERTICAL_AXIS } from "../utils/flex-layout.js";
-import { resolveExtent } from "../layout/box-constraints.js";
+import { stackMinIntrinsic, withDeclaredExtent } from "../layout/min-intrinsic.js";
+import { extentSpecs, resolveSize, } from "../layout/box-constraints.js";
 import { childrenForceBreak, packChildren, } from "../layout/fragmentation.js";
 import { FlexiblePDFElement, SizedPDFElement, } from "./pdf-element.js";
 export class ContainerElement extends SizedPDFElement {
-    constructor({ x, y, width, height, children, gap, main, cross, widthFactor, heightFactor, breakBefore, breakAfter, }) {
+    constructor({ x, y, width, height, children, gap, main, cross, reverse, wrap, alignContent, breakBefore, breakAfter, ...sizing }) {
         super({ x, y, width, height });
         this.children = children;
         this.gap = gap ?? 0;
         this.main = main ?? "start";
         this.cross = cross ?? "stretch";
-        this.requested = { width, height, widthFactor, heightFactor };
+        this.reverse = reverse ?? false;
+        this.wrap = wrap ?? false;
+        this.alignContent = alignContent;
+        this.requested = { ...sizing, width, height };
         this.breakBefore = breakBefore ?? false;
         this.breakAfter = breakAfter ?? false;
     }
@@ -62,6 +66,9 @@ export class ContainerElement extends SizedPDFElement {
             gap: this.gap,
             main: this.main,
             cross: this.cross,
+            reverse: this.reverse,
+            wrap: this.wrap,
+            alignContent: this.alignContent,
             breakAfter,
         });
     }
@@ -87,23 +94,30 @@ export class ContainerElement extends SizedPDFElement {
         const ownFlexChild = !horizontal && this.children.some((c) => c instanceof FlexiblePDFElement);
         return ownFlexChild || this.children.some((c) => c.needsBoundedMain(horizontal));
     }
+    /** A Column stacks vertically, so widths overlap and heights add up. */
+    minIntrinsicMain(horizontal, ctx) {
+        const content = stackMinIntrinsic(this.children, this.gap, !horizontal, horizontal, ctx, this.wrap);
+        return withDeclaredExtent(content, horizontal ? this.requested.width : this.requested.height, horizontal ? this.requested.minWidth : this.requested.minHeight);
+    }
     calculateLayout(constraints, offset, ctx) {
         this.x = offset.x;
         this.y = offset.y;
         // Relative sizing: a pinned extent (fixed points or a fraction of the offered box, clamped into
         // the constraints) wins; else fill a bounded axis; else stay `undefined` and shrink-wrap below.
         // A Column nested in a Row gets unbounded width - passing 0 there would collapse children to 0.
-        const explicitWidth = resolveExtent(this.requested.width, this.requested.widthFactor, constraints.maxWidth, constraints.hasBoundedWidth);
-        const explicitHeight = resolveExtent(this.requested.height, this.requested.heightFactor, constraints.maxHeight, constraints.hasBoundedHeight);
+        const specs = extentSpecs(this.requested);
+        const resolved = resolveSize(specs.width, specs.height, this.requested.aspectRatio, constraints);
+        const { width: explicitWidth, height: explicitHeight, constraints: bounds } = resolved;
+        // Fill-or-shrink-wrap is decided by the constraints we were GIVEN; a min/max only caps the result.
         const boundedWidth = explicitWidth !== undefined
-            ? constraints.constrainWidth(explicitWidth)
+            ? bounds.constrainWidth(explicitWidth)
             : constraints.hasBoundedWidth
-                ? constraints.maxWidth
+                ? bounds.maxWidth
                 : undefined;
         const boundedHeight = explicitHeight !== undefined
-            ? constraints.constrainHeight(explicitHeight)
+            ? bounds.constrainHeight(explicitHeight)
             : constraints.hasBoundedHeight
-                ? constraints.maxHeight
+                ? bounds.maxHeight
                 : undefined;
         // Vertical stack: cross = width (children fill it), main = height (the stacking extent).
         const crossAvail = boundedWidth ?? Infinity;
@@ -113,7 +127,14 @@ export class ContainerElement extends SizedPDFElement {
             // Vertical flex stack (main = height, cross = width). The shared helper measures
             // fixed children, distributes the leftover to flex children, and places everything
             // in source order.
-            result = FlexLayoutHelper.layout(this.children, VERTICAL_AXIS, mainAvail, crossAvail, this.y, this.x, { gap: this.gap, main: this.main, cross: this.cross }, ctx);
+            result = FlexLayoutHelper.layout(this.children, VERTICAL_AXIS, mainAvail, crossAvail, this.y, this.x, {
+                gap: this.gap,
+                main: this.main,
+                cross: this.cross,
+                reverse: this.reverse,
+                wrap: this.wrap,
+                alignContent: this.alignContent,
+            }, ctx);
         }
         // Pinned/bounded axis takes that extent; an unbounded one shrink-wraps to the children (height =
         // the stack, width = the widest child). Top-left coordinates; the container draws nothing, and

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

@@ -1,3 +1,4 @@
+import type { Radii } from "../ir/display-list.js";
 import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
 import { LayoutContext, SizedPDFElement } from "./pdf-element.js";
 export declare enum BoxFit {
@@ -55,9 +56,20 @@ interface ImageElementParams {
     widthFactor?: number;
     /** Height as a fraction (0..1) of the offered height; see `widthFactor`. */
     heightFactor?: number;
+    /** Lower / upper bounds per axis, in points or as a fraction; see `SizingParams`. */
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    minWidthFactor?: number;
+    maxWidthFactor?: number;
+    minHeightFactor?: number;
+    maxHeightFactor?: number;
+    /** width / height; overrides the image's OWN ratio (CSS `aspect-ratio`), `fit` then places it. */
+    aspectRatio?: number;
     fit?: BoxFit;
-    /** Corner radius in points; rounds the image box (0 = sharp, default). */
-    radius?: number;
+    /** Corner radius in points - one number or per corner; rounds the image box (0 = sharp, default). */
+    radius?: number | Radii;
     /** Alternate text for accessibility (tagged PDF). With `alt` the image is a Figure; without, decoration. */
     alt?: string;
 }
@@ -69,8 +81,10 @@ export declare class ImageElement extends SizedPDFElement {
     private radius;
     private readonly alt?;
     private requested;
+    /** min/max/aspectRatio, kept as given so every layout pass re-resolves them. */
+    private sizing;
     private intrinsic?;
-    constructor({ image, width, height, widthFactor, heightFactor, fit, radius, alt, }: ImageElementParams);
+    constructor({ image, width, height, widthFactor, heightFactor, fit, radius, alt, ...sizing }: ImageElementParams);
     /**
      * Loads the image and records its intrinsic pixel size. Runs in the async pre-layout pass (layout
      * itself is synchronous and cannot await jimp) so `calculateLayout` can turn a width-only image
@@ -87,7 +101,7 @@ export declare class ImageElement extends SizedPDFElement {
         height: number | undefined;
         image: CustomImage;
         fit: BoxFit;
-        radius: number;
+        radius: number | Radii;
         alt: string | undefined;
     };
 }

package/dist/elements/image-element.js

@@ -1,7 +1,7 @@
 import { getImageDimensions } from "../utils/image-helper.js";
 import { latin1FromBytes } from "../utils/bytes.js";
 import { readFileBytesAsync } from "../platform/node-fs.js";
-import { resolveExtent } from "../layout/box-constraints.js";
+import { extentSpecs, resolveSize, } from "../layout/box-constraints.js";
 import { SizedPDFElement } from "./pdf-element.js";
 // path.extname without node:path (browser-safe): the substring from the last dot, if it sits after the
 // last slash (so a dot in a directory name does not count). Enough for image file extensions.
@@ -100,7 +100,7 @@ export class CustomBytesImage extends CustomImage {
     }
 }
 export class ImageElement extends SizedPDFElement {
-    constructor({ image, width, height, widthFactor, heightFactor, fit = BoxFit.none, radius, alt, }) {
+    constructor({ image, width, height, widthFactor, heightFactor, fit = BoxFit.none, radius, alt, ...sizing }) {
         // Seed this.width/height from the request so getProps() reflects it before layout; calculateLayout
         // then reads `requested` (never the mutated fields) and overwrites these with the laid-out size.
         super({ x: 0, y: 0, width });
@@ -109,6 +109,7 @@ export class ImageElement extends SizedPDFElement {
         this.requested = { width, height };
         this.widthFactor = widthFactor;
         this.heightFactor = heightFactor;
+        this.sizing = sizing;
         this.fit = fit;
         this.radius = radius ?? 0;
         this.alt = alt;
@@ -136,22 +137,36 @@ export class ImageElement extends SizedPDFElement {
         this.y = offset.y;
         // Relative sizing: a fixed size or a fraction of the offered box (fraction only in a bounded axis).
         // Read from `requested` (not this.width/height, which we overwrite below) so every pass re-resolves.
-        let w = resolveExtent(this.requested.width, this.widthFactor, constraints.maxWidth, constraints.hasBoundedWidth);
-        let h = resolveExtent(this.requested.height, this.heightFactor, constraints.maxHeight, constraints.hasBoundedHeight);
-        // Aspect auto-size: when the user pinned exactly ONE axis, derive the other from the intrinsic
-        // ratio (CSS `width: 50%; height: auto`). Only fires once the pre-pass resolved the pixel size.
-        if (this.intrinsic && this.intrinsic.width > 0 && this.intrinsic.height > 0) {
+        const specs = extentSpecs({
+            ...this.sizing,
+            width: this.requested.width,
+            height: this.requested.height,
+            widthFactor: this.widthFactor,
+            heightFactor: this.heightFactor,
+        });
+        // An explicit `aspectRatio` wins over the image's own, as it does in CSS - and only it may size a
+        // box with NEITHER axis pinned. Left to the intrinsic ratio that would change what an unsized image
+        // has always done here (fill both axes and let `fit` sort it out).
+        const resolved = resolveSize(specs.width, specs.height, this.sizing.aspectRatio, constraints);
+        let w = resolved.width;
+        let h = resolved.height;
+        const bounds = resolved.constraints;
+        // Aspect auto-size: when exactly ONE axis is pinned, derive the other from the intrinsic ratio
+        // (CSS `width: 50%; height: auto`). Only fires once the pre-pass resolved the pixel size.
+        if (this.sizing.aspectRatio === undefined &&
+            this.intrinsic &&
+            this.intrinsic.width > 0 &&
+            this.intrinsic.height > 0) {
             const ratio = this.intrinsic.width / this.intrinsic.height;
             if (w !== undefined && h === undefined)
-                h = w / ratio;
+                h = bounds.constrainHeight(w / ratio);
             else if (h !== undefined && w === undefined)
-                w = h * ratio;
+                w = bounds.constrainWidth(h * ratio);
         }
         // Fall back to the prior behavior for an unpinned axis: a bounded axis fills, otherwise keep the
         // requested fixed size (or undefined). Read from `requested`, never the mutated this.width/height.
-        this.width = w ?? (constraints.hasBoundedWidth ? constraints.maxWidth : this.requested.width);
-        this.height =
-            h ?? (constraints.hasBoundedHeight ? constraints.maxHeight : this.requested.height);
+        this.width = w ?? (bounds.hasBoundedWidth ? bounds.maxWidth : this.requested.width);
+        this.height = h ?? (bounds.hasBoundedHeight ? bounds.maxHeight : this.requested.height);
         // Top-left coordinates; the fit logic (renderer) and the Y-flip (seam) run later.
         return { width: this.width ?? 0, height: this.height ?? 0 };
     }

package/dist/elements/index.d.ts

@@ -24,3 +24,5 @@ export * from "./layout/rotated-element.js";
 export * from "./layout/rotated-box-element.js";
 export * from "./line-element.js";
 export * from "./row-element.js";
+export * from "./svg-element.js";
+export * from "./canvas-element.js";

package/dist/elements/index.js

@@ -24,3 +24,5 @@ export * from "./layout/rotated-element.js";
 export * from "./layout/rotated-box-element.js";
 export * from "./line-element.js";
 export * from "./row-element.js";
+export * from "./svg-element.js";
+export * from "./canvas-element.js";

package/dist/elements/layout/expanded-element.d.ts

@@ -9,7 +9,9 @@ export declare class ExpandedElement extends FlexiblePDFElement implements Fragm
     private y;
     private width;
     private height;
-    constructor({ flex, child }: ExpandedElementParams);
+    constructor({ flex, basis, basisFactor, child }: ExpandedElementParams);
+    /** Layout-transparent: the floor is whatever the wrapped child needs. */
+    minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     /**
      * When the column paginates, a flex region can't "fill" across pages, so it delegates to
@@ -24,6 +26,8 @@ export declare class ExpandedElement extends FlexiblePDFElement implements Fragm
         y: number;
         width: number;
         height: number;
+        basis: number;
+        basisFactor: number | undefined;
         child: PDFElement;
     };
 }

package/dist/elements/layout/expanded-element.js

@@ -3,14 +3,18 @@ import { FlexiblePDFElement, } from "../pdf-element.js";
 import { BoxConstraints } from "../../layout/box-constraints.js";
 import { isFragmentable } from "../../layout/fragmentation.js";
 export class ExpandedElement extends FlexiblePDFElement {
-    constructor({ flex, child }) {
-        super({ flex });
+    constructor({ flex, basis, basisFactor, child }) {
+        super({ flex, basis, basisFactor });
         this.x = 0;
         this.y = 0;
         this.width = 0;
         this.height = 0;
         this.child = child;
     }
+    /** Layout-transparent: the floor is whatever the wrapped child needs. */
+    minIntrinsicMain(horizontal, ctx) {
+        return this.child.minIntrinsicMain(horizontal, ctx);
+    }
     calculateLayout(constraints, offset, ctx) {
         if (constraints.hasBoundedWidth)
             this.width = constraints.maxWidth;
@@ -50,7 +54,14 @@ export class ExpandedElement extends FlexiblePDFElement {
         };
     }
     cloneWithChild(child) {
-        return new ExpandedElement({ flex: this.flex, child });
+        // The basis has to come along: a fragment that lost it would claim only its share of the leftover,
+        // so a `flexBasis` slot would silently change width on the page it continues onto.
+        return new ExpandedElement({
+            flex: this.flex,
+            basis: this.basis,
+            basisFactor: this.basisFactor,
+            child,
+        });
     }
     getProps() {
         return {
@@ -58,6 +69,8 @@ export class ExpandedElement extends FlexiblePDFElement {
             y: this.y,
             width: this.width,
             height: this.height,
+            basis: this.basis,
+            basisFactor: this.basisFactor,
             child: this.child,
         };
     }

package/dist/elements/layout/keep-together-element.d.ts

@@ -26,6 +26,8 @@ export declare class KeepTogetherElement extends PDFElement implements Fragmenta
     constructor({ child }: {
         child: PDFElement;
     });
+    /** Layout-transparent: the floor is whatever the wrapped child needs. */
+    minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     relativeSizeFactor(horizontal: boolean): number | undefined;
     needsBoundedMain(horizontal: boolean): boolean;

package/dist/elements/layout/keep-together-element.js

@@ -26,6 +26,10 @@ export class KeepTogetherElement extends PDFElement {
         this.warnedBreakConflict = false;
         this.child = child;
     }
+    /** Layout-transparent: the floor is whatever the wrapped child needs. */
+    minIntrinsicMain(horizontal, ctx) {
+        return this.child.minIntrinsicMain(horizontal, ctx);
+    }
     calculateLayout(constraints, offset, ctx) {
         return this.child.calculateLayout(constraints, offset, ctx);
     }

package/dist/elements/layout/padding-element.d.ts

@@ -1,8 +1,10 @@
 import { PDFElement, LayoutContext, WithChild, SizedPDFElement } from "../pdf-element.js";
 import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
 import { Fragmentable, FragmentResult } from "../../layout/fragmentation.js";
+import { type EdgeSpecs } from "../../layout/insets.js";
 interface PaddingElementParams extends WithChild {
-    margin: [number, number, number, number];
+    /** Still unresolved: a side may be a percentage of the offered WIDTH (see `Insets`). */
+    margin: EdgeSpecs;
 }
 export declare class PaddingElement extends SizedPDFElement implements Fragmentable {
     private child;
@@ -19,13 +21,18 @@ export declare class PaddingElement extends SizedPDFElement implements Fragmenta
     breaksBefore(): boolean;
     breaksAfter(): boolean;
     private cloneWithChild;
+    /**
+     * The child plus our own insets. A PERCENTAGE inset counts as zero here: it resolves against a width
+     * that is not decided yet, which is exactly how CSS treats a percentage when sizing intrinsically.
+     */
+    minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     getProps(): {
         x: number;
         y: number;
         width: number | undefined;
         height: number | undefined;
-        margin: [number, number, number, number];
+        margin: EdgeSpecs;
         child: PDFElement;
     };
 }

package/dist/elements/layout/padding-element.js

@@ -2,6 +2,7 @@ import { Validator } from "../../validators/element-validator.js";
 import { SizedPDFElement } from "../pdf-element.js";
 import { BoxConstraints } from "../../layout/box-constraints.js";
 import { isFragmentable } from "../../layout/fragmentation.js";
+import { resolveEdges } from "../../layout/insets.js";
 export class PaddingElement extends SizedPDFElement {
     constructor({ margin, child }) {
         super({ x: 0, y: 0 });
@@ -18,7 +19,7 @@ export class PaddingElement extends SizedPDFElement {
         if (!isFragmentable(this.child)) {
             return { fitted: null, remainder: this };
         }
-        const [marginTop, marginRight, marginBottom, marginLeft] = this.margin;
+        const [marginTop, marginRight, marginBottom, marginLeft] = resolveEdges(this.margin, width);
         const childWidth = width - marginLeft - marginRight;
         const childMaxHeight = maxHeight - marginTop - marginBottom;
         const split = this.child.fragment(childMaxHeight, childWidth, ctx);
@@ -42,13 +43,22 @@ export class PaddingElement extends SizedPDFElement {
     cloneWithChild(child) {
         return new PaddingElement({ margin: this.margin, child });
     }
+    /**
+     * The child plus our own insets. A PERCENTAGE inset counts as zero here: it resolves against a width
+     * that is not decided yet, which is exactly how CSS treats a percentage when sizing intrinsically.
+     */
+    minIntrinsicMain(horizontal, ctx) {
+        const [top, right, bottom, left] = resolveEdges(this.margin, 0);
+        return (this.child.minIntrinsicMain(horizontal, ctx) + (horizontal ? left + right : top + bottom));
+    }
     calculateLayout(constraints, offset, ctx) {
         // Padding takes the width it is offered; its height shrink-wraps the child.
         if (constraints.hasBoundedWidth)
             this.width = constraints.maxWidth;
         this.x = offset.x;
         this.y = offset.y;
-        const [marginTop, marginRight, marginBottom, marginLeft] = this.margin;
+        // Percentages resolve against the width we were OFFERED, so every pass gets the same answer.
+        const [marginTop, marginRight, marginBottom, marginLeft] = resolveEdges(this.margin, constraints.maxWidth);
         // The child is inset by the margins: shifted down/right, narrowed by the
         // horizontal margins, and left height-unbounded so it sizes to its own content.
         const childOffset = {

package/dist/elements/layout/page-builder-element.js

@@ -27,6 +27,8 @@ export class PageBuilderElement extends PDFElement {
         return (ctx.pageInfo ?? {
             pageNumber: 1,
             pageCount: 1,
+            subPageNumber: 1,
+            subPageTotalPages: 1,
             pageSize: resolvePageSize(ctx.pageConfig),
         });
     }

package/dist/elements/layout/struct-group.d.ts

@@ -16,6 +16,8 @@ export declare class StructGroup extends PDFElement implements Fragmentable {
         role: string;
         child: PDFElement;
     });
+    /** Layout-transparent: the floor is whatever the wrapped child needs. */
+    minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     /** Only splittable when the wrapped child is - so a StructGroup(Row) is moved whole to the next page,
      *  not clipped at the boundary (isFragmentable honours this veto). */

package/dist/elements/layout/struct-group.js

@@ -14,6 +14,10 @@ export class StructGroup extends PDFElement {
         this.role = role;
         this.child = child;
     }
+    /** Layout-transparent: the floor is whatever the wrapped child needs. */
+    minIntrinsicMain(horizontal, ctx) {
+        return this.child.minIntrinsicMain(horizontal, ctx);
+    }
     calculateLayout(constraints, offset, ctx) {
         return this.child.calculateLayout(constraints, offset, ctx);
     }

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

@@ -3,6 +3,7 @@ import type { PDFPageConfig } from "./page-element.js";
 import type { ResolvedTextStyle } from "../text/text-style.js";
 import type { OverflowPolicy } from "../layout/fragmentation.js";
 import type { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
+import type { CrossAlign } from "../layout/alignment.js";
 /**
  * Everything the layout pass needs, threaded explicitly (no global singleton):
  * font metrics for measuring, and the geometry of the page currently being laid out.
@@ -29,8 +30,18 @@ export interface PositioningFrame {
  * the document's final physical page total. `pageSize` is the media box in points, orientation applied.
  */
 export interface PageInfo {
+    /** 1-based, counting PHYSICAL pages across the whole document. */
     pageNumber: number;
+    /** Physical pages in the whole document. */
     pageCount: number;
+    /**
+     * 1-based within the LOGICAL page this sheet came from - the `Page(...)` element the author wrote.
+     * A document of one `Page` has `subPageNumber === pageNumber`; a document of several (an invoice
+     * plus its attachment, say) restarts the count at each one.
+     */
+    subPageNumber: number;
+    /** Physical pages this logical page produced. */
+    subPageTotalPages: number;
     pageSize: {
         width: number;
         height: number;
@@ -84,6 +95,17 @@ export declare abstract class PDFElement {
      * the parent hands it the line's bounded main extent instead of `Infinity`. Default: no.
      */
     needsBoundedMain(_horizontal: boolean): boolean;
+    /**
+     * The smallest main-axis extent this element can be squeezed into and still hold its content - CSS's
+     * `min-content` size, which is what an automatic `min-width` resolves to on a flex item. The shrink
+     * pass floors every child at this value, so a line that overflows badly stops squeezing rather than
+     * grinding a paragraph down to one word per line (which would only trade a wide box for a tall one).
+     *
+     * `horizontal` = the width. Default 0: an element with no opinion may be squeezed to nothing, which
+     * is what an empty box or a plain drawing can do without harm. Text and the layout containers
+     * override it; containers recurse, since a Row is only as unsqueezable as its children.
+     */
+    minIntrinsicMain(_horizontal: boolean, _ctx: LayoutContext): number;
     /**
      * Whether this element IS a forced page break (a `PageBreak`). The pagination packer cuts the flow
      * at such a marker: everything before it stays, everything after starts a new page. Default: no.
@@ -108,6 +130,36 @@ export declare abstract class PDFElement {
      * parent packer once this element has been placed whole. Default: no.
      */
     breaksAfter(): boolean;
+    /**
+     * This child's own cross-axis alignment inside its Column / Row (CSS `align-self`), overriding the
+     * container's `align`. Lives on the base element because any child of a stack may set it, not just
+     * the sized ones. `undefined` means "follow the container".
+     */
+    alignSelf?: CrossAlign;
+    /** Sets `alignSelf` and returns the element, so a factory can thread it through in one expression. */
+    withAlignSelf(align: CrossAlign | undefined): this;
+    /**
+     * 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.
+     */
+    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
+     * 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.
+     */
+    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. */
+    withOrder(order: number | undefined): this;
 }
 export declare abstract class SizedPDFElement extends PDFElement {
     protected x: number;
@@ -120,14 +172,32 @@ export declare abstract class SizedPDFElement extends PDFElement {
 export declare abstract class FlexiblePDFElement extends PDFElement {
     protected flex: number;
     protected verticalChildAlignment: VerticalAlignment;
+    /** Points reserved before any leftover is shared out (CSS `flex-basis`); default 0. */
+    protected basis: number;
+    /** The same as a fraction of the line, for `flexBasis: "25%"`. */
+    protected basisFactor?: number;
     constructor(data: FlexibleElement);
     getFlex(): number;
+    /**
+     * The main extent this child starts from, before the leftover is shared out. `lineMain` is what the
+     * line offers its items (its extent minus the gaps), so a percentage basis resolves against the same
+     * base a percentage WIDTH already does - and falls back to 0 on an unbounded axis, where a fraction
+     * has no meaning.
+     */
+    /** Whether a PERCENTAGE basis was given - it resolves to 0 on an unbounded axis, so asking for the
+     *  number alone cannot tell "no basis" from "a basis that does not apply here". */
+    hasBasisFactor(): boolean;
+    getBasis(lineMain: number): number;
 }
 export declare enum HorizontalAlignment {
+    /** CSS `text-align: start` - the side the writing STARTS on: left in `ltr`, right in `rtl`. The
+     *  default, so a right-to-left paragraph begins on the right without anyone asking for it. */
+    start = "START",
     left = "LEFT",
     right = "RIGHT",
     center = "CENTER",
-    block = "BLOCK"
+    /** CSS `text-align: justify` - both edges line up, the last line of a paragraph excepted. */
+    justify = "JUSTIFY"
 }
 export declare enum VerticalAlignment {
     top = "TOP",
@@ -142,6 +212,10 @@ export interface WithChild {
 }
 export interface FlexibleElement {
     flex: number;
+    /** Points reserved before the leftover is shared out (CSS `flex-basis`). */
+    basis?: number;
+    /** The same as a fraction of the line, for `flexBasis: "25%"`. */
+    basisFactor?: number;
     verticalChildAlignment?: VerticalAlignment;
 }
 export interface SizedElement {