@nowline/layout 0.8.6 → 0.9.0

package/src/nodes/group-node.ts

@@ -1,70 +1,30 @@
 // GroupNode — Renderable for a `group { ... }` block. Sequences
-// children inside the group's content area using the same row-pack
-// engine `SwimlaneNode` uses, so an item whose desired start collides
-// with a sibling's `rightEdge`, caption `spillX`, or a slack-arrow
-// corridor bumps to a new row inside the group. The group's reported
-// `box.height` grows with the row stack so parent containers stack
-// against the actual painted extent.
+// children inside the group's body through `sequenceRowTrack`
+// (row-track.ts), the loop `SwimlaneNode` uses, so an item whose desired
+// start collides with a sibling's `rightEdge`, caption `spillX`, or a
+// slack-arrow corridor bumps to a new row inside the group.
 //
-// Filled-style groups paint a title chiclet flush in the upper-left
-// corner of the box; the layout reserves vertical top padding equal
-// to the chiclet height plus a small gutter before the first inner
-// row begins.
-
-import type { EntityProperty, GroupBlock, ItemDeclaration, ParallelBlock } from '@nowline/core';
-import { isItemDeclaration } from '@nowline/core';
-import { deriveItemDurationDays } from '../calendar.js';
-import { propValues } from '../dsl-utils.js';
+// The group is drawn above and around its content, never beside it
+// (specs/true-width-layout.md §3.3): a header band (title, inline-date
+// glyphs, a bracket spanning exactly its dates) over a body padded above
+// and below its rows. Its box spans exactly its children's earliest start
+// and latest end; see `container-header-geometry.ts`.
+
+import type { GroupBlock } from '@nowline/core';
+import { containerChrome } from '../container-header-geometry.js';
+import { propValue, propValues } from '../dsl-utils.js';
 import { computeContainerInlineDatePins, pickInlineDate } from '../inline-date-pin-geometry.js';
-import type { LayoutContext, TrackCursor } from '../layout-context.js';
-import { RowPacker } from '../row-packer.js';
+import type { LayoutContext, LayoutHelpers, TrackCursor } from '../layout-context.js';
+import { resolvePinnedOrSequentialStart } from '../start-rules.js';
 import { resolveStyle } from '../style-resolution.js';
