@nowline/layout 0.8.6 → 0.10.0

package/src/phases/measure.ts

@@ -0,0 +1,329 @@
+// Phase 2, measure (specs/layout-phases.md §3.3): everything the chart is
+// laid out around, sized before any lane is placed. The header (its card
+// fixes the chart's left edge and top), pixels per day and the natural
+// time scale, the header rows above the chart (now-pill row, tick panel,
+// wave strip, marker band) and the timeline of the natural window.
+//
+// The marker band is an estimate: floating milestones get their x only
+// from placement, and an extended axis can add calendar runs, so finalize
+// packs every marker again (f5) and grows the band when it needs more
+// rows (f7). Nothing here reads placement state.
+
+import type { NowlineFile, ResolveResult } from '@nowline/core';
+import { cappedPixelsPerDay } from '../canvas-width.js';
+import { propValue } from '../dsl-utils.js';
+import { resolveHeaderLogo } from '../header-logo.js';
+import type { LayoutOptions } from '../layout.js';
+import { HeaderNode, type MeasuredHeader } from '../nodes/header-node.js';
+import {
+    calendarMarkerEntries,
+    type DatePinnedMarker,
+    datePinnedMarkerEntries,
+    markerLabelsRightX,
+    markerRowPlacements,
+    packMarkerRow,
+} from '../nodes/marker-band.js';
+import { MARKER_ROW_CENTER_OFFSET_PX, MARKER_ROW_PITCH_PX } from '../nodes/marker-geometry.js';
+import { hasVisibleWaves } from '../schedule.js';
+import { resolveStyle } from '../style-resolution.js';
+import { estimateTextWidth } from '../text-measure.js';
+import {
+    GUTTER_PX,
+    HEADER_HEIGHT_PX,
+    NOW_PILL_HEIGHT_PX,
+    WAVE_STRIP_HEIGHT_PX,
+} from '../themes/shared.js';
+import { TimeScale } from '../time-scale.js';
+import type { MarkerRowPlacement, PositionedTimelineScale } from '../types.js';
+import {
+    buildHeaderTicks,
+    buildNonWorkingRuns,
+    buildWorkingExceptions,
+    type ViewPreset,
+} from '../view-preset.js';
+import type { DateWindow, RoadmapScope } from './date-window.js';
+
+/** Gap (px) between the header rows and the chart top. */
+const HEADER_ROWS_TO_CHART_GAP_PX = 8;
+
+export interface MeasuredRoadmap {
+    header: MeasuredHeader;
+    /** The node that measured the header; finalize places it (f15). */
+    headerNode: HeaderNode;
+    /** The natural axis. f2 keeps `originX` and `ppd` when it extends the scale. */
+    axis: { originX: number; ppd: number; naturalWidth: number; scale: TimeScale };
+    /** The canvas right edge before anything grows it: the natural axis plus a gutter. */
+    naturalChartRightX: number;
+    bands: HeaderBands;
+    /** Ticks and calendar runs for the natural window; f2 refreshes them. */
+    timeline: PositionedTimelineScale;
+    markers: MarkerEstimate;
+}
+
+/** The rows above the chart, top to bottom, and where the chart starts. */
+export interface HeaderBands {
+    timelineY: number;
+    /**
+     * The now-pill row, reserved here when `today` falls inside the natural
+     * window. When the axis extension (f2) brings `today` in, f7 reserves it.
+     */
+    pillRowHeight: number;
+    tickPanelY: number;
+    tickPanelHeight: number;
+    waveStripY: number;
+    markerRowY: number;
+    /** Rows the pre-pack needed. f7 grows the band when the final pack needs more. */
+    estimatedMarkerRows: number;
+    /** Height of the rows above: pill row, tick panel, wave strip, estimated marker band. */
+    rowsHeight: number;
+    chartTopY: number;
+    /** Height of the mirrored bottom tick panel (f8); 0 when there is none. */
+    bottomTickPanelHeight: number;
+}
+
+export interface MarkerEstimate {
+    /** Date-pinned anchors and milestones with their x; they seed the entity edges. */
+    datePinned: ReadonlyArray<DatePinnedMarker>;
+    /** Pre-pack placements, already at the band's y. */
+    placements: ReadonlyMap<string, MarkerRowPlacement>;
+    /**
+     * Whether the band is drawn at all: the roadmap declares an anchor or a
+     * milestone, or the natural window holds a titled run or a working
+     * exception.
+     */
+    hasEntities: boolean;
+}
+
+export function measureRoadmap(
+    file: NowlineFile,
+    resolved: ResolveResult,
+    options: LayoutOptions,
+    scope: RoadmapScope,
+    window: DateWindow,
+): MeasuredRoadmap {
+    const { locale, styleCtx } = scope;
+    const { calendar, preset: scale, startDate, timelineDays, nonWorking } = window;
+    const endDate = window.naturalEndDate;
+    // Waves only draw when one has items (specs/waves.md §9.1).
+    const plan = hasVisibleWaves(window.schedule) ? window.schedule.plan : undefined;
+    const headerStyle = scope.roadmapStyle;
+
+    // `top` (default) keeps the legacy single-strip header; `bottom`
+    // suppresses the top tick panel (now-pill and marker row stay
+    // at the top because anchors / milestones live there); `both`
+    // mirrors the strip at the chart bottom too. See specs/dsl.md
+    // and specs/rendering.md § Timeline Scale.
+    // `header-height` sizes every tick panel (top and mirrored bottom);
+    // `none` drops them all, whatever `timeline-position` asks for.
+    const tickPanelBucketHeight =
+        HEADER_HEIGHT_PX[headerStyle.headerHeight as keyof typeof HEADER_HEIGHT_PX] ??
+        HEADER_HEIGHT_PX.md;
+    const showTopTickPanel = tickPanelBucketHeight > 0 && headerStyle.timelinePosition !== 'bottom';
+    const showBottomTickPanel =
+        tickPanelBucketHeight > 0 &&
+        (headerStyle.timelinePosition === 'bottom' || headerStyle.timelinePosition === 'both');
+
+    // Measure the header: the beside card's size or the above band's
+    // height, which fix the chart's left edge and top. The company logo
+    // (when the caller loaded one) widens the card by its slot and can
+    // make it taller; see header-logo.ts.
+    const titleStr = file.roadmapDecl?.title ?? file.roadmapDecl?.name ?? '';
+    const authorStr = propValue(file.roadmapDecl?.properties ?? [], 'author');
+    const headerNode = new HeaderNode({
+        title: titleStr,
+        author: authorStr,
+        style: headerStyle,
+        logo: resolveHeaderLogo(file, options.logo),
+    });
+    const measuredHeader = headerNode.measure();
+    const { chartLeftX } = measuredHeader;
+
+    // The chart sizes to natural content width (date window × ppd) plus
+    // chrome padding. `options.width`, when set, is a best-effort
+    // maximum canvas width: it shrinks ppd (never below
+    // `MIN_PIXELS_PER_DAY`) so header card + gutters + timeline fit,
+    // but caption spills and run labels can still grow the canvas
+    // past it in finalize. The two `GUTTER_PX` insets keep the header
+    // card and attribution wordmark from butting against the canvas edges.
+    const ppd = cappedPixelsPerDay({
+        naturalPixelsPerDay: scale.pixelsPerUnit / calendar.daysPerUnit(scale.unit),
+        dayCount: timelineDays,
+        chromeWidth: chartLeftX + 2 * GUTTER_PX,
+        maxWidth: options.width,
+    });
+    const naturalWidth = timelineDays * ppd;
+    const originX = chartLeftX + GUTTER_PX;
+    const totalChartWidth = naturalWidth;
+
+    // Header layout (top → bottom):
+    //   1. Now-pill row    (16 px) — only when there's a now-line
+    //   2. Tick-label panel (`header-height`, 24 px at md) — unless
+    //      `timeline-position:bottom` or `header-height:none`
+    //   3. Wave strip      (20 px) — only when the roadmap declares waves
+    //   4. Marker row       (≥26 px) — sized to the packed row count
+    //   5. 8 px gap, then the chart begins
+    const willHaveNowline =
+        options.today !== undefined && options.today >= startDate && options.today <= endDate;
+    const pillRowHeight = willHaveNowline ? NOW_PILL_HEIGHT_PX : 0;
+    // When `timeline-position:bottom` or `header-height:none` is set,
+    // the top tick panel collapses to height 0 — the now-pill and
+    // marker row stack directly without the date strip between them.
+    const tickPanelHeight = showTopTickPanel ? tickPanelBucketHeight : 0;
+    // The wave strip (specs/waves.md §8.8) has a fixed height, so the
+    // chart top is known before the barrier passes run; it sits above
+    // the marker rows, so the post-hoc marker re-pack never moves it.
+    const waveStripHeight = plan ? WAVE_STRIP_HEIGHT_PX : 0;
+
+    // Build the time scale up front — packMarkerRow needs it to
+    // resolve date-pinned entity x positions before we can size the
+    // marker row band.
+    const timeScale = new TimeScale({
+        domain: [startDate, endDate],
+        range: [originX, originX + naturalWidth],
+        calendar,
+        nonWorking,
+    });
+    // Titled non-working runs and working exceptions join the marker
+    // row (5b). These are provisional: they size the band before the
+    // timeline exists, and their ticks only decide `seam`, which the
+    // labels never read. Finalize re-packs with the final ones.
+    const provisionalRunEntries = calendarMarkerEntries(
+        buildNonWorkingRuns(timeScale, [], scale.unit, false),
+        buildWorkingExceptions(timeScale),
+    );
+    const hasMarkerEntities =
+        resolved.content.anchors.size + resolved.content.milestones.size > 0 ||
+        provisionalRunEntries.length > 0;
+    // Initial canvas extent = natural date window + canonical
+    // gutters. Item caption spills are unknown until the swimlane
+    // pass runs and grow the canvas in finalize. The now-pill doesn't
+    // contribute here — `buildNowline` flips it to flag mode whenever a
+    // centered pill would clip an edge.
+    const naturalChartRightX = originX + totalChartWidth + GUTTER_PX;
+
+    // Resolve each date-pinned anchor and milestone's x. Used both for
+    // the marker-row pack and for `after:` resolution downstream — an
+    // item with `after:kickoff` would otherwise see an empty
+    // entityRightEdges entry and silently fall through to `cursor.x`
+    // (= the chart origin). After-only milestones still resolve later
+    // once their predecessors are known.
+    const datePinnedEntries = datePinnedMarkerEntries(
+        resolved.content.anchors,
+        resolved.content.milestones,
+        timeScale,
+    );
+
+    // Pack the date-pinned markers. Each entity gets a row index
+    // (0 = in-row baseline, 1 = bumped down by one step, …) and a
+    // label box that may be flipped to the LEFT side when the natural
+    // right-side label would overflow the canvas. Earlier
+    // entries claim row 0; later ones drop to row 1+ when their
+    // bounding box (diamond + label) overlaps an already-placed
+    // entry. The renderer reads `labelBox.x/y` directly.
+    // Titled runs and working exceptions pack after the markers. Every
+    // entry packs against
+    // the right edge the post-layout canvas growth will give its label.
+    const preliminaryEntries = [...datePinnedEntries, ...provisionalRunEntries];
+    const packed = packMarkerRow(
+        preliminaryEntries,
+        chartLeftX,
+        markerLabelsRightX(preliminaryEntries, chartLeftX, naturalChartRightX, estimateTextWidth),
+        estimateTextWidth,
+    );
+    const markerRowsCount = hasMarkerEntities ? Math.max(1, packed.rowCount) : 0;
+    const markerRowHeight = markerRowsCount * MARKER_ROW_PITCH_PX;
+    const headerRowsHeight = pillRowHeight + tickPanelHeight + waveStripHeight + markerRowHeight;
+    const timelineHeightBudget = headerRowsHeight + HEADER_ROWS_TO_CHART_GAP_PX;
+    const timelineY = headerRowsTimelineY(measuredHeader, headerRowsHeight);
+    const tickPanelY = timelineY + pillRowHeight;
+    const waveStripY = tickPanelY + tickPanelHeight;
+    const markerRowY = waveStripY + waveStripHeight;
+
+    const ticks = buildHeaderTicks(timeScale, scale, calendar, locale);
+    const timeline: PositionedTimelineScale = {
+        box: { x: originX, y: timelineY, width: naturalWidth, height: 0 },
+        ticks,
+        pixelsPerDay: ppd,
+        originX,
+        startDate,
+        endDate,
+        labelStyle: resolveStyle('roadmap', [], styleCtx),
+        pillRowHeight,
+        tickPanelY,
+        tickPanelHeight,
+        markerRow: {
+            y: markerRowY + MARKER_ROW_CENTER_OFFSET_PX,
+            height: markerRowHeight,
+            collisionY: markerRowY - 8,
+        },
+        // `bottomTickPanelY` / `bottomTickPanelHeight` are filled in by
+        // finalize, AFTER swimlanes + includes are placed (and after the
+        // marker re-pack potentially grows the chart), so the panel sits
+        // directly above the footnote area.
+        minorGrid: headerStyle.minorGrid,
+        ...(plan ? { waveStrip: { y: waveStripY, height: waveStripHeight } } : {}),
+    };
+    setCalendarRuns(timeline, timeScale, scale.unit);
+
+    return {
+        header: measuredHeader,
+        headerNode,
+        axis: { originX, ppd, naturalWidth, scale: timeScale },
+        naturalChartRightX,
+        bands: {
+            timelineY,
+            pillRowHeight,
+            tickPanelY,
+            tickPanelHeight,
+            waveStripY,
+            markerRowY,
+            estimatedMarkerRows: markerRowsCount,
+            rowsHeight: headerRowsHeight,
+            chartTopY: timelineY + timelineHeightBudget,
+            bottomTickPanelHeight: showBottomTickPanel ? tickPanelBucketHeight : 0,
+        },
+        timeline,
+        markers: {
+            datePinned: datePinnedEntries,
+            // AnchorNode and MilestoneNode read these to recover both the y
+            // and the resolved label box; after-only milestones (not
+            // pre-positioned here) take the band's first row until the
+            // final pack.
+            placements: markerRowPlacements(packed.placements, markerRowY),
+            hasEntities: hasMarkerEntities,
+        },
+    };
+}
+
+/**
+ * Where header rows `rowsHeight` tall start (the timeline y). In beside
+ * mode the header card's BOTTOM aligns with the bottom of the header rows
+ * so it visually anchors to the chart's top. When the card is taller than
+ * the rows + a 4 px top inset, push the timeline down so the card has room
+ * without clipping above the canvas.
+ */
+export function headerRowsTimelineY(header: MeasuredHeader, rowsHeight: number): number {
+    return Math.max(header.chartTopY, header.minRowsBottomY - rowsHeight);
+}
+
+/**
+ * Set (or refresh) the timeline's non-working runs from its current ticks,
+ * and its working exceptions. `nonWorkingDisplay` and `nonWorking` stay
+ * omitted when the window holds no non-working day, and `workingExceptions`
+ * when it holds no exception, so a calendar without either keeps its exact
+ * model shape. The extension pass only grows the window, so a refresh never
+ * loses an entry.
+ */
+export function setCalendarRuns(
+    timeline: PositionedTimelineScale,
+    scale: TimeScale,
+    unit: ViewPreset['unit'],
+): void {
+    const runs = buildNonWorkingRuns(scale, timeline.ticks, unit, timeline.minorGrid);
+    if (runs) {
+        timeline.nonWorkingDisplay = scale.showsNonWorking ? 'show' : 'hide';
+        timeline.nonWorking = runs;
+    }
+    const exceptions = buildWorkingExceptions(scale);
+    if (exceptions) timeline.workingExceptions = exceptions;
+}

