@nowline/layout 0.2.0

package/src/item-bar-geometry.ts

@@ -0,0 +1,222 @@
+// Item-bar internal geometry — the "rails" inside an item rectangle:
+// caption text (title + meta), label chips along the bottom, status
+// dot at the upper-right, footnote indicators just left of the dot,
+// and the link icon tile at the bottom-right.
+//
+// These metrics are shared between layout (label-chip placement,
+// future content-aware width estimation) and renderer (text baselines
+// + glyph positions). Keeping them in one module means a single edit
+// re-skins every item bar consistently — the alternative is hunting
+// matching `+ 12`s across two packages.
+//
+// Coordinate convention: every offset is **relative to the item's
+// `box`** (`box.x` for X, `box.y` for Y), with `box.height` /
+// `box.width` used as the "right edge" / "bottom edge" anchor where
+// noted.
+
+// ---- Caption (title + meta text) ---------------------------------
+
+/** Horizontal inset (px) for the caption's left edge inside the bar. */
+export const ITEM_CAPTION_INSET_X_PX = 12;
+
+/**
+ * When the bar's title would overflow to the right, layout sets
+ * `textSpills` and the caption renders to the RIGHT of the bar; this
+ * is the gap (px) between the bar's right edge and the spilled
+ * caption.
+ */
+export const ITEM_CAPTION_SPILL_GAP_PX = 6;
+
+/** Baseline Y of the title text relative to the bar's top. */
+export const ITEM_CAPTION_TITLE_BASELINE_OFFSET_PX = 20;
+
+/** Baseline Y of the meta text (second line) relative to the bar's top. */
+export const ITEM_CAPTION_META_BASELINE_OFFSET_PX = 38;
+
+/** Font size (px) of the title text. */
+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;
+
+// ---- Status dot (upper-right glyph) ------------------------------
+
+/** Distance (px) from the bar's right edge to the dot's center. */
+export const ITEM_STATUS_DOT_INSET_RIGHT_PX = 12;
+
+/** Distance (px) from the bar's top edge to the dot's center. */
+export const ITEM_STATUS_DOT_INSET_TOP_PX = 12;
+
+/** Radius (px) of the status dot. */
+export const ITEM_STATUS_DOT_RADIUS_PX = 5;
+
+// ---- Footnote indicators (numbers next to status dot) ------------
+
+/**
+ * X offset (px from bar's right edge) where the rightmost footnote
+ * digit's anchor sits. Tuned to leave room for the status dot.
+ */
+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;
+
+/**
+ * Horizontal step (px) between consecutive footnote indicators when
+ * an item carries more than one footnote — they walk LEFT from the
+ * status dot.
+ */
+export const ITEM_FOOTNOTE_INDICATOR_STEP_PX = 8;
+
+// ---- Link icon tile (bottom-right) -------------------------------
+
+/** Side length (px) of the square link-icon tile. */
+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;
+
+// ---- Narrow-bar decoration spill --------------------------------
+
+/**
+ * Horizontal gap (px) between consecutive decorations (status dot,
+ * link icon, footnote, title) when they spill into the column to
+ * the right of a bar that's too narrow to host them inside.
+ */
+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.
+ */
+export const MIN_BAR_WIDTH_FOR_DOT_PX = ITEM_STATUS_DOT_INSET_RIGHT_PX + ITEM_STATUS_DOT_RADIUS_PX;
+
+/**
+ * Minimum bar width (px) needed to host the link-icon tile AND the
+ * status dot inside the bar with at least
+ * `ITEM_DECORATION_SPILL_GAP_PX` of breathing room between them.
+ * Below this, the link icon would visually collide with (or push
+ * into) the dot's column, so the icon spills out and renders ahead
+ * of the (also-spilled) title.
+ */
+export const MIN_BAR_WIDTH_FOR_LINK_AND_DOT_PX =
+    ITEM_LINK_ICON_INSET_PX +
+    ITEM_LINK_ICON_TILE_SIZE_PX +
+    ITEM_DECORATION_SPILL_GAP_PX +
+    ITEM_STATUS_DOT_INSET_RIGHT_PX +
+    ITEM_STATUS_DOT_RADIUS_PX;
+
+/**
+ * Minimum bar width (px) needed to host the footnote indicator at
+ * its inset-right position without overshooting the bar's left
+ * edge or colliding with a leading link icon. Approximate width
+ * for one digit is 8px (font-size 10, bold).
+ */
+export const MIN_BAR_WIDTH_FOR_FOOTNOTE_PX = ITEM_FOOTNOTE_INDICATOR_INSET_RIGHT_PX + 1;
+
+// ---- Label chips (along the bar's bottom) ------------------------
+
+/** Height (px) of a label chip rectangle. */
+export const LABEL_CHIP_HEIGHT_PX = 13;
+
+/**
+ * Vertical gap (px) between the top of the bottom progress strip and
+ * the BOTTOM of a label chip. Keeps chips from touching the strip and
+ * gives a clear visual rail.
+ */
+export const LABEL_CHIP_GAP_ABOVE_PROGRESS_STRIP_PX = 3;
+
+/** Horizontal gap (px) between consecutive chips in a row. */
+export const LABEL_CHIP_GAP_BETWEEN_PX = 4;
+
+/**
+ * Vertical gap (px) between two stacked chip rows when chips spill
+ * outside the bar and form a multi-row column to the right.
+ */
+export const LABEL_CHIP_ROW_GAP_PX = 4;
+
+/**
+ * Vertical row pitch (px) for a stacked chip column — chip height +
+ * inter-row gap.
+ */
+export const LABEL_CHIP_ROW_STEP_PX = LABEL_CHIP_HEIGHT_PX + LABEL_CHIP_ROW_GAP_PX;
+
+/**
+ * Slack budget (fraction) applied ONCE per item when chips spill
+ * outside the bar. If a chip would overflow its row by less than
+ * `SPILL_ROW_SLACK_FRACTION × chip.width`, the row is allowed to
+ * stretch by the overflow amount and keep the chip on it instead of
+ * wrapping. This rescues "lonely chip" cases where one chip just
+ * barely overshoots; once the slack is consumed, no further row
+ * expansions happen for that item.
+ */
+export const SPILL_ROW_SLACK_FRACTION = 0.25;
+
+export interface ChipRowSample<T> {
+    id: T;
+    width: number;
+}
+
+export interface SpillChipPack<T> {
+    /** Rows ordered top-to-bottom — `rows[0]` sits at the chip
+     *  column's top y, `rows[1]` one `LABEL_CHIP_ROW_STEP_PX` below,
+     *  and so on. */
+    rows: ChipRowSample<T>[][];
+    /** True when the slack rule was used to keep an extra chip on
+     *  row 0 (or whichever row was being filled when the overflow
+     *  happened). At most one expansion per item. */
+    expanded: boolean;
+}
+
+/**
+ * Pack `chips` into rows for the SPILL column to the right of an
+ * item bar. Each row is capped at `barVisualWidth` (with gaps
+ * between chips). When a chip would overflow:
+ *
+ * - If the row is empty, place the chip anyway (a chip wider than
+ *   the cap occupies its own row).
+ * - Else if the slack rule applies (`overflow ≤ 0.25 × chip.width`)
+ *   AND the slack hasn't already been used for this item, expand
+ *   the current row by `overflow` and keep the chip on it.
+ * - Else wrap the chip to a fresh row.
+ */
+export function packSpillChips<T>(
+    chips: ChipRowSample<T>[],
+    barVisualWidth: number,
+): SpillChipPack<T> {
+    if (chips.length === 0) return { rows: [[]], expanded: false };
+    const rows: ChipRowSample<T>[][] = [[]];
+    let used = 0;
+    let rowCap = barVisualWidth;
+    let expanded = false;
+    for (const chip of chips) {
+        const row = rows[rows.length - 1];
+        const needed = (row.length === 0 ? 0 : LABEL_CHIP_GAP_BETWEEN_PX) + chip.width;
+        const wouldBe = used + needed;
+        if (wouldBe <= rowCap) {
+            row.push(chip);
+            used = wouldBe;
+            continue;
+        }
+        if (row.length === 0) {
+            row.push(chip);
+            used = chip.width;
+            continue;
+        }
+        const overflow = wouldBe - rowCap;
+        const slack = chip.width * SPILL_ROW_SLACK_FRACTION;
+        if (!expanded && overflow <= slack) {
+            row.push(chip);
+            used = wouldBe;
+            rowCap = wouldBe;
+            expanded = true;
+            continue;
+        }
+        rows.push([chip]);
+        used = chip.width;
+        rowCap = barVisualWidth;
+    }
+    return { rows, expanded };
+}

