@nowline/layout 0.0.0-dev.20260601071750.g04bdff9

package/src/layout.ts

@@ -0,0 +1,1530 @@
+import type {
+    EntityProperty,
+    GroupBlock,
+    ItemDeclaration,
+    LabelDeclaration,
+    NowlineFile,
+    ParallelBlock,
+    ResolveResult,
+    SwimlaneDeclaration,
+} from '@nowline/core';
+import { isGroupBlock, isItemDeclaration, isParallelBlock } from '@nowline/core';
+import {
+    addDays,
+    daysBetween,
+    deriveItemDurationDays,
+    deriveTotalEffortDays,
+    resolveDuration,
+} from './calendar.js';
+import {
+    estimateCapacitySuffixWidth,
+    formatCapacityNumber,
+    parseCapacityValue,
+    resolveCapacityIcon,
+} from './capacity.js';
+import { parseDate, propValue, propValues } from './dsl-utils.js';
+import {
+    ChannelGrid,
+    collectRoutingObstacles,
+    type EdgeRouteRequest,
+    routeChannelEdges,
+} from './edge-routing.js';
+import {
+    HEADER_AUTHOR_FONT_SIZE_PX,
+    HEADER_AUTHOR_LINE_HEIGHT_PX,
+    HEADER_CARD_PADDING_BOTTOM,
+    HEADER_CARD_PADDING_TOP,
+    HEADER_CARD_PADDING_X,
+    HEADER_TITLE_FONT_SIZE_PX,
+    HEADER_TITLE_LINE_HEIGHT_PX,
+    HEADER_TITLE_TO_AUTHOR_GAP_PX,
+} from './header-card-geometry.js';
+import { localeStrings } from './i18n.js';
+import { computeItemInlineDatePins, pickInlineDate } from './inline-date-pin-geometry.js';
+import {
+    ITEM_CAPTION_INSET_X_PX,
+    ITEM_CAPTION_META_BASELINE_OFFSET_PX,
+    ITEM_CAPTION_SPILL_GAP_PX,
+    ITEM_CAPTION_TITLE_FONT_SIZE_PX,
+    ITEM_DECORATION_SPILL_GAP_PX,
+    ITEM_FOOTNOTE_INDICATOR_STEP_PX,
+    ITEM_LINK_ICON_TILE_SIZE_PX,
+    ITEM_STATUS_DOT_RADIUS_PX,
+    LABEL_CHIP_GAP_ABOVE_PROGRESS_STRIP_PX,
+    LABEL_CHIP_GAP_BETWEEN_PX,
+    LABEL_CHIP_HEIGHT_PX,
+    LABEL_CHIP_ROW_STEP_PX,
+    MIN_BAR_WIDTH_FOR_DOT_PX,
+    MIN_BAR_WIDTH_FOR_FOOTNOTE_PX,
+    MIN_BAR_WIDTH_FOR_LINK_AND_DOT_PX,
+    packSpillChips,
+} from './item-bar-geometry.js';
+import { type LayoutContext, newCursor, type TrackCursor } from './layout-context.js';
+import { GroupNode } from './nodes/group-node.js';
+import { ItemNode } from './nodes/item-node.js';
+import { ParallelNode } from './nodes/parallel-node.js';
+import { RoadmapNode } from './nodes/roadmap-node.js';
+import { SwimlaneNode } from './nodes/swimlane-node.js';
+import { resolveLabelChipStyle, resolveStyle, type StyleContext } from './style-resolution.js';
+import type { ThemeName } from './themes/index.js';
+import {
+    GUTTER_PX,
+    HEADER_BESIDE_MAX_WIDTH_PX,
+    HEADER_BESIDE_MIN_WIDTH_PX,
+    ITEM_INSET_PX,
+    MIN_ITEM_WIDTH,
+    NOW_PILL_LABEL_FONT_SIZE_PX,
+    NOW_PILL_LABEL_INSET_X_PX,
+    NOW_PILL_WIDTH_PX,
+    PADDING_PX,
+    PROGRESS_STRIP_HEIGHT_PX,
+} from './themes/shared.js';
+import type {
+    BoundingBox,
+    LinkIconKind,
+    Point,
+    PositionedCapacity,
+    PositionedDependencyEdge,
+    PositionedGroup,
+    PositionedIncludeRegion,
+    PositionedItem,
+    PositionedLabelChip,
+    PositionedNowline,
+    PositionedParallel,
+    PositionedRoadmap,
+    PositionedSwimlane,
+    PositionedTrackChild,
+    StatusKind,
+} from './types.js';
+import type { ViewPreset } from './view-preset.js';
+import { daysPerUnit } from './working-calendar.js';
+
+export interface LayoutOptions {
+    theme?: ThemeName;
+    today?: Date;
+    width?: number; // total SVG width in px; default 1280
+    /**
+     * BCP-47 tag controlling axis labels, the now-pill string, and the
+     * quarter prefix. Resolved by the caller (CLI flag → env vars). When
+     * undefined, layout falls back to the file's `nowline v1 locale:` and
+     * then to `en-US`. See `specs/localization.md`.
+     */
+    locale?: string;
+}
+
+export type LayoutResult = PositionedRoadmap;
+
+function statusFromProp(raw: string | undefined): StatusKind {
+    switch (raw) {
+        case 'done':
+        case 'completed':
+            return 'done';
+        case 'in-progress':
+        case 'active':
+            return 'in-progress';
+        case 'at-risk':
+        case 'blocked':
+        case 'planned':
+            return raw;
+        case undefined:
+            return 'planned';
+        default:
+            return 'neutral';
+    }
+}
+
+function parseProgressFraction(raw: string | undefined): number {
+    if (!raw) return 0;
+    const m = /^(\d{1,3})%$/.exec(raw);
+    if (!m) return 0;
+    return Math.max(0, Math.min(100, parseInt(m[1], 10))) / 100;
+}
+
+// Resolve a `size:NAME` value to its size declaration's effort literal, used
+// by displays that want the literal duration string (not days). Returns the
+// original string for raw literals (`1w`, `3d`) and undefined for missing
+// values. m5 will adjust callers to apply capacity-aware derivation when the
+// caller wants the calendar duration; this helper continues to expose the
+// raw effort/duration literal for chips, captions, and tooltips.
+function resolveDurationLiteral(
+    raw: string | undefined,
+    ctx: { sizes: Map<string, import('./types.js').ResolvedSize> },
+): string | undefined {
+    if (!raw) return undefined;
+    if (/^\d+(?:\.\d+)?[dwmqy]$/.test(raw) || /^\d+%$/.test(raw)) return raw;
+    return ctx.sizes.get(raw)?.effortLiteral ?? raw;
+}
+
+// Resolve a person/team id to its declared title when present (id otherwise).
+function resolveActorDisplay(
+    raw: string | undefined,
+    ctx: {
+        teams: Map<string, import('@nowline/core').TeamDeclaration>;
+        persons: Map<string, import('@nowline/core').PersonDeclaration>;
+    },
+): string | undefined {
+    if (!raw) return undefined;
+    return ctx.teams.get(raw)?.title ?? ctx.persons.get(raw)?.title ?? raw;
+}
+
+function parseLinkIcon(link: string | undefined): { icon: LinkIconKind; href?: string } {
+    if (!link) return { icon: 'none' };
+    const lower = link.toLowerCase();
+    if (lower.includes('linear.app')) return { icon: 'linear', href: link };
+    if (lower.includes('github.com')) return { icon: 'github', href: link };
+    if (lower.includes('atlassian.net') || lower.includes('jira.')) {
+        return { icon: 'jira', href: link };
+    }
+    return { icon: 'generic', href: link };
+}
+
+// Bake a named/hex color from a label's `bg:` or `fg:` into the chip style.
+function buildLabelChip(
+    label: LabelDeclaration,
+    ctx: StyleContext,
+    x: number,
+    y: number,
+    maxWidth?: number,
+): PositionedLabelChip {
+    const style = resolveLabelChipStyle(label, ctx);
+    // Prefer the short name (id) when it exists — chips inside an item bar
+    // are tight; the long title risks overflowing.
+    const text = label.name ?? label.title ?? '';
+    const padKey = style.padding === 'none' ? 'xs' : style.padding;
+    const pad = PADDING_PX[padKey as keyof typeof PADDING_PX];
+    let width = Math.max(20, Math.round(text.length * 5.5 + pad * 2));
+    if (maxWidth !== undefined) width = Math.min(width, maxWidth);
+    return {
+        text,
+        style,
+        box: { x, y, width, height: LABEL_CHIP_HEIGHT_PX },
+    };
+}
+
+// Sequence a set of nodes into a single horizontal track. `parallelInside`
+// indicates the caller is inside a ParallelBlock and each child occupies a
+// fresh sub-track (caller passes a new cursor per call).
+function sequenceItem(
+    node: ItemDeclaration,
+    cursor: TrackCursor,
+    ctx: LayoutContext,
+    ownerOverride?: string,
+): PositionedItem {
+    const props = node.properties;
+    const style = resolveStyle('item', props, ctx.styleCtx);
+    // Sizing precedence (specs/dsl.md § "Sizing precedence"):
+    //   1. `duration:LITERAL` wins as the calendar duration — `size:NAME`
+    //      becomes a pure annotation (chip only).
+    //   2. Otherwise, `size:NAME` derives `effort ÷ capacity` (default
+    //      capacity = 1).
+    // The validator requires one of the two on every item.
+    const sizeRef = propValue(props, 'size');
+    const sizeResolved = sizeRef ? (ctx.sizes.get(sizeRef) ?? null) : null;
+    const durationDays = deriveItemDurationDays(props, ctx.sizes, ctx.cal);
+    // Total work in single-engineer days, used below to normalize a literal
+    // `remaining:` value into a progress fraction. Stays per-engineer
+    // regardless of the item's `capacity:` so a `remaining:1w` always means
+    // "one engineer-week of work left".
+    const totalEffortDays = deriveTotalEffortDays(props, ctx.sizes, ctx.cal);
+    const afterRaw = propValues(props, 'after');
+    const beforeRaw = propValues(props, 'before');
+    const dateRaw = propValue(props, 'date');
+    const remainingDays = resolveDuration(propValue(props, 'remaining'), ctx.sizes, ctx.cal);
+
+    // Resolve start x: explicit date > after-chain > cursor position.
+    // `after:` accepts both entity ids (looked up in entityRightEdges) and
+    // inline ISO date literals (resolved through the time scale). The
+    // validator enforces "at most one inline date per direction" so at most
+    // one element will hit the date path per item.
+    let startX = cursor.x;
+    const explicitDate = parseDate(dateRaw);
+    if (explicitDate) {
+        const xd = ctx.scale.forwardWithinDomain(explicitDate);
+        if (xd !== null) startX = xd;
+    } else if (afterRaw.length > 0) {
+        let maxEnd = cursor.x;
+        for (const ref of afterRaw) {
+            const inlineDate = parseDate(ref);
+            if (inlineDate) {
+                const xd = ctx.scale.forwardWithinDomain(inlineDate);
+                if (xd !== null) maxEnd = Math.max(maxEnd, xd);
+                continue;
+            }
+            const endX = ctx.entityRightEdges.get(ref);
+            if (endX !== undefined) maxEnd = Math.max(maxEnd, endX);
+        }
+        startX = Math.max(cursor.x, maxEnd);
+    }
+
+    const naturalWidth = Math.max(MIN_ITEM_WIDTH, durationDays * ctx.timeline.pixelsPerDay);
+    // Logical extent — what the item "owns" in time (used for chaining,
+    // `after:` lookups, dependency-arrow attach points).
+    const logicalLeft = startX;
+    const logicalRight = startX + naturalWidth;
+
+    const linkRaw = propValue(props, 'link');
+    const linkInfo = parseLinkIcon(linkRaw);
+    const hasLinkIcon = linkInfo.icon !== 'none';
+
+    // Pre-compute the chip row geometry — every chip renders at its
+    // NATURAL text-fit width on a single horizontal row, never
+    // truncated. We only need the total row width here so we can
+    // decide whether the row fits inside the bar; concrete chip
+    // (x, y) placement comes after ItemNode resolves the visible
+    // bar box below.
+    //
+    // Chips sit at the bar's bottom (just above the progress strip)
+    // and the link icon (when present) sits in the bar's UPPER-LEFT
+    // corner, so they no longer share a vertical band — chips have
+    // the full caption-inset-bounded inner width regardless of
+    // whether a link icon is rendered. The link-icon column's
+    // horizontal cost is borne by the caption (title/meta) inset
+    // instead, see `ItemNode`.
+    const visualWidthPredict = Math.max(MIN_ITEM_WIDTH, naturalWidth - 2 * ITEM_INSET_PX);
+    const labelIds = propValues(props, 'labels');
+    const chipSamples: { id: LabelDeclaration; width: number }[] = [];
+    for (const labelId of labelIds) {
+        const label = ctx.labels.get(labelId);
+        if (!label) continue;
+        const sample = buildLabelChip(label, ctx.styleCtx, 0, 0);
+        chipSamples.push({ id: label, width: sample.box.width });
+    }
+    let chipRowWidth = 0;
+    for (let i = 0; i < chipSamples.length; i += 1) {
+        if (i > 0) chipRowWidth += LABEL_CHIP_GAP_BETWEEN_PX;
+        chipRowWidth += chipSamples[i].width;
+    }
+    const chipInsideAvailWidth = Math.max(0, visualWidthPredict - 2 * ITEM_CAPTION_INSET_X_PX);
+    const chipsOutside = chipSamples.length > 0 && chipRowWidth > chipInsideAvailWidth;
+
+    // Handle `before:` — item must end by the earliest cap. Each cap is
+    // either an entity id (looked up in entityLeftEdges) or an inline ISO
+    // date literal (resolved through the time scale). The validator enforces
+    // "at most one inline date per direction" so at most one element per
+    // before-list will hit the date path.
+    let hasOverflow = false;
+    let overflowBox: BoundingBox | undefined;
+    let overflowAnchorId: string | undefined;
+    if (beforeRaw.length > 0) {
+        let earliestCapX: number | undefined;
+        let earliestCapRef: string | undefined;
+        for (const ref of beforeRaw) {
+            const inlineDate = parseDate(ref);
+            const capX = inlineDate
+                ? (ctx.scale.forwardWithinDomain(inlineDate) ?? undefined)
+                : ctx.entityLeftEdges.get(ref);
+            if (capX === undefined) continue;
+            if (earliestCapX === undefined || capX < earliestCapX) {
+                earliestCapX = capX;
+                earliestCapRef = ref;
+            }
+        }
+        if (earliestCapX !== undefined && logicalRight > earliestCapX) {
+            hasOverflow = true;
+            overflowBox = {
+                x: earliestCapX,
+                y: cursor.y,
+                width: logicalRight - earliestCapX,
+                height: ctx.bandScale.bandwidth(),
+            };
+            overflowAnchorId = earliestCapRef;
+        }
+    }
+
+    // Progress fraction
+    const statusRaw = propValue(props, 'status');
+    const status = statusFromProp(statusRaw);
+    let progress = parseProgressFraction(statusRaw);
+    if (progress === 0 && status === 'done') progress = 1;
+    const remainingPctMatch = /^(\d{1,3})%$/.exec(propValue(props, 'remaining') ?? '');
+    if (progress === 0 && status === 'in-progress' && remainingPctMatch) {
+        const pct = Math.max(0, Math.min(100, parseInt(remainingPctMatch[1], 10))) / 100;
+        progress = 1 - pct;
+    }
+    if (progress === 0 && status === 'in-progress' && remainingDays > 0 && totalEffortDays > 0) {
+        // `remaining:` literal is single-engineer days; `totalEffortDays`
+        // is also single-engineer days, so the ratio is unit-correct.
+        // Clamp to [0, 1] — the renderer paints 100% remaining when the
+        // author overshot, matching the spec's "warn-and-clamp" overflow
+        // behavior. (Validation defers the warn to layout-time today; a
+        // future diagnostics channel can surface it back to the user.)
+        progress = Math.max(0, Math.min(1, 1 - remainingDays / totalEffortDays));
+    }
+
+    // Apply the status-tinted item background when the resolved bg is still
+    // theme-default. Authors who set explicit `bg:` keep their override.
+    // Per m2d handoff Resolution 3: layout owns this so the renderer stays
+    // palette-dumb.
+    const STATUS_TINT_LIGHT: Record<StatusKind, string> = {
+        done: '#ecfdf5',
+        'in-progress': '#eff6ff',
+        'at-risk': '#fffbeb',
+        blocked: '#fee2e2',
+        planned: '#f8fafc',
+        neutral: '#f8fafc',
+    };
+    const STATUS_TINT_DARK: Record<StatusKind, string> = {
+        done: '#052e16',
+        'in-progress': '#172554',
+        'at-risk': '#422006',
+        blocked: '#7f1d1d',
+        planned: '#1e293b',
+        neutral: '#1e293b',
+    };
+    const STATUS_TINT_GREY: Record<StatusKind, string> = {
+        done: '#ebebeb',
+        'in-progress': '#e4e4e4',
+        'at-risk': '#eeeeee',
+        blocked: '#dcdcdc',
+        planned: '#f5f5f5',
+        neutral: '#f5f5f5',
+    };
+    const STATUS_BORDER: Record<StatusKind, string> = {
+        done: ctx.styleCtx.theme.status.done,
+        'in-progress': ctx.styleCtx.theme.status.inProgress,
+        'at-risk': ctx.styleCtx.theme.status.atRisk,
+        blocked: ctx.styleCtx.theme.status.blocked,
+        planned: ctx.styleCtx.theme.status.planned,
+        neutral: ctx.styleCtx.theme.status.neutral,
+    };
+    const themeName = ctx.styleCtx.theme.name;
+    const isDark = themeName === 'dark';
+    const themeDefaultBg = isDark ? '#0f172a' : '#ffffff';
+    const themeDefaultFg = themeName === 'grayscale' ? '#9e9e9e' : '#94a3b8';
+    if (style.bg === themeDefaultBg) {
+        style.bg =
+            themeName === 'grayscale'
+                ? STATUS_TINT_GREY[status]
+                : isDark
+                  ? STATUS_TINT_DARK[status]
+                  : STATUS_TINT_LIGHT[status];
+    }
+    if (style.fg === themeDefaultFg) {
+        style.fg = STATUS_BORDER[status];
+    }
+
+    // Pre-format the secondary line shown inside the item bar.
+    //
+    // Driver-only meta line (`rendering.md` § Item size chip): exactly one
+    // leading token — the explicit non-empty `duration:LITERAL` when set,
+    // otherwise the size chip when `size:` drives. Never both; bar width
+    // already encodes derived calendar span for sized items.
+    const explicitDurationLiteral = propValue(props, 'duration');
+    const durationDrives =
+        !!explicitDurationLiteral && /^\d+(?:\.\d+)?[dwmqy]$/.test(explicitDurationLiteral);
+    const sizeChipText = sizeResolved ? (sizeResolved.title ?? sizeResolved.name) : '';
+    const driverToken: string | undefined = durationDrives
+        ? explicitDurationLiteral
+        : sizeChipText || undefined;
+    const remainingRaw = propValue(props, 'remaining');
+    const remainingLiteral = resolveDurationLiteral(remainingRaw, ctx);
+    const ownerDisplay = resolveActorDisplay(ownerOverride ?? propValue(props, 'owner'), ctx);
+    const metaHead = (): string => [driverToken, ownerDisplay].filter(Boolean).join(' ');
+    let metaText: string | undefined;
+    if (status === 'in-progress' && remainingLiteral) {
+        const head = metaHead();
+        metaText = head
+            ? `${head} — ${remainingLiteral} remaining`
+            : `${remainingLiteral} remaining`;
+    } else if (status === 'in-progress' && progress > 0 && progress < 1) {
+        const pct = Math.round((1 - progress) * 100);
+        const head = metaHead();
+        metaText = head ? `${head} — ${pct}% remaining` : `${pct}% remaining`;
+    } else if (ownerDisplay || driverToken) {
+        metaText = metaHead() || undefined;
+    }
+
+    // Capacity suffix — appended after metaText at render time. Layout's
+    // job here is to (a) parse the value out of `capacity:`, (b) format
+    // the display number, (c) resolve `capacity-icon` to either a
+    // built-in name or a literal string the renderer can paint directly,
+    // and (d) feed the suffix's estimated width into ItemNode so spill
+    // detection accounts for `2w 5×` rather than just `2w`. The suffix
+    // disappears entirely when capacity is missing or non-positive.
+    const capacityRaw = propValue(props, 'capacity');
+    const capacityValue = parseCapacityValue(capacityRaw);
+    let capacity: PositionedCapacity | null = null;
+    let capacityTrailingWidth = 0;
+    if (capacityValue !== null) {
+        const capacityText = formatCapacityNumber(capacityValue);
+        const capacityIcon = resolveCapacityIcon(style.capacityIcon, ctx.symbols);
+        capacity = { value: capacityValue, text: capacityText, icon: capacityIcon };
+        const META_FONT_SIZE_PX_LOCAL = 11;
+        // Add a small leading separator (a single space's worth) only when
+        // the suffix sits next to existing meta text, so `m 5×` has air
+        // between the driver token and the count. Standalone suffix needs no
+        // leading separator.
+        const separatorWidth = metaText ? estimateTextWidth(' ', META_FONT_SIZE_PX_LOCAL) : 0;
+        capacityTrailingWidth =
+            separatorWidth +
+            estimateCapacitySuffixWidth(capacityText, capacityIcon, META_FONT_SIZE_PX_LOCAL);
+    }
+
+    // Visual bar + caption-spill decision delegated to ItemNode. Logical
+    // extent (used by chaining and `after:` lookups) stays on
+    // logicalLeft/logicalRight; ItemNode computes the inset visual box and
+    // whether the title+meta line overflows the bar's inner padded width.
+    const titleStr = node.title ?? node.name ?? '';
+    const placed = new ItemNode({
+        id: node.name ?? '',
+        title: titleStr,
+        logicalLeftX: logicalLeft,
+        logicalRightX: logicalRight,
+        metaText,
+        metaTrailingWidth: capacityTrailingWidth,
+        hasLinkIcon,
+    }).place({ x: logicalLeft, y: cursor.y }, { time: ctx.scale, bands: ctx.bandScale, style });
+    const itemBox = placed.box;
+    const bandwidth = ctx.bandScale.bandwidth();
+
+    // Narrow-bar decoration spill — when a bar is too narrow to host
+    // the dot, link icon, or footnote with its full inset, those
+    // glyphs render in the same spill column as the (already-
+    // spilling) caption text, in reading order
+    // `[bar][dot][icon][title][footnote#…][meta]`. Each decoration's
+    // threshold is independent (a 20-px-wide bar can host the dot
+    // but not the icon, etc.); see the `MIN_BAR_WIDTH_FOR_*`
+    // constants in `item-bar-geometry`.
+    //
+    // Forcing `textSpills` when `iconSpills` keeps the icon and
+    // title visually adjacent — otherwise a spilled icon would
+    // float at `bar.right + 6` while the title stayed inside the
+    // bar, breaking the icon→title affordance.
+    const dotSpills = itemBox.width < MIN_BAR_WIDTH_FOR_DOT_PX;
+    const iconSpills = hasLinkIcon && itemBox.width < MIN_BAR_WIDTH_FOR_LINK_AND_DOT_PX;
+    const footnoteSpillsForNarrow = itemBox.width < MIN_BAR_WIDTH_FOR_FOOTNOTE_PX;
+    const textSpills = placed.textSpills || iconSpills;
+
+    // Label chips lay out left → right at natural text width.
+    //
+    // INSIDE the bar (chipsOutside === false): single row,
+    // left-aligned at the caption inset, anchored just above the
+    // bottom progress strip.
+    //
+    // OUTSIDE the bar (chipsOutside === true): the whole chip set
+    // moves to the spill column at `bar.right + 6`. Within the
+    // column, chips pack into rows capped at the bar's visual
+    // width — see `packSpillChips`. Row 0 sits at the same y the
+    // single-row would have used; subsequent rows stack DOWNWARD by
+    // one `LABEL_CHIP_ROW_STEP_PX`.
+    //
+    // When chips spill, the BAR ITSELF GROWS DOWNWARD so the chip
+    // column reads as enclosed by the bar — the painted footprint
+    // of the bar is `bandwidth + chipBarExtra` and the bottom
+    // progress strip moves with the new bottom edge. Chip Y is
+    // anchored to the ORIGINAL bandwidth (relative to the bar's
+    // top), not to the grown box.height, so row 0 stays where a
+    // single-row chip would naturally render and rows 1..N grow
+    // downward into the new bar area.
+    //
+    // When the caption ALSO spills (`textSpills && chipsOutside`),
+    // row 0's y drops below the meta baseline so the spilled stack
+    // reads `title → meta → chip-row-0 → chip-row-1 → ...` at a
+    // single column inside the (now-taller) bar.
+    let chipPack: ReturnType<typeof packSpillChips<LabelDeclaration>> | null = null;
+    if (chipsOutside) {
+        chipPack = packSpillChips(chipSamples, itemBox.width);
+    }
+    const chipRowCount = chipPack ? chipPack.rows.length : chipSamples.length > 0 ? 1 : 0;
+    // Capacity suffix renders on the same line as metaText. Treat the meta
+    // line as present whenever EITHER metaText OR a capacity suffix will
+    // paint, so chip-row pitch reserves the right amount of vertical space.
+    const hasMeta = metaText !== undefined || capacity !== null;
+    const chipBarExtra = computeChipBarExtra(
+        chipsOutside,
+        textSpills,
+        chipRowCount,
+        bandwidth,
+        hasMeta,
+    );
+    if (chipBarExtra > 0) {
+        itemBox.height = bandwidth + chipBarExtra;
+    }
+
+    const labelChips: PositionedLabelChip[] = [];
+    const baseChipY =
+        itemBox.y +
+        bandwidth -
+        PROGRESS_STRIP_HEIGHT_PX -
+        LABEL_CHIP_HEIGHT_PX -
+        LABEL_CHIP_GAP_ABOVE_PROGRESS_STRIP_PX;
+    const captionStackChipY =
+        itemBox.y + ITEM_CAPTION_META_BASELINE_OFFSET_PX + LABEL_CHIP_GAP_ABOVE_PROGRESS_STRIP_PX;
+    // Inside-bar chips with meta need to clear the meta baseline —
+    // the natural `baseChipY` (anchored to bar bottom) sits above
+    // the meta line at typical bandwidths, so the chip rect would
+    // overlap the meta text vertically. Use whichever Y is lower.
+    // Outside-bar chips already reuse `captionStackChipY` when the
+    // caption ALSO spills; with caption inside we don't need to
+    // shift them since they're horizontally separated from the meta.
+    const stackBelowMeta =
+        (chipsOutside && textSpills) || (!chipsOutside && hasMeta && chipSamples.length > 0);
+    const chipRow0Y = stackBelowMeta ? Math.max(baseChipY, captionStackChipY) : baseChipY;
+    const chipStartX = chipsOutside
+        ? itemBox.x + itemBox.width + ITEM_CAPTION_SPILL_GAP_PX
+        : itemBox.x + ITEM_CAPTION_INSET_X_PX;
+
+    let chipsRightX = chipStartX;
+    if (chipPack) {
+        for (let r = 0; r < chipPack.rows.length; r += 1) {
+            const rowY = chipRow0Y + r * LABEL_CHIP_ROW_STEP_PX;
+            let rowCursorX = chipStartX;
+            for (const sample of chipPack.rows[r]) {
+                const chip = buildLabelChip(sample.id, ctx.styleCtx, rowCursorX, rowY);
+                labelChips.push(chip);
+                rowCursorX += chip.box.width + LABEL_CHIP_GAP_BETWEEN_PX;
+            }
+            const rowRight = rowCursorX - LABEL_CHIP_GAP_BETWEEN_PX;
+            if (rowRight > chipsRightX) chipsRightX = rowRight;
+        }
+    } else {
+        let rowCursorX = chipStartX;
+        for (const sample of chipSamples) {
+            const chip = buildLabelChip(sample.id, ctx.styleCtx, rowCursorX, chipRow0Y);
+            labelChips.push(chip);
+            rowCursorX += chip.box.width + LABEL_CHIP_GAP_BETWEEN_PX;
+        }
+        chipsRightX = chipSamples.length > 0 ? rowCursorX - LABEL_CHIP_GAP_BETWEEN_PX : chipStartX;
+    }
+
+    // Footnote superscript indicators. Per `specs/dsl.md`, footnotes
+    // attach via the `on:` property on the footnote declaration only —
+    // there is no forward `footnote:` property on the host entity. Walk
+    // `footnoteHosts` (built from each footnote's `on:` list) and emit
+    // a superscript for every footnote that names this item.
+    const footnoteIndicatorSet = new Set<number>();
+    if (node.name) {
+        for (const [fid, hosts] of ctx.footnoteHosts.entries()) {
+            if (hosts.includes(node.name)) {
+                const n = ctx.footnoteIndex.get(fid);
+                if (n !== undefined) footnoteIndicatorSet.add(n);
+            }
+        }
+    }
+    const footnoteIndicators = [...footnoteIndicatorSet].sort((a, b) => a - b);
+
+    const owner = ownerDisplay ?? ownerOverride ?? propValue(props, 'owner');
+    const description = node.description?.text;
+
+    // Footnote glyphs only need to spill when there's at least one
+    // indicator AND the bar is too narrow to host them at the inset-
+    // right anchor. Compute the final boolean here once we know the
+    // indicator count.
+    const footnoteSpills = footnoteIndicators.length > 0 && footnoteSpillsForNarrow;
+
+    // Spill-column x positions for the decorations. The cluster
+    // mirrors the in-bar reading order so users see the same visual
+    // hierarchy whether everything fits inside or trails off to the
+    // right:
+    //
+    //   In-bar (default):  [icon] [title]    [¹²]   [dot]
+    //   Spilled (narrow):  [bar] [icon?] [title][¹²?] [dot?]
+    //
+    // The dot lives at the trailing edge in BOTH cases — pushing it
+    // to the LEFT of the title (with the title trailing it) read as
+    // the dot belonging to the next item, not this one. A missing
+    // decoration just collapses out of the row; e.g. an item with
+    // no link AND a too-narrow bar gives `[bar] [title] [dot]`.
+    //
+    // `decorationsRightX` is the furthest right edge any spilled
+    // glyph reaches; the row-packer uses it (alongside spilled-chip
+    // width) to reserve x-extent so the next chained item bumps to
+    // a fresh row instead of landing under the spilled cluster.
+    const SPILL_COLUMN_X0 = itemBox.x + itemBox.width + ITEM_CAPTION_SPILL_GAP_PX;
+    let spillCursor = SPILL_COLUMN_X0;
+    // Advance the cursor by `gap` IFF something has already been
+    // placed in the column — keeps the cluster from leaving a
+    // dangling gap past its final glyph (which would over-reserve
+    // x-extent and shift downstream items).
+    let needGap = false;
+    let iconSpillX: number | null = null;
+    if (iconSpills) {
+        if (needGap) spillCursor += ITEM_DECORATION_SPILL_GAP_PX;
+        iconSpillX = spillCursor;
+        spillCursor = iconSpillX + ITEM_LINK_ICON_TILE_SIZE_PX;
+        needGap = true;
+    }
+    let captionSpillWidth = 0;
+    if (textSpills) {
+        if (needGap) spillCursor += ITEM_DECORATION_SPILL_GAP_PX;
+        const titleW = estimateTextWidth(titleStr, ITEM_CAPTION_TITLE_FONT_SIZE_PX);
+        // Spill column width is the wider of the title and the *full* meta
+        // line (text + capacity suffix). `capacityTrailingWidth` is 0 when
+        // no capacity suffix is rendered, so this stays a no-op for items
+        // without `capacity:`.
+        const metaW = (metaText ? estimateTextWidth(metaText, 11) : 0) + capacityTrailingWidth;
+        captionSpillWidth = Math.max(titleW, metaW);
+        spillCursor += captionSpillWidth;
+        needGap = true;
+    }
+    let footnoteSpillStartX: number | null = null;
+    if (footnoteSpills) {
+        if (needGap) spillCursor += ITEM_DECORATION_SPILL_GAP_PX;
+        footnoteSpillStartX = spillCursor;
+        spillCursor += footnoteIndicators.length * ITEM_FOOTNOTE_INDICATOR_STEP_PX;
+        needGap = true;
+    }
+    let dotSpillCx: number | null = null;
+    if (dotSpills) {
+        if (needGap) spillCursor += ITEM_DECORATION_SPILL_GAP_PX;
+        dotSpillCx = spillCursor + ITEM_STATUS_DOT_RADIUS_PX;
+        spillCursor = dotSpillCx + ITEM_STATUS_DOT_RADIUS_PX;
+        needGap = true;
+    }
+    const decorationsRightX = Math.max(itemBox.x + itemBox.width, spillCursor);
+
+    const id = node.name;
+    if (id) {
+        // Entity edges live in LOGICAL space so chained items / `after:`
+        // references / dependency-arrow attach points sit on the column
+        // boundary, not on the visually inset bar edge. The visible 12 px
+        // gutter between bars then becomes a clean attach corridor.
+        ctx.entityLeftEdges.set(id, logicalLeft);
+        ctx.entityRightEdges.set(id, logicalRight);
+        ctx.entityMidpoints.set(id, {
+            x: (logicalLeft + logicalRight) / 2,
+            y: itemBox.y + itemBox.height / 2,
+        });
+        // Visual edges — where dependency arrows actually attach. These
+        // sit ITEM_INSET_PX inside the column boundaries so the arrows
+        // emerge from the painted bar edge instead of the inter-column
+        // gutter. See LayoutContext.entityVisualLeftX/RightX.
+        ctx.entityVisualLeftX.set(id, itemBox.x);
+        ctx.entityVisualRightX.set(id, itemBox.x + itemBox.width);
+        // Dependency-arrow source point. Default = the bar's right
+        // edge at row midpoint. When the caption spills past the
+        // bar's right edge (`textSpills`), the spilled title /
+        // meta occupy the area immediately right of the bar at
+        // row midline. Keep X on the bar's right edge so the
+        // arrow visually leaves the bar's side, but drop Y to the
+        // vertical center of the bottom progress strip so the
+        // arrow runs UNDERNEATH the spilled text rather than
+        // through it. Mirrors the slack-arrow attach below.
+        const arrowSource: Point = textSpills
+            ? {
+                  x: itemBox.x + itemBox.width,
+                  y: itemBox.y + itemBox.height - PROGRESS_STRIP_HEIGHT_PX / 2,
+              }
+            : {
+                  x: itemBox.x + itemBox.width,
+                  y: itemBox.y + itemBox.height / 2,
+              };
+        ctx.itemArrowSource.set(id, arrowSource);
+        ctx.itemFlowKey.set(id, ctx.currentFlowKey);
+        // Slack-arrow attach Y. Defaults to the bar's row midpoint; when
+        // the caption spills past the bar's right edge, drop to the
+        // progress-strip's vertical center so the arrow aligns with the
+        // bottom-edge progress bar instead of running through the
+        // adjacent title/meta text. The `/ 2` keeps the attach point on
+        // the strip's vertical center if `PROGRESS_STRIP_HEIGHT_PX` is
+        // ever bumped.
+        const slackAttachY = textSpills
+            ? itemBox.y + itemBox.height - PROGRESS_STRIP_HEIGHT_PX / 2
+            : itemBox.y + itemBox.height / 2;
+        ctx.itemSlackAttachY.set(id, slackAttachY);
+    }
+
+    cursor.x = logicalRight;
+    cursor.maxX = Math.max(cursor.maxX, cursor.x);
+    // The next row in a parallel/group/lane starts at
+    // `cursor.y + cursor.height`. Default pitch is `bandScale.step()`
+    // (bandwidth + inter-row gap). When the bar grew to enclose a
+    // spilled chip column, the pitch grows by the SAME amount so the
+    // inter-row gap stays constant — the next row's bar starts
+    // `step − bandwidth` px below the (now-taller) bar bottom.
+    cursor.height = Math.max(cursor.height, ctx.bandScale.step() + chipBarExtra);
+
+    const inlineDatePins = computeItemInlineDatePins({
+        box: itemBox,
+        afterDate: pickInlineDate(afterRaw),
+        beforeDate: pickInlineDate(beforeRaw),
+        hasLinkIcon,
+        footnoteCount: footnoteIndicators.length,
+    });
+
+    const result: PositionedItem = {
+        kind: 'item',
+        id,
+        title: titleStr,
+        box: itemBox,
+        status,
+        progressFraction: progress,
+        footnoteIndicators,
+        labelChips,
+        chipsOutside,
+        chipsRightX,
+        linkIcon: linkInfo.icon,
+        linkHref: linkInfo.href,
+        hasOverflow,
+        overflowBox,
+        overflowAnchorId,
+        owner,
+        description,
+        metaText,
+        textSpills,
+        dotSpills,
+        iconSpills,
+        footnoteSpills,
+        dotSpillCx,
+        iconSpillX,
+        footnoteSpillStartX,
+        decorationsRightX,
+        capacity,
+        size: sizeResolved,
+        style,
+        inlineDatePins: inlineDatePins.length > 0 ? inlineDatePins : undefined,
+    };
+    return result;
+}
+
+function sequenceParallel(
+    node: ParallelBlock,
+    cursor: TrackCursor,
+    ctx: LayoutContext,
+): PositionedParallel {
+    return new ParallelNode(node, { sequenceOne, newCursor }).place(cursor, ctx);
+}
+
+function sequenceGroup(node: GroupBlock, cursor: TrackCursor, ctx: LayoutContext): PositionedGroup {
+    return new GroupNode(node, {
+        sequenceItem,
+        sequenceOne,
+        resolveChildStart,
+        newCursor,
+        estimateTextWidth,
+        predictItemChipExtraHeight,
+    }).place(cursor, ctx);
+}
+
+function sequenceOne(
+    node: ItemDeclaration | GroupBlock | ParallelBlock,
+    cursor: TrackCursor,
+    ctx: LayoutContext,
+): PositionedTrackChild {
+    if (isItemDeclaration(node)) return sequenceItem(node, cursor, ctx);
+    if (isParallelBlock(node)) return sequenceParallel(node, cursor, ctx);
+    if (isGroupBlock(node)) return sequenceGroup(node, cursor, ctx);
+    throw new Error(
+        `Unknown swimlane child type: ${(node as { $type?: string }).$type ?? 'unknown'}`,
+    );
+}
+
+// Rough px-width estimate for sans-serif text. Intentionally pessimistic
+// (uses ~0.58 em per char) so we err toward "doesn't fit" and trigger a
+// row bump rather than draw an item with a clipped title.
+function estimateTextWidth(text: string, fontSize: number): number {
+    return text.length * fontSize * 0.58;
+}
+
+/**
+ * Compute the extra vertical px the bar grows when its spilled chip
+ * column would otherwise extend below the (single-row) bottom. The
+ * bar's painted footprint becomes `bandwidth + chipBarExtra`, the
+ * progress strip rides the new bottom, and chip rows pack inside
+ * the taller bar (anchored from the bar TOP so row 0 doesn't shift
+ * when the bar grows).
+ *
+ * Returns 0 when chips fit inside the bar, when there are no chips,
+ * or when the spilled column happens to fit inside `bandwidth` (a
+ * single row with the caption inside, for instance).
+ *
+ * The same number is the row-pitch increase the swimlane / group
+ * row-packer needs to reserve so the next row clears the taller
+ * bar — `cursor.height = step + chipBarExtra` and the predict
+ * helper returns this verbatim.
+ */
+function computeChipBarExtra(
+    chipsOutside: boolean,
+    captionSpills: boolean,
+    chipRowCount: number,
+    bandwidth: number,
+    hasMeta: boolean,
+): number {
+    if (chipRowCount === 0) return 0;
+    // Row 0 anchor relative to the bar's TOP — three regimes:
+    //
+    //   1. chipsOutside + captionSpills → chips stack below the
+    //      spilled meta line (`captionStackTop`).
+    //   2. chips INSIDE the bar AND meta is present → chip top must
+    //      clear the meta baseline; the natural `baseTop` sits
+    //      ABOVE the meta line at default bandwidth (=56), so we
+    //      take whichever is lower of base/captionStack.
+    //   3. otherwise (in-bar w/o meta, or chipsOutside w/o caption
+    //      spill) → row 0 hugs the bar bottom at `baseTop`.
+    //
+    // Cases (2) and (3-with-multi-row-spill) can both grow the bar;
+    // case (3-with-single-row-inside-no-meta) never grows.
+    const baseTop =
+        bandwidth -
+        PROGRESS_STRIP_HEIGHT_PX -
+        LABEL_CHIP_HEIGHT_PX -
+        LABEL_CHIP_GAP_ABOVE_PROGRESS_STRIP_PX;
+    const captionStackTop =
+        ITEM_CAPTION_META_BASELINE_OFFSET_PX + LABEL_CHIP_GAP_ABOVE_PROGRESS_STRIP_PX;
+    let chipRow0Top: number;
+    if (chipsOutside && captionSpills) {
+        chipRow0Top = captionStackTop;
+    } else if (!chipsOutside && hasMeta) {
+        chipRow0Top = Math.max(baseTop, captionStackTop);
+    } else {
+        chipRow0Top = baseTop;
+    }
+    const lastRowBottomTop =
+        chipRow0Top + (chipRowCount - 1) * LABEL_CHIP_ROW_STEP_PX + LABEL_CHIP_HEIGHT_PX;
+    // The bar must be tall enough to fit `lastRowBottomTop` plus a
+    // GAP above the progress strip plus the progress strip itself.
+    const requiredHeight =
+        lastRowBottomTop + LABEL_CHIP_GAP_ABOVE_PROGRESS_STRIP_PX + PROGRESS_STRIP_HEIGHT_PX;
+    return Math.max(0, requiredHeight - bandwidth);
+}
+
+/**
+ * Predict an item's bar growth (and therefore row-pitch growth) for
+ * a multi-row spilled chip column BEFORE the bar is sequenced. Used
+ * by the swimlane / group row-packer so neighboring rows on later
+ * rows are positioned correctly without a retroactive shift.
+ *
+ * Mirrors the chip-pack + caption-spill arithmetic in
+ * `sequenceItem` so prediction and placement agree byte-for-byte.
+ */
+function predictItemChipExtraHeight(item: ItemDeclaration, ctx: LayoutContext): number {
+    const props = item.properties;
+    const labelIds = propValues(props, 'labels');
+    if (labelIds.length === 0) return 0;
+    const durationDays = deriveItemDurationDays(props, ctx.sizes, ctx.cal);
+    const naturalWidth = Math.max(MIN_ITEM_WIDTH, durationDays * ctx.timeline.pixelsPerDay);
+    const visualWidth = Math.max(MIN_ITEM_WIDTH, naturalWidth - 2 * ITEM_INSET_PX);
+    const samples: { id: LabelDeclaration; width: number }[] = [];
+    for (const labelId of labelIds) {
+        const label = ctx.labels.get(labelId);
+        if (!label) continue;
+        const sample = buildLabelChip(label, ctx.styleCtx, 0, 0);
+        samples.push({ id: label, width: sample.box.width });
+    }
+    if (samples.length === 0) return 0;
+    let chipRowWidth = 0;
+    for (let i = 0; i < samples.length; i += 1) {
+        if (i > 0) chipRowWidth += LABEL_CHIP_GAP_BETWEEN_PX;
+        chipRowWidth += samples[i].width;
+    }
+    const insideAvail = Math.max(0, visualWidth - 2 * ITEM_CAPTION_INSET_X_PX);
+    const chipsOutside = chipRowWidth > insideAvail;
+
+    // `hasMeta` mirrors `metaText !== undefined` in `sequenceItem`,
+    // plus the capacity suffix (which renders on the same meta line).
+    // metaText is set whenever an item declares a duration, owner,
+    // or remaining — so we just check those four props. Status
+    // strings (in-progress) only matter when paired with one of
+    // these, so this is an upper bound (false-positives still grow
+    // the bar by exactly the same amount as the renderer would, so
+    // they stay byte-stable).
+    const hasMeta =
+        propValue(props, 'duration') !== undefined ||
+        propValue(props, 'size') !== undefined ||
+        propValue(props, 'owner') !== undefined ||
+        propValue(props, 'remaining') !== undefined ||
+        propValue(props, 'capacity') !== undefined;
+
+    const titleStr = item.title ?? item.name ?? '';
+    const titleW = titleStr ? estimateTextWidth(titleStr, ITEM_CAPTION_TITLE_FONT_SIZE_PX) : 0;
+    const captionSpills = titleW > insideAvail;
+    const pack = chipsOutside ? packSpillChips(samples, visualWidth) : null;
+    const chipRowCount = pack ? pack.rows.length : samples.length > 0 ? 1 : 0;
+    return computeChipBarExtra(
+        chipsOutside,
+        captionSpills,
+        chipRowCount,
+        ctx.bandScale.bandwidth(),
+        hasMeta,
+    );
+}
+
+// Resolve the desired startX for a swimlane child, honoring `date:` (fixed
+// pin) > `start:` (fixed pin) > `after:` (chain after refs) > sequential
+// default (continue from `seqDefault`, which is the lane's rightmost time
+// cursor across all rows).
+//
+// `after:` accepts both entity ids (looked up in `ctx.entityRightEdges`) and
+// inline ISO date literals (looked up via `ctx.scale.forwardWithinDomain`).
+// The validator already enforces "at most one inline date per direction" so
+// at most one element in the list will hit the date path.
+function resolveChildStart(
+    props: EntityProperty[],
+    seqDefault: number,
+    laneLeftX: number,
+    ctx: LayoutContext,
+): number {
+    const explicitDate =
+        parseDate(propValue(props, 'date')) ?? parseDate(propValue(props, 'start'));
+    if (explicitDate) {
+        const xd = ctx.scale.forwardWithinDomain(explicitDate);
+        if (xd !== null) return xd;
+    }
+    const afterRefs = propValues(props, 'after');
+    if (afterRefs.length > 0) {
+        let maxEnd = laneLeftX;
+        for (const ref of afterRefs) {
+            const inlineDate = parseDate(ref);
+            if (inlineDate) {
+                const xd = ctx.scale.forwardWithinDomain(inlineDate);
+                if (xd !== null) maxEnd = Math.max(maxEnd, xd);
+                continue;
+            }
+            const endX = ctx.entityRightEdges.get(ref);
+            if (endX !== undefined) maxEnd = Math.max(maxEnd, endX);
+        }
+        return Math.max(laneLeftX, maxEnd);
+    }
+    return seqDefault;
+}
+
+function _buildSwimlane(
+    lane: SwimlaneDeclaration,
+    y: number,
+    bandIndex: number,
+    ctx: LayoutContext,
+): { positioned: PositionedSwimlane; usedHeight: number } {
+    return new SwimlaneNode(
+        { lane, bandIndex },
+        {
+            sequenceItem,
+            sequenceOne,
+            resolveChildStart,
+            newCursor,
+            estimateTextWidth,
+            predictItemChipExtraHeight,
+        },
+    ).place({ x: ctx.timeline.originX, y }, ctx);
+}
+
+// Card-sizing constants for beside-mode headers live in
+// `header-card-geometry.ts` so the renderer can paint with the same
+// numbers the layout sized against. Title and author both wrap at
+// MAX_CONTENT_WIDTH (= MAX header width minus 2 * padding). The card
+// hugs its content in the MIN..MAX range and grows vertically when
+// wrapping is needed.
+//
+// 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;
+
+interface SizedHeader {
+    titleLines: string[];
+    authorLines: string[];
+    cardWidth: number;
+    cardHeight: number;
+    boxWidth: number;
+}
+
+// Word-wrap `text` so that no line wider than `maxWidth` (in px). Long single
+// words are kept on their own line even if they overflow — we never split a
+// word in the middle.
+function wrapText(text: string, maxWidth: number, fontSize: number): string[] {
+    if (!text) return [];
+    const words = text.split(/\s+/).filter((w) => w.length > 0);
+    if (words.length === 0) return [];
+    const lines: string[] = [];
+    let cur = '';
+    for (const word of words) {
+        const trial = cur ? `${cur} ${word}` : word;
+        if (cur && estimateTextWidth(trial, fontSize) > maxWidth) {
+            lines.push(cur);
+            cur = word;
+        } else {
+            cur = trial;
+        }
+    }
+    if (cur) lines.push(cur);
+    return lines;
+}
+
+function sizeBesideHeader(title: string, author: string | undefined): 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));
+
+    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),
+    );
+
+    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 cardHeight =
+        HEADER_CARD_PADDING_TOP + titleBlockHeight + authorBlockHeight + HEADER_CARD_PADDING_BOTTOM;
+
+    // `boxWidth` only includes the LEFT outer pad — the right-side breathing
+    // room between the card and the chart is owned by `GUTTER_PX` in
+    // `RoadmapNode`. 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, boxWidth };
+}
+
+// Compute a sensible [startDate, endDate] window.
+//
+// Precedence:
+//   1. Explicit `length:` on the roadmap declaration wins.
+//   2. Otherwise we derive the end day from the actual content extent
+//      (latest item end, anchor date, milestone date/after, and today's
+//      now-line if it falls past the content). This keeps the rendered
+//      chart from defaulting to a 180-day desert when the content only
+//      spans a few weeks.
+//   3. As a last resort (no content + no length), fall back to a small
+//      4-week placeholder so an empty roadmap still draws a sensible axis.
+function computeDateWindow(
+    file: NowlineFile,
+    ctx: {
+        cal: import('./calendar.js').CalendarConfig;
+        sizes: Map<string, import('./types.js').ResolvedSize>;
+    },
+    resolved: ResolveResult,
+    today: Date | undefined,
+    scale: ViewPreset,
+): { startDate: Date; endDate: Date } {
+    const roadmap = file.roadmapDecl;
+    const props = roadmap?.properties ?? [];
+    const startRaw = propValue(props, 'start');
+    // Spec (`specs/dsl.md`): "A roadmap with no `start:` and no dates is
+    // purely relative — renderers choose their own reference date (e.g.
+    // the day of rendering)." Use the caller's `today` (the resolved
+    // `--now`) when present so the start lines up with the now-line, and
+    // fall back to actual today's UTC midnight otherwise. Either default
+    // is dangerous — output drifts day-to-day — but it's strictly better
+    // than the legacy "Jan 1 of the current year" fallback that drifted
+    // every January 1 by 365 days at once. Authors should set `start:`
+    // for any roadmap they want to be reproducible.
+    const startDate = parseDate(startRaw) ?? defaultStartDate(today);
+    const lengthRaw = propValue(props, 'length');
+    if (lengthRaw) {
+        const days = literalDays(lengthRaw, ctx.cal);
+        if (days > 0) {
+            return { startDate, endDate: addDays(startDate, days) };
+        }
+    }
+    const contentDays = computeContentEndDay(resolved, ctx, startDate, today);
+    const tickDays = daysPerUnit(scale.unit, ctx.cal);
+    // Round up to the smallest tick boundary that is `>= contentDays`. When
+    // the latest content lands exactly on a tick boundary the chart ends
+    // exactly there (no extra trailing tick); otherwise we extend to the
+    // next tick so the right edge always sits on a labelled column.
+    const padded =
+        contentDays > 0 ? Math.ceil(contentDays / tickDays) * tickDays : 4 * ctx.cal.daysPerWeek;
+    return { startDate, endDate: addDays(startDate, Math.max(1, padded)) };
+}
+
+/**
+ * Reference date used when a roadmap omits `start:`. Prefers the
+ * caller-supplied `today` (UTC midnight already, when it comes from
+ * the CLI); falls back to actual today's UTC midnight so the layout
+ * still produces a valid window for direct API callers that don't pass
+ * a `today`. Date components are taken in UTC to match `parseDate`.
+ */
+function defaultStartDate(today: Date | undefined): Date {
+    const ref = today ?? new Date();
+    return new Date(Date.UTC(ref.getUTCFullYear(), ref.getUTCMonth(), ref.getUTCDate()));
+}
+
+function literalDays(literal: string, cal: import('./calendar.js').CalendarConfig): number {
+    const m = /^(\d+(?:\.\d+)?)([dwmqy])$/.exec(literal);
+    if (!m) return 0;
+    const n = parseFloat(m[1]);
+    switch (m[2]) {
+        case 'd':
+            return n;
+        case 'w':
+            return n * cal.daysPerWeek;
+        case 'm':
+            return n * cal.daysPerMonth;
+        case 'q':
+            return n * cal.daysPerQuarter;
+        case 'y':
+            return n * cal.daysPerYear;
+        default:
+            return 0;
+    }
+}
+
+// Walk every dated/sequenced entity in the resolved content and return the
+// latest day-offset from `startDate`. Mirrors the sequencer's start-rules
+// (date: > start: > after: > previous-in-lane) without producing positions.
+function computeContentEndDay(
+    resolved: ResolveResult,
+    ctx: {
+        cal: import('./calendar.js').CalendarConfig;
+        sizes: Map<string, import('./types.js').ResolvedSize>;
+    },
+    startDate: Date,
+    today: Date | undefined,
+): number {
+    const itemEnd = new Map<string, number>();
+    const anchorEnd = new Map<string, number>();
+    const milestoneEnd = new Map<string, number>();
+    let maxDay = 0;
+
+    // Resolve a single `after:` element to a day-offset from `startDate`.
+    // The element is either an entity id (looked up in itemEnd / anchorEnd /
+    // milestoneEnd) or an inline ISO date literal (converted directly via
+    // `daysBetween`). The validator already enforces "at most one inline date
+    // per direction", so at most one element per list will hit the date path.
+    const resolveAfterDay = (ref: string): number => {
+        const inlineDate = parseDate(ref);
+        if (inlineDate) return daysBetween(startDate, inlineDate);
+        if (itemEnd.has(ref)) return itemEnd.get(ref)!;
+        if (anchorEnd.has(ref)) return anchorEnd.get(ref)!;
+        if (milestoneEnd.has(ref)) return milestoneEnd.get(ref)!;
+        return 0;
+    };
+
+    // Pre-seed anchors fixed by `date:` so items that reference them get a
+    // valid end-day during the lane walk.
+    for (const anchor of resolved.content.anchors.values()) {
+        const d = parseDate(propValue(anchor.properties, 'date'));
+        if (d && anchor.name) {
+            const day = daysBetween(startDate, d);
+            anchorEnd.set(anchor.name, day);
+            maxDay = Math.max(maxDay, day);
+        }
+    }
+
+    const walkLane = (children: SwimlaneDeclaration['content'], baselineEnd: number): number => {
+        let prevEnd = baselineEnd;
+        for (const child of children) {
+            if (child.$type === 'DescriptionDirective') continue;
+            prevEnd = walkNode(child as ItemDeclaration | GroupBlock | ParallelBlock, prevEnd);
+            maxDay = Math.max(maxDay, prevEnd);
+        }
+        return prevEnd;
+    };
+
+    const walkNode = (
+        node: ItemDeclaration | GroupBlock | ParallelBlock,
+        prevEnd: number,
+    ): number => {
+        if (isItemDeclaration(node)) {
+            const dur = deriveItemDurationDays(node.properties, ctx.sizes, ctx.cal);
+            const dateProp = parseDate(propValue(node.properties, 'date'));
+            const startProp = parseDate(propValue(node.properties, 'start'));
+            const afterRefs = propValues(node.properties, 'after');
+            let start = prevEnd;
+            if (dateProp) {
+                start = daysBetween(startDate, dateProp);
+            } else if (startProp) {
+                start = daysBetween(startDate, startProp);
+            } else if (afterRefs.length > 0) {
+                start = Math.max(prevEnd, ...afterRefs.map(resolveAfterDay));
+            }
+            const end = start + dur;
+            if (node.name) itemEnd.set(node.name, end);
+            return end;
+        }
+        if (isParallelBlock(node)) {
+            // All children share the parallel's start; the block's effective
+            // end is the maximum child end. The parallel's own `after:`
+            // (including inline-date pins) widens that shared start.
+            const afterRefs = propValues(node.properties, 'after');
+            const containerStart =
+                afterRefs.length > 0
+                    ? Math.max(prevEnd, ...afterRefs.map(resolveAfterDay))
+                    : prevEnd;
+            let parallelEnd = containerStart;
+            for (const child of node.content) {
+                if (child.$type === 'DescriptionDirective') continue;
+                const childEnd = walkNode(child as ItemDeclaration | GroupBlock, containerStart);
+                parallelEnd = Math.max(parallelEnd, childEnd);
+            }
+            return parallelEnd;
+        }
+        if (isGroupBlock(node)) {
+            // The group's own `after:` (including inline-date pins) widens
+            // the baseline before walking the inner sequential lane.
+            const afterRefs = propValues(node.properties, 'after');
+            const containerStart =
+                afterRefs.length > 0
+                    ? Math.max(prevEnd, ...afterRefs.map(resolveAfterDay))
+                    : prevEnd;
+            return walkLane(node.content as SwimlaneDeclaration['content'], containerStart);
+        }
+        return prevEnd;
+    };
+
+    for (const lane of resolved.content.swimlanes.values()) {
+        walkLane(lane.content, 0);
+    }
+
+    // Milestones (after items so `after:` references can resolve).
+    for (const ms of resolved.content.milestones.values()) {
+        const d = parseDate(propValue(ms.properties, 'date'));
+        if (d) {
+            const day = daysBetween(startDate, d);
+            if (ms.name) milestoneEnd.set(ms.name, day);
+            maxDay = Math.max(maxDay, day);
+            continue;
+        }
+        const after = propValues(ms.properties, 'after');
+        if (after.length > 0) {
+            // Milestones disallow inline date literals at the validator
+            // level (rule 24a — milestones already have `date:`). The
+            // shared `resolveAfterDay` helper still handles such input
+            // gracefully if it slips past, treating the date as the
+            // milestone's effective day.
+            const day = Math.max(0, ...after.map(resolveAfterDay));
+            if (ms.name) milestoneEnd.set(ms.name, day);
+            maxDay = Math.max(maxDay, day);
+        }
+    }
+
+    // Isolated includes contribute their own content extent against the
+    // shared timeline.
+    for (const region of resolved.content.isolatedRegions) {
+        const nestedMax = computeContentEndDay(
+            {
+                config: region.config,
+                content: region.content,
+                diagnostics: [],
+                processedFiles: new Set(),
+            },
+            ctx,
+            startDate,
+            undefined,
+        );
+        maxDay = Math.max(maxDay, nestedMax);
+    }
+
+    if (today) {
+        const t = daysBetween(startDate, today);
+        if (t > 0) maxDay = Math.max(maxDay, t);
+    }
+
+    return maxDay;
+}
+
+function buildDependencies(
+    items: Map<string, ItemDeclaration>,
+    swimlanes: PositionedSwimlane[],
+    includes: PositionedIncludeRegion[],
+    ctx: LayoutContext,
+): PositionedDependencyEdge[] {
+    // m2g+: collect every painted item bar + every visible parallel /
+    // group bracket once, hand to the channel router so it can drop
+    // vertical legs in clean inter-column gutters and nudge away from
+    // bracket strokes that would otherwise be hugged.
+    const grid = new ChannelGrid(collectRoutingObstacles(swimlanes, includes));
+
+    interface Pending {
+        fromId: string;
+        toId: string;
+    }
+    const requests: EdgeRouteRequest[] = [];
+    const pending: Pending[] = [];
+
+    for (const [id, item] of items) {
+        const afters = propValues(item.properties, 'after');
+        const targetMid = ctx.entityMidpoints.get(id);
+        const targetVisualLeftX = ctx.entityVisualLeftX.get(id);
+        if (!targetMid || targetVisualLeftX === undefined) continue;
+        // The arrow always TERMINATES at the target item's left
+        // visual edge, vertically centered on the bar.
+        const targetPoint: Point = { x: targetVisualLeftX, y: targetMid.y };
+        for (const pred of afters) {
+            // Source point depends on what kind of predecessor `pred`
+            // is. For ITEMS we use the per-item arrow source point
+            // — (visualRight, midY) by default, dropping to
+            // (visualRight, bar.bottom - PROGRESS_STRIP_HEIGHT/2) when
+            // the caption spilled past the right edge so the arrow
+            // exits below the spilled title / meta text. For ANCHORS
+            // / MILESTONES we attach to the marker's vertical CUT
+            // LINE at the TARGET item's row mid-Y — the dashed/solid
+            // cut line already drops through the chart and reads as
+            // the arrow's stem, so a short horizontal stub from the
+            // line into the bar's left edge is the cleanest
+            // connection.
+            const itemSource = ctx.itemArrowSource.get(pred);
+            let from: Point;
+            const isMarkerPred = itemSource === undefined;
+            if (itemSource) {
+                from = itemSource;
+            } else {
+                const markerMid = ctx.entityMidpoints.get(pred);
+                if (!markerMid) continue;
+                from = { x: markerMid.x, y: targetMid.y };
+            }
+            // Skip same-row contiguous chains for ITEM → ITEM only:
+            // when the target sits immediately to the right of the
+            // source on the same row, the spatial flow already
+            // conveys ordering and an arrow is redundant noise.
+            // MARKER → ITEM stubs always draw (the cut line is the
+            // stem; the short stub completes the visual connection
+            // even when the bar is right next to the cut line).
+            if (
+                !isMarkerPred &&
+                Math.abs(from.y - targetPoint.y) < 0.5 &&
+                targetPoint.x - from.x < 20
+            ) {
+                continue;
+            }
+            requests.push({
+                fromId: pred,
+                toId: id,
+                from,
+                to: targetPoint,
+                isMarkerSource: isMarkerPred,
+            });
+            pending.push({ fromId: pred, toId: id });
+        }
+    }
+
+    const routed = routeChannelEdges(requests, grid);
+    const out: PositionedDependencyEdge[] = [];
+    for (let i = 0; i < routed.length; i++) {
+        const r = routed[i];
+        out.push({
+            fromId: pending[i].fromId,
+            toId: pending[i].toId,
+            waypoints: r.waypoints,
+            kind: r.underBar ? 'underBar' : 'normal',
+            style: resolveStyle('item', [], ctx.styleCtx),
+        });
+    }
+    return out;
+}
+
+function buildNowline(
+    today: Date | undefined,
+    ctx: LayoutContext,
+    locale: string,
+): PositionedNowline | null {
+    if (!today) return null;
+    const x = ctx.scale.forwardWithinDomain(today);
+    if (x === null) return null;
+    // Pill row is the band reserved at the very top of the timeline area.
+    // The line drops from the bottom of the pill (top of the date headers)
+    // through any marker row and into the chart, so the pill and line stay
+    // visually connected.
+    const pillTopY = ctx.timeline.box.y;
+    const lineTopY = ctx.timeline.tickPanelY;
+    // Pill width is locale-aware: en-US's `'now'` (3 chars) fits the
+    // 36 px default trivially; longer strings like fr's `'maint.'`
+    // (6 chars) need a wider pill to avoid clipping. Floor at the
+    // default so en-US output stays byte-stable; grow when the
+    // measured label needs it. The 2× inset matches the renderer's
+    // flag-mode label inset (`NOW_PILL_LABEL_INSET_X_PX`) and gives
+    // the same visual padding to centered-mode strings.
+    const label = localeStrings(locale).nowLabel;
+    const labelTextWidth = estimateTextWidth(label, NOW_PILL_LABEL_FONT_SIZE_PX);
+    const pillWidth = Math.max(
+        NOW_PILL_WIDTH_PX,
+        Math.ceil(labelTextWidth + 2 * NOW_PILL_LABEL_INSET_X_PX),
+    );
+    // The "chart's left edge" the pill must clear is `chartLeftX` (in
+    // beside-mode, the right edge of the header card; in above-mode,
+    // the canvas left edge at x=0). originX = chartLeftX + GUTTER_PX,
+    // so we recover chartLeftX as `originX - GUTTER_PX`.
+    const chartLeftX = ctx.timeline.originX - GUTTER_PX;
+    const halfPill = pillWidth / 2;
+    let pillMode: 'center' | 'flag-right' | 'flag-left';
+    if (x - halfPill < chartLeftX) {
+        // Centered pill would intrude into the header card / past the
+        // canvas left edge — anchor the pill's LEFT side to the line
+        // and let it extend right into the chart.
+        pillMode = 'flag-right';
+    } else if (x + halfPill > ctx.chartRightX) {
+        // Centered pill would clip past the canvas right edge — anchor
+        // the pill's RIGHT side to the line and let it extend left.
+        pillMode = 'flag-left';
+    } else {
+        pillMode = 'center';
+    }
+    // Bottom-most Y the now-line should reach. When a mirrored bottom
+    // tick panel exists, thread the line through it (so the line ties
+    // the two date strips together visually). Otherwise stop at the
+    // last swimlane — never extend into the footnote area below.
+    const bottomTickPanelY = ctx.timeline.bottomTickPanelY;
+    const bottomTickPanelHeight = ctx.timeline.bottomTickPanelHeight ?? 0;
+    const lineBottomY =
+        bottomTickPanelY !== undefined && bottomTickPanelHeight > 0
+            ? bottomTickPanelY + bottomTickPanelHeight
+            : ctx.swimlaneBottomY;
+    return {
+        x,
+        topY: lineTopY,
+        bottomY: lineBottomY,
+        pillTopY,
+        pillMode,
+        label,
+        pillWidth,
+        style: resolveStyle('item', [], ctx.styleCtx),
+    };
+}
+
+// Mutable layout-time context shared across helpers.
+
+// Traverse the full content tree to build an `items` map keyed by id.
+function collectItems(swimlanes: SwimlaneDeclaration[]): Map<string, ItemDeclaration> {
+    const out = new Map<string, ItemDeclaration>();
+    const walk = (node: ItemDeclaration | GroupBlock | ParallelBlock): void => {
+        if (isItemDeclaration(node)) {
+            if (node.name) out.set(node.name, node);
+            return;
+        }
+        if (isParallelBlock(node)) {
+            for (const child of node.content) {
+                if (child.$type === 'DescriptionDirective') continue;
+                walk(child as ItemDeclaration | GroupBlock);
+            }
+            return;
+        }
+        if (isGroupBlock(node)) {
+            for (const child of node.content) {
+                if (child.$type === 'DescriptionDirective') continue;
+                walk(child as ItemDeclaration | GroupBlock | ParallelBlock);
+            }
+            return;
+        }
+    };
+    for (const lane of swimlanes) {
+        for (const child of lane.content) {
+            if (child.$type === 'DescriptionDirective') continue;
+            walk(child as ItemDeclaration | GroupBlock | ParallelBlock);
+        }
+    }
+    return out;
+}
+
+export function layoutRoadmap(
+    file: NowlineFile,
+    resolved: ResolveResult,
+    options: LayoutOptions = {},
+): LayoutResult {
+    return new RoadmapNode().place(file, resolved, options, {
+        sequenceItem,
+        sequenceOne,
+        resolveChildStart,
+        newCursor,
+        estimateTextWidth,
+        predictItemChipExtraHeight,
+        computeDateWindow,
+        sizeBesideHeader,
+        collectItems,
+        buildDependencies,
+        buildNowline,
+    });
+}