-import {
-    GROUP_BOTTOM_PAD_PX,
-    GROUP_BRACKET_LABEL_OVERHANG_PX,
-    GROUP_TITLE_TAB_GUTTER_PX,
-    GROUP_TITLE_TAB_HEIGHT_PX,
-    ITEM_INSET_PX,
-    MIN_ITEM_WIDTH,
-    TRACK_BLOCK_TAIL_GUTTER_PX,
-} from '../themes/shared.js';
-import type {
-    BoundingBox,
-    PositionedGroup,
-    PositionedItem,
-    PositionedTrackChild,
-} from '../types.js';
-
-export interface GroupNodeDeps {
-    sequenceItem: (
-        child: ItemDeclaration,
-        cursor: TrackCursor,
-        ctx: LayoutContext,
-        ownerOverride?: string,
-    ) => PositionedItem;
-    sequenceOne: (
-        child: ItemDeclaration | GroupBlock | ParallelBlock,
-        cursor: TrackCursor,
-        ctx: LayoutContext,
-    ) => PositionedTrackChild;
-    resolveChildStart: (
-        props: EntityProperty[],
-        seqDefault: number,
-        laneLeftX: number,
-        ctx: LayoutContext,
-    ) => number;
-    newCursor: (x: number, y: number) => TrackCursor;
-    estimateTextWidth: (text: string, fontSize: number) => number;
-    /** Predict the extra vertical height an item's wrapped label-chip
-     *  rows will add to its bar; used to size the row-packer's row
-     *  pitch ahead of the call to `sequenceItem`. */
-    predictItemChipExtraHeight: (item: ItemDeclaration, ctx: LayoutContext) => number;
-}
+import type { BoundingBox, PositionedGroup } from '../types.js';
+import { waveFloorX } from '../wave-layout.js';
+import { sequenceRowTrack } from './row-track.js';
 
 export class GroupNode {
     constructor(
         public readonly node: GroupBlock,
-        private readonly deps: GroupNodeDeps,
+        private readonly helpers: LayoutHelpers,
     ) {}
 
     get id(): string {
@@ -72,18 +32,41 @@ export class GroupNode {
     }
 
     /**
-     * Sequence children inside the group's content area, advance the
-     * parent `cursor` past the group's right edge plus
-     * `TRACK_BLOCK_TAIL_GUTTER_PX` of breathing room, and return a
-     * `PositionedGroup` whose `box.height` covers the chiclet pad,
-     * every row-packed child row, and the bottom pad.
+     * Sequence children inside the group's body, advance the parent
+     * `cursor` to the group's end in time (its children's duration ends,
+     * never a caption spill or a header title), and return a
+     * `PositionedGroup` whose box covers the header, the padded rows and
+     * the group's dates.
      */
     place(cursor: TrackCursor, ctx: LayoutContext): PositionedGroup {
         const { node } = this;
-        const { deps } = this;
+        const { helpers } = this;
         const style = resolveStyle('group', node.properties, ctx.styleCtx);
-        const startX = cursor.x;
-        const title = node.title ?? node.name;
+        // The group starts after every `after:` term, then its own wave and
+        // its lead wave floor it, so its box never opens in a column before
+        // its first piece of work (specs/waves.md §5.1). A lane child's
+        // cursor already sits there (`resolveChildStart`), so this is the
+        // identity for it; a parallel's group track starts at the parallel's
+        // start, so this is where its `after:` applies
+        // (specs/scheduler-unification.md §8 decision 5).
+        const startX = waveFloorX(
+            node,
+            resolvePinnedOrSequentialStart(node.properties, cursor.x, ctx),
+            ctx,
+        );
+        // In a roadmap with waves, a group with no title, no `style:` and
+        // no `labels:` that carries `wave:` only assigns membership: it
+        // draws nothing, which would otherwise sit exactly on the wave
+        // boundary its box opens at, and reserves nothing
+        // (specs/waves.md §9.7). An id alone does not make it titled
+        // (Example 4's `api-track`).
+        const waveOnly =
+            ctx.waves !== undefined &&
+            node.title === undefined &&
+            propValue(node.properties, 'wave') !== undefined &&
+            propValue(node.properties, 'style') === undefined &&
+            propValues(node.properties, 'labels').length === 0;
+        const title = waveOnly ? undefined : (node.title ?? node.name);
 
         // Group children chain in time inside the group, so they
         // form one sub-flow under the parent's flow path. See
@@ -91,170 +74,65 @@ export class GroupNode {
         const previousFlowKey = ctx.currentFlowKey;
         ctx.nextGroupId += 1;
         ctx.currentFlowKey = `${previousFlowKey}/group:${node.name ?? `group-${ctx.nextGroupId}`}`;
-        // Mirrors `renderGroup`'s `hasFill` decision so the painted box
-        // and the layout's reservation agree on whether a chiclet exists.
-        const hasChiclet = style.bg !== 'none' && style.bg !== '#ffffff' && Boolean(title);
-        const topPad = hasChiclet ? GROUP_TITLE_TAB_HEIGHT_PX + GROUP_TITLE_TAB_GUTTER_PX : 0;
-        const bottomPad = hasChiclet ? GROUP_BOTTOM_PAD_PX : 0;
-        // Bracket-style groups paint their label at `box.y - 2`, so the
-        // label glyph overhangs ABOVE box.y. Without an explicit
-        // reservation, two bracket-titled groups stacked in a parallel
-        // collide: the previous sibling's bracket-foot ends at its
-        // box.bottom, and the next sibling's label visual top sits just
-        // above box.y — they touch in the gap. Shift `box.y` down by
-        // the overhang amount so the glyph lands in space we own.
-        const bracketLabelOverhang = !hasChiclet && title ? GROUP_BRACKET_LABEL_OVERHANG_PX : 0;
-        const startY = cursor.y + bracketLabelOverhang;
-
-        const step = ctx.bandScale.step();
-        const groupContentLeftX = startX;
-        const packer = new RowPacker({
-            laneLeftX: groupContentLeftX,
-            originY: startY + topPad,
-            minRowHeight: step,
-            slackCorridors: ctx.slackCorridors,
+        const afterDate = pickInlineDate(propValues(node.properties, 'after'));
+        const beforeDate = pickInlineDate(propValues(node.properties, 'before'));
+        const chrome = containerChrome({
+            drawn: !waveOnly,
+            hasTitle: Boolean(title),
+            hasPins: Boolean(afterDate || beforeDate),
+            hasBracket: style.bracket !== 'none',
         });
-        let timeCursorX = groupContentLeftX;
-
-        const children: PositionedTrackChild[] = [];
-        for (const child of node.content) {
-            if (child.$type === 'DescriptionDirective') continue;
-
-            if (!isItemDeclaration(child)) {
-                const blockProps = (child as ParallelBlock | GroupBlock).properties ?? [];
-                const blockStart = deps.resolveChildStart(
-                    blockProps,
-                    timeCursorX,
-                    groupContentLeftX,
-                    ctx,
-                );
-                const { rowIndex, y: blockY } = packer.placeBlock();
-                const innerCursor = deps.newCursor(blockStart, blockY);
-                const positioned = deps.sequenceOne(
-                    child as ItemDeclaration | GroupBlock | ParallelBlock,
-                    innerCursor,
-                    ctx,
-                );
-                children.push(positioned);
-                const blockEnd = positioned.box.x + positioned.box.width;
-                const blockHeight = Math.max(step, innerCursor.height);
-                packer.commitBlock({
-                    rowIndex,
-                    placed: positioned,
-                    blockHeight,
-                    blockEnd,
-                });
-                timeCursorX = Math.max(timeCursorX, blockEnd);
-                continue;
-            }
-
-            const props = (child as ItemDeclaration).properties;
-            const desiredStart = deps.resolveChildStart(props, timeCursorX, groupContentLeftX, ctx);
-            // Predict logical extent so the row-packer can bump on
-            // collision before we hand off to `sequenceItem`. Mirrors
-            // SwimlaneNode's pre-flight width math.
-            const durationDays = deriveItemDurationDays(props, ctx.sizes, ctx.cal);
-            const naturalWidth = Math.max(MIN_ITEM_WIDTH, durationDays * ctx.timeline.pixelsPerDay);
-            const desiredEnd = desiredStart + naturalWidth;
-            const childId = (child as ItemDeclaration).name ?? '';
-
-            const chipExtra = deps.predictItemChipExtraHeight(child as ItemDeclaration, ctx);
-            const predictedHeight = step + chipExtra;
-            const { rowIndex, y: rowY } = packer.placeItem({
-                childId,
-                desiredStart,
-                desiredEnd,
-                // Row pitch = `step()` + extra chip-row height. Keeps
-                // the inter-row visible gap (= step - bandwidth) intact
-                // when an item's labels wrap and grow the bar.
-                predictedHeight,
-            });
 
-            const innerCursor = deps.newCursor(desiredStart, rowY);
-            const positioned = deps.sequenceItem(child as ItemDeclaration, innerCursor, ctx);
-            children.push(positioned);
-
-            const itemLogicalEnd = positioned.box.x + positioned.box.width + ITEM_INSET_PX;
-            timeCursorX = Math.max(timeCursorX, itemLogicalEnd);
-
-            let spillReservation: number | null = null;
-            const hasAnySpill =
-                positioned.textSpills ||
-                positioned.chipsOutside ||
-                positioned.dotSpills ||
-                positioned.iconSpills ||
-                positioned.footnoteSpills;
-            if (hasAnySpill) {
-                const farRight = Math.max(
-                    positioned.decorationsRightX,
-                    positioned.chipsOutside ? positioned.chipsRightX : 0,
-                );
-                spillReservation = farRight + 6;
-            }
-
-            packer.commitItem({
-                rowIndex,
-                placed: positioned,
-                logicalEnd: itemLogicalEnd,
-                spillReservation,
-                rowHeight: predictedHeight,
-            });
-        }
-
-        const innerHeight = Math.max(step, packer.usedHeight());
-        // The group's painted box hugs everything its children put on
-        // screen, including caption text that spills past a bar's right
-        // edge. `usedRightX` is the rightmost extent any row reached —
-        // either a bar's logical right or a caption's reserved spill —
-        // so the orange tint visually "owns" the spilled title/meta.
-        //
-        // The cursor channel (`cursor.x` / `cursor.maxX`) stays on the
-        // COMPACT `timeCursorX` (bar logical ends only). Bubbling the
-        // wide `visualRightX` upward would propagate through
-        // `ParallelNode.maxRight → parallel.box.width → swimlane
-        // blockEnd → timeCursorX`, pushing every subsequent sibling
-        // right by the spill width — including siblings on entirely
-        // different rows of the parent swimlane. The painted box and
-        // the logical cursor advance are intentionally decoupled here.
-        const visualRightX = Math.max(timeCursorX, packer.usedRightX());
+        const track = sequenceRowTrack(
+            node,
+            { leftX: startX, firstRowY: cursor.y + chrome.header + chrome.pad },
+            ctx,
+            helpers,
+        );
+        const { children, timeCursorX, timeStartX } = track;
+
+        // Every row's height carries the inter-row gap below it; the body
+        // ends `pad` below the last child's painted bottom, not below that
+        // gap, and the cursor adds the gap back after the body so a sibling
+        // stacked below keeps the same rhythm as two items.
+        const step = ctx.bandScale.step();
+        const interRowGap = step - ctx.bandScale.bandwidth();
+        const contentHeight = Math.max(step, track.packer.usedHeight()) - interRowGap;
+        // The bracket and body span exactly the children's dates
+        // (specs/true-width-layout.md §3.3): what the group paints past them
+        // (a spilled caption, its title) is footprint the row packer keeps,
+        // not width.
         const box: BoundingBox = {
-            x: startX,
-            y: startY,
-            width: visualRightX - startX,
-            height: topPad + innerHeight + bottomPad,
+            x: timeStartX,
+            y: cursor.y,
+            width: timeCursorX - timeStartX,
+            height: chrome.header + chrome.pad + contentHeight + chrome.pad,
         };
-        cursor.x = timeCursorX + TRACK_BLOCK_TAIL_GUTTER_PX;
-        cursor.maxX = Math.max(cursor.maxX, cursor.x);
-        // The painted `box.height` is the group's tight visual
-        // footprint (chiclet + content + bottomPad). The cursor
-        // advance, however, must include one inter-row gap
-        // (`step - bandwidth`) so a sibling stacked below in a
-        // `parallel` (or any track-pack consumer) doesn't butt
-        // right up against the group's bottom edge. Items naturally
-        // include that gap because they report `cursor.height = step`
-        // (bandwidth + gap); groups need to add it explicitly since
-        // their painted height is gap-less.
-        const interRowGap = ctx.bandScale.step() - ctx.bandScale.bandwidth();
-        cursor.height = Math.max(cursor.height, bracketLabelOverhang + box.height + interRowGap);
+        // A parallel joins on its tracks' ends, as engine C does
+        // (specs/scheduler-unification.md §8 decision 8).
+        cursor.startX = box.x;
+        cursor.x = timeCursorX;
+        cursor.height = Math.max(cursor.height, box.height + interRowGap);
         const id = node.name;
+        // `after:` the group is a time path: its last child's duration end.
         if (id) {
             ctx.entityLeftEdges.set(id, box.x);
-            ctx.entityRightEdges.set(id, box.x + box.width);
+            ctx.entityRightEdges.set(id, timeCursorX);
         }
         ctx.currentFlowKey = previousFlowKey;
-        const inlineDatePins = computeContainerInlineDatePins({
-            box,
-            afterDate: pickInlineDate(propValues(node.properties, 'after')),
-            beforeDate: pickInlineDate(propValues(node.properties, 'before')),
-        });
+        const inlineDatePins = waveOnly
+            ? []
+            : computeContainerInlineDatePins({ box, afterDate, beforeDate, title });
         return {
             kind: 'group',
             id,
             title,
             box,
+            headerHeight: chrome.header,
             children,
             style,
             inlineDatePins: inlineDatePins.length > 0 ? inlineDatePins : undefined,
+            ...(waveOnly ? { waveOnly: true as const } : {}),
         };
     }
 }

package/src/nodes/header-node.ts

@@ -0,0 +1,255 @@
+// HeaderNode — the roadmap header (title, author, company logo) in both
+// positions, `beside` (a card left of the chart) and `above` (a band over
+// it). `measure` sizes it before anything else is laid out, because the
+// header decides where the chart starts: its left edge in beside mode,
+// its top in above mode, and how low the header rows must end so the
+// beside card fits (specs/layout-phases.md §3.7).
+//
+// HeaderNode does not implement `Renderable`: that signature is built
+// around a time scale and a row band, which a header has no use for.
+
+import {
+    HEADER_AUTHOR_FONT_SIZE_PX,
+    HEADER_AUTHOR_LINE_HEIGHT_PX,
+    HEADER_CARD_PADDING_BOTTOM,
+    HEADER_CARD_PADDING_TOP,
+    HEADER_CARD_PADDING_X,
+    HEADER_LOGO_GAP_PX,
+    HEADER_LOGO_PAD_Y_PX,
+    HEADER_TITLE_FONT_SIZE_PX,
+    HEADER_TITLE_LINE_HEIGHT_PX,
+    HEADER_TITLE_TO_AUTHOR_GAP_PX,
+} from '../header-card-geometry.js';
+import type { LogoDimensions, ScaledLogo } from '../header-logo.js';
+import { estimateTextWidth, wrapText } from '../text-measure.js';
+import {
+    HEADER_ABOVE_HEIGHT_PX,
+    HEADER_BESIDE_MAX_WIDTH_PX,
+    HEADER_BESIDE_MIN_WIDTH_PX,
+} from '../themes/shared.js';
+import type { BoundingBox, HeaderPosition, PositionedHeader, ResolvedStyle } from '../types.js';
+
+// Left margin between the canvas's left edge and the visible card. The
+// matching right-side breathing room is owned by `GUTTER_PX` (the canonical
+// content gutter, applied between `chartLeftX` and `originX`), so the gap
+// from the card's right edge to the timeline strip is the same as the gap
+// between two adjacent items.
+const HEADER_CARD_OUTER_PAD = 6;
+
+/** Clearance (px) the beside card keeps from the canvas top. */
+const HEADER_CARD_TOP_INSET = 4;
+
+/** Gap (px) between the header (or the canvas top) and the chart. */
+const CHART_TOP_GAP_PX = 8;
+
+export interface MeasuredHeader {
+    position: HeaderPosition;
+    titleLines: string[];
+    authorLines: string[];
+    cardWidth: number;
+    /** Card height, grown when the logo is taller than the text. */
+    cardHeight: number;
+    /** Card height the title / author text alone needs. */
+    textCardHeight: number;
+    /** Width the logo takes left of the text, gap included; 0 without a logo. */
+    logoSlot: number;
+    logo?: ScaledLogo;
+    /** Beside: the card's box width, which is also `chartLeftX`. Above: 0. */
+    chartLeftX: number;
+    /** Above: the band height, bumped for an `xl` logo. Beside never reads it. */
+    aboveHeight: number;
+    /** Where the chart may start: below the canvas top, or below the above band. */
+    chartTopY: number;
+    /** Beside: the lowest the header rows may end so the card fits (card + 4 px inset). Above: 0. */
+    minRowsBottomY: number;
+}
+
+/** The positioned header without its attribution box, which finalize adds last. */
+export type PositionedHeaderParts = Omit<PositionedHeader, 'attributionBox'>;
+
+/** Where the chart ended up, as far as the header needs to know. */
+export interface HeaderFrame {
+    /** Bottom of the header rows; the beside card's bottom hugs it. */
+    rowsBottomY: number;
+    /** Bottom of the chart; the beside header column runs down to it. */
+    chartBottomY: number;
+    /** The final canvas right edge; the above band spans to it. */
+    canvasRightX: number;
+}
+
+export interface HeaderNodeInput {
+    /** The roadmap's title (or name); an empty string when it has neither. */
+    title: string;
+    author?: string;
+    /** The resolved `default roadmap` style; `headerPosition` picks the mode. */
+    style: ResolvedStyle;
+    /** The drawn logo size, when the file declares a logo and the caller loaded one. */
+    logo?: ScaledLogo;
+}
+
+export class HeaderNode {
+    constructor(private readonly input: HeaderNodeInput) {}
+
+    measure(): MeasuredHeader {
+        const { title, author, style, logo } = this.input;
+        const isBeside = style.headerPosition === 'beside';
+        // Pre-size the beside-mode header card. Width = max line width +
+        // padding, clamped to MIN..MAX with word-wrap once the title
+        // exceeds MAX. Above mode keeps the fixed-strip geometry (full
+        // canvas width, fixed height) but still reads the wrapped lines.
+        const sized = sizeBesideHeader(title, author, logo);
+        // Above-mode strip: fixed height, bumped only when the logo plus
+        // its clearance is taller (`logo-size:xl`).
+        const aboveHeight = logo
+            ? Math.max(HEADER_ABOVE_HEIGHT_PX, logo.height + 2 * HEADER_LOGO_PAD_Y_PX)
+            : HEADER_ABOVE_HEIGHT_PX;
+        return {
+            position: style.headerPosition,
+            titleLines: sized.titleLines,
+            authorLines: sized.authorLines,
+            cardWidth: sized.cardWidth,
+            cardHeight: sized.cardHeight,
+            textCardHeight: sized.textCardHeight,
+            logoSlot: sized.logoSlot,
+            ...(logo ? { logo } : {}),
+            chartLeftX: isBeside ? sized.boxWidth : 0,
+            aboveHeight,
+            chartTopY: isBeside ? CHART_TOP_GAP_PX : aboveHeight + CHART_TOP_GAP_PX,
+            // In beside mode the card's BOTTOM aligns with the bottom of the
+            // header rows so it visually anchors to the chart's top. The
+            // rows must end low enough for the card plus a 4 px top inset;
+            // the measure phase pushes the timeline down when they would not.
+            minRowsBottomY: isBeside ? sized.cardHeight + HEADER_CARD_TOP_INSET : 0,
+        };
+    }
+
+    /**
+     * The header box, the card, the logo box and the text inset, once the
+     * chart's extent is known. Beside: a column `chartLeftX` wide down to
+     * the chart bottom, with the card's bottom on `rowsBottomY`. Above: a
+     * band `aboveHeight` tall across the canvas, the card filling it.
+     */
+    place(measured: MeasuredHeader, frame: HeaderFrame): PositionedHeaderParts {
+        const { title, author, style } = this.input;
+        const isBeside = measured.position === 'beside';
+        const box: BoundingBox = isBeside
+            ? { x: 0, y: 0, width: measured.chartLeftX, height: frame.chartBottomY }
+            : { x: 0, y: 0, width: frame.canvasRightX, height: measured.aboveHeight };
+        // The visible card inside the box. Beside, its BOTTOM hugs the
+        // bottom of the header rows so the title block anchors to the
+        // chart's top edge whichever header rows are present; the measure
+        // phase already pushed the rows down far enough for the card to
+        // keep HEADER_CARD_TOP_INSET from the canvas top.
+        const cardBox: BoundingBox = isBeside
+            ? {
+                  x: HEADER_CARD_OUTER_PAD,
+                  y: frame.rowsBottomY - measured.cardHeight,
+                  width: measured.cardWidth,
+                  height: measured.cardHeight,
+              }
+            : { x: 0, y: 0, width: frame.canvasRightX, height: measured.aboveHeight };
+        // Logo at the card's left padding, vertically centered; the text
+        // shifts right past it and centers in the (possibly taller) card.
+        let logo: PositionedHeader['logo'];
+        let textInset: PositionedHeader['textInset'];
+        if (measured.logo) {
+            logo = {
+                box: {
+                    x: box.x + cardBox.x + HEADER_CARD_PADDING_X,
+                    y: box.y + cardBox.y + (cardBox.height - measured.logo.height) / 2,
+                    width: measured.logo.width,
+                    height: measured.logo.height,
+                },
+                assetRef: measured.logo.assetRef,
+                intrinsic: measured.logo.intrinsic,
+            };
+            textInset = {
+                x: measured.logoSlot,
+                y: Math.max(0, (cardBox.height - measured.textCardHeight) / 2),
+            };
+        }
+        return {
+            box,
+            position: style.headerPosition,
+            title,
+            author,
+            titleLines: measured.titleLines,
+            authorLines: measured.authorLines,
+            cardBox,
+            logo,
+            ...(textInset ? { textInset } : {}),
+            style,
+        };
+    }
+}
+
+/** Sized output from the beside-mode header word-wrap pass. */
+interface SizedHeader {
+    titleLines: string[];
+    authorLines: string[];
+    cardWidth: number;
+    cardHeight: number;
+    textCardHeight: number;
+    logoSlot: number;
+    boxWidth: number;
+}
+
+function sizeBesideHeader(
+    title: string,
+    author: string | undefined,
+    logo?: LogoDimensions,
+): SizedHeader {
+    const maxContentWidth = HEADER_BESIDE_MAX_WIDTH_PX - 2 * HEADER_CARD_PADDING_X;
+    const titleLines = wrapText(title, maxContentWidth, HEADER_TITLE_FONT_SIZE_PX);
+    const authorLines = wrapText(author ?? '', maxContentWidth, HEADER_AUTHOR_FONT_SIZE_PX);
+
+    let widest = 0;
+    for (const line of titleLines)
+        widest = Math.max(widest, estimateTextWidth(line, HEADER_TITLE_FONT_SIZE_PX));
+    for (const line of authorLines)
+        widest = Math.max(widest, estimateTextWidth(line, HEADER_AUTHOR_FONT_SIZE_PX));
+
+    // A logo sits left of the text and widens the card past the text-only
+    // MAX clamp (which bounds the text column, not the logo slot).
+    const hasText = titleLines.length > 0 || authorLines.length > 0;
+    const logoSlot = logo ? logo.width + (hasText ? HEADER_LOGO_GAP_PX : 0) : 0;
+
+    const naturalCardWidth = widest + 2 * HEADER_CARD_PADDING_X;
+    // `HEADER_BESIDE_{MIN,MAX}_WIDTH_PX` bound the **boxWidth** (= cardWidth
+    // + left outer pad). Subtract one outer pad to derive the cardWidth
+    // bounds.
+    const cardWidth = Math.max(
+        HEADER_BESIDE_MIN_WIDTH_PX - HEADER_CARD_OUTER_PAD,
+        Math.min(HEADER_BESIDE_MAX_WIDTH_PX - HEADER_CARD_OUTER_PAD, naturalCardWidth) + logoSlot,
+    );
+
+    const titleBlockHeight =
+        titleLines.length > 0 ? (titleLines.length - 1) * HEADER_TITLE_LINE_HEIGHT_PX : 0;
+    const authorBlockHeight =
+        authorLines.length > 0
+            ? HEADER_TITLE_TO_AUTHOR_GAP_PX +
+              (authorLines.length - 1) * HEADER_AUTHOR_LINE_HEIGHT_PX
+            : 0;
+    const textCardHeight =
+        HEADER_CARD_PADDING_TOP + titleBlockHeight + authorBlockHeight + HEADER_CARD_PADDING_BOTTOM;
+    // A logo taller than the text block grows the card; logo and text are
+    // then both centered vertically.
+    const cardHeight = logo
+        ? Math.max(textCardHeight, logo.height + 2 * HEADER_LOGO_PAD_Y_PX)
+        : textCardHeight;
+
+    // `boxWidth` only includes the LEFT outer pad — the right-side breathing
+    // room between the card and the chart is owned by `GUTTER_PX` in the
+    // measure phase. So `boxWidth` doubles as `chartLeftX` (the card's right
+    // edge in canvas coordinates).
+    const boxWidth = cardWidth + HEADER_CARD_OUTER_PAD;
+    return {
+        titleLines,
+        authorLines,
+        cardWidth,
+        cardHeight,
+        textCardHeight,
+        logoSlot,
+        boxWidth,
+    };
+}