@draftably/markdown 0.2.3 → 0.2.4

package/dist/types/src/engines/routing/doglegs.d.ts

@@ -0,0 +1,16 @@
+import { type Line } from './conflicts.ts';
+import type { NearBox, Obstacle, Point, RoutingSettings } from './types.ts';
+export interface Lanes {
+    xs: number[];
+    ys: number[];
+}
+export declare function laneLines(used: Line[], s: RoutingSettings): Lanes;
+export declare function doglegs(a: Point, b: Point, obs: Obstacle[], s: RoutingSettings, lanes: Lanes, near: NearBox[], room: number, visit: (path: Point[], k: number, horizontal?: boolean) => void): void;
+/**
+ * A lower bound on the crossings `conflicts` finds between a dogleg (2 to 4 points, before
+ * `compress`) and `used`: segments that cross well inside both. Two such crossings are never one
+ * point of one route, so each is a crossing `conflicts` counts. Runs along a fixed line use the
+ * level or upright segments that span it; a dogleg's middle run, which moves with its lane, uses
+ * the segments inside its fixed span.
+ */
+export declare function crossingFloor(used: Line[]): (a: Point, b: Point) => (raw: Point[], horizontal?: boolean) => number;

package/dist/types/src/engines/routing/find.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from './context.ts';
+import type { Obstacle, PriorRoute, Route, RouteEdge } from './types.ts';
+/** The sides an edge had before, to keep them (`portStability`) or, with `quick`, to reuse them. */
+type Prior = PriorRoute | null | undefined;
+export declare function find(ctx: Context, e: RouteEdge, used: Route[], old?: Prior, wall?: Obstacle[]): Route;
+export {};

package/dist/types/src/engines/routing/geometry.d.ts

@@ -0,0 +1,24 @@
+import type { Obstacle, Point, Rect, Side } from './types.ts';
+export declare const SIDES: Side[], EPS = 0.0001;
+export declare const round: (n: number) => number, clamp: (n: number, a: number, b: number) => number;
+export declare const clone: <T>(v: T) => T, cmp: (a: string, b: string) => 0 | 1 | -1;
+export declare const center: (r: Rect) => Point;
+export declare const same: (a: Point, b: Point) => boolean;
+/** Distance along the axes: every line is level or upright. */
+export declare const distance: (a: Point, b: Point) => number;
+/** The unit vector out of each side. */
+export declare const vector: Record<Side, Point>;
+export declare function inflate<R extends Rect>(r: R, p: number): R;
+/** Whether the level or upright segment a→b enters an obstacle. A slanted segment always does. */
+export declare function blocked(a: Point, b: Point, obs: Obstacle[]): boolean;
+/** A path with rounded points, without repeats or points inside a straight run. */
+export declare function compress(ps: Point[]): Point[];
+export declare function segments(ps: Point[]): [Point, Point][];
+export declare function below(a: number[], v: number): number;
+export declare function atMost(a: number[], v: number): number;
+export declare function lengthOf(ps: Point[]): number;
+export declare function bendsOf(start: Point, ps: Point[], end: Point): number;
+/** Length of a route's axis-aligned segments that lies inside rectangle `r`. */
+export declare function insideLength(ps: Point[], r: Rect): number;
+/** The length of a path, added segment by segment. */
+export declare const pathLength: (ps: Point[]) => number;

package/dist/types/src/engines/routing/heap.d.ts

@@ -0,0 +1,20 @@
+/** A binary min-heap on `f`, in typed arrays. `pop` leaves the entry in `key` and `g`. */
+export declare class Heap {
+    keys: Int32Array;
+    gs: Float64Array;
+    fs: Float64Array;
+    length: number;
+    key: number;
+    g: number;
+    constructor();
+    push(key: number, g: number, f: number): void;
+    pop(): void;
+}
+/** A binary min-heap of objects ordered by `before`. */
+export declare class Queue<T> {
+    items: T[];
+    before: (a: T, b: T) => boolean;
+    constructor(before: (a: T, b: T) => boolean);
+    push(v: T): void;
+    pop(): T;
+}

