@nowline/layout 0.8.5 → 0.9.0

package/src/types.ts

@@ -3,6 +3,9 @@
 // top-left. All colors in `ResolvedStyle` are concrete hex strings baked
 // in by style-resolution; the renderer is palette-dumb.
 
+import type { FrameTabGeometry } from './frame-tab-geometry.js';
+import type { NonWorkingDisplay } from './non-working-display.js';
+
 export type SizeBucket = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
 export type ShadowKind = 'none' | 'subtle' | 'soft' | 'hard';
 export type BorderKind = 'solid' | 'dashed' | 'dotted';
@@ -17,9 +20,16 @@ export type HeaderPosition = 'beside' | 'above';
 //     either edge of the viewport
 export type TimelinePosition = 'top' | 'bottom' | 'both';
 export type StatusKind = 'planned' | 'in-progress' | 'done' | 'at-risk' | 'blocked' | 'neutral';
+/**
+ * Which hatch stroke marks background work on a fill (specs/waves.md §9.3):
+ * `dark` (`wave.hatch`) on a light fill, `light` (`wave.hatchOnDark`) on a
+ * dark one.
+ */
+export type WaveHatchKind = 'dark' | 'light';
 
-// The 17 style properties from specs/dsl.md § Style Properties plus header-position
-// and the two roadmap-only readability knobs (`timeline-position`, `minor-grid`).
+// The style properties from specs/dsl.md § Style Properties, including the
+// roadmap-only knobs (`header-height`, `header-position`, `timeline-position`,
+// `minor-grid`, `non-working`).
 // Every one has a concrete value after resolution (theme + defaults fill gaps).
 export interface ResolvedStyle {
     bg: string; // hex or 'none'
@@ -50,6 +60,12 @@ export interface ResolvedStyle {
     capacityIcon: string;
     timelinePosition: TimelinePosition;
     minorGrid: boolean;
+    /**
+     * How a calendar's non-working days are drawn (roadmap-only, from
+     * `default roadmap non-working:`). Default `'hide'`; a surface option
+     * overrides it (`LayoutOptions.nonWorking`).
+     */
+    nonWorking: NonWorkingDisplay;
 }
 
 export interface BoundingBox {
@@ -90,8 +106,13 @@ export interface Point {
 
 // Header + attribution mark + optional logo.
 export interface PositionedLogo {
+    // Drawn box in canvas coordinates. Its aspect ratio matches the asset's,
+    // so the logo fills it exactly.
     box: BoundingBox;
     assetRef?: string; // path as declared in DSL; renderer resolves via AssetResolver
+    // The asset's own size (SVG width/height or viewBox, raster pixels),
+    // which the renderer scales from.
+    intrinsic?: { width: number; height: number };
 }
 
 export interface PositionedHeader {
@@ -110,6 +131,10 @@ export interface PositionedHeader {
     // height grows for wrapped lines).
     cardBox: BoundingBox;
     logo?: PositionedLogo;
+    // Offset applied to every title and author line, set only when a logo
+    // shares the card: `x` clears the logo, `y` centers the text block
+    // when the logo made the card taller than the text needs.
+    textInset?: Point;
     style: ResolvedStyle;
     // Attribution mark (Nowline wordmark + link) lives in the top-right.
     attributionBox: BoundingBox;
@@ -166,11 +191,107 @@ export interface PositionedTimelineScale {
     // is purely a date reference for tall canvases.
     bottomTickPanelY?: number;
     bottomTickPanelHeight?: number;
+    /**
+     * The wave strip row (specs/waves.md §8.8): `WAVE_STRIP_HEIGHT_PX`
+     * high, directly under the top tick panel (under the now-pill row
+     * with `timeline-position:bottom`) and above the marker rows, which
+     * move down by its height. Present only when some declared wave has
+     * items (specs/waves.md §9.1); the mirrored bottom panel never has one.
+     */
+    waveStrip?: {
+        y: number;
+        height: number;
+    };
     // When `true`, the renderer draws a faint dotted line at every tick
     // boundary (not just major ticks) using `theme.timeline.minorGridLine`.
     // Mirrors the roadmap's resolved `minor-grid` style property. Default
     // `false` preserves byte-stable output for existing roadmaps.
     minorGrid: boolean;
+    /**
+     * How the axis shows non-working days (specs/working-calendar.md §7):
+     * `hide` collapses them to zero width, `show` draws them at full width.
+     * Present, with `nonWorking`, only when the window holds a non-working
+     * day.
+     */
+    nonWorkingDisplay?: NonWorkingDisplay;
+    /** The window's non-working runs, left to right; see `PositionedNonWorkingRun`. */
+    nonWorking?: PositionedNonWorkingRun[];
+    /**
+     * The window's labelled working exceptions, left to right; see
+     * `PositionedWorkingException`. Omitted when there are none.
+     */
+    workingExceptions?: PositionedWorkingException[];
+}
+
+/**
+ * One run of days that titled dated `working` rules turn from non-working
+ * to working (specs/working-calendar.md §7.4, §7.5). It is labelled in the
+ * marker row like a titled non-working run, but never drawn as a cut line
+ * or a band: a working day removes no time.
+ */
+export interface PositionedWorkingException {
+    /** The run's first day: its column start under `hide`, its day start under `show` (clamped to the window). */
+    x: number;
+    /** First day the rules turn (UTC midnight). */
+    from: Date;
+    /** Last day the rules turn, inclusive (UTC midnight). */
+    through: Date;
+    /** Titles of the titled dated working rules that turn a day of the run. */
+    titles: string[];
+    /** The titles joined with `, `, then ` · +Nd` for the N days turned. */
+    label: string;
+    /** Resolved placement of `label` in the marker row, like `PositionedNonWorkingRun.labelBox`. */
+    labelBox?: BoundingBox;
+    labelSide?: 'left' | 'right';
+}
+
+/**
+ * One maximal run of non-working days in (or straddling) the window
+ * (specs/working-calendar.md §7.5). Under `hide` its `width` is 0 and `x`
+ * is the start of the next working day. Under `show` it spans its days,
+ * with `x` and the right edge clamped to the window; `from` / `through`
+ * keep the run's real dates.
+ */
+export interface PositionedNonWorkingRun {
+    x: number;
+    width: number;
+    /** First non-working date of the run (UTC midnight). */
+    from: Date;
+    /** Last non-working date of the run, inclusive. */
+    through: Date;
+    /** Titles of the dated rules inside it; omitted for a plain weekend. */
+    titles?: string[];
+    /**
+     * The marker-row label of a titled run: its titles joined with `, `,
+     * then ` · Nd` for the N working days of the open-ended week the run
+     * closes (dropped when N is 0). Omitted on a run without titles.
+     */
+    label?: string;
+    /**
+     * Resolved placement of `label` in the marker row, exactly like
+     * `PositionedMilestone.labelBox` / `labelSide`. Omitted on a run
+     * without titles.
+     */
+    labelBox?: BoundingBox;
+    labelSide?: 'left' | 'right';
+    /**
+     * Set under `hide` on a titled run, at every scale: the renderer draws
+     * the named cut line at `x` from the label row down through the chart
+     * (spec §7.2, "a named seam always draws"). Independent of `seam`.
+     */
+    cut?: true;
+    /**
+     * Set at the days scale when the run lies strictly inside the chart and
+     * no grid line is drawn at its x; the renderer draws a seam there.
+     * Never set under `show`.
+     */
+    seam?: true;
+    /**
+     * Set under `show` at the days and weeks scales, or when the run has
+     * titles: the renderer paints the run as a shaded band. Coarser scales
+     * leave a plain weekend unpainted.
+     */
+    band?: true;
 }
 
 /**
@@ -250,9 +371,56 @@ export interface InlineDatePin {
 export interface PositionedItem {
     kind: 'item';
     id?: string;
+    /**
+     * The full, unwrapped title exactly as authored, explicit line breaks
+     * included (`"Technology\nSelection"` keeps its newline here). Always
+     * present, wrapped or not.
+     */
     title: string;
+    /**
+     * The title split into the lines the renderer paints, one `<text>` per
+     * line. Present when the painted lines differ from `[title]`:
+     *
+     *   - the title word-wrapped INSIDE the bar (`length === 2`, at most
+     *     `ITEM_CAPTION_TITLE_MAX_LINES`), or
+     *   - the title carries explicit `\n` breaks (any `length >= 2`, in-bar
+     *     or spilled to the right of the bar). Lines are trimmed, leading
+     *     and trailing empty lines are dropped, interior empty lines stay as
+     *     blank entries. An explicit title never auto-wraps.
+     *
+     * Omitted for a one-line title, and for a break-free title that spilled
+     * to the right (always one line), unless the caption cap at the chart's
+     * end truncated it (`titleTruncated`). Line `n` (0-based) sits at baseline
+     * `ITEM_CAPTION_TITLE_BASELINE_OFFSET_PX + n * ITEM_CAPTION_TITLE_LINE_HEIGHT_PX`
+     * from the bar's top, and the meta line follows at
+     * `itemCaptionMetaBaselineOffset(titleLines.length)`. A multi-line
+     * caption with a meta line grows the bar (`box.height`) by 16px per
+     * extra line.
+     */
+    titleLines?: string[];
+    /**
+     * True when a spilled caption that would run past the axis end was
+     * capped at the overhang budget past it: `titleLines` carries the lines truncated
+     * with `…`, and the renderer gives the bar the full `title` as its
+     * `<title>` tooltip (specs/rendering.md § "Caption cap at the chart's
+     * end"). Omitted otherwise.
+     */
+    titleTruncated?: true;
     box: BoundingBox;
+    /**
+     * The item's dates in x: its scheduled start and end through the time
+     * scale. The bar (`box`) is drawn inside them, a seam in from each
+     * (specs/true-width-layout.md §3.1); dependency arrows and milestone
+     * slack lines read them (§3.4, §3.5).
+     */
+    dateSpan: { startX: number; endX: number };
     status: StatusKind;
+    /**
+     * The status dot's resolved colour: the theme's `statusDot.onLight` or
+     * `onDark` entry for `status`, picked by the luminance of `style.bg`
+     * (`statusDotColor` in `status-dot.ts`).
+     */
+    statusDotColor: string;
     progressFraction: number; // 0..1; 1 == fully filled
     footnoteIndicators: number[]; // 1-based superscript numbers, empty when no footnotes
     labelChips: PositionedLabelChip[];
@@ -286,12 +454,14 @@ export interface PositionedItem {
     // renderer stays palette-and-string-dumb.
     metaText?: string;
     // True when the title OR the meta line is wider than the bar's inner
-    // padded width. We treat title + meta as an atomic block: if either
+    // padded width AND a word-wrap of the title can't make it fit (see
+    // `titleLines`). We treat title + meta as an atomic block: if either
     // one wouldn't fit inside the bar, BOTH get drawn beside the bar
     // (stacked, just past its right edge) so they read as one caption
     // rather than splitting across the bar boundary. The layout also
     // bumps the next item to a fresh row so the spilled caption has
-    // empty space to occupy.
+    // empty space to occupy. A title that wrapped inside the bar has
+    // `textSpills === false` and reserves no spill extent.
     textSpills: boolean;
     /** True when the bar is too narrow to host the status dot inside
      *  with its full inset (`MIN_BAR_WIDTH_FOR_DOT_PX`). The dot
@@ -342,6 +512,32 @@ export interface PositionedItem {
      */
     size: ResolvedSize | null;
     style: ResolvedStyle;
+    /**
+     * Wave membership (specs/waves.md §8.7): `member` for an item with an
+     * effective wave, `background` for one without. Set on every item, in
+     * the main lanes and in isolated regions, when the roadmap declares
+     * waves; omitted otherwise.
+     */
+    waveRole?: 'member' | 'background';
+    /**
+     * The hatch kind for the bar's fill (`waveHatchKind` in
+     * `wave-hatch.ts`). Set exactly on background items; omitted otherwise.
+     */
+    waveHatch?: WaveHatchKind;
+    /**
+     * The hover tooltip line wave membership adds to the bar, localized
+     * (`Background (no wave)`; specs/waves.md §9.3). Set only on
+     * background items; omitted otherwise.
+     */
+    waveTooltip?: string;
+    /**
+     * Present when the item's `after:DATE` pin falls on a non-working day
+     * and that pin set the start (NL.I1008, specs/working-calendar.md §6):
+     * `key` / `pin` are the pin as written, `start` the working day the
+     * item starts on (YYYY-MM-DD). Omitted when a later `after:` ref, the
+     * lane cursor or a wave floor set the start.
+     */
+    nonWorkingPin?: { key: 'after'; pin: string; start: string };
 }
 
 /**
@@ -359,6 +555,15 @@ export interface PositionedCapacity {
     text: string;
     /** Resolved glyph instruction, or `null` when the icon is `'none'`. */
     icon: ResolvedCapacityIconRef | null;
+    /**
+     * For a built-in SVG icon (person, people, points, time): the px terms
+     * that, added in order to the start x of the text run the suffix is
+     * painted in (the item caption x, or the lane badge x), give the icon's
+     * x, from `capacityIconDxTerms`. Kept apart so the sum rounds the same
+     * as adding each width to x in turn. Omitted for every other glyph,
+     * which paints inside the `<text>`.
+     */
+    iconDxTerms?: readonly number[];
 }
 
 /**
@@ -384,20 +589,36 @@ export interface PositionedGroup {
     kind: 'group';
     id?: string;
     title?: string;
+    /** The whole container: `box.y` is the header's top, `box.x` and
+     *  `box.width` span exactly its children's dates
+     *  (specs/true-width-layout.md §3.3). */
     box: BoundingBox;
-    // Bracket is drawn on the left edge when style.bracket != 'none'.
+    /** Header band height above the body (title, glyphs, bracket); 0 when
+     *  there is no header. The body runs from `box.y + headerHeight` to the
+     *  box's bottom. */
+    headerHeight: number;
     children: PositionedTrackChild[];
     /** Inline-date pins attached to this group (`after:DATE` / `before:DATE`).
      *  See `InlineDatePin` and specs/rendering.md "Inline-date glyph". */
     inlineDatePins?: InlineDatePin[];
     style: ResolvedStyle;
+    /**
+     * True for an untitled group with no `style:` and no `labels:` that
+     * carries `wave:`, in a roadmap with waves: it only assigns wave
+     * membership, so the renderer draws nothing for it (specs/waves.md §9.7).
+     * Omitted otherwise.
+     */
+    waveOnly?: true;
 }
 
 export interface PositionedParallel {
     kind: 'parallel';
     id?: string;
     title?: string;
+    /** The whole container, as `PositionedGroup.box`. */
     box: BoundingBox;
+    /** Header band height above the body, as `PositionedGroup.headerHeight`. */
+    headerHeight: number;
     children: PositionedTrackChild[]; // sub-tracks stacked vertically
     /** Inline-date pins attached to this parallel (`after:DATE` / `before:DATE`).
      *  See `InlineDatePin` and specs/rendering.md "Inline-date glyph". */
@@ -416,8 +637,15 @@ export interface PositionedSwimlane {
     nested: PositionedSwimlane[]; // recursive sub-swimlanes
     style: ResolvedStyle;
     // Owner display string ("Platform Team", "Sam Chen") rendered inside
-    // the frame tab. Resolved from team/person id → title.
+    // the frame tab. Resolved from team/person id → title (nested teams
+    // included); the bare id when it names neither.
     owner?: string;
+    /**
+     * What `owner` names, for the glyph that leads it in the frame tab:
+     * `person` for a declared person, `team` otherwise (a team, or an id
+     * that names neither). Set exactly when `owner` is.
+     */
+    ownerKind?: 'person' | 'team';
     // Footnote indicator numbers attached to this swimlane (via `on:` in the
     // footnote declaration). Rendered in the upper-right of the frame tab.
     footnoteIndicators: number[];
@@ -434,6 +662,13 @@ export interface PositionedSwimlane {
      * want the badge fully hidden simply omit `capacity:`.
      */
     capacity: PositionedCapacity | null;
+    /**
+     * The frame tab's geometry, from `frameTabGeometry` with the lane's
+     * box x, its title, the owner display title and the capacity badge and
+     * footnote-indicator widths. Layout sizes the tab's collision box from
+     * it and the renderer draws it as is. Null when the lane has no title.
+     */
+    tab: FrameTabGeometry | null;
     /**
      * Tri-state utilization underline data when the lane declares
      * `capacity:` AND has at least one item contributing load AND has not
@@ -512,6 +747,12 @@ export interface PositionedAnchor {
     // (start-anchored text) — no further geometry decisions.
     labelBox: BoundingBox;
     labelSide: 'left' | 'right';
+    /**
+     * The anchor's `date:` (YYYY-MM-DD) when it falls on a non-working day
+     * the axis hides; the renderer surfaces it as a `<title>`. Omitted on a
+     * working day and under a calendar with no non-working days.
+     */
+    hiddenDate?: string;
 }
 
 export interface PositionedMilestone {
@@ -526,6 +767,16 @@ export interface PositionedMilestone {
     // milestone has zero or one predecessor.
     slackArrows?: Array<{ x: number; y: number }>;
     isOverrun: boolean; // true when the aggregated predecessor end exceeds `date:`
+    /**
+     * Where an overrun dated milestone actually lands: the end of its
+     * latest predecessor or overrunning wave. `center` stays on the
+     * planned date; the renderer draws that diamond in the overrun colour,
+     * a dotted span on the same row to a second diamond at `slip.x`, and
+     * puts the label and the cut line there (specs/rendering.md,
+     * Milestones). Omitted when the milestone does not overrun, or when
+     * the two diamonds would meet.
+     */
+    slip?: { x: number };
     style: ResolvedStyle;
     // Vertical span of the milestone's cut line through the swimlane area.
     cutTopY: number;
@@ -533,6 +784,31 @@ export interface PositionedMilestone {
     // See PositionedAnchor.labelBox — same packing logic applies.
     labelBox: BoundingBox;
     labelSide: 'left' | 'right';
+    /**
+     * True when the diamond sits on a wave boundary (within 0.5 px of any
+     * `S_k` or `E_k` other than the origin; specs/waves.md §9.2). The
+     * boundary line carries the vertical, so the cut line is not drawn.
+     * Omitted when false and when the roadmap has no waves.
+     */
+    onWaveBoundary?: boolean;
+    /**
+     * The wave that runs past this dated milestone: its `after:` lists the
+     * wave and the wave's end `E_k` lies past `date:` (NL.I1007). The
+     * latest-ending such wave; omitted when none.
+     */
+    overrunByWave?: string;
+    /**
+     * The milestone's own `date:` (YYYY-MM-DD), set together with
+     * `overrunByWave`, so NL.I1007 never reads the date back off x.
+     */
+    overrunDate?: string;
+    /**
+     * The milestone's `date:` (YYYY-MM-DD) when it falls on a non-working
+     * day the axis hides; the renderer surfaces it as a `<title>`. Omitted
+     * on a working day, for after-only milestones, and under a calendar
+     * with no non-working days.
+     */
+    hiddenDate?: string;
 }
 
 /**
@@ -559,7 +835,7 @@ export interface MarkerRowPlacement {
 export interface SlackCorridor {
     xStart: number; // slack pred's right edge (logical chart x)
     xEnd: number; // binding pred's right edge / milestone center.x
-    y: number; // slack pred's row midpoint
+    y: number; // slack pred's slack-arrow attach y, in the chart's local frame
     slackPredId: string; // exempt from bumping (owns the arrow's origin)
     milestoneId: string;
 }
@@ -567,19 +843,23 @@ export interface SlackCorridor {
 export interface PositionedDependencyEdge {
     fromId: string;
     toId: string;
-    waypoints: Point[]; // first = source port; last = target port
-    /**
-     * - `normal`   — orthogonal arrow drawn AFTER swimlane / item /
-     *   marker fills so it sits on top of lane bands.
-     * - `overflow` — currently unused at construction; reserved for the
-     *   red `before:` overrun annotation arrow.
-     * - `underBar` — channel router could not find a clear vertical
-     *   gutter between the source and target columns; the arrow's
-     *   vertical leg crosses one or more item bars. The renderer paints
-     *   these edges BEFORE bar fills with a thinner stroke so the bar
-     *   stays the visual foreground.
-     */
-    kind: 'normal' | 'overflow' | 'underBar';
+    /**
+     * Orthogonal path on the dates (specs/true-width-layout.md §3.4): first
+     * = source port, last = target port, where the arrowhead's tip lands.
+     * Item and container sources route vertical, horizontal (in a gap
+     * between rows), vertical; a target on its source's row and a marker
+     * stub are one horizontal leg.
+     */
+    waypoints: Point[];
+    /** The target waits on its source: the horizontal legs are dotted. */
+    slack: boolean;
+    /**
+     * Arrowhead width across its leg, scaled down to the target's width;
+     * a target narrower than `ARROW_HEAD_MIN_PX` gets a dot that wide
+     * (`head: 'dot'`) instead (§8 O6).
+     */
+    headWidth: number;
+    head: 'arrow' | 'dot';
     style: ResolvedStyle;
 }
 
@@ -597,12 +877,40 @@ export interface PositionedFootnoteArea {
 }
 
 export interface PositionedFootnoteEntry {
+    /**
+     * The title of the isolated region the footnote comes from; the
+     * renderer heads each region's run of entries with it. Omitted on the
+     * host's own footnotes.
+     */
+    region?: string;
+    /**
+     * Baseline of the region's heading row, on the first entry of each
+     * region's run only.
+     */
+    regionHeadingY?: number;
     number: number;
+    /** Baseline of the entry's first row, where its number sits. */
+    y: number;
     title: string;
+    /** The title's rows: one unless it is wider than the panel. */
+    titleLines: PositionedFootnoteLine[];
     description?: string;
+    /**
+     * The description's rows, the first led by `— `: beside the title when
+     * its first word fits there, the rest wrapped at the title's x. Omitted
+     * when the footnote has no description.
+     */
+    descriptionLines?: PositionedFootnoteLine[];
     style: ResolvedStyle;
 }
 
+/** One row of footnote text, at its baseline. */
+export interface PositionedFootnoteLine {
+    x: number;
+    y: number;
+    text: string;
+}
+
 export interface PositionedIncludeRegion {
     sourcePath: string; // relative to the parent file
     label: string; // e.g. the child roadmap's title or basename
@@ -612,6 +920,193 @@ export interface PositionedIncludeRegion {
     // tick row above the region.
     nestedSwimlanes: PositionedSwimlane[];
     style: ResolvedStyle;
+    /**
+     * Wave crossings over this region's background bars (specs/waves.md
+     * §9.3, §9.8), re-emitted inside the region because its opaque fill
+     * hides the global layers. Omitted when there are none.
+     */
+    waveCrossings?: PositionedWaveCrossing[];
+    /**
+     * The region's own anchors and milestones, in its own marker row
+     * under the label tab; their cut lines stop at its last lane. Omitted
+     * when it has none to draw.
+     */
+    anchors?: PositionedAnchor[];
+    milestones?: PositionedMilestone[];
+    /**
+     * The region's own dependency edges, routed among its lanes. Omitted
+     * when it has none.
+     */
+    edges?: PositionedDependencyEdge[];
+}
+
+/**
+ * One wave's solved span (specs/waves.md §5.1, §8.7), in declaration order.
+ * Only present in a roadmap that declares waves.
+ */
+export interface PositionedWave {
+    id: string;
+    /** The wave's title, else its id. */
+    title: string;
+    /** 0-based declaration order. */
+    index: number;
+    /** `S_k` in logical px. */
+    startX: number;
+    /** `E_k` in logical px; equals `startX` for an empty wave. */
+    endX: number;
+    /** `S_k` as a whole UTC day. */
+    startDate: Date;
+    /** `E_k` as a whole UTC day, exclusive. */
+    endDate: Date;
+    /** Members placed in the main lanes and first-level isolated regions. */
+    memberCount: number;
+    /** True when the wave has no members (it spans no time). */
+    empty: boolean;
+    /**
+     * The member that sets `E_k` (its id, else its title). Omitted when no
+     * member's end equals `E_k` with `E_k > S_k` (§5.1 "Held by").
+     */
+    heldBy?: string;
+    /** The wave's `after:` value that set `S_k`, when it beat `E_{k-1}`. */
+    floorRef?: string;
+    /**
+     * 0-based position among the non-empty waves; drives the strip-cell
+     * alternation (even: `wave.stripFill`, odd: `wave.stripFillAlt`), so
+     * empty waves and gaps never break it. Omitted for an empty wave.
+     */
+    visibleOrdinal?: number;
+    /** The wave's column: `startX..endX` × `chartTopY..swimlaneBottomY`. */
+    columnBox: BoundingBox;
+    /** The wave's strip cell (specs/waves.md §9.1). */
+    strip: PositionedWaveStrip;
+    /** Resolved colours (specs/waves.md §9.4). */
+    style: PositionedWaveStyle;
+    /** 1-based numbers of the footnotes whose `on:` names this wave, ascending. */
+    footnoteIndicators: number[];
+}
+
+/** One wave's strip cell (specs/waves.md §9.1). */
+export interface PositionedWaveStrip {
+    /** `startX..endX` at `waveStrip.y`; zero width for an empty wave. */
+    box: BoundingBox;
+    /** The label text; omitted when `labelKind` is `none`. */
+    label?: string;
+    /**
+     * The painted cell: `box` clipped to the timeline's backing panel and
+     * inset by `WAVE_CELL_INSET_PX` (half the panel's stroke) so it never
+     * covers the panel border. Omitted for an empty wave and for one that
+     * lies outside the timeline.
+     */
+    cell?: BoundingBox;
+    /**
+     * Where the label is drawn when the wave has a `cell`: `x` is the text
+     * centre (`labelX`, moved left when the superscripts would cover it)
+     * and `halo` the backing box in the cell's fill. Omitted when there is
+     * no label or no cell.
+     */
+    labelDraw?: { x: number; halo: BoundingBox };
+    /**
+     * The calendar glyph for a declared date floor (`wave launch after:2026-11-02`),
+     * at the cell's left, vertically centred in the strip, whether or not the
+     * floor opened a gap. The label clears it. Omitted when the wave has no
+     * date floor, no `cell`, or the cell is too narrow to host it.
+     */
+    inlineDatePin?: InlineDatePin;
+    /**
+     * The footnote superscripts when `footnotesShown` and the wave has a
+     * `cell`: `rightX` is the last superscript's right edge (they walk left
+     * by `ITEM_FOOTNOTE_INDICATOR_STEP_PX`, end-anchored) and `halo` their
+     * backing box. Omitted otherwise.
+     */
+    superscripts?: { rightX: number; halo: BoundingBox };
+    /**
+     * Which step of the fit chain won: the title, the id, the title
+     * ellipsized to 3 or more characters plus "…", the 1-based `#k`, or
+     * no label. Always `none` for an empty wave (it has no cell).
+     */
+    labelKind: 'title' | 'id' | 'ellipsis' | 'ordinal' | 'none';
+    /**
+     * Centre of the visible part of the span (clipped to the timeline);
+     * `startX` for an empty wave, which is not drawn.
+     */
+    labelX: number;
+    /**
+     * The cell's hover text, e.g. `Launch · 2026-02-02 – 2026-02-23 · held
+     * by i2` (end exclusive). An empty wave reads `title · date · no items`.
+     */
+    tooltip: string;
+    /**
+     * True when `footnoteIndicators` are drawn right-aligned in the cell;
+     * false when there are none or they did not fit (they are then not
+     * drawn; the footnote panel still lists the footnote).
+     */
+    footnotesShown: boolean;
+    /**
+     * The floor reference (`fy-budget`, `2026-02-02`) centred in the gap
+     * this wave's start floor opened before it (`S_k > E_{k-1}`, k >= 2),
+     * when it fits; drawn in muted italics. `halo` is its backing box in the
+     * panel's fill, sized from the text's estimated width at 10 px (the one
+     * its fit was tested at). Omitted otherwise.
+     */
+    gapLabel?: { text: string; x: number; halo: BoundingBox };
+}
+
+/** A wave's resolved colours (specs/waves.md §9.4). */
+export interface PositionedWaveStyle {
+    /** The style's `bg`: the column tint and the strip-cell overlay. Omitted when unset. */
+    tint?: string;
+    /** The cell's base fill by `visibleOrdinal` parity. */
+    stripFill: string;
+    /** Label colour: the style's `text`, else `wave.labelText`, else a dark or light pick at 4.5:1. */
+    text: string;
+    /** Boundary colour: the style's `fg`, else `wave.boundary`. */
+    boundary: string;
+    /** `4 2` for `border:dashed`, `1 2` for `dotted`, null for solid. */
+    boundaryDash: string | null;
+}
+
+/**
+ * One wave boundary line (specs/waves.md §9.2), at a distinct x in
+ * `{S_k} ∪ {E_k}` of the non-empty waves other than the origin. It runs
+ * from the top of the strip down to `swimlaneBottomY`.
+ */
+export interface PositionedWaveBoundary {
+    x: number;
+    topY: number;
+    bottomY: number;
+    stroke: string;
+    dash: string | null;
+}
+
+/**
+ * A boundary drawn over a background bar whose visual extent strictly
+ * contains it (specs/waves.md §9.3), from the bar's top to its bottom.
+ */
+export interface PositionedWaveCrossing {
+    x: number;
+    topY: number;
+    bottomY: number;
+    stroke: string;
+}
+
+/** One legend entry (specs/waves.md §9.5). */
+export interface WaveLegendEntry {
+    /** The hatch swatch for background work, the legend's only entry. */
+    kind: 'background';
+    /** The entry's full text. */
+    text: string;
+    /** The swatch box: a hatched bar. */
+    swatch: BoundingBox;
+    /** The swatch's hatch kind, a default item bar's fill. */
+    hatch: WaveHatchKind;
+    /** The text, one run on the swatch's line. `y` is the text baseline. */
+    runs: Array<{ text: string; x: number; y: number }>;
+}
+
+/** The wave legend below the chart (specs/waves.md §9.5). */
+export interface PositionedWaveLegend {
+    box: BoundingBox;
+    entries: WaveLegendEntry[];
 }
 
 // Top-level result handed to the renderer.
@@ -638,4 +1133,18 @@ export interface PositionedRoadmap {
     includes: PositionedIncludeRegion[];
     // Frame (chart area) in chart-space. Useful for renderer overlays.
     chartBox: BoundingBox;
+    /**
+     * The wave barrier driver's result (specs/waves.md §8.7): the passes it
+     * ran and whether it hit the `n + 1` cap (NL.W1002, invalid input).
+     * Present only when the roadmap declares waves.
+     */
+    waveSolve?: { passes: number; capped: boolean };
+    /** The waves in declaration order; present only when the roadmap declares waves. */
+    waves?: PositionedWave[];
+    /** Wave boundary lines, left to right; omitted when there are none. */
+    waveBoundaries?: PositionedWaveBoundary[];
+    /** Crossings over the main lanes' background bars; omitted when there are none. */
+    waveCrossings?: PositionedWaveCrossing[];
+    /** The wave legend; present only when one of its triggers holds (§9.5). */
+    waveLegend?: PositionedWaveLegend;
 }