@mermaid-js/diagram-sequence 13.0.0-alpha.0 → 13.0.0-alpha.1

package/dist/ascii/draw.d.ts

@@ -0,0 +1,16 @@
+import { type GlyphSet } from '@mermaid-js/core/ascii';
+import type { SequenceLayout } from '../layout/index.ts';
+/** How the lines of a label sit in its box: `messageAlign` / `noteAlign`, else centred. */
+export type Align = 'left' | 'center' | 'right';
+export interface DrawOptions {
+    /** The front-matter title, for a diagram with no `title` statement of its own. */
+    readonly title?: string;
+    readonly messageAlign?: Align;
+    readonly noteAlign?: Align;
+}
+/**
+ * Draws a sequence layout in cells. Returns the text: `\n` line ends, no trailing spaces, the
+ * empty margin around the drawing trimmed, and `title` (the front-matter title, when the
+ * diagram has no `title` statement of its own) centred on the first line.
+ */
+export declare function drawSequence(layout: SequenceLayout, glyphs: GlyphSet, options?: DrawOptions): string;

package/dist/ascii/draw.js

@@ -0,0 +1,391 @@
+// cspell:words Grooff
+// Draws a sequence layout computed in cells onto the text grid (D100, D108, D82): participant
+// boxes with their lifelines, activation bars as heavy lifelines, fragment frames with the
+// keyword tab on the top border and dashed section dividers, message lines with their heads,
+// self loops, notes as boxes, and every label last so lines never cut through text.
+// Two forms follow mermaid-ascii's sequence renderer (Alexander Grooff, pkg/sequence/charset.go
+// at 5a9df15): an activation drawn as the lifeline made heavy, and the async heads `(` and `)`.
+// No code is taken from it: this draws v13's own cell layout with core's text-grid kit, whose
+// mermaid-ascii port core's THIRD_PARTY_NOTICES lists.
+import { armOf, Canvas, cellWidth, DOWN, drawBox, drawText, glyphFor, LEFT, RIGHT, sideOf, UP, } from '@mermaid-js/core/ascii';
+import { ARROW_HEADS } from "../model.js";
+import { symbolForm } from "./symbols.js";
+/** The cell each head (`ARROW_HEADS`) is drawn as: a half head is a harpoon, barb up or down. */
+const CELL = {
+    arrow: 'arrow',
+    open: 'open',
+    cross: 'cross',
+    solidTop: 'top',
+    stickTop: 'top',
+    solidBottom: 'bottom',
+    stickBottom: 'bottom',
+};
+const headOf = (h) => (h ? CELL[h] : undefined);
+// Heads the glyph sets have no entry for: the async head (as mermaid-ascii draws it) and the
+// half heads as harpoons, barb up (`top`) or down (`bottom`); ASCII has only `<` and `>`.
+const OPEN = { left: '(', right: ')' };
+const HARPOON = {
+    top: { left: '↼', right: '⇀' },
+    bottom: { left: '↽', right: '⇁' },
+};
+function headGlyph(glyphs, head, d) {
+    const side = d === LEFT ? 'left' : 'right';
+    switch (head) {
+        case 'arrow':
+            return sideOf(glyphs.head, d);
+        case 'cross':
+            return glyphs.cross;
+        case 'open':
+            return OPEN[side];
+        case 'top':
+        case 'bottom':
+            return glyphs.name === 'unicode' ? HARPOON[head][side] : sideOf(glyphs.head, d);
+    }
+}
+const dirOf = (a, b) => {
+    if (b.x !== a.x)
+        return b.x > a.x ? RIGHT : LEFT;
+    return b.y > a.y ? DOWN : UP;
+};
+/**
+ * Draws a run of cells as one line: each cell gets arms to its neighbours, the ends also the
+ * arm that carries the line on, so a straight run is `─` to the end and a turn is a corner.
+ */
+function drawRun(canvas, glyphs, cells, dotted) {
+    const last = cells.length - 1;
+    cells.forEach((c, i) => {
+        let arms = 0;
+        if (i > 0)
+            arms |= armOf(dirOf(c, cells[i - 1]), 1);
+        if (i < last)
+            arms |= armOf(dirOf(c, cells[i + 1]), 1);
+        if (i === 0 && last > 0)
+            arms |= armOf(dirOf(cells[1], c), 1);
+        if (i === last && last > 0)
+            arms |= armOf(dirOf(cells[last - 1], c), 1);
+        if (last === 0)
+            arms = armOf(LEFT, 1) | armOf(RIGHT, 1);
+        let glyph = glyphFor(arms, glyphs);
+        if (dotted && arms === (armOf(LEFT, 1) | armOf(RIGHT, 1)))
+            glyph = glyphs.dotted.h;
+        if (dotted && arms === (armOf(UP, 1) | armOf(DOWN, 1)))
+            glyph = glyphs.dotted.v;
+        if (glyph)
+            canvas.draw(c.x, c.y, glyph);
+    });
+}
+/** A one-armed stub merged into the line glyph at a cell: a lifeline becomes a tee. */
+function stub(canvas, glyphs, x, y, d) {
+    if (canvas.get(x, y) === ' ')
+        return;
+    canvas.draw(x, y, glyphFor(armOf(d, 1), glyphs));
+}
+const row = (x1, x2, y) => {
+    const out = [];
+    const step = x2 >= x1 ? 1 : -1;
+    for (let x = x1; x !== x2 + step; x += step)
+        out.push({ x, y });
+    return out;
+};
+const column = (x, y1, y2) => {
+    const out = [];
+    for (let y = y1; y <= y2; y++)
+        out.push({ x, y });
+    return out;
+};
+const textOf = (label, i) => (label.lines[i] ?? []).map((r) => r.text).join('');
+/** Writes each line of a placed label in the label's width, aligned as `align` says. */
+function writeLabel(canvas, p, align = 'center') {
+    const { text } = p;
+    text.lines.forEach((_, i) => {
+        const line = textOf(text, i);
+        const room = p.width - cellWidth(line);
+        let x = p.x + Math.floor(room / 2);
+        if (align === 'left')
+            x = p.x;
+        else if (align === 'right')
+            x = p.x + room;
+        drawText(canvas, x, p.y + i, line);
+    });
+}
+/** Writes a label's lines centred in a row band `x … x + width − 1`, from row `y`. */
+function writeCentred(canvas, label, x, width, y) {
+    label.lines.forEach((_, i) => {
+        const line = textOf(label, i);
+        drawText(canvas, x + Math.floor((width - cellWidth(line)) / 2), y + i, line);
+    });
+}
+/** The first column from which `length` cells of row `y` up to `to` are plain border. */
+function plainRun(canvas, glyphs, from, to, y, length) {
+    let run = 0;
+    for (let x = from; x <= to; x++) {
+        run = canvas.get(x, y) === glyphs.solid.h ? run + 1 : 0;
+        if (run === length)
+            return x - length + 1;
+    }
+    return undefined;
+}
+/** Clears a rectangle's cells to spaces (what a filled SVG shape hides). */
+function clear(canvas, r) {
+    for (let y = r.y; y < r.y + r.height; y++)
+        for (let x = r.x; x < r.x + r.width; x++)
+            canvas.set(x, y, ' ');
+}
+/**
+ * Writes `text` on a frame's top border from column `x`, with a space either side
+ * (`┌─ text ──┐`) where that leaves the corners `left` and `right` standing.
+ */
+function onBorder(canvas, x, y, text, left, right) {
+    if (x - 1 > left)
+        canvas.set(x - 1, y, ' ');
+    const end = drawText(canvas, x, y, text);
+    if (end < right)
+        canvas.set(end, y, ' ');
+}
+class Drawing {
+    layout;
+    glyphs;
+    align;
+    canvas = new Canvas();
+    labels = [];
+    columns;
+    // Layout coordinates may be negative (a box's margin left of the first column).
+    dx;
+    dy;
+    constructor(layout, glyphs, align) {
+        this.layout = layout;
+        this.glyphs = glyphs;
+        this.align = align;
+        this.columns = new Map(layout.participants.map((p) => [p.id, p]));
+        this.dx = -layout.bounds.x;
+        this.dy = -layout.bounds.y;
+    }
+    rect(r) {
+        return { x: r.x + this.dx, y: r.y + this.dy, width: r.width, height: r.height };
+    }
+    at(p) {
+        return { ...p, x: p.x + this.dx, y: p.y + this.dy };
+    }
+    draw() {
+        this.boxes();
+        this.lifelines();
+        this.fragments();
+        this.activations();
+        for (const m of this.layout.messages)
+            this.message(m);
+        this.notes();
+        this.participants();
+        const { title } = this.layout;
+        if (title)
+            this.labels.push(() => writeLabel(this.canvas, this.at(title)));
+        for (const label of this.labels)
+            label();
+        return this.canvas.toString();
+    }
+    boxes() {
+        for (const b of this.layout.boxes) {
+            const r = this.rect(b);
+            drawBox(this.canvas, this.glyphs, r);
+            if (b.label) {
+                const label = this.at(b.label);
+                const right = r.x + r.width - 1;
+                // Centred in the box as drawn, which may be narrower than the label's own room.
+                const first = textOf(label.text, 0);
+                const x = Math.max(r.x + 1, r.x + Math.floor((r.width - cellWidth(first)) / 2));
+                this.labels.push(() => onBorder(this.canvas, x, r.y, first, r.x, right));
+                for (let i = 1; i < label.text.lines.length; i++)
+                    this.labels.push(() => drawText(this.canvas, label.x, label.y + i, textOf(label.text, i)));
+            }
+        }
+    }
+    lifelines() {
+        const { canvas, glyphs } = this;
+        for (const p of this.layout.participants) {
+            const x = p.lifeline.x + this.dx;
+            for (let y = p.lifeline.y1 + this.dy; y < p.lifeline.y2 + this.dy; y++)
+                canvas.draw(x, y, glyphs.dotted.v);
+        }
+    }
+    // A bar is the lifeline drawn heavy from its first row to its last: a bar on a bar is one
+    // column to the right, as v12 offsets it.
+    activations() {
+        const heavy = glyphFor(armOf(UP, 2) | armOf(DOWN, 2), this.glyphs);
+        for (const a of this.layout.activations) {
+            const x = a.x + a.width - 1 + this.dx;
+            // Only the lifeline turns heavy: a frame border the bar starts or ends on stays.
+            for (let y = a.y + this.dy; y <= a.y + a.height + this.dy; y++) {
+                const here = this.canvas.get(x, y);
+                if (here === ' ' || here === this.glyphs.dotted.v || here === heavy)
+                    this.canvas.set(x, y, heavy);
+            }
+        }
+    }
+    fragments() {
+        const { canvas, glyphs } = this;
+        for (const f of this.layout.fragments) {
+            // A frame's edges are lines between cells: its border takes the cells on them, so the
+            // last row and column it holds (a message line, a lifeline) stay inside.
+            const r = { ...this.rect(f), width: f.width + 1, height: f.height + 1 };
+            drawBox(canvas, glyphs, r);
+            const right = r.x + r.width - 1;
+            for (const s of f.sections) {
+                const y = s.y + this.dy;
+                if (r.width > 2)
+                    drawRun(canvas, glyphs, row(r.x + 1, right - 1, y), true);
+                stub(canvas, glyphs, r.x, y, RIGHT);
+                stub(canvas, glyphs, right, y, LEFT);
+                if (s.label) {
+                    const label = this.at(s.label);
+                    this.labels.push(() => writeLabel(canvas, label));
+                }
+            }
+            const tab = this.at(f.tab);
+            // The keyword goes on the first stretch of plain border it fits, so the lifeline
+            // crossings (`┼`) stay; on none, right after the corner.
+            const keyword = textOf(tab.text, 0);
+            this.labels.push(() => {
+                const at = plainRun(canvas, glyphs, r.x + 1, right - 1, r.y, cellWidth(keyword) + 2);
+                onBorder(canvas, (at ?? r.x + 1) + 1, r.y, keyword, r.x, right);
+            });
+            if (f.title) {
+                const title = this.at(f.title);
+                this.labels.push(() => writeLabel(canvas, title));
+            }
+        }
+    }
+    message(m) {
+        if (m.self)
+            this.selfLoop(m, m.self);
+        else
+            this.line(m);
+        // The layout put the sequence number in front of the label (`1. Hello`).
+        if (m.label) {
+            const label = this.at(m.label);
+            this.labels.push(() => writeLabel(this.canvas, label, this.align.message));
+        }
+    }
+    /** A self message: out along its row, down, and back to the lifeline. */
+    selfLoop(m, self) {
+        const { canvas, glyphs } = this;
+        const y = m.y + this.dy;
+        const startX = m.startX + this.dx;
+        const end = headOf(ARROW_HEADS[m.arrow].end);
+        const start = headOf(ARROW_HEADS[m.arrow].start);
+        const right = self.right + this.dx;
+        const bottom = self.bottom + this.dy;
+        const lifeline = (this.columns.get(m.from)?.lifeline.x ?? m.startX - 1) + this.dx;
+        // A central circle sits on the lifeline; the loop leaves from the cell next to it.
+        const first = m.central ? lifeline + 1 : startX;
+        const cells = [...row(first, right, y)];
+        for (let j = y + 1; j <= bottom; j++)
+            cells.push({ x: right, y: j });
+        cells.push(...row(right - 1, first, bottom));
+        drawRun(canvas, glyphs, cells, m.arrow.includes('dotted'));
+        // `A()->>A` leaves from a circle, `A->>()A` comes back to one (mermaid-ascii: both rows).
+        const fromCircle = m.central === 'from' || m.central === 'both';
+        const toCircle = m.central === 'to' || m.central === 'both';
+        if (fromCircle)
+            canvas.set(lifeline, y, glyphs.circle);
+        else
+            stub(canvas, glyphs, first - 1, y, RIGHT);
+        if (toCircle)
+            canvas.set(lifeline, bottom, glyphs.circle);
+        if (end)
+            canvas.set(first, bottom, headGlyph(glyphs, end, LEFT));
+        if (start)
+            canvas.set(first, y, headGlyph(glyphs, start, LEFT));
+    }
+    /** A message between two lifelines, with its heads and central circles. */
+    line(m) {
+        const { canvas, glyphs } = this;
+        const y = m.y + this.dy;
+        const startX = m.startX + this.dx;
+        const stopX = m.stopX + this.dx;
+        const dotted = m.arrow.includes('dotted');
+        const end = headOf(ARROW_HEADS[m.arrow].end);
+        const start = headOf(ARROW_HEADS[m.arrow].start);
+        const d = stopX >= startX ? RIGHT : LEFT;
+        const step = d === RIGHT ? 1 : -1;
+        const from = this.columns.get(m.from);
+        const to = this.columns.get(m.to);
+        const fromCircle = m.central === 'from' || m.central === 'both';
+        const toCircle = m.central === 'to' || m.central === 'both';
+        // A circle sits on the lifeline, so the line runs from the cell next to it.
+        const first = fromCircle && from ? from.lifeline.x + this.dx + step : startX;
+        drawRun(canvas, glyphs, row(first, stopX, y), dotted);
+        if (!fromCircle)
+            stub(canvas, glyphs, first - step, y, d);
+        if (end)
+            canvas.set(stopX, y, headGlyph(glyphs, end, d));
+        if (start)
+            canvas.set(first, y, headGlyph(glyphs, start, d === RIGHT ? LEFT : RIGHT));
+        if (fromCircle && from)
+            canvas.set(from.lifeline.x + this.dx, y, glyphs.circle);
+        if (toCircle && to)
+            canvas.set(to.lifeline.x + this.dx, y, glyphs.circle);
+    }
+    notes() {
+        const { canvas, glyphs } = this;
+        for (const n of this.layout.notes) {
+            const r = this.rect(n);
+            clear(canvas, r);
+            drawBox(canvas, glyphs, r);
+            // A box side the note spans is drawn through it (the layout keeps the text clear).
+            for (const b of this.layout.boxes) {
+                const box = this.rect(b);
+                for (const x of [box.x, box.x + box.width - 1])
+                    if (x > r.x && x < r.x + r.width - 1)
+                        drawRun(canvas, glyphs, column(x, r.y, r.y + r.height - 1), false);
+            }
+            const label = this.at(n.label);
+            this.labels.push(() => writeLabel(canvas, label, this.align.note));
+        }
+    }
+    participants() {
+        const { canvas, glyphs } = this;
+        for (const p of this.layout.participants) {
+            const options = symbolForm(p.kind) ?? {};
+            const x = p.x + this.dx;
+            const lifeline = p.lifeline.x + this.dx;
+            const box = (top, joint) => {
+                const r = { x, y: top, width: p.width, height: p.height };
+                clear(canvas, r);
+                drawBox(canvas, glyphs, r, options);
+                const border = joint === DOWN ? top + p.height - 1 : top;
+                const outside = joint === DOWN ? border + 1 : border - 1;
+                if (canvas.get(lifeline, outside) !== ' ')
+                    canvas.draw(lifeline, border, glyphFor(armOf(joint, 1), glyphs));
+                const rows = p.label.lines.length;
+                writeCentred(canvas, p.label, x, p.width, top + p.labelY - Math.floor(rows / 2));
+            };
+            box(p.top + this.dy, DOWN);
+            if (p.bottom !== undefined)
+                box(p.bottom + this.dy, UP);
+        }
+    }
+}
+/**
+ * Draws a sequence layout in cells. Returns the text: `\n` line ends, no trailing spaces, the
+ * empty margin around the drawing trimmed, and `title` (the front-matter title, when the
+ * diagram has no `title` statement of its own) centred on the first line.
+ */
+export function drawSequence(layout, glyphs, options = {}) {
+    const align = { message: options.messageAlign ?? 'center', note: options.noteAlign ?? 'center' };
+    let lines = new Drawing(layout, glyphs, align).draw().split('\n');
+    const title = options.title;
+    while (lines.length > 0 && lines[0] === '')
+        lines.shift();
+    while (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    const margin = Math.min(...lines.filter((l) => l !== '').map((l) => l.search(/\S/)));
+    if (margin > 0 && Number.isFinite(margin))
+        lines = lines.map((l) => l.slice(margin));
+    const text = title?.trim();
+    if (text) {
+        const width = Math.max(0, ...lines.map(cellWidth));
+        const out = new Canvas();
+        drawText(out, Math.max(0, Math.floor((width - cellWidth(text)) / 2)), 0, text);
+        lines.unshift(out.toString(), '');
+    }
+    return lines.join('\n');
+}

package/dist/ascii/symbols.d.ts

@@ -0,0 +1,4 @@
+import type { BoxOptions } from '@mermaid-js/core/ascii';
+import type { ParticipantKind } from '../model.ts';
+/** The box options a participant kind is drawn with, or undefined when it has no text form. */
+export declare function symbolForm(kind: ParticipantKind): BoxOptions | undefined;

package/dist/ascii/symbols.js

@@ -0,0 +1,9 @@
+const FORMS = {
+    participant: {},
+    actor: { form: 'rounded' },
+    database: { form: 'caps' },
+};
+/** The box options a participant kind is drawn with, or undefined when it has no text form. */
+export function symbolForm(kind) {
+    return FORMS[kind];
+}

package/dist/ascii/warnings.d.ts

@@ -0,0 +1,28 @@
+import type { Warning } from '@mermaid-js/core';
+import type { AstNode } from '@mermaid-js/core/parser-kit';
+import type { SequenceLayout } from '../layout/index.ts';
+import type { SequenceModel } from '../model.ts';
+/** The feature kinds an `ASCII_DROPPED` warning names, in the order they are reported. */
+export type AsciiDroppedFeature = 'style' | 'emphasis' | 'link' | 'accessibility';
+/** One feature kind text output dropped (D82). */
+export interface AsciiDroppedWarning extends Warning {
+    readonly code: 'ASCII_DROPPED';
+    readonly feature: AsciiDroppedFeature;
+    readonly astIds: readonly string[];
+}
+/** The participant symbols drawn as plain boxes because they have no text form (D82). */
+export interface AsciiShapeWarning extends Warning {
+    readonly code: 'ASCII_SHAPE';
+    readonly shapes: readonly string[];
+    readonly astIds: readonly string[];
+}
+export type AsciiWarning = AsciiDroppedWarning | AsciiShapeWarning;
+/**
+ * The warnings for one drawing of `model`; `shown` holds the ids of the participants drawn.
+ * `ast` adds the statements' ids (`st:3` for a `link` line, `accTitle`, …).
+ */
+export declare function asciiWarnings(model: SequenceModel, layout: SequenceLayout, options: {
+    readonly ast?: AstNode;
+    readonly charset: 'unicode' | 'ascii';
+    readonly config: Readonly<Record<string, unknown>>;
+}): AsciiWarning[];

package/dist/ascii/warnings.js

@@ -0,0 +1,141 @@
+import { Style } from '@mermaid-js/core/text';
+import { symbolForm } from "./symbols.js";
+const WHAT = {
+    style: 'colours (box colours, rect highlighting)',
+    emphasis: 'bold and italic text',
+    link: 'actor menus (links, properties, details)',
+    accessibility: 'accTitle and accDescr',
+};
+function rects(statements, out) {
+    for (const s of statements) {
+        if (s.kind === 'rect') {
+            out.push(s.ast);
+            rects(s.statements, out);
+        }
+        else if (s.kind === 'fragment')
+            for (const sec of s.sections)
+                rects(sec.statements, out);
+    }
+}
+// The statements behind each feature kind, by AST node type.
+const STATEMENTS = {
+    style: [],
+    emphasis: [],
+    link: ['Links', 'Link', 'Properties', 'Details'],
+    accessibility: ['AccTitle', 'AccDescr'],
+};
+/**
+ * The AST ids by node type. A menu statement counts only while it still carries its `menu`:
+ * a later redeclaration drops it, as v12 dropped the merged menu, and the plugin draws none.
+ */
+function idsByType(ast, out) {
+    if (!ast)
+        return;
+    const dropped = STATEMENTS.link.includes(ast.type) && !('menu' in ast && ast.menu);
+    if (!dropped) {
+        const list = out.get(ast.type);
+        if (list)
+            list.push(ast.id);
+        else
+            out.set(ast.type, [ast.id]);
+    }
+    for (const child of ast.children ?? [])
+        idsByType(child, out);
+}
+const emphasised = (label) => label?.lines.some((line) => line.some((run) => (run.style & (Style.Bold | Style.Italic)) !== 0)) ?? false;
+// `sequence.*FontWeight` set bold, which text cannot show either.
+const WEIGHTS = ['actorFontWeight', 'messageFontWeight', 'noteFontWeight'];
+const bold = (v) => v === 'bold' || v === 'bolder' || Number(v) >= 600;
+/** The AST ids of the drawn elements whose text is bold or italic. */
+function emphasisIds(layout) {
+    const out = [];
+    for (const p of layout.participants)
+        if (emphasised(p.label))
+            out.push(p.ast);
+    for (const m of layout.messages)
+        if (emphasised(m.label?.text))
+            out.push(m.ast);
+    for (const n of layout.notes)
+        if (emphasised(n.label.text))
+            out.push(n.ast);
+    for (const f of layout.fragments)
+        if (emphasised(f.title?.text) || f.sections.some((s) => emphasised(s.label?.text)))
+            out.push(f.ast);
+    for (const b of layout.boxes)
+        if (emphasised(b.label?.text))
+            out.push(b.ast);
+    return out;
+}
+const hasKeys = (o) => o !== undefined && Object.keys(o).length > 0;
+/**
+ * The warnings for one drawing of `model`; `shown` holds the ids of the participants drawn.
+ * `ast` adds the statements' ids (`st:3` for a `link` line, `accTitle`, …).
+ */
+export function asciiWarnings(model, layout, options) {
+    const shown = new Set(layout.participants.map((p) => p.id));
+    const { ast } = options;
+    const found = {
+        style: undefined,
+        emphasis: undefined,
+        link: undefined,
+        accessibility: undefined,
+    };
+    const add = (feature, ids) => {
+        (found[feature] ??= []).push(...ids);
+    };
+    const coloured = model.boxes.filter((b) => b.color !== undefined).map((b) => b.ast);
+    const rectIds = [];
+    rects(model.statements, rectIds);
+    if (coloured.length > 0 || rectIds.length > 0)
+        add('style', [...coloured, ...rectIds]);
+    const menus = model.participants.filter((p) => shown.has(p.id) && (hasKeys(p.links) || hasKeys(p.properties)));
+    if (menus.length > 0)
+        add('link', menus.map((p) => p.ast));
+    const emphasis = emphasisIds(layout);
+    if (emphasis.length > 0 || WEIGHTS.some((k) => bold(options.config[k])))
+        add('emphasis', emphasis);
+    if (model.accTitle.trim() !== '' || model.accDescr.trim() !== '')
+        add('accessibility', []);
+    const stmts = new Map();
+    idsByType(ast, stmts);
+    for (const feature of Object.keys(STATEMENTS)) {
+        const ids = STATEMENTS[feature].flatMap((type) => stmts.get(type) ?? []);
+        if (ids.length > 0)
+            add(feature, ids);
+    }
+    const out = [];
+    for (const feature of Object.keys(WHAT)) {
+        const ids = found[feature];
+        if (!ids)
+            continue;
+        out.push({
+            code: 'ASCII_DROPPED',
+            feature,
+            astIds: [...new Set(ids)],
+            message: `Text output has no ${WHAT[feature]}; dropped.`,
+        });
+    }
+    const shapes = [];
+    const astIds = [];
+    for (const p of model.participants) {
+        if (!shown.has(p.id) || symbolForm(p.kind))
+            continue;
+        if (!shapes.includes(p.kind))
+            shapes.push(p.kind);
+        astIds.push(p.ast);
+    }
+    // ASCII has no half arrowheads: `-|\` and friends are drawn as `>` and `<`.
+    const half = layout.messages.filter((m) => /_(?:top|bottom)/u.test(m.arrow)).map((m) => m.ast);
+    if (options.charset === 'ascii' && half.length > 0) {
+        shapes.push('half-arrowhead');
+        astIds.push(...half);
+    }
+    if (shapes.length > 0)
+        out.push({
+            code: 'ASCII_SHAPE',
+            shapes,
+            astIds,
+            message: `Text output draws these as plain boxes or full heads: ${shapes.join(', ')}.`,
+        });
+    return out;
+}

package/dist/ascii.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The sequence diagram's text output (D100, D108, DESIGN §6.3), a separate lazily loaded entry
+ * (`@mermaid-js/diagram-sequence/ascii`, manifest key `ascii`) so SVG renders never load it.
+ *
+ * It draws the same `SequenceLayout` the SVG renderer draws, computed with the cell metrics
+ * (the cell measurer and the cell profile, D108), with core's text-grid kit.
+ */
+import type { TextRenderContext } from '@mermaid-js/core';
+import type { SequenceModel } from './model.ts';
+import { type SequenceLayout } from './layout/index.ts';
+export type { AsciiDroppedFeature, AsciiDroppedWarning, AsciiShapeWarning, AsciiWarning, } from './ascii/warnings.ts';
+/**
+ * Lays a sequence diagram out in cells: the cell measurer and the cell profile
+ * (`ascii.padding`), whatever `ctx` carries (D108).
+ */
+export declare function layoutAscii(model: SequenceModel, ctx: TextRenderContext): SequenceLayout;
+/**
+ * The sequence diagram's `ascii` hook (DESIGN §12.1): the drawing as text, `\n` line ends, no
+ * trailing spaces. Warns once per feature kind it drops and once for the participant symbols
+ * drawn as plain boxes (D82). A layout not in cells is redone with `layoutAscii`.
+ */
+export declare function ascii(model: SequenceModel, layout: SequenceLayout, ctx: TextRenderContext): string;

package/dist/ascii.js

@@ -0,0 +1,34 @@
+import { ascii as asciiGlyphs, asciiOptions, cellMeasurer, unicode } from '@mermaid-js/core/ascii';
+import { cellProfile } from '@mermaid-js/core/layout';
+import { layoutSequence } from "./layout/index.js";
+import { drawSequence } from "./ascii/draw.js";
+import { asciiWarnings } from "./ascii/warnings.js";
+/**
+ * Lays a sequence diagram out in cells: the cell measurer and the cell profile
+ * (`ascii.padding`), whatever `ctx` carries (D108).
+ */
+export function layoutAscii(model, ctx) {
+    const { padding } = asciiOptions(ctx.config);
+    return layoutSequence(model, { ...ctx, measurer: cellMeasurer, units: cellProfile(padding) });
+}
+/**
+ * The sequence diagram's `ascii` hook (DESIGN §12.1): the drawing as text, `\n` line ends, no
+ * trailing spaces. Warns once per feature kind it drops and once for the participant symbols
+ * drawn as plain boxes (D82). A layout not in cells is redone with `layoutAscii`.
+ */
+export function ascii(model, layout, ctx) {
+    const laid = layout.units === 'cell' ? layout : layoutAscii(model, ctx);
+    const glyphs = asciiOptions(ctx.config).charset === 'ascii' ? asciiGlyphs : unicode;
+    const config = (ctx.config.sequence ?? {});
+    const warnings = asciiWarnings(model, laid, { ast: ctx.ast, charset: glyphs.name, config });
+    for (const w of warnings)
+        ctx.warn(w);
+    // The diagram's own `title` statement is laid out; else the front-matter title goes on top.
+    const seq = ctx.config.sequence ?? {};
+    const align = (v) => v === 'left' || v === 'center' || v === 'right' ? v : undefined;
+    return drawSequence(laid, glyphs, {
+        ...(laid.title || ctx.title === undefined ? {} : { title: ctx.title }),
+        ...(align(seq.messageAlign) ? { messageAlign: align(seq.messageAlign) } : {}),
+        ...(align(seq.noteAlign) ? { noteAlign: align(seq.noteAlign) } : {}),
+    });
+}

package/dist/facet/completions.d.ts

@@ -0,0 +1,3 @@
+import type { CompletionItem, DocumentView, ProbeResult } from '@mermaid-js/core/parser-kit';
+import type { SequenceDocument } from '../parser/ast.ts';
+export declare function sequenceCompletions(probe: ProbeResult, doc: DocumentView<SequenceDocument>): CompletionItem[];