package/src/phases/place.ts

@@ -0,0 +1,318 @@
+// Phase 3, place (specs/layout-phases.md §3.4): the root context, the
+// entity-edge seeds from the date-pinned markers, the footnote index, the
+// lanes inside the wave barrier driver (P1), the corridor rerun (P2), the
+// kept isolated regions (P4), the chart bottom (P5) and the milestones (P6).
+//
+// Placement never reads the canvas: lanes leave their width to finalize,
+// regions are fitted only there, and milestones get their marker row and
+// label box from the final pack. It places on the natural scale, which
+// finalize may extend but never re-places on.
+//
+// Placement lays the chart out in local coordinates, with its top at y 0:
+// lanes, regions, milestone cut lines and slack arrows. The chart's top on
+// the canvas is known only once the header rows above it stop growing, so
+// finalize translates the whole chart there, once (f7).
+
+import type { ResolveResult, SwimlaneDeclaration } from '@nowline/core';
+import { AxisColumns } from '../axis-columns.js';
+import { defaultRowBand } from '../band-scale.js';
+import { localeStrings } from '../i18n.js';
+import { createLayoutContext, type LayoutContext, type LayoutHelpers } from '../layout-context.js';
+import { indexFootnotes } from '../nodes/footnote-node.js';
+import { buildIncludeRegions } from '../nodes/include-node.js';
+import {
+    buildMilestones,
+    collectSlackCorridors,
+    type MilestonePlacement,
+} from '../nodes/milestone-node.js';
+import { SwimlaneNode } from '../nodes/swimlane-node.js';
+import { hasVisibleWaves, type RoadmapSchedule } from '../schedule.js';
+import { isScheduleWarmStart } from '../start-rules.js';
+import { resolveStyle } from '../style-resolution.js';
+import { SPACING_PX } from '../themes/shared.js';
+import type { TimeScale } from '../time-scale.js';
+import type { PositionedIncludeRegion, PositionedRoadmap, PositionedSwimlane } from '../types.js';
+import { solveWaveBarriers, type WaveBarrierSeed } from '../wave-barrier.js';
+import {
+    beginWavePass,
+    createWaveLayoutState,
+    freezeWaves,
+    seedWaveEdges,
+    WAVE_EDGE_TOLERANCE_PX,
+} from '../wave-layout.js';
+import type { DateWindow, RoadmapScope } from './date-window.js';
+import type { MeasuredRoadmap } from './measure.js';
+
+/** Gap (px) between the last lane and the first isolated region's tab. */
+const LANES_TO_REGIONS_GAP_PX = 8;
+
+/** A placed chart, every y in the chart's local frame (top at 0) until f7 translates it. */
+export interface PlacedChart {
+    /** Entity maps and placed items of the kept pass; finalize reads them, never writes placements. */
+    ctx: LayoutContext;
+    swimlanes: PositionedSwimlane[];
+    includes: PositionedIncludeRegion[];
+    /**
+     * Each kept region's own context, in `includes` order: its placed
+     * items and marker edges, which its dependency edges read (f11).
+     */
+    regionContexts: LayoutContext[];
+    /** x, slack arrows and overrun; f6 adds the row and label box and builds `PositionedMilestone`. */
+    milestones: MilestonePlacement[];
+    laneEntries: SwimlaneDeclaration[];
+    /** Rightmost bar or spilled caption of the kept lane pass. */
+    maxRightX: number;
+    /** Bottom of the last lane or region (P5). */
+    bottomY: number;
+    waveSolve?: PositionedRoadmap['waveSolve'];
+}
+
+export function placeChart(
+    resolved: ResolveResult,
+    scope: RoadmapScope,
+    window: DateWindow,
+    measured: MeasuredRoadmap,
+    helpers: LayoutHelpers,
+): PlacedChart {
+    const { theme, styleCtx } = scope;
+    const { cal, calendar, schedule } = window;
+    const plan = schedule.plan;
+    const { originX, scale: timeScale } = measured.axis;
+    const { timeline } = measured;
+
+    // Footnotes index must exist before sequencing items reference
+    // them.
+    const ctx = createLayoutContext(
+        resolved,
+        {
+            theme,
+            cal,
+            schedule,
+            timeline,
+            scale: timeScale,
+            calendar,
+            axisColumns: new AxisColumns(window, timeScale),
+            bandScale: defaultRowBand(),
+            waves: plan
+                ? createWaveLayoutState(
+                      plan,
+                      timeScale,
+                      originX,
+                      localeStrings(scope.locale).waveBackgroundItem,
+                      hasVisibleWaves(schedule),
+                  )
+                : undefined,
+        },
+        {
+            chartTopY: 0,
+            chartBottomY: 0,
+            swimlaneBottomY: 0,
+        },
+        {
+            footnotes: indexFootnotes(resolved.content.footnotes),
+            // A copy: the final pack (P10) replaces the context's
+            // placements, and the estimate stays as measured.
+            markerRowPlacements: new Map(measured.markers.placements),
+        },
+    );
+
+    // Seed the entity-edge maps from the date-pinned pack so item
+    // `after:kickoff` references resolve before swimlanes run. Mid
+    // points use the row-aware centerY so dependency arrows from the
+    // anchor land on the diamond's actual row.
+    for (const e of measured.markers.datePinned) {
+        const placement = ctx.markerRowPlacements.get(e.id);
+        if (!placement) continue;
+        ctx.entityLeftEdges.set(e.id, e.centerX);
+        ctx.entityRightEdges.set(e.id, e.centerX);
+        ctx.entityMidpoints.set(e.id, { x: e.centerX, y: placement.centerY });
+    }
+
+    // Snapshot the entity maps after pre-positioning so we can reset
+    // them between the two swimlane passes. Date-pinned anchors and
+    // milestones live in this baseline; item-derived entries get
+    // re-added on each pass.
+    const baselineEntityLeft = new Map(ctx.entityLeftEdges);
+    const baselineEntityRight = new Map(ctx.entityRightEdges);
+    const baselineEntityMid = new Map(ctx.entityMidpoints);
+    // Item-only maps don't carry baseline entries (date-pinned
+    // markers are never placed items), so pass-2 reruns reset them
+    // to fresh empties. With waves, every reset re-seeds the wave
+    // edges (`entityRightEdges[w_k] = E_k`, `entityLeftEdges[w_k] =
+    // S_k`) on top of the baseline, so forward references stay
+    // dropped exactly as they are without waves.
+    const resetEntityMaps = (): void => {
+        ctx.entityLeftEdges = new Map(baselineEntityLeft);
+        ctx.entityRightEdges = new Map(baselineEntityRight);
+        ctx.entityMidpoints = new Map(baselineEntityMid);
+        // placedItems and itemFlowKey only ever hold item entries
+        // (markers never write to them), so a fresh map is the right
+        // reset: the next pass's items will repopulate.
+        ctx.placedItems = new Map();
+        ctx.itemFlowKey = new Map();
+        ctx.currentFlowKey = '';
+        if (ctx.waves) seedWaveEdges(ctx.waves, ctx.entityLeftEdges, ctx.entityRightEdges);
+    };
+
+    // Build swimlanes (declared order). Inter-band gap comes from
+    // the swimlane default style's `spacing` bucket. Default
+    // `spacing: none` keeps existing samples byte-stable; bumping to
+    // `md` introduces an 8 px gap.
+    const laneEntries = [...resolved.content.swimlanes.values()];
+    const swimlaneDefaultStyle = resolveStyle('swimlane', [], styleCtx);
+    const interBandGapPx = SPACING_PX[swimlaneDefaultStyle.spacing as keyof typeof SPACING_PX] ?? 0;
+
+    const runSwimlaneLoop = (): {
+        swimlanes: PositionedSwimlane[];
+        nextY: number;
+        maxRightX: number;
+    } => {
+        ctx.nextParallelId = 0;
+        ctx.nextGroupId = 0;
+        const out: PositionedSwimlane[] = [];
+        let cursorY = ctx.chartTopY;
+        let bIndex = 0;
+        let maxRightX = ctx.timeline.originX;
+        for (const lane of laneEntries) {
+            if (bIndex > 0) cursorY += interBandGapPx;
+            const { positioned, usedHeight, usedRightX } = new SwimlaneNode(
+                { lane, bandIndex: bIndex },
+                helpers,
+            ).place({ x: ctx.timeline.originX, y: cursorY }, ctx);
+            out.push(positioned);
+            cursorY += usedHeight;
+            if (usedRightX > maxRightX) maxRightX = usedRightX;
+            bIndex++;
+        }
+        return { swimlanes: out, nextY: cursorY, maxRightX };
+    };
+
+    const isolated = resolved.content.isolatedRegions;
+
+    // Pass 1 — place items without corridor knowledge. With waves
+    // (specs/waves.md §8.3-§8.4) it is the barrier driver's pass
+    // loop: each pass resets the maps, re-seeds the wave edges, places
+    // the lanes with the pass's floors, then places the isolated
+    // regions only to accumulate their members (those region
+    // placements are discarded). The driver iterates to the least
+    // fixpoint; its last pass ran with the solved S/E, so its lane
+    // placements are kept.
+    let pass: ReturnType<typeof runSwimlaneLoop>;
+    let waveSolve: PositionedRoadmap['waveSolve'];
+    const waves = ctx.waves;
+    if (waves) {
+        let last: ReturnType<typeof runSwimlaneLoop> | undefined;
+        // Warm start (specs/scheduler-unification.md §5, F4): engine C's
+        // `S_k` and `E_k`, projected, are a lower bound of engine A's, so
+        // the passes start from them and settle on the same fixpoint in
+        // fewer passes.
+        const seed = isScheduleWarmStart() ? waveSeed(waves.ids, schedule, timeScale) : undefined;
+        const solved = solveWaveBarriers(
+            waves.ids.length,
+            waves.origin,
+            waves.floors,
+            (S, E) => {
+                beginWavePass(waves, S, E);
+                resetEntityMaps();
+                last = runSwimlaneLoop();
+                if (isolated.length > 0) {
+                    buildIncludeRegions(
+                        isolated,
+                        ctx,
+                        last.nextY + LANES_TO_REGIONS_GAP_PX,
+                        helpers,
+                        measured.naturalChartRightX,
+                    );
+                }
+                return waves.pass;
+            },
+            WAVE_EDGE_TOLERANCE_PX,
+            seed,
+        );
+        // From here on the barrier is frozen: later placements floor
+        // with the solved S/E and accumulate nothing.
+        freezeWaves(waves, solved);
+        waveSolve = { passes: solved.passes, capped: solved.capped };
+        pass = last as ReturnType<typeof runSwimlaneLoop>;
+    } else {
+        pass = runSwimlaneLoop();
+    }
+    let swimlanes = pass.swimlanes;
+    let y = pass.nextY;
+
+    // Collect slack-arrow corridors from the milestones (mirrors
+    // MilestoneNode.place's pred resolution). When the result is
+    // non-empty, an item sat inside an arrow's path on pass 1 — rerun
+    // the swimlane loop with corridors known so the row-packer can
+    // bump the offending items down to a clear row. Bumping never
+    // changes an item's x, so corridors stay valid across the rerun;
+    // no fixed-point iteration needed. With waves the rerun runs once,
+    // after the barrier has settled: it floors with the frozen S/E,
+    // and the reset re-seeds the wave edges.
+    const corridors = collectSlackCorridors(resolved.content.milestones, ctx);
+    if (corridors.length > 0) {
+        resetEntityMaps();
+        ctx.slackCorridors = corridors;
+        pass = runSwimlaneLoop();
+        swimlanes = pass.swimlanes;
+        y = pass.nextY;
+    }
+
+    // Include regions under the swimlanes. Reserve the 8 px gap +
+    // tab-reserve only when there's at least one isolated region —
+    // otherwise the now-line and chart bottom would extend past the
+    // last swimlane into empty space. With waves this is the one kept
+    // region placement, floored with the frozen S/E.
+    let includes: PositionedIncludeRegion[] = [];
+    let regionContexts: LayoutContext[] = [];
+    if (isolated.length > 0) {
+        const r = buildIncludeRegions(
+            isolated,
+            ctx,
+            y + LANES_TO_REGIONS_GAP_PX,
+            helpers,
+            measured.naturalChartRightX,
+        );
+        includes = r.regions;
+        regionContexts = r.contexts;
+        y = r.endY;
+    }
+
+    ctx.chartBottomY = y;
+    ctx.swimlaneBottomY = y;
+
+    // Milestones first so anchors know which xs are occupied (for
+    // collision bumps). Placement gives each its x, slack arrows and
+    // overrun; its marker row and label box come from the final pack in
+    // finalize, once every centerX is known and the canvas is final.
+    const milestones = buildMilestones(resolved.content.milestones, ctx);
+
+    return {
+        ctx,
+        swimlanes,
+        includes,
+        regionContexts,
+        milestones,
+        laneEntries,
+        maxRightX: pass.maxRightX,
+        bottomY: y,
+        ...(waveSolve ? { waveSolve } : {}),
+    };
+}
+
+/**
+ * The barrier driver's warm start: engine C's wave spans projected to px
+ * (`start` is `S_k`; the exclusive `end` projects to `E_k`). A wave C did
+ * not schedule seeds nothing.
+ */
+function waveSeed(
+    ids: readonly string[],
+    schedule: RoadmapSchedule,
+    scale: TimeScale,
+): WaveBarrierSeed {
+    const spans = ids.map((id) => schedule.waves?.get(id));
+    return {
+        S: spans.map((w) => (w ? scale.forward(w.start) : null)),
+        E: spans.map((w) => (w ? scale.forward(w.end) : null)),
+    };
+}