package/src/lane-utilization.ts

@@ -0,0 +1,259 @@
+// Lane utilization computation per specs/rendering.md § Lane utilization
+// underline.
+//
+// Walks a positioned lane's children (items, plus the items inside parallel
+// and group blocks), collects each contributor's pixel span and capacity load,
+// then sweeps the timeline to produce a list of half-open segments
+// classified `green | yellow | red` against the lane's resolved capacity and
+// thresholds. Adjacent same-classification segments coalesce so the renderer
+// paints one rectangle per color band rather than per event boundary.
+//
+// Pure data in / pure data out — no AST, no theme, no side effects. Lives
+// next to `capacity.ts` (the other capacity-helper module) and is tested in
+// isolation.
+
+import type { DefaultDeclaration, SwimlaneDeclaration } from '@nowline/core';
+import { propValue } from './dsl-utils.js';
+import type {
+    PositionedItem,
+    PositionedLaneUtilization,
+    PositionedTrackChild,
+    PositionedUtilizationSegment,
+    UtilizationClassification,
+} from './types.js';
+
+/**
+ * Built-in defaults used when neither the lane nor its `default swimlane`
+ * declares a threshold. Mirrors specs/dsl.md rule 17d.
+ */
+export const DEFAULT_UTILIZATION_WARN_FRACTION = 0.8; // 80%
+export const DEFAULT_UTILIZATION_OVER_FRACTION = 1.0; // 100%
+
+/**
+ * One contributor to a lane's load function: a single positioned item with
+ * its visual horizontal span and the load it contributes during that span.
+ * Children inside `parallel` / `group` blocks contribute individually so
+ * concurrent load reads correctly (the parallel block itself spans the union
+ * of its children's bars but does not itself add load — only the items do).
+ */
+interface LoadContributor {
+    startX: number;
+    endX: number;
+    load: number;
+}
+
+/**
+ * Walk the lane's positioned children and return one `LoadContributor` per
+ * item that contributes load. Items inside `parallel` and `group` blocks are
+ * descended into recursively; the block envelopes themselves contribute
+ * nothing (they are pure containers).
+ *
+ * `inferItemLoad` mirrors the spec's "Default capacity" table:
+ *   - Explicit `capacity:N` → that value.
+ *   - Sized item without explicit `capacity:` → 1 (the default for sized
+ *     items, matching the duration-derivation default).
+ *   - Duration-literal item without `capacity:` → 0 (the bar paints normally
+ *     but does not contribute load — this is the legacy "uncounted" item
+ *     family from before the size system existed).
+ */
+export function collectLoadContributors(children: PositionedTrackChild[]): LoadContributor[] {
+    const out: LoadContributor[] = [];
+    walk(children, out);
+    return out;
+}
+
+function walk(children: PositionedTrackChild[], out: LoadContributor[]): void {
+    for (const child of children) {
+        if (child.kind === 'item') {
+            const load = inferItemLoad(child);
+            if (load > 0 && child.box.width > 0) {
+                out.push({
+                    startX: child.box.x,
+                    endX: child.box.x + child.box.width,
+                    load,
+                });
+            }
+        } else if (child.kind === 'parallel' || child.kind === 'group') {
+            walk(child.children, out);
+        }
+    }
+}
+
+function inferItemLoad(item: PositionedItem): number {
+    if (item.capacity) return item.capacity.value;
+    if (item.size) return 1;
+    return 0;
+}
+
+/**
+ * Compute a lane's utilization model. Returns `null` when there is no
+ * meaningful underline to paint:
+ *   - Lane has no `capacity:` (no denominator → undefined utilization).
+ *   - Lane has no items contributing load (collectLoadContributors returns
+ *     an empty list).
+ *   - Both thresholds resolve to `none` (caller has opted out of every
+ *     color band; nothing to paint).
+ *
+ * The returned `PositionedLaneUtilization` carries the resolved thresholds
+ * (in fraction form, or `null` for opt-out) alongside the segments so the
+ * renderer can render legends / tooltips without re-resolving anything.
+ */
+export function computeLaneUtilization(opts: {
+    children: PositionedTrackChild[];
+    capacityValue: number;
+    warnFraction: number | null;
+    overFraction: number | null;
+}): PositionedLaneUtilization | null {
+    if (opts.capacityValue <= 0) return null;
+    if (opts.warnFraction === null && opts.overFraction === null) return null;
+
+    const contributors = collectLoadContributors(opts.children);
+    if (contributors.length === 0) return null;
+
+    // Build sorted unique x coordinates from every event boundary.
+    const xSet = new Set<number>();
+    for (const c of contributors) {
+        xSet.add(c.startX);
+        xSet.add(c.endX);
+    }
+    const xs = Array.from(xSet).sort((a, b) => a - b);
+    if (xs.length < 2) return null;
+
+    // Per half-open interval [xs[j], xs[j+1]) compute the active load by
+    // summing every contributor whose span covers the interval midpoint.
+    // O(n²) but n is small (typically <20 items per lane); avoids the
+    // bookkeeping of an event-stream sweep without a measurable cost.
+    const raw: PositionedUtilizationSegment[] = [];
+    for (let j = 0; j < xs.length - 1; j++) {
+        const a = xs[j];
+        const b = xs[j + 1];
+        const mid = (a + b) / 2;
+        let load = 0;
+        for (const c of contributors) {
+            if (c.startX <= mid && mid < c.endX) load += c.load;
+        }
+        raw.push({
+            startX: a,
+            endX: b,
+            load,
+            classification: classifyLoad(
+                load,
+                opts.capacityValue,
+                opts.warnFraction,
+                opts.overFraction,
+            ),
+        });
+    }
+
+    // Coalesce adjacent same-classification segments so the renderer paints
+    // one rectangle per visible color band rather than per event boundary.
+    const segments: PositionedUtilizationSegment[] = [];
+    for (const s of raw) {
+        const last = segments[segments.length - 1];
+        if (last && last.classification === s.classification && last.endX === s.startX) {
+            last.endX = s.endX;
+            // Keep the first interval's `load` as a representative; the
+            // coalesced span may have varying load within a single color
+            // band but renderers paint by class, not by exact load.
+        } else {
+            segments.push({ ...s });
+        }
+    }
+
+    return {
+        segments,
+        capacityValue: opts.capacityValue,
+        warnFraction: opts.warnFraction,
+        overFraction: opts.overFraction,
+    };
+}
+
+/**
+ * Classify a single load value against the lane's resolved capacity and
+ * thresholds. Spec § "Load function and segmentation":
+ *   - `u < warn-at` → green (healthy; includes `u = 0` so the underline
+ *     stays continuous).
+ *   - `warn-at ≤ u < over-at` → yellow.
+ *   - `u ≥ over-at` → red.
+ *
+ * `null` thresholds disable that color band: a `null` warnFraction collapses
+ * to a binary green / red indicator; a `null` overFraction collapses to
+ * green / yellow; both `null` is unreachable here (caller short-circuits
+ * upstream).
+ */
+export function classifyLoad(
+    load: number,
+    capacity: number,
+    warnFraction: number | null,
+    overFraction: number | null,
+): UtilizationClassification {
+    const u = load / capacity;
+    if (overFraction !== null && u >= overFraction) return 'red';
+    if (warnFraction !== null && u >= warnFraction) return 'yellow';
+    return 'green';
+}
+
+/**
+ * Resolve the lane's effective utilization thresholds, applying the spec's
+ * resolution order:
+ *
+ *   1. Lane's own `utilization-warn-at:` / `utilization-over-at:` properties.
+ *   2. The applicable `default swimlane` declaration's properties.
+ *   3. Built-in defaults (`warn-at:80%`, `over-at:100%`).
+ *
+ * Each side resolves independently — a lane can pin only one threshold and
+ * inherit the other from defaults / built-ins. The returned `null` means
+ * "opted out via `none`" and disables that color band downstream.
+ *
+ * Malformed values (already reported by the validator) are treated as
+ * "unset" — the resolver falls through to the next layer rather than
+ * double-reporting.
+ */
+export function resolveLaneUtilizationThresholds(
+    lane: SwimlaneDeclaration,
+    defaults: Map<string, DefaultDeclaration>,
+): { warn: number | null; over: number | null } {
+    const dflt = defaults.get('swimlane');
+    const warn = resolveThreshold(
+        propValue(lane.properties, 'utilization-warn-at'),
+        dflt ? propValue(dflt.properties, 'utilization-warn-at') : undefined,
+        DEFAULT_UTILIZATION_WARN_FRACTION,
+    );
+    const over = resolveThreshold(
+        propValue(lane.properties, 'utilization-over-at'),
+        dflt ? propValue(dflt.properties, 'utilization-over-at') : undefined,
+        DEFAULT_UTILIZATION_OVER_FRACTION,
+    );
+    return { warn, over };
+}
+
+function resolveThreshold(
+    laneVal: string | undefined,
+    defaultVal: string | undefined,
+    builtinFraction: number,
+): number | null {
+    const raw = laneVal ?? defaultVal;
+    const parsed = parseThresholdRaw(raw);
+    if (parsed.kind === 'unset') return builtinFraction;
+    if (parsed.kind === 'none') return null;
+    return parsed.value;
+}
+
+type ParsedThreshold = { kind: 'unset' } | { kind: 'none' } | { kind: 'number'; value: number };
+
+const PERCENT_RE = /^\d+(?:\.\d+)?%$/;
+const DECIMAL_FRACTION_RE = /^\d+\.\d+$/;
+
+function parseThresholdRaw(val: string | undefined): ParsedThreshold {
+    if (val === undefined) return { kind: 'unset' };
+    if (val === 'none') return { kind: 'none' };
+    if (PERCENT_RE.test(val)) {
+        const n = parseFloat(val) / 100;
+        return Number.isFinite(n) && n > 0 ? { kind: 'number', value: n } : { kind: 'unset' };
+    }
+    if (DECIMAL_FRACTION_RE.test(val)) {
+        const n = parseFloat(val);
+        return Number.isFinite(n) && n > 0 ? { kind: 'number', value: n } : { kind: 'unset' };
+    }
+    return { kind: 'unset' };
+}

