@nowline/layout 0.8.5 → 0.9.0

package/src/inline-date-pin-geometry.ts

@@ -4,7 +4,7 @@
 // slot; `before:DATE` paints it in the top-RIGHT slot. The two helpers
 // below produce `Point` coordinates for the glyph's top-left corner, plus
 // a `spilled` flag indicating whether the bar was too narrow to host the
-// glyph inside (item case only — containers always have room).
+// glyph inside (item case only — containers never spill).
 //
 // Slot interleaving rules (per specs/rendering.md "Inline-date glyph"):
 //
@@ -18,25 +18,26 @@
 //   footnotes are present (so the inline-date glyph inserts at the LEFT
 //   end of the existing badge cluster rather than reordering it).
 //
-//   Container (group, parallel): glyph sits at the bounding box's top
-//   corners with the standard inset. Containers don't carry status dots
-//   or footnote indicators in their own decoration row, so no
-//   interleaving math is needed.
+//   Container (group, parallel): the glyphs sit in the header band, in the
+//   title row above the bracket (see `computeContainerInlineDatePins`).
+//   Containers don't carry status dots or footnote indicators, so the
+//   only neighbor to clear is the container's own title.
 
+import { parseIsoDate } from '@nowline/core/internal';
+import {
+    CONTAINER_BRACKET_LINE_OFFSET_PX,
+    containerHeaderTitleWidth,
+    containerHeaderTitleX,
+} from './container-header-geometry.js';
 import {
     INLINE_DATE_GLYPH_GAP_PX,
-    INLINE_DATE_GLYPH_INSET_LEFT_PX,
     INLINE_DATE_GLYPH_INSET_RIGHT_PX,
     INLINE_DATE_GLYPH_INSET_TOP_PX,
     INLINE_DATE_GLYPH_TILE_SIZE_PX,
     ITEM_CAPTION_SPILL_GAP_PX,
-    ITEM_FOOTNOTE_INDICATOR_INSET_RIGHT_PX,
-    ITEM_FOOTNOTE_INDICATOR_STEP_PX,
-    ITEM_LINK_ICON_INSET_PX,
-    ITEM_LINK_ICON_TILE_SIZE_PX,
-    ITEM_STATUS_DOT_INSET_RIGHT_PX,
-    ITEM_STATUS_DOT_RADIUS_PX,
-    MIN_BAR_WIDTH_FOR_INLINE_DATE_PX,
+    inlineDateGlyphSpills,
+    itemAfterGlyphInsideLeftX,
+    itemBeforeGlyphInsideLeftX,
 } from './item-bar-geometry.js';
 import type { BoundingBox, InlineDatePin, Point } from './types.js';
 
@@ -68,15 +69,13 @@ export function computeItemInlineDatePins(opts: ItemInlineDatePinInputs): Inline
     const pins: InlineDatePin[] = [];
     const tileSize = INLINE_DATE_GLYPH_TILE_SIZE_PX;
     const topY = box.y + INLINE_DATE_GLYPH_INSET_TOP_PX;