package/dist/types/src/engines/routing/improve.d.ts

@@ -0,0 +1,7 @@
+import type { Context } from './context.ts';
+/**
+ * Routes again each line that is blocked, crosses, shares a run, runs too close to another or
+ * uses a far side, worst first, and keeps a new route when the whole drawing costs less. Returns
+ * how many it kept.
+ */
+export declare function improve(ctx: Context): number;

package/dist/types/src/engines/routing/nudge.d.ts

@@ -0,0 +1,7 @@
+import type { Context } from './context.ts';
+/**
+ * Slide complete internal orthogonal segments into nearby free channels.
+ * Endpoints, sides, node coordinates and authored waypoint routes stay fixed.
+ * Returns how many routes it moved.
+ */
+export declare function nudge(ctx: Context): number;

package/dist/types/src/engines/routing/paths.d.ts

@@ -0,0 +1,8 @@
+import { type Context } from './context.ts';
+import type { Obstacle, Point, Route, RouteEdge, Side } from './types.ts';
+/**
+ * Whether a path leaves and enters along its sides' normals, stays level or upright, clears the
+ * obstacles (its own end boxes aside, on the first and last segment) and never doubles back.
+ */
+export declare function validPath(points: Point[], e: RouteEdge, fs: Side, ts: Side, obs: Obstacle[]): boolean;
+export declare function simplify(ctx: Context, points: Point[], e: RouteEdge, fs: Side, ts: Side, obs: Obstacle[], used: Route[]): Point[];

package/dist/types/src/engines/routing/planned.d.ts

@@ -0,0 +1,7 @@
+import type { Context } from './context.ts';
+import type { Route, RouteEdge } from './types.ts';
+/**
+ * A line's planned route (`plan`, from a `flow` scope's ranks) is its route when it leaves and
+ * enters by facing sides and clears every box.
+ */
+export declare function planned(ctx: Context, e: RouteEdge): Route | null;

package/dist/types/src/engines/routing/ports.d.ts

@@ -0,0 +1,10 @@
+import type { End, Point, Rect, Route, RoutingSettings, ShapeKind, Side } from './types.ts';
+/** The fields of a route that hold the side and the offset of one end. */
+export declare const sideKey: (end: End) => `${End}Side`;
+export declare const offsetKey: (end: End) => `${End}Offset`;
+/** The point on `side` of a shape, `offset` along it from the middle, on the shape's outline. */
+export declare function port(rect: Rect & {
+    shape?: ShapeKind;
+}, side: Side, offset?: number): Point;
+export declare const TIGHT_PITCH = 12;
+export declare function slot(id: string, side: Side, r: Rect, used: Route[], s: RoutingSettings, other: Rect, tight?: boolean, spread?: boolean): number;

package/dist/types/src/engines/routing/repair.d.ts

@@ -0,0 +1,9 @@
+import type { Context } from './context.ts';
+/**
+ * Edges are routed one at a time, so a crossing priced when the later edge was routed is never
+ * repaired: moving either line alone costs more than the crossing. Try each crossing pair
+ * together: route one with the other's line as a wall, then the other round it, and keep the
+ * pair when the drawing as a whole costs less (NEXT.md item 9, R6).
+ * Returns how many pairs it rerouted.
+ */
+export declare function repair(ctx: Context): number;

package/dist/types/src/engines/routing/score.d.ts