package/src/layout-context.ts

@@ -0,0 +1,182 @@
+// Layout context — shared internal types used by `layout.ts` and the
+// node files under `nodes/`. Extracted so per-entity nodes (e.g.
+// `swimlane-node.ts`) can type their inputs without forcing a circular
+// import on the production composition root in `layout.ts`.
+
+import type {
+    EntityProperty,
+    GroupBlock,
+    ItemDeclaration,
+    LabelDeclaration,
+    ParallelBlock,
+    SymbolDeclaration,
+} from '@nowline/core';
+import type { BandScale } from './band-scale.js';
+import type { resolveCalendar } from './calendar.js';
+import type { StyleContext } from './style-resolution.js';
+import type { TimeScale } from './time-scale.js';
+import type {
+    MarkerRowPlacement,
+    Point,
+    PositionedItem,
+    PositionedTimelineScale,
+    PositionedTrackChild,
+    ResolvedSize,
+    SlackCorridor,
+} from './types.js';
+import type { WorkingCalendar } from './working-calendar.js';
+
+/** Slim accumulator used while sequencing items into a track. */
+export interface TrackCursor {
+    /** Left edge where the next item begins. */
+    x: number;
+    /** Top edge of the current row. */
+    y: number;
+    /** Accumulated height of the track. */
+    height: number;
+    /** Rightmost edge reached. */
+    maxX: number;
+}
+
+export function newCursor(x: number, y: number): TrackCursor {
+    return { x, y, height: 0, maxX: x };
+}
+
+/**
+ * Shared layout state passed through the per-entity sequencers and
+ * Renderable nodes. Owns the resolved calendar/timeline/style scope plus
+ * the running entity-edge maps that `after:` / `before:` references read.
+ */
+export interface LayoutContext {
+    cal: ReturnType<typeof resolveCalendar>;
+    styleCtx: StyleContext;
+    sizes: Map<string, ResolvedSize>;
+    labels: Map<string, LabelDeclaration>;
+    teams: Map<string, import('@nowline/core').TeamDeclaration>;
+    persons: Map<string, import('@nowline/core').PersonDeclaration>;
+    /**
+     * Custom `symbol` declarations from `ResolvedConfig.symbols`. Used by
+     * `resolveCapacityIcon` (in `capacity.ts`) to dereference custom symbol
+     * ids like `capacity-icon:budget` to the symbol's `unicode:` payload.
+     * Empty when the file declares no symbols.
+     */
+    symbols: Map<string, SymbolDeclaration>;
+    footnoteIndex: Map<string, number>;
+    /** For each footnote id, the list of `on:` host ids it references. */
+    footnoteHosts: Map<string, string[]>;
+    timeline: PositionedTimelineScale;
+    scale: TimeScale;
+    calendar: WorkingCalendar;
+    bandScale: BandScale;
+    entityLeftEdges: Map<string, number>;
+    entityRightEdges: Map<string, number>;
+    entityMidpoints: Map<string, Point>;
+    /**
+     * Visual edges for items (entries with a painted bar). Differs
+     * from `entityLeftEdges`/`entityRightEdges` (logical column
+     * boundaries) by `ITEM_INSET_PX` on each side so dependency
+     * arrows attach to the painted bar edge instead of landing in
+     * the inter-column gutter. Anchors and milestones are absent —
+     * their attach geometry uses `(center.x, target.row.midY)` on
+     * the cut line, computed inline by `buildDependencies`.
+     */
+    entityVisualLeftX: Map<string, number>;
+    entityVisualRightX: Map<string, number>;
+    /**
+     * Per-item exit point for `after:` dependency arrows leaving
+     * this entity. Default = `(visualRight, midY)`. When the
+     * caption spills past the bar's right edge (`textSpills`), the
+     * exit drops to `(box.x + box.width / 2, box.y + box.height)`
+     * — the bottom-middle of the progress strip — so the arrow
+     * doesn't visually pierce the spilled title/meta text to the
+     * right of the bar.
+     */
+    itemArrowSource: Map<string, Point>;
+    /**
+     * Flow key for each item, used to dedupe milestone slack arrows.
+     * A "flow" is the deepest enclosing single-track container —
+     * swimlane root, sequential group, or one parallel sub-track.
+     * Two items share a flowKey iff they share that container path
+     * (file order already encodes their ordering, so only the
+     * latest predecessor in each flow contributes a slack arrow).
+     */
+    itemFlowKey: Map<string, string>;
+    /**
+     * The flow key currently being built by the swimlane walk.
+     * Container nodes (`SwimlaneNode`, `GroupNode`, `ParallelNode`)
+     * push their own segment onto this string before recursing into
+     * children and restore it afterward. `sequenceItem` reads this
+     * value to populate `itemFlowKey`.
+     */
+    currentFlowKey: string;
+    /**
+     * Y coordinate where milestone slack arrows attach for each item id.
+     * Defaults to the item's row midpoint; when an item's caption spills
+     * past the bar's right edge, drops to the progress-strip's vertical
+     * center (`box.y + box.height - PROGRESS_STRIP_HEIGHT_PX / 2`) so the
+     * arrow stays clear of the spilled title/meta line and visually
+     * aligns with the bottom-edge progress bar instead.
+     */
+    itemSlackAttachY: Map<string, number>;
+    /**
+     * Horizontal arrow corridors that the swimlane row-packer must avoid.
+     * Empty during the first layout pass; populated from the first
+     * pass's milestones and consulted on the second pass so the binding
+     * predecessor (and any unrelated overlapping item) drops to a row
+     * whose Y does not match the corridor.
+     */
+    slackCorridors: SlackCorridor[];
+    /**
+     * Pre-computed marker-row placement (row index + label box + side)
+     * for every anchor and date-pinned milestone. After-only milestones
+     * pack against this map at build time; date-pinned entries are
+     * snapshot upstream so their (Y, label) survives swimlane reflows.
+     */
+    markerRowPlacements: Map<string, MarkerRowPlacement>;
+    chartTopY: number;
+    chartBottomY: number;
+    /**
+     * Y coordinate at the bottom of the last swimlane / include region.
+     * Distinct from `chartBottomY`, which extends through any mirrored
+     * bottom timeline tick panel. Marker cut-lines (anchors, milestones)
+     * stop here so they never invade the bottom date strip; the now-line
+     * uses the wider `chartBottomY` (or the bottom panel's bottom edge)
+     * to thread the entire timeline strip.
+     */
+    swimlaneBottomY: number;
+    chartRightX: number;
+}
+
+/**
+ * Bundle of layout-internal helper callbacks injected from `layout.ts`
+ * into the per-entity Renderable nodes. Keeping the helpers in
+ * `layout.ts` (rather than splitting them across many tiny files) means
+ * the nodes stay small and importable without a runtime cycle: they
+ * receive the helpers at construction time via this struct.
+ */
+export interface LayoutHelpers {
+    sequenceItem: (
+        child: ItemDeclaration,
+        cursor: TrackCursor,
+        ctx: LayoutContext,
+        ownerOverride?: string,
+    ) => PositionedItem;
+    sequenceOne: (
+        child: ItemDeclaration | GroupBlock | ParallelBlock,
+        cursor: TrackCursor,
+        ctx: LayoutContext,
+    ) => PositionedTrackChild;
+    resolveChildStart: (
+        props: EntityProperty[],
+        seqDefault: number,
+        laneLeftX: number,
+        ctx: LayoutContext,
+    ) => number;
+    newCursor: (x: number, y: number) => TrackCursor;
+    estimateTextWidth: (text: string, fontSize: number) => number;
+    /** Predict the extra height an item's wrapped label-chip rows will
+     *  add, so callers can size the row pitch BEFORE handing off to
+     *  `sequenceItem`. Returns 0 when the item's labels all fit on a
+     *  single chip row. */
+    predictItemChipExtraHeight: (item: ItemDeclaration, ctx: LayoutContext) => number;
+}