-    const spilled = box.width < MIN_BAR_WIDTH_FOR_INLINE_DATE_PX;
+    const spilled = inlineDateGlyphSpills(box.width);
 
     if (afterDate) {
-        const insideLeftX = hasLinkIcon
-            ? box.x +
-              ITEM_LINK_ICON_INSET_PX +
-              ITEM_LINK_ICON_TILE_SIZE_PX +
-              INLINE_DATE_GLYPH_GAP_PX
-            : box.x + INLINE_DATE_GLYPH_INSET_LEFT_PX;
+        // Walk RIGHT past the link tile when there is one; the formula is
+        // shared with the caption's left inset, see
+        // `itemAfterGlyphInsideLeftX`.
+        const insideLeftX = itemAfterGlyphInsideLeftX(box.x, hasLinkIcon);
         const glyphLeft: Point = spilled
             ? {
                   x: box.x - ITEM_CAPTION_SPILL_GAP_PX - tileSize,
@@ -93,31 +92,17 @@ export function computeItemInlineDatePins(opts: ItemInlineDatePinInputs): Inline
     }
 
     if (beforeDate) {
-        // Walk LEFT from the rightmost top-decoration slot:
-        //   - rightmost footnote anchors at (box.right - INSET_RIGHT_PX)
-        //   - leftmost footnote sits one step further left per extra digit
-        //   - status dot left edge sits at (box.right - INSET_RIGHT - DOT_RADIUS)
-        //   - inline-date glyph sits one INLINE_DATE_GLYPH_GAP_PX further left
+        // Walk LEFT from the rightmost top-decoration slot; the formula is
+        // shared with the title first-line clearance, see
+        // `itemBeforeGlyphInsideLeftX`.
         const rightEdge = box.x + box.width;
-        let anchorRightX: number;
-        if (footnoteCount > 0) {
-            const leftmostFootnoteCenter =
-                rightEdge -
-                ITEM_FOOTNOTE_INDICATOR_INSET_RIGHT_PX -
-                (footnoteCount - 1) * ITEM_FOOTNOTE_INDICATOR_STEP_PX;
-            anchorRightX = leftmostFootnoteCenter - INLINE_DATE_GLYPH_GAP_PX;
-        } else {
-            const dotLeftEdge =
-                rightEdge - ITEM_STATUS_DOT_INSET_RIGHT_PX - ITEM_STATUS_DOT_RADIUS_PX;
-            anchorRightX = dotLeftEdge - INLINE_DATE_GLYPH_GAP_PX;
-        }
-        const insideRightX = anchorRightX - tileSize;
+        const insideLeftX = itemBeforeGlyphInsideLeftX(rightEdge, footnoteCount);
         const glyphLeft: Point = spilled
             ? {
                   x: rightEdge + ITEM_CAPTION_SPILL_GAP_PX,
                   y: topY,
               }
-            : { x: insideRightX, y: topY };
+            : { x: insideLeftX, y: topY };
         pins.push({
             side: 'before',
             isoDate: beforeDate,
@@ -131,50 +116,60 @@ export function computeItemInlineDatePins(opts: ItemInlineDatePinInputs): Inline
 }
 
 export interface ContainerInlineDatePinInputs {
-    /** Bounding box that anchors the glyph corners. For styled groups and
-     *  bracketed parallels this is the visible box; for unstyled groups
-     *  and bare parallels it is the logical bounding box (leftmost child
-     *  start, rightmost child end, top of the highest child row). */
+    /** The container's box: `box.y` is its header's top, `box.x` and
+     *  `box.width` its dates. */
     box: BoundingBox;
     afterDate: string | undefined;
     beforeDate: string | undefined;
+    /** The title painted in the header, if any. */
+    title: string | undefined;
 }
 
 /**
  * Compute inline-date pin glyph placements for a container (group or
- * parallel). The glyphs sit flush to the box's top-LEFT (`after`) and
- * top-RIGHT (`before`) corners with the standard inset; containers
- * never spill (they always have room for a 12 px tile in their own
- * top-decoration row).
+ * parallel). Containers never spill. Both glyphs sit in the header's title
+ * row, above the bracket line (specs/true-width-layout.md §3.3):
+ *
+ *   - `after` takes the row's leftmost slot, on the container's start; the
+ *     title follows one gap past it (`containerHeaderTitleX`).
+ *   - `before` sits the standard inset short of the container's end (a
+ *     sibling may start on that end, level with the header), but never
+ *     slides left onto the title (estimated width) or the `after` glyph:
+ *     when those run past its slot, it sits one gap past whichever ends
+ *     last, beyond the bracket's end, and the row reserves it.
  */
 export function computeContainerInlineDatePins(
     opts: ContainerInlineDatePinInputs,
 ): InlineDatePin[] {
-    const { box, afterDate, beforeDate } = opts;
+    const { box, afterDate, beforeDate, title } = opts;
     if (!afterDate && !beforeDate) return [];
 
     const pins: InlineDatePin[] = [];
     const tileSize = INLINE_DATE_GLYPH_TILE_SIZE_PX;
-    const topY = box.y + INLINE_DATE_GLYPH_INSET_TOP_PX;
+    const topY = box.y + (CONTAINER_BRACKET_LINE_OFFSET_PX - tileSize) / 2;
+    // Right edge of whatever already occupies the row's left end.
+    let leftClearX = title
+        ? containerHeaderTitleX(box.x, Boolean(afterDate)) + containerHeaderTitleWidth(title)
+        : box.x;
 
     if (afterDate) {
+        leftClearX = Math.max(leftClearX, box.x + tileSize);
         pins.push({
             side: 'after',
             isoDate: afterDate,
-            glyphTopLeft: { x: box.x + INLINE_DATE_GLYPH_INSET_LEFT_PX, y: topY },
+            glyphTopLeft: { x: box.x, y: topY },
             glyphSize: tileSize,
             spilled: false,
         });
     }
 
     if (beforeDate) {
+        const flushRightX = box.x + box.width - INLINE_DATE_GLYPH_INSET_RIGHT_PX - tileSize;
+        const clearX = leftClearX > box.x ? leftClearX + INLINE_DATE_GLYPH_GAP_PX : box.x;
         pins.push({
             side: 'before',
             isoDate: beforeDate,
-            glyphTopLeft: {
-                x: box.x + box.width - INLINE_DATE_GLYPH_INSET_RIGHT_PX - tileSize,
-                y: topY,
-            },
+            glyphTopLeft: { x: Math.max(flushRightX, clearX), y: topY },
             glyphSize: tileSize,
             spilled: false,
         });
@@ -184,13 +179,15 @@ export function computeContainerInlineDatePins(
 }
 
 /**
- * Returns the first ISO date literal in `values`, or undefined when none
- * is present. The validator enforces "at most one inline date per
- * direction" so this lookup is unambiguous.
+ * Returns the first ISO date literal in `values` that names a real
+ * calendar day, or undefined when none is present. The validator enforces
+ * "at most one inline date per direction" so this lookup is unambiguous.
+ * An impossible day (`2026-02-30`, NL.E0405) is no date: the scheduler
+ * ignores it, so it gets no glyph either.
  */
 export function pickInlineDate(values: readonly string[]): string | undefined {
     for (const v of values) {
-        if (/^\d{4}-\d{2}-\d{2}$/.test(v)) return v;
+        if (parseIsoDate(v)) return v;
     }
     return undefined;
 }

package/src/item-bar-geometry.ts

@@ -14,6 +14,8 @@
 // `box.width` used as the "right edge" / "bottom edge" anchor where
 // noted.
 
+import { estimateTextWidth } from './text-measure.js';
+
 // ---- Caption (title + meta text) ---------------------------------
 
 /** Horizontal inset (px) for the caption's left edge inside the bar. */
@@ -39,6 +41,66 @@ export const ITEM_CAPTION_TITLE_FONT_SIZE_PX = 13;
 /** Font size (px) of the meta text. */
 export const ITEM_CAPTION_META_FONT_SIZE_PX = 11;
 
+/**
+ * Baseline-to-baseline pitch (px) between consecutive TITLE lines when
+ * a long title word-wraps inside the bar. The meta line sits one more
+ * pitch below the last title line for every extra title line, see
+ * `itemCaptionMetaBaselineOffset`.
+ */
+export const ITEM_CAPTION_TITLE_LINE_HEIGHT_PX = 16;
+
+/**
+ * Most title lines layout will wrap a title onto inside the bar. A
+ * title that needs more than this spills to the right of the bar as a
+ * single line instead.
+ */
+export const ITEM_CAPTION_TITLE_MAX_LINES = 2;
+
+/**
+ * Baseline Y (px from the bar's top) of the meta line when the title
+ * occupies `lineCount` lines. One line gives the classic
+ * `ITEM_CAPTION_META_BASELINE_OFFSET_PX`; each extra title line pushes
+ * the meta baseline down by `ITEM_CAPTION_TITLE_LINE_HEIGHT_PX`.
+ */
+export function itemCaptionMetaBaselineOffset(lineCount: number): number {
+    return (
+        ITEM_CAPTION_META_BASELINE_OFFSET_PX +
+        (Math.max(1, lineCount) - 1) * ITEM_CAPTION_TITLE_LINE_HEIGHT_PX
+    );
+}
+
+/**
+ * Baseline Y (px from the bar's top) of the LAST caption line: the
+ * meta line when the item has one, otherwise the final title line.
+ * Anything stacked below the caption (label chips) must clear this.
+ */
+export function itemCaptionLastBaselineOffset(lineCount: number, hasMeta: boolean): number {
+    if (hasMeta) return itemCaptionMetaBaselineOffset(lineCount);
+    return (
+        ITEM_CAPTION_TITLE_BASELINE_OFFSET_PX +
+        (Math.max(1, lineCount) - 1) * ITEM_CAPTION_TITLE_LINE_HEIGHT_PX
+    );
+}
+
+/**
+ * Extra bar height (px) a wrapped title needs on top of the default
+ * `bandwidth`. The default bar is sized so the caption's last baseline
+ * is at most `ITEM_CAPTION_META_BASELINE_OFFSET_PX`; anything below
+ * that grows the bar by the overshoot:
+ *
+ *   - 1 title line (with or without meta): 0.
+ *   - 2 title lines, no meta: line 2 lands at baseline 36, so 0.
+ *   - 2 title lines + meta: meta baseline 54, so 16.
+ *
+ * The same number is the row-pitch increase for the bar's row.
+ */
+export function computeTitleBarExtra(lineCount: number, hasMeta: boolean): number {
+    return Math.max(
+        0,
+        itemCaptionLastBaselineOffset(lineCount, hasMeta) - ITEM_CAPTION_META_BASELINE_OFFSET_PX,
+    );
+}
+
 // ---- Status dot (upper-right glyph) ------------------------------
 
 /** Distance (px) from the bar's right edge to the dot's center. */
@@ -61,6 +123,13 @@ export const ITEM_FOOTNOTE_INDICATOR_INSET_RIGHT_PX = 22;
 /** Baseline Y (px from bar's top) for footnote indicator digits. */
 export const ITEM_FOOTNOTE_INDICATOR_BASELINE_OFFSET_PX = 14;
 
+/**
+ * Font size (px) of the footnote indicator digits. The renderer paints
+ * them at this size and layout measures them with it (to find the
+ * cluster's left edge), so both read the same constant.
+ */
+export const ITEM_FOOTNOTE_INDICATOR_FONT_SIZE_PX = 10;
+
 /**
  * Horizontal step (px) between consecutive footnote indicators when
  * an item carries more than one footnote — they walk LEFT from the
@@ -76,6 +145,65 @@ export const ITEM_LINK_ICON_TILE_SIZE_PX = 14;
 /** Distance (px) from the bar's right/bottom edges to the tile's edge. */
 export const ITEM_LINK_ICON_INSET_PX = 6;
 
+/**
+ * Horizontal gap (px) between the link-icon tile's right edge and the
+ * start of the caption text when both render inside the bar.
+ */
+export const ITEM_LINK_ICON_TO_CAPTION_GAP_PX = 4;
+
+/**
+ * The item carries an inline `after:DATE` glyph, on a bar of the given
+ * painted width. Passed to `itemCaptionInsetX` so the glyph, not just
+ * the link tile, reserves room at the caption's left edge.
+ */
+export interface ItemCaptionAfterGlyph {
+    /** Painted bar width (px): `box.width`. Decides whether the glyph spills. */
+    barWidth: number;
+}
+
+/**
+ * Left inset (px) of the in-bar caption from the bar's left edge. It is
+ * `ITEM_CAPTION_INSET_X_PX` normally, pushed right past the link-icon
+ * tile (and its gap) when the bar carries a link icon, and pushed right
+ * past the `after:` inline-date glyph (and a gap) when the bar carries
+ * one INSIDE it:
+ *
+ *   - no link icon, no glyph: 12
+ *   - link icon, no glyph: 24
+ *   - glyph, no link icon: 22 (the glyph spans 6..18, plus a 4 px gap)
+ *   - glyph and link icon: 40 (the glyph spans 24..36, plus a 4 px gap)
+ *
+ * A glyph on a bar narrower than `MIN_BAR_WIDTH_FOR_INLINE_DATE_PX`
+ * spills out of the bar to the left and reserves nothing.
+ *
+ * `hasLinkIcon` is the same flag `computeItemInlineDatePins` places the
+ * glyph with, and the glyph's right edge comes from the same helper
+ * (`itemAfterGlyphInsideLeftX`), so the inset and the glyph can't
+ * disagree. The inset applies to every caption line, not only line 1,
+ * so the caption's left edge stays straight.
+ */
+export function itemCaptionInsetX(
+    hasLinkIcon: boolean,
+    afterGlyph?: ItemCaptionAfterGlyph,
+): number {
+    let inset = ITEM_CAPTION_INSET_X_PX;
+    if (hasLinkIcon) {
+        const linkColumn =
+            ITEM_LINK_ICON_INSET_PX +
+            ITEM_LINK_ICON_TILE_SIZE_PX +
+            ITEM_LINK_ICON_TO_CAPTION_GAP_PX -
+            ITEM_CAPTION_INSET_X_PX;
+        inset = ITEM_CAPTION_INSET_X_PX + Math.max(0, linkColumn);
+    }
+    if (afterGlyph && !inlineDateGlyphSpills(afterGlyph.barWidth)) {
+        // Offsets from a left edge of 0, so the numbers are exact integers.
+        const glyphRight =
+            itemAfterGlyphInsideLeftX(0, hasLinkIcon) + INLINE_DATE_GLYPH_TILE_SIZE_PX;
+        inset = Math.max(inset, glyphRight + ITEM_DECORATION_SPILL_GAP_PX);
+    }
+    return inset;
+}
+
 // ---- Narrow-bar decoration spill --------------------------------
 
 /**
@@ -86,12 +214,14 @@ export const ITEM_LINK_ICON_INSET_PX = 6;
 export const ITEM_DECORATION_SPILL_GAP_PX = 4;
 
 /**
- * Minimum bar width (px) needed to host the status dot inside the
- * bar with its full inset. Below this, the dot would have to
- * extend past the bar's left edge, so the dot spills into the
- * caption column to the right of the bar instead.
+ * Minimum bar width (px) at which the status dot sits INSIDE the bar:
+ * the dot's centre is `ITEM_STATUS_DOT_INSET_RIGHT_PX` from the right
+ * edge, so a bar of twice that width has the same air on both sides
+ * of it (the centre sits mid-bar). A narrower bar would crowd the
+ * dot against its left edge, so the dot spills into the caption
+ * column to the right of the bar instead.
  */
-export const MIN_BAR_WIDTH_FOR_DOT_PX = ITEM_STATUS_DOT_INSET_RIGHT_PX + ITEM_STATUS_DOT_RADIUS_PX;
+export const MIN_BAR_WIDTH_FOR_DOT_PX = 2 * ITEM_STATUS_DOT_INSET_RIGHT_PX;
 
 /**
  * Minimum bar width (px) needed to host the link-icon tile AND the
@@ -116,6 +246,71 @@ export const MIN_BAR_WIDTH_FOR_LINK_AND_DOT_PX =
  */
 export const MIN_BAR_WIDTH_FOR_FOOTNOTE_PX = ITEM_FOOTNOTE_INDICATOR_INSET_RIGHT_PX + 1;
 
+/** What sits in a bar's spill column, in reading order. */
+export interface SpillClusterInput {
+    /** The bar's visual right edge. */
+    barRightX: number;
+    /** The link icon spilled out of the bar. */
+    iconSpills: boolean;
+    /** The spilled caption's width (its widest title line or the meta line), or null when it stays in the bar. */
+    captionWidth: number | null;
+    /** Spilled footnote indicators; 0 when they stay in the bar. */
+    footnoteCount: number;
+    /** The status dot spilled out of the bar. */
+    dotSpills: boolean;
+}
+
+/** Where each part of a spill column sits; null for a part that is not in it. */
+export interface SpillCluster {
+    iconSpillX: number | null;
+    captionX: number | null;
+    footnoteSpillStartX: number | null;
+    dotSpillCx: number | null;
+    /** Right edge of the last part, or the column's start when it is empty. */
+    rightX: number;
+}
+
+/**
+ * Lay out a bar's spill column `[icon?] [caption?] [¹²?] [dot?]` from
+ * `ITEM_CAPTION_SPILL_GAP_PX` past the bar, one `ITEM_DECORATION_SPILL_GAP_PX`
+ * between the parts that are present and none after the last. The item
+ * measure reads it to cap a caption at the chart's end, and `sequenceItem`
+ * places the parts with it.
+ */
+export function layoutSpillCluster(input: SpillClusterInput): SpillCluster {
+    let cursor = input.barRightX + ITEM_CAPTION_SPILL_GAP_PX;
+    // A gap goes in only once something is already in the column, so the
+    // cluster leaves no dangling gap past its last part.
+    let needGap = false;
+    let iconSpillX: number | null = null;
+    if (input.iconSpills) {
+        iconSpillX = cursor;
+        cursor = iconSpillX + ITEM_LINK_ICON_TILE_SIZE_PX;
+        needGap = true;
+    }
+    let captionX: number | null = null;
+    if (input.captionWidth !== null) {
+        if (needGap) cursor += ITEM_DECORATION_SPILL_GAP_PX;
+        captionX = cursor;
+        cursor += input.captionWidth;
+        needGap = true;
+    }
+    let footnoteSpillStartX: number | null = null;
+    if (input.footnoteCount > 0) {
+        if (needGap) cursor += ITEM_DECORATION_SPILL_GAP_PX;
+        footnoteSpillStartX = cursor;
+        cursor += input.footnoteCount * ITEM_FOOTNOTE_INDICATOR_STEP_PX;
+        needGap = true;
+    }
+    let dotSpillCx: number | null = null;
+    if (input.dotSpills) {
+        if (needGap) cursor += ITEM_DECORATION_SPILL_GAP_PX;
+        dotSpillCx = cursor + ITEM_STATUS_DOT_RADIUS_PX;
+        cursor = dotSpillCx + ITEM_STATUS_DOT_RADIUS_PX;
+    }
+    return { iconSpillX, captionX, footnoteSpillStartX, dotSpillCx, rightX: cursor };
+}
+
 // ---- Inline-date glyph (after:DATE / before:DATE corner badge) ---
 //
 // Renders the renderer's built-in `calendar` SVG at top-LEFT (`after`)
@@ -165,6 +360,147 @@ export const MIN_BAR_WIDTH_FOR_INLINE_DATE_PX =
     INLINE_DATE_GLYPH_TILE_SIZE_PX +
     INLINE_DATE_GLYPH_INSET_RIGHT_PX;
 
+/**
+ * True when a bar of painted width `barWidth` is too narrow to host the
+ * inline-date glyph inside, so it spills (`before:` right, `after:` left).
+ * The one threshold behind the glyph's `spilled` flag and the caption
+ * inset's decision to reserve room for it.
+ */
+export function inlineDateGlyphSpills(barWidth: number): boolean {
+    return barWidth < MIN_BAR_WIDTH_FOR_INLINE_DATE_PX;
+}
+
+/**
+ * Left x of the `after:` inline-date glyph when it sits INSIDE the bar,
+ * for a bar whose left edge is at `leftEdge`:
+ *
+ *   - no link icon: the glyph sits at the leftmost top-decoration slot,
+ *     `INLINE_DATE_GLYPH_INSET_LEFT_PX` (6) from the edge
+ *   - link icon: one `INLINE_DATE_GLYPH_GAP_PX` right of the tile's right
+ *     edge (6 + 14 + 4 = 24 from the edge)
+ *
+ * The one formula behind both the glyph placement
+ * (`computeItemInlineDatePins`) and the caption's left inset
+ * (`itemCaptionInsetX`), so the two can never disagree. Pass
+ * `leftEdge = 0` to get the offset from the bar's left edge.
+ */
+export function itemAfterGlyphInsideLeftX(leftEdge: number, hasLinkIcon: boolean): number {
+    return hasLinkIcon
+        ? leftEdge +
+              ITEM_LINK_ICON_INSET_PX +
+              ITEM_LINK_ICON_TILE_SIZE_PX +
+              INLINE_DATE_GLYPH_GAP_PX
+        : leftEdge + INLINE_DATE_GLYPH_INSET_LEFT_PX;
+}
+
+/**
+ * Left x of the `before:` inline-date glyph when it sits INSIDE the bar,
+ * for a bar whose right edge is at `rightEdge`. The glyph walks LEFT
+ * from the rightmost top-decoration slot:
+ *
+ *   - rightmost footnote anchors at (rightEdge - INSET_RIGHT_PX)
+ *   - the leftmost footnote sits one step further left per extra digit
+ *   - the status dot's left edge sits at (rightEdge - INSET_RIGHT - DOT_RADIUS)
+ *   - the glyph sits one `INLINE_DATE_GLYPH_GAP_PX` further left than
+ *     whichever of those is leftmost (footnotes win when present, since
+ *     they are always left of the dot)
+ *
+ * The one formula behind both the glyph placement
+ * (`computeItemInlineDatePins`) and the title first-line clearance
+ * (`itemTitleFirstLineRightReservePx`), so the two can never disagree.
+ * Pass `rightEdge = 0` to get the offset from the bar's right edge
+ * (negative, inside the bar) with exact integer arithmetic.
+ */
+export function itemBeforeGlyphInsideLeftX(rightEdge: number, footnoteCount: number): number {
+    let anchorRightX: number;
+    if (footnoteCount > 0) {
+        const leftmostFootnoteCenter =
+            rightEdge -
+            ITEM_FOOTNOTE_INDICATOR_INSET_RIGHT_PX -
+            (footnoteCount - 1) * ITEM_FOOTNOTE_INDICATOR_STEP_PX;
+        anchorRightX = leftmostFootnoteCenter - INLINE_DATE_GLYPH_GAP_PX;
+    } else {
+        const dotLeftEdge = rightEdge - ITEM_STATUS_DOT_INSET_RIGHT_PX - ITEM_STATUS_DOT_RADIUS_PX;
+        anchorRightX = dotLeftEdge - INLINE_DATE_GLYPH_GAP_PX;
+    }
+    return anchorRightX - INLINE_DATE_GLYPH_TILE_SIZE_PX;
+}
+
+// ---- Title first-line clearance (top-right decoration cluster) ---
+//
+// The status dot, footnote digits and `before:` glyph all sit in the
+// bar's upper-right at the title's first-line height (title baseline
+// 20, cluster y roughly 5-17). Line 2 (baseline 36) and the meta line
+// (baseline 38) are below the cluster, so only the FIRST title line has
+// to stay clear of it; every other caption line may use the full inner
+// width.
+
+export interface ItemTitleFirstLineReserveInputs {
+    /** Painted bar width (px): `box.width`. */
+    barWidth: number;
+    /**
+     * Footnote indicator labels in the order the renderer paints them,
+     * left to right (ascending footnote number). Empty when the item
+     * carries no footnote.
+     */
+    footnoteLabels: readonly string[];
+    /** True when the item has an inline `before:DATE` glyph. */
+    hasBeforeGlyph: boolean;
+}
+
+/**
+ * Right-side space (px) the FIRST title line must leave free, measured
+ * from the bar's right edge: the larger of the plain right inset
+ * (`ITEM_CAPTION_INSET_X_PX`) and the distance to the top-right
+ * cluster's left edge plus `ITEM_DECORATION_SPILL_GAP_PX` of air.
+ *
+ * The cluster is the leftmost of three parts, each counted only when it
+ * renders INSIDE the bar (a narrow bar spills it into the column to the
+ * right instead, where it can't touch the title):
+ *
+ *   - status dot: left edge at (right - 17); absent below
+ *     `MIN_BAR_WIDTH_FOR_DOT_PX` (24). Dot only gives 21.
+ *   - footnote digits: leftmost digit's left edge at
+ *     (right - 22 - (n-1) * 8 - width); absent when they spill
+ *     (`MIN_BAR_WIDTH_FOR_FOOTNOTE_PX`).
+ *   - `before:` glyph: its left x, from `itemBeforeGlyphInsideLeftX`;
+ *     absent when it spills (`MIN_BAR_WIDTH_FOR_INLINE_DATE_PX`).
+ *
+ * Offsets are computed from a right edge of 0 (inside the bar is
+ * negative) so the common cases are exact integers.
+ */
+export function itemTitleFirstLineRightReservePx(opts: ItemTitleFirstLineReserveInputs): number {
+    const { barWidth, footnoteLabels, hasBeforeGlyph } = opts;
+    let clusterLeft = Number.POSITIVE_INFINITY;
+    if (barWidth >= MIN_BAR_WIDTH_FOR_DOT_PX) {
+        clusterLeft = Math.min(
+            clusterLeft,
+            -(ITEM_STATUS_DOT_INSET_RIGHT_PX + ITEM_STATUS_DOT_RADIUS_PX),
+        );
+    }
+    const footnoteCount = footnoteLabels.length;
+    const footnotesInside = footnoteCount > 0 && barWidth >= MIN_BAR_WIDTH_FOR_FOOTNOTE_PX;
+    if (footnotesInside) {
+        // Digit `k` (0 = leftmost) anchors its RIGHT end at
+        // `-22 - (n-1-k) * 8`, so its left edge is that minus its width.
+        // Normally digit 0 reaches furthest left; checking all of them
+        // also covers a wide late digit (e.g. footnote 100 next to 9).
+        for (let k = 0; k < footnoteCount; k += 1) {
+            const anchorX =
+                -ITEM_FOOTNOTE_INDICATOR_INSET_RIGHT_PX -
+                (footnoteCount - 1 - k) * ITEM_FOOTNOTE_INDICATOR_STEP_PX;
+            const left =
+                anchorX -
+                estimateTextWidth(footnoteLabels[k], ITEM_FOOTNOTE_INDICATOR_FONT_SIZE_PX);
+            clusterLeft = Math.min(clusterLeft, left);
+        }
+    }
+    if (hasBeforeGlyph && barWidth >= MIN_BAR_WIDTH_FOR_INLINE_DATE_PX) {
+        clusterLeft = Math.min(clusterLeft, itemBeforeGlyphInsideLeftX(0, footnoteCount));
+    }
+    return Math.max(ITEM_CAPTION_INSET_X_PX, -clusterLeft + ITEM_DECORATION_SPILL_GAP_PX);
+}
+
 // ---- Label chips (along the bar's bottom) ------------------------
 
 /** Height (px) of a label chip rectangle. */

package/src/item-port-geometry.ts

@@ -0,0 +1,69 @@
+// Arrow ends: where dependency arrows and milestone slack lines meet an
+// item bar or a container.
+//
+// Every end is a pure function of the entity's FINAL geometry (its box,
+// plus an item's `dateSpan` and the row bandwidth), read when the arrows
+// are built, never captured while the entity is placed. Layout moves
+// placed content down afterwards (a marker band that outgrows its sizing
+// pushes the whole chart down), and a port captured at placement time
+// would stay behind at the old y. Nothing moves horizontally, so the
+// dates in x an item records at placement stay true.
+//
+// Rules (specs/true-width-layout.md §3.4, §3.5):
+//
+//   - x comes from the dates: the router puts the port in the middle of
+//     the source's last day and the target's first day (`edge-routing.ts`).
+//   - y comes from the painted edges: top and bottom of the bar, or of the
+//     container (its header's top to its body's bottom).
+//   - On its own row an arrow runs at the row's NOMINAL midline,
+//     `box.y + bandwidth / 2`, so a bar grown by a wrapped title or a chip
+//     column shares the line with its un-grown row neighbours. A source
+//     whose caption spills right leaves at the centre of its bottom
+//     progress strip instead, so the leg runs under the caption; milestone
+//     slack lines leave on the same y.
+
+import type { ArrowEnd } from './edge-routing.js';
+import { PROGRESS_STRIP_HEIGHT_PX } from './themes/shared.js';
+import type { PositionedGroup, PositionedItem, PositionedParallel } from './types.js';
+
+/** Y of the bottom progress strip's vertical center. */
+function progressStripMidY(item: PositionedItem): number {
+    return item.box.y + item.box.height - PROGRESS_STRIP_HEIGHT_PX / 2;
+}
+
+/** An item as an arrow end. */
+export function itemArrowEnd(item: PositionedItem, bandwidth: number): ArrowEnd {
+    const { box } = item;
+    return {
+        startX: item.dateSpan.startX,
+        endX: item.dateSpan.endX,
+        paintedX: box.x,
+        paintedWidth: box.width,
+        top: box.y,
+        bottom: box.y + box.height,
+        rowY: box.y + bandwidth / 2,
+        exitY: itemSlackAttachY(item, bandwidth),
+    };
+}
+
+/** A group or parallel as an arrow source: its box spans exactly its dates. */
+export function containerArrowEnd(container: PositionedGroup | PositionedParallel): ArrowEnd {
+    const { box } = container;
+    return {
+        startX: box.x,
+        endX: box.x + box.width,
+        paintedX: box.x,
+        paintedWidth: box.width,
+        top: box.y,
+        bottom: box.y + box.height,
+    };
+}
+
+/**
+ * Y where a milestone slack line leaves `item`: the row's nominal midline,
+ * or the progress strip's center when the caption spilled (so the line
+ * runs under the spilled title / meta text). Its x is the item's end date.
+ */
+export function itemSlackAttachY(item: PositionedItem, bandwidth: number): number {
+    return item.textSpills ? progressStripMidY(item) : item.box.y + bandwidth / 2;
+}