@@ -0,0 +1,12 @@
+import type { Context } from './context.ts';
+import type { Candidate, Point, PriorRoute, Route, RouteEdge, Side } from './types.ts';
+/**
+ * The score of a candidate route of edge `e` against the routed lines `used`: length, bends,
+ * standoff, crossings and lane conflicts, plus what its sides cost (far sides, conventions, fans,
+ * the layout's direction, a change from `old`). `from` and `to` are the sides the edge may use.
+ */
+export declare function createScorer(ctx: Context, e: RouteEdge, used: Route[], old: PriorRoute | null | undefined, from: Side[], to: Side[]): {
+    axis: (c: Candidate) => number;
+    score: (points: Point[], c: Candidate, bound?: number, floor?: boolean) => number;
+    sideFloor: (c: Candidate) => number;
+};

package/dist/types/src/engines/routing/search.d.ts

@@ -0,0 +1,16 @@
+import type { NearBox, Obstacle, Point, Route, RoutingSettings } from './types.ts';
+/** Search window margins round the two boxes, tried in turn; null is the whole grid. */
+export declare const WINDOWS: (number | null)[];
+/** A search window: only grid lines inside it are used. */
+export interface Window {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/**
+ * A* over the grid of lines through the ends, the obstacles' sides, the standoff bands and a lane
+ * beside every routed line. Returns the cheapest path from `start` to `end`, or null when none
+ * is found within `limit` visits.
+ */
+export declare function search(start: Point, end: Point, obs: Obstacle[], used: Route[], s: RoutingSettings, near?: NearBox[], limit?: number, win?: Window | null): Point[] | null;

package/dist/types/src/engines/routing/settings.d.ts

@@ -0,0 +1,4 @@
+import type { RoutingSettings } from './types.ts';
+export declare const defaults: RoutingSettings;
+/** Checked settings: defaults under `raw`, with every number held to its range. */
+export declare function settings(raw?: Partial<RoutingSettings>): RoutingSettings;

package/dist/types/src/engines/routing/sidepairs.d.ts

@@ -0,0 +1,20 @@
+import type { Context } from './context.ts';
+import type { Candidate, Obstacle, PriorRoute, Route, RouteEdge, Side } from './types.ts';
+/** One pair of sides an edge may use, with its ports and stubs, and how to look for its paths. */
+export interface SidePair {
+    c: Candidate;
+    /** Stacked neighbours closer than two stubs: the stubs meet halfway and no grid search runs. */
+    tight: boolean;
+    /** The obstacles its doglegs must clear. */
+    walls: Obstacle[];
+    /** The two ports face each other on one clear line. */
+    straight: boolean;
+    /** False for an edge with waypoints: only the grid search routes it. */
+    paths: boolean;
+}
+/**
+ * Port choice: for each allowed pair of sides, the port offsets the fans already on those sides
+ * leave free, the stubs out of them, and the obstacles gated to them. Pairs whose stubs are
+ * blocked, or whose diamond vertex is taken while another is free, are left out.
+ */
+export declare function sidePairs(ctx: Context, e: RouteEdge, used: Route[], edgeObs: Obstacle[], from: Side[], to: Side[], axis: (c: Candidate) => number, old: PriorRoute | null | undefined): SidePair[];

package/dist/types/src/engines/routing/tidy-ports.d.ts

@@ -0,0 +1,13 @@
+import type { Context } from './context.ts';
+import type { Box, End, Point, Route } from './types.ts';
+/**
+ * Tries a tidy move: new points for some routes, by index, with their new offsets. It stands
+ * only when every moved route stays valid and nothing gets worse.
+ */
+export type Attempt = (changes: Map<number, Point[]>, extra?: Record<number, Partial<Route>>, throughWaypoints?: boolean, slack?: number) => boolean;
+/** Whether a shape's sides are straight, so a port may slide along them. */
+export declare const flat: (r: Box) => boolean;
+export declare const ends: End[];
+/** The point `k` steps in from one end of a path. */
+export declare const tip: (ps: Point[], end: End, k?: number) => Point;
+export declare function centrePorts(ctx: Context, attempt: Attempt): void;

package/dist/types/src/engines/routing/tidy.d.ts

@@ -0,0 +1,10 @@
+import type { Context } from './context.ts';
+/**
+ * Tidy: make routes look drafted on purpose. Ports on a side sit symmetrically
+ * about its centre, edges fanning from one side turn on one line, and parallel
+ * runs in a corridor keep one pitch. A move stands only when every moved route
+ * stays valid and nothing gets worse: no crossing, shared run, lane conflict,
+ * short step or standoff cost is added.
+ * Returns how many moves stood.
+ */
+export declare function tidy(ctx: Context): number;

package/dist/types/src/engines/routing/tuning.d.ts

@@ -0,0 +1,9 @@
+import type { Flow, Side } from './types.ts';
+export declare const AXIS_PENALTY = 100, TRAILING: Record<Flow, Side>, LEADING: Record<Flow, Side>, BACK_PENALTY = 300, BACK_OUT: Record<Flow, Side[]>, BACK_IN: Record<Flow, Side[]>;
+export declare const HOOK_PENALTY = 80;
+export declare const ARRIVE_BELOW = 40, ARRIVE_RIGHT = 12, LEAVE_BACK = 12, DETOUR_WEIGHT = 0.5, LINGER_WEIGHT = 0.3, BOUND_SLACK = 1;
+export declare const FAN_PITCH = 10;
+export declare const DETOUR_RATIO = 1.75, DETOUR_SOFT = 1.2, BAND_COST = 120;
+export declare const PORT_SLACK = 4;
+export declare const FAR_PENALTY = 100, OWN_STANDOFF = 1;
+export declare const MAX_REPAIRS = 4, FAN_GROUP = 4, REPAIR_EDGES = 32;

package/dist/types/src/engines/routing/types.d.ts

@@ -0,0 +1,157 @@
+import type { EdgeLayout, Point, Rect, RoutingSettings, ShapeKind, Side } from '../../model/types.ts';
+export interface RouteNodeInput extends Rect {
+    id: string;
+    parentId?: string;
+    shape: ShapeKind;
+    /** The stub for lines that end on an open group's frame: the group's rectangle. */
+    frame?: boolean;
+}
+export interface RouteGroupInput extends Rect {
+    id: string;
+    parentId?: string;
+    collapsed: boolean;
+    /** Width of the header's icon and title from the group's left edge; the rest of the band is open. */
+    titleWidth?: number;
+    /** Height of the title band the router keeps clear; 28 when unset. */
+    titleHeight?: number;
+}
+export interface RouteEdgeInput {
+    id: string;
+    from: string;
+    to: string;
+    directed?: boolean;
+    /** The edge's text. A labelled edge keeps the full port gap in a fan. */
+    label?: string;
+    cfg: EdgeLayout;
+}
+export interface RouteInput {
+    nodes: RouteNodeInput[];
+    groups: RouteGroupInput[];
+    edges: RouteEdgeInput[];
+}
+export interface Route {
+    id: string;
+    from: string;
+    to: string;
+    fromSide: Side;
+    toSide: Side;
+    fromOffset: number;
+    toOffset: number;
+    points: Point[];
+    blocked: boolean;
+    reason?: string;
+}
+export interface PriorRoute {
+    id: string;
+    fromSide: Side;
+    toSide: Side;
+}
+/** What a set of routes costs: the counts the passes compare and the report shows. */
+export interface RouteMetrics {
+    crossings: number;
+    shared: number;
+    lanePairs: number;
+    laneDeficit: number;
+    minimumConflictingGap: number | null;
+    requestedEdgeGap: number;
+    blocked: number;
+    bends: number;
+    length: number;
+}
+export interface RoutingReport extends RouteMetrics {
+    initial: RouteMetrics;
+    accepted: number;
+    /** Crossing pairs the repair pass rerouted. Absent with `quick` or `facing: false`. */
+    repaired?: number;
+    nudged: number;
+    tidied?: number;
+    edges: number;
+    milliseconds: number;
+    passes: number;
+}
+export interface RoutingResult {
+    routes: Route[];
+    report: RoutingReport;
+}
+export interface RoutingOptions extends Partial<RoutingSettings> {
+    previous?: PriorRoute[];
+    quick?: boolean;
+    /** A reading direction for every edge without its own `cfg.flow`; forward edges run along it. */
+    direction?: 'right' | 'down';
+    /**
+     * Keep fans on the sides facing their other ends, off far sides, and a full standoff away
+     * from their own end boxes. On unless false.
+     */
+    facing?: boolean;
+    /**
+     * Keep lines out of a group's title band, except a line straight into or out of a member's
+     * top. On unless false.
+     */
+    titleBands?: boolean;
+    /** Search each route near its two boxes first, and the whole grid only when that fails. On unless false. */
+    window?: boolean;
+    /** Even out ports, fans and corridors after routing. On unless false. */
+    tidy?: boolean;
+    /**
+     * In the tidy pass, straighten steps under 12px by sliding a run (and its port, or through a
+     * fold lane's waypoints) onto the next. On unless false.
+     */
+    jogs?: boolean;
+}
+export type Axis = 'x' | 'y';
+/** Which end of an edge: its source or its target. */
+export type End = 'from' | 'to';
+export type Flow = 'right' | 'down';
+/** A shape the router ends lines on: a node, or a collapsed group drawn as a box. */
+export type Box = Rect & {
+    id: string;
+    parentId?: string;
+    shape?: ShapeKind;
+    frame?: boolean;
+};
+/**
+ * A rectangle no line may enter. `across` lets an upright line cross it but none run along it;
+ * with `gates`, only at those x coordinates.
+ */
+export type Obstacle = Rect & {
+    id?: string;
+    across?: boolean;
+    gates?: number[];
+};
+/** A box or group border that lines should keep `band` away from, at a cost instead of a wall. */
+export type NearBox = Rect & {
+    id: string;
+    band: number;
+    /** A group border: it counts from both sides. */
+    border?: boolean;
+    weight?: number;
+};
+/** A side and offset the repair pass fixes at one end of an edge. */
+export interface Pin {
+    side: Side;
+    offset: number;
+}
+/** An edge as routed: the input edge with a config, and the repair pass's pins. */
+export type RouteEdge = RouteEdgeInput & {
+    pin?: Partial<Record<End, Pin>>;
+};
+/** One choice of sides and ports for an edge, with its stubs and the obstacles it sees. */
+export interface Candidate {
+    /** Source and target sides. */
+    fs: Side;
+    ts: Side;
+    /** Port offsets along those sides. */
+    fo: number;
+    toff: number;
+    start: Point;
+    end: Point;
+    /** Where the stubs out of each port end. */
+    as: Point;
+    bs: Point;
+    obs: Obstacle[];
+    /** A lower bound on the route's score, to order the grid searches. */
+    lower: number;
+    /** The fan-out cost of the side pair, worked out once. */
+    fanout?: number;
+}
+export type { EdgeLayout, Point, Rect, RoutingSettings, ShapeKind, Side };

package/dist/types/src/engines/routing-engine.d.ts

@@ -0,0 +1,20 @@
+import { compute } from './routing/compute.ts';
+import { conflicts, parallelConflicts, type Line } from './routing/conflicts.ts';
+import { blocked } from './routing/geometry.ts';
+import { port } from './routing/ports.ts';
+import { settings } from './routing/settings.ts';
+export declare const RouteLab: {
+    compute: typeof compute;
+    settings: typeof settings;
+    defaults: import("./routing/types.ts").RoutingSettings;
+    port: typeof port;
+    blocked: typeof blocked;
+    conflicts: typeof conflicts;
+    parallelConflicts: typeof parallelConflicts;
+    /** Crossings and shared run length of a set of routes, each counted against the ones before it. */
+    metrics: (routes: Line[]) => {
+        crossings: number;
+        shared: number;
+    };
+};
+export type { PriorRoute, Route, RouteEdgeInput, RouteGroupInput, RouteInput, RouteMetrics, RouteNodeInput, RoutingOptions, RoutingReport, RoutingResult, } from './routing/types.ts';

package/dist/types/src/import/import-core.d.ts

@@ -29,6 +29,9 @@ export interface NativeEdge {
     head?: EndMarker;
     tail?: EndMarker;
     dashed?: boolean;
+    /** Sequence diagrams: the kind of message, and the earlier message a reply answers. */
+    message?: 'call' | 'send' | 'reply';
+    answers?: string;
     constraint?: false;
     fromSide?: 'left' | 'right' | 'top' | 'bottom';
     toSide?: 'left' | 'right' | 'top' | 'bottom';
@@ -36,6 +39,8 @@ export interface NativeEdge {
 export interface NativeLayout {
     scope: string;
     kind: 'flow' | 'column' | 'row' | 'sequence';
+    /** `sequence` only: draw activation bars from calls and their replies. */
+    activations?: true;
     direction?: 'right' | 'down';
 }
 export interface NativeColor {

package/dist/types/src/import/mermaid-sequence.d.ts

@@ -1,6 +1,6 @@
 /**
  * Mermaid `sequenceDiagram` -> native source. Participants become nodes and messages become edges
- * in file order. Native sequences have no fragments, so each top-level branch of a block becomes
+ * in file order, each with its kind: a call, a send or a reply that names the call it answers. Native sequences have no fragments, so each top-level branch of a block becomes
  * a phase band, and the warning says that the branch logic is gone.
  */
 import { type Diagnostic, type ImportResult } from './import-core';

package/dist/types/src/model/appearance.d.ts

@@ -9,6 +9,7 @@ import type { Footnote } from './footnote';
 import type { Note } from './note';
 import { type FontRole, type TypeProfile } from './fonts';
 import type { FileConfig } from './link';
+import type { MessageKind } from './markers';
 export type ThemeId = 'drafting' | 'fieldnotes' | 'signal' | 'ink' | 'blueprint' | 'drafting-dark';
 export declare const THEME_IDS: ThemeId[];
 export declare const DEFAULT_THEME: ThemeId;
@@ -101,10 +102,18 @@ export interface Heading {
 /** The connection styles a `legend line` row can explain. */
 export declare const LEGEND_LINES: readonly ["dashed", "solid"];
 export type LegendLine = (typeof LEGEND_LINES)[number];
-/** One row of the key: a color swatch (`family`), or a short connection (`line`). */
+/**
+ * One row of the key: a color swatch (`family`), a short connection (`line`), or the mark of a
+ * kind of sequence message (`message`), which the drawing adds for each kind it uses.
+ */
 export interface LegendEntry {
     family?: string;
     line?: LegendLine;
+    message?: MessageKind;
+    /** An activation bar, which a sequence with `activations=on` adds a row for. */
+    activation?: true;
+    /** Words with no swatch: a sequence's line that its rows show order, not time. */
+    caption?: true;
     /** Shade of the swatch; nodes' default when omitted. */
     shade?: Shade;
     label: string;

package/dist/types/src/model/labels.d.ts

@@ -62,6 +62,12 @@ export interface NodeLabel {
 export declare function nodeLabel(doc: Diagram, id: string, title: string, r: Rect): NodeLabel;
 /** Bounds of a shape together with its label. */
 export declare function visualBounds(doc: Diagram, id: string, title: string, r: Rect): Rect;
+/** Text width a sequence phase's label wraps to, so a long one does not push the lanes right. */
+export declare const PHASE_WRAP = 96;
+/** Inset of a phase label from its band's top left corner. */
+export declare const PHASE_TAB = 8;
+/** A phase label's lines, in the annotation type. */
+export declare const phaseLabelLines: (label: string, r: ResolvedAppearance) => string[];
 /** Text width a sequence message's label wraps to; the gap between participants follows it. */
 export declare const MESSAGE_WRAP = 168;
 /**
@@ -93,6 +99,23 @@ export declare function edgeLabelSize(label: string, r?: ResolvedAppearance, mes
     w: number;
     h: number;
 };
+/**
+ * An activation bar: its width, how far a nested bar steps to the right, how far it runs past
+ * its first and last rows, and the length of a bar whose call gets no reply.
+ */
+export declare const ACTIVATION: {
+    w: number;
+    step: number;
+    over: number;
+    stub: number;
+};
+/** Room between a local action's label and its box, on each side. */
+export declare const ACTION_PAD = 5;
+/** The box of a local action: its label and `ACTION_PAD` round it, centred on the lifeline. */
+export declare function actionSize(label: string, r: ResolvedAppearance): {
+    w: number;
+    h: number;
+};
 /**
  * What a self-message draws, measured from where its row meets the lifeline: how far right, how
  * far above the row and how far below it.

package/dist/types/src/model/markers.d.ts

@@ -30,10 +30,17 @@ export declare const markerBox: (kind: Exclude<EndMarker, "none">, tail: boolean
 };
 /** The fill a marker takes on this line and surface. */
 export declare function markerFill(kind: Exclude<EndMarker, 'none'>, ink: string, surface: string): string;
+/**
+ * What `message=` accepts on a sequence message, plus `action`, which an `action` line makes.
+ * Each says what the author means; none is read from a line's style.
+ */
+export declare const MESSAGE_KINDS: readonly ["interaction", "call", "send", "reply", "outcome"];
+export type MessageKind = (typeof MESSAGE_KINDS)[number] | 'action';
 type Ends = {
     directed?: boolean;
     head?: EndMarker;
     tail?: EndMarker;
+    message?: MessageKind;
 };
 /** An undirected edge has no marks, whatever else it holds. */
 export declare const headOf: (e: Ends) => EndMarker;

package/dist/types/src/model/note.d.ts

@@ -46,13 +46,22 @@ export declare function noteBox(look: ResolvedAppearance, note: Note): PlacedNot
  * Spots in a sequence's side margins, by index in `notes`, for notes on the messages in `rows`.
  * `left` and `right` are the margins' inner edges and `top` the highest a note goes. A note is
  * level with its row, or pushed down clear of the note above it. The panel grows round these, so
- * no note here can cover the drawing.
+ * no note here can cover the drawing. A note on a message in a phase stays inside that phase's
+ * band (`bands`, by message), which `marginNoteRoom` makes tall enough for its notes.
  */
 export declare function marginNotes(look: ResolvedAppearance, notes: readonly Note[], rows: ReadonlyMap<string, number>, { left, right, top }: {
     left: number;
     right: number;
     top: number;
-}): (Rect | null)[];
+}, bands?: ReadonlyMap<string, {
+    y: number;
+    h: number;
+}>): (Rect | null)[];
+/**
+ * The height a phase band needs for the margin notes on its messages (`ids`): the taller of its
+ * two sides, each a stack of its notes.
+ */
+export declare function marginNoteRoom(look: ResolvedAppearance, notes: readonly Note[], ids: string[]): number;
 /**
  * Place every anchored note beside its object or message, clear of shapes, group borders, lines
  * and earlier notes when a nearby spot allows it. Frame notes, and notes whose object is not drawn,

package/dist/types/src/model/routes.d.ts

@@ -1,4 +1,4 @@
-import { type PriorRoute, type Route, type RoutingResult } from '../engines/routing-engine.js';
+import { type PriorRoute, type Route, type RoutingResult } from '../engines/routing-engine';
 import { type ResolvedAppearance } from './appearance';
 import { type VisibleGraph } from './graph';
 import type { Diagram, EdgeLayout, Point, Rect, ShapeKind, Side } from './types';
@@ -132,8 +132,10 @@ export declare function routeInput(doc: Diagram, vg: VisibleGraph, all: Map<stri
         tail?: import("./markers").EndMarker;
         emphasis: boolean;
         dashed: boolean;
-        status?: import("./status.js").Status;
-        spot?: import("./status.js").Spot;
+        message?: import("./markers").MessageKind;
+        replyTo?: string;
+        status?: import("./status").Status;
+        spot?: import("./status").Spot;
     }[];
 };
 /**

package/dist/types/src/model/status.d.ts

@@ -82,3 +82,21 @@ export declare function withState(doc: Diagram, id: string): Diagram;
 export declare function usedStatuses(doc: Diagram): StatusCount[];
 /** The color key's rows: a diff draws no family colors, so it lists only its statuses. */
 export declare const drawnLegend: (doc: Diagram) => LegendEntry[];
+/** What every sequence says under its drawing. */
+export declare const SEQUENCE_CAPTION = "Rows show order, not elapsed time.";
+/**
+ * The events that belong with one event of a sequence: a message, the reply that answers it,
+ * and the message a reply answers. Only pairs the file states, never a guess from direction.
+ */
+export declare function replyPair(doc: Diagram, id: string): string[];
+/**
+ * A sequence in words, for a reader who cannot see it: the participants, then each event in
+ * order with its kind. An exported SVG carries it as its description unless the host gives one.
+ */
+export declare function sequenceDescription(doc: Diagram): string | undefined;
+/**
+ * The key a sequence draws for its kinds of message: one row for each mark in use, so a reader
+ * never has to guess what a solid head or a box means. Nothing unless a message has a kind. A
+ * plain message and a shown result draw the same arrow, so they share a row.
+ */
+export declare function messageKey(doc: Diagram): LegendEntry[];

package/dist/types/src/model/types.d.ts

@@ -13,7 +13,7 @@ export type PortSide = Side | 'auto';
 export type Direction = 'RIGHT' | 'DOWN';
 export type Theme = 'light' | 'dark';
 import type { DiagramAppearance, Shade } from './appearance';
-import type { EndMarker } from './markers';
+import type { EndMarker, MessageKind } from './markers';
 import type { Spot, Status } from './status';
 export type ShapeKind = 'box' | 'pill' | 'circle' | 'diamond' | 'text' | 'icon' | 'image'
 /** A seam between two cells of a `cells` group. */
@@ -70,6 +70,13 @@ export interface DiagramEdge {
     tail?: EndMarker;
     emphasis: boolean;
     dashed: boolean;
+    /**
+     * A sequence message's meaning, from `message=`, or `action` for work one participant does
+     * (an `action` line; `from` and `to` are that participant). Unset for a plain message.
+     */
+    message?: MessageKind;
+    /** With `message: 'reply'`: the earlier message this one answers, from `answers=`. */
+    replyTo?: string;
     /** How it differs between two versions of the diagram. */
     status?: Status;
     /** How the drawn emphasis state treats it; see `withState`. */
@@ -93,6 +100,8 @@ export interface EdgeLayout {
     toOffset?: number;
     /** A sequence message: drawn straight between the two lifelines at this height, not routed. */
     row?: number;
+    /** A message between distant lanes: the middle of the gap between lifelines its label sits in. */
+    labelX?: number;
     /**
      * Set by the compiler for a forward line in a `flow` scope: its route planned from the ranks.
      * The quick router takes it as it is when it clears every box.
@@ -274,8 +283,18 @@ export interface SequenceLayout {
         rows: Record<string, number>;
         phases: SequencePhase[];
         grow: number;
+        activations?: Activation[];
     };
+    /** With `activations=on`: the bars on the lifelines of participants at work on a call. */
+    activations?: Activation[];
+    /** The `activations=on` switch itself, which the Inspector turns on and off. */
+    bars?: true;
 }
+/** One activation bar: its participant, the call that opened it, and its box. */
+export type Activation = Rect & {
+    node: string;
+    call: string;
+};
 export type SequencePhase = {
     id: string;
     label: string;