package/src/renderable.ts

@@ -14,9 +14,29 @@
 //      Recursively places children inside this call.
 //
 // `place` may invoke `measure` again — implementations should make
-// `measure` cheap. The production nodes (`ItemNode`, `SwimlaneNode`,
-// etc. under `nodes/`) follow this pattern: place re-measures, but
-// measure is O(content) without I/O.
+// `measure` cheap: O(content), without I/O. Of the production nodes
+// only `ItemNode` implements the interface (below).
+//
+// Which nodes measure (specs/layout-phases.md, §3.6 and §3.7):
+//
+//   - `ItemNode` implements `Renderable`, and its measure is complete:
+//     `measureItem` (`nodes/item-measure.ts`) sizes the bar once, wrapped
+//     title and chip growth included, and the row track takes the row
+//     pitch from it before the item is placed. Nothing patches a placed
+//     item's height afterwards.
+//   - Lanes, groups and parallels do not measure. Their height is the
+//     result of row packing on x positions, so measuring them would be
+//     placing them twice; they stay single-pass (`sequenceRowTrack`).
+//     Anchors, milestones, include regions and the footnote panel place
+//     directly as well.
+//   - `HeaderNode` has `measure()` and `place()` of its own and does not
+//     take this signature: it has no time scale or band to measure
+//     against. Its logo slot and text inset live there; drawing the logo
+//     stays in the renderer.
+//   - The roadmap itself is split by phase, not by node: the measure
+//     phase (`phases/measure.ts`) sizes the header, the axis and the
+//     header rows before any lane is placed, and the finalize phase
+//     (`phases/finalize.ts`) runs everything that needs final geometry.
 
 import type { BandScale } from './band-scale.js';
 import type { TimeScale } from './time-scale.js';