@meltemi/diagrams-model 1.9.0 → 1.10.17

package/dist/flow.js

@@ -1,8 +1,9 @@
 import { isToken, } from "@meltemi/diagrams-language";
-import { DIRECTIONS, LAYOUT_MODES, ALIGN_EDGES, ANIMATION_EFFECT_PROPERTIES, AXES, ELEMENT_ONLY_PROPERTIES, FLOW_PROFILE, FREE_PROFILE, MAIN_LAYER, PORTS, PORT_SIDES, RELATION_ONLY_PROPERTIES, diagramStatements, profileTakesShape, takesShape, profileTakesRotation, takesRotation, } from "./schema.js";
+import { DIRECTIONS, LAYOUT_MODES, ALIGN_EDGES, ANIMATION_EFFECT_PROPERTIES, AXES, ELEMENT_ONLY_PROPERTIES, FLOW_PROFILE, FREE_PROFILE, LINE_REFUSED_PROPERTIES, LIST_LAYOUTS, LIST_PROPERTIES, MAIN_LAYER, PEN_PROPERTIES, PEN_REFUSED_PROPERTIES, PEN_WIDTH_RANGE, PORTS, PORT_SIDES, RELATION_ARROWS, RELATION_ONLY_PROPERTIES, STICKY_PROPERTIES, STICKY_REFUSED_PROPERTIES, TEXTLESS_KINDS, TEXT_PROPERTIES, diagramStatements, isFreeStyleProperty, profileTakesShape, takesShape, profileTakesRotation, takesRotation, } from "./schema.js";
 import { relationAllowed, } from "./diagram-types.js";
 import { messages } from "./messages/index.js";
-import { StyleDefinitions, checkArg, describeArg, headerHasError, readClasses, readPropertyBlock, readStatementValue, refuseFreeProperties, singleIdent, spanOf, targetHint, } from "./style-values.js";
+import { StyleDefinitions, argumentOf, checkArg, describeArg, describeSpec, headerHasError, readClasses, readPropertyBlock, readStatementValue, refuseFreeProperties, singleIdent, spanOf, TAG_FORM, targetHint, } from "./style-values.js";
+import { outlined } from "./outline.js";
 /** Element kinds drawn without an outline, which a moving dash cannot follow. */
 const NO_OUTLINE_KINDS = new Set([
     "note",
@@ -115,6 +116,10 @@ export class FlowAnalyzer {
     layerUses = [];
     layerRanges = new Map();
     animations = [];
+    /** Dashes on notes and texts, whose outline is checked once every style is read. */
+    pendingDashes = [];
+    /** The `on <element>` clauses of notes, resolved once every element is declared. */
+    attachments = [];
     references = [];
     entityReferences = [];
     placementBlocks = [];
@@ -148,6 +153,7 @@ export class FlowAnalyzer {
             routing: "auto",
             layers: [MAIN_LAYER],
             autonumber: null,
+            spacing: null,
         };
     }
     /** Sequence diagrams: the ordered events, their index and the scenarios. */
@@ -198,6 +204,8 @@ export class FlowAnalyzer {
             this.declare(decl.stmt, decl.groupPath);
         for (const rel of classified.relations)
             this.relation(rel.stmt, rel.groupPath);
+        // After the relations, which may declare elements that only they mention.
+        this.resolveAttachments();
         this.assignKeys();
         this.afterRelations(classified);
         for (const stmt of classified.properties)
@@ -216,6 +224,7 @@ export class FlowAnalyzer {
                 this.styleOrAnimate(stmt, keyword);
         }
         this.checkLayers();
+        this.checkOutlinedDashes();
         this.finish();
         if (this.declared)
             this.checkDeclared(this.declared);
@@ -254,6 +263,33 @@ export class FlowAnalyzer {
             hasErrors: this.node.hasError || this.errors > 0,
         };
     }
+    /**
+     * A dash follows an outline: a note or a free text that no style statement, class or rule of the
+     * diagram gives a `fill`, `stroke` or `pattern` has none, nor a sticky without a `stroke`, and
+     * the dash is refused and dropped.
+     */
+    checkOutlinedDashes() {
+        const source = {
+            styles: this.styles,
+            classes: this.definitions.classes,
+            rules: this.definitions.rules,
+        };
+        for (const { name, token, stmt } of this.pendingDashes) {
+            const element = this.elementsById.get(name);
+            if (!element || outlined(source, element))
+                continue;
+            this.error("animate.invalid-target", messages().diagnostics.flow.dashNeedsOutline(name, element.kind), token, {
+                hints: [
+                    element.kind === "sticky"
+                        ? messages().hints.flow.dashStroke
+                        : messages().hints.flow.dashOutline,
+                ],
+            });
+            const at = this.animations.findIndex((a) => a.node === stmt && a.target === name && a.effect === "dash");
+            if (at >= 0)
+                this.animations.splice(at, 1);
+        }
+    }
     /** A declared type's rules: required properties, and the kinds relations may join. */
     checkDeclared(definition) {
         for (const element of this.elements) {
@@ -335,17 +371,32 @@ export class FlowAnalyzer {
                     keyword in this.profile.groupProperties) {
                     continue;
                 }
+                // `layout`, `spacing` and `align` make a list of a free group; other profiles have none.
+                if (isListProperty(keyword)) {
+                    if (!(keyword in this.profile.groupProperties)) {
+                        const m = messages();
+                        this.invalid(m.diagnostics.flow.listInProfile(keyword, this.profile.name), stmt.keyword, [m.hints.flow.listsInFree]);
+                    }
+                    continue;
+                }
                 const m = messages();
-                const hints = otherKind
-                    ? [otherKind]
-                    : diagramStatements(this.profile).includes(keyword)
-                        ? [m.hints.flow.diagramLevel(keyword)]
-                        : [m.hints.flow.groupContents];
+                const misplaced = this.misplacedHint(keyword);
+                const hints = misplaced
+                    ? [misplaced]
+                    : otherKind
+                        ? [otherKind]
+                        : diagramStatements(this.profile).includes(keyword)
+                            ? [m.hints.flow.diagramLevel(keyword)]
+                            : [m.hints.flow.groupContents];
                 const candidates = otherKind
                     ? this.declarationWords()
-                    : diagramStatements(this.profile).includes(keyword)
+                    : misplaced || diagramStatements(this.profile).includes(keyword)
                         ? []
-                        : ["description", "url"];
+                        : [
+                            "description",
+                            "url",
+                            ...LIST_PROPERTIES.filter((name) => name in this.profile.groupProperties),
+                        ];
                 this.error("prop.unknown", m.diagnostics.flow.unknownInGroup(keyword), stmt.keyword, {
                     hints,
                     data: { candidates },
@@ -364,6 +415,14 @@ export class FlowAnalyzer {
             this.error("prop.unknown", messages().diagnostics.flow.unknownInDiagram(keyword, this.profile.name), stmt.keyword, { hints, data: { candidates: this.statementCandidates(keyword) } });
         }
     }
+    /**
+     * The profile's own hint for a statement written outside the block it belongs in (a sequence
+     * `tag` outside a message or participant block), in the interface language; undefined for every
+     * other statement.
+     */
+    misplacedHint(_keyword) {
+        return undefined;
+    }
     /** Hints for an unknown statement at the diagram level, in the interface language. */
     statementHints(keyword, stmt) {
         const otherKind = this.otherProfileKind(keyword);
@@ -374,7 +433,7 @@ export class FlowAnalyzer {
         if (stmt.args.length === 0 && !stmt.block) {
             hints.push(m.declareElement(keyword, this.profile.shorthand.box));
         }
-        hints.push(this.free ? m.freeStatements : m.flowStatements);
+        hints.push(this.free ? m.freeStatements(FREE_DECLARATIONS) : m.flowStatements);
         return hints;
     }
     /** The statements an unknown one at the diagram level may have meant, for fixes. */
@@ -399,7 +458,7 @@ export class FlowAnalyzer {
             return undefined;
         }
         const m = messages().hints.flow;
-        return this.free ? m.freeDeclarations : m.flowDeclarations(keyword);
+        return this.free ? m.freeDeclarations(FREE_DECLARATIONS) : m.flowDeclarations(keyword);
     }
     // ------------------------------------------------------------------ elements
     declare(stmt, groupPath) {
@@ -420,6 +479,11 @@ export class FlowAnalyzer {
                 technology: null,
                 external: false,
                 shape: data ? "cylinder" : null,
+                line: null,
+                pen: null,
+                list: null,
+                attachedTo: null,
+                attachedToRange: null,
                 typeKind: null,
                 data: {},
                 groupPath,
@@ -435,19 +499,29 @@ export class FlowAnalyzer {
         const typeKind = declaredKind ? stmt.keyword.text : null;
         const kind = (declaredKind ? "box" : stmt.keyword.text);
         const sourced = kind === "text" || kind === "icon" || kind === "image";
+        const note = kind === "note" && !declaredKind;
         const second = { text: '"Text"', icon: '"<pack>:<name>"', image: '"<path>"' }[kind];
-        const form = sourced
-            ? `\`${kind} <id> ${second}\``
-            : `\`${kind} <id> ["Label"]${kind === "group" ? " { ... }" : ""}\``;
+        const form = note
+            ? '`note <id> "Text" [on <element>]`'
+            : sourced
+                ? `\`${kind} <id> ${second}\``
+                : `\`${kind} <id> ["Label"]${kind === "group" ? " { ... }" : ""}\``;
         const example = {
             text: 'text heading "Architecture"',
             icon: 'icon server "tabler:server"',
             image: 'image logo "logo.png"',
+            note: 'note limits "500 rps" on api',
         }[kind];
         if (stmt.chain) {
             this.invalid(messages().diagnostics.common.singleBlock(kind), stmt.chain.clauses[1].keyword);
             return;
         }
+        if (kind === "line" && !declaredKind)
+            return this.declareLine(stmt, groupPath);
+        if (kind === "pen" && !declaredKind)
+            return this.declarePen(stmt, groupPath);
+        if (kind === "sticky" && !declaredKind)
+            return this.declareSticky(stmt, groupPath);
         const [idArg, labelArg, ...extra] = stmt.args;
         const idToken = singleIdent(idArg);
         if (!idToken) {
@@ -491,22 +565,32 @@ export class FlowAnalyzer {
                 sourceRange = this.range(labelArg);
             }
         }
-        else if (sourced) {
+        else if (sourced || (note && this.notesNeedText)) {
             const m = messages();
             this.invalid(m.diagnostics.flow.needsSource(kind, idToken.text, form), stmt, [
                 m.hints.example(example),
             ]);
         }
+        // A note may end with `on <element>`; nothing else follows a label.
+        let attachment;
         if (extra.length > 0) {
-            this.invalid(messages().diagnostics.flow.valueAfter(sourced ? kind : "label", form), extra[0]);
-            return;
+            attachment = note ? this.attachmentOf(extra, form) : undefined;
+            if (!attachment) {
+                if (!note || !isWord(extra[0], "on")) {
+                    this.invalid(messages().diagnostics.flow.valueAfter(note ? "text" : sourced ? kind : "label", form), extra[0]);
+                }
+                return;
+            }
         }
         const block = kind === "group"
-            ? { ...this.groupBlock(stmt.block, idToken), ports: [], values: {} }
-            : this.elementBlock(stmt.block, declaredKind
-                ? { ...this.profile.elementProperties, ...tableOf(declaredKind.properties) }
-                : this.profile.elementProperties, "Element", idToken);
-        const { values: blockValues, ...blockFields } = block;
+            ? { ...this.groupBlock(stmt.block, idToken), ports: [], tags: [], values: {} }
+            : {
+                ...this.elementBlock(stmt.block, declaredKind
+                    ? { ...this.profile.elementProperties, ...tableOf(declaredKind.properties) }
+                    : this.profile.elementProperties, "Element", idToken),
+                list: null,
+            };
+        const { values: blockValues, list, ...blockFields } = block;
         const added = this.addElement({
             id: idToken.text,
             kind,
@@ -520,6 +604,11 @@ export class FlowAnalyzer {
             technology: null,
             external: false,
             shape: null,
+            line: null,
+            pen: null,
+            list,
+            attachedTo: attachment?.target ?? null,
+            attachedToRange: attachment ? this.range(attachment.arg) : null,
             typeKind,
             data: declaredKind ? dataOf(blockValues, declaredKind.properties) : {},
             groupPath,
@@ -528,6 +617,8 @@ export class FlowAnalyzer {
             idToken,
             node: stmt,
         });
+        if (added && attachment)
+            this.attachments.push({ note: idToken.text, ...attachment, stmt });
         if (!added || source === null || !sourceRange)
             return;
         if (kind === "icon")
@@ -535,6 +626,240 @@ export class FlowAnalyzer {
         else
             this.images.push({ element: idToken.text, path: source, range: sourceRange });
     }
+    /**
+     * `line <id> ["Label"] from (x, y) to (x, y) [via [(x, y), ...]] [{ ... }]`: a free line that
+     * joins no element, its points in the interior coordinates of its innermost group. The label is
+     * empty unless written: a line has no name to show.
+     */
+    declareLine(stmt, groupPath) {
+        const form = '`line <id> ["Label"] from (x, y) to (x, y) [via [(x, y), ...]]`';
+        const m = messages();
+        const [idArg, ...rest] = stmt.args;
+        const idToken = singleIdent(idArg);
+        if (!idToken) {
+            this.invalid(m.diagnostics.common.expected(form), idArg ?? stmt.keyword, [
+                m.hints.example("line divider from (40, 200) to (520, 200)"),
+            ]);
+            return;
+        }
+        const refuse = (at) => this.invalid(m.diagnostics.flow.linePoints, at ?? stmt, [m.hints.flow.form(form)]);
+        const labelArg = rest[0]?.kind === "StringLiteral" ? rest[0] : undefined;
+        const [fromWord, fromArg, toWord, toArg, viaWord, viaList, extra] = labelArg
+            ? rest.slice(1)
+            : rest;
+        if (!isWord(fromWord, "from"))
+            return refuse(fromWord);
+        const from = readPoint(fromArg);
+        if (!from)
+            return refuse(fromArg);
+        if (!isWord(toWord, "to"))
+            return refuse(toWord);
+        const to = readPoint(toArg);
+        if (!to)
+            return refuse(toArg);
+        const via = [];
+        if (viaWord) {
+            if (!isWord(viaWord, "via") || viaList?.kind !== "List")
+                return refuse(viaList ?? viaWord);
+            for (const item of viaList.items) {
+                const point = readPoint(item);
+                if (!point)
+                    return refuse(item);
+                via.push(point);
+            }
+            if (extra)
+                return refuse(extra);
+        }
+        const { values: _values, ...blockFields } = this.elementBlock(stmt.block, this.profile.elementProperties, "Element", idToken);
+        this.addElement({
+            id: idToken.text,
+            kind: "line",
+            label: labelArg?.kind === "StringLiteral" ? labelArg.value : "",
+            implicit: false,
+            ...blockFields,
+            source: null,
+            sourceRange: null,
+            labelWritten: labelArg !== undefined,
+            entity: null,
+            technology: null,
+            external: false,
+            shape: null,
+            line: { from, to, via },
+            pen: null,
+            list: null,
+            attachedTo: null,
+            attachedToRange: null,
+            typeKind: null,
+            data: {},
+            groupPath,
+            range: this.range(stmt),
+            idRange: this.range(idToken),
+            idToken,
+            node: stmt,
+        });
+    }
+    /**
+     * `pen <id> [(x, y), (x, y), ...] [{ ... }]`: a freehand stroke through its points, in the
+     * interior coordinates of its innermost group as a line's are. One point is a dot; decimals are
+     * kept. A pen has no label.
+     */
+    declarePen(stmt, groupPath) {
+        const form = "`pen <id> [(x, y), (x, y), ...]`";
+        const m = messages();
+        const [idArg, list, extra] = stmt.args;
+        const idToken = singleIdent(idArg);
+        if (!idToken) {
+            this.invalid(m.diagnostics.common.expected(form), idArg ?? stmt.keyword, [
+                m.hints.example("pen arrow [(40, 60), (90.5, 58), (140, 70)]"),
+            ]);
+            return;
+        }
+        const hints = [m.hints.flow.form(form)];
+        if (list?.kind === "StringLiteral") {
+            return this.invalid(m.diagnostics.flow.penNoLabel(idToken.text), list, hints);
+        }
+        if (list?.kind !== "List" || list.items.length === 0) {
+            return this.invalid(m.diagnostics.flow.penPoints, list ?? stmt, hints);
+        }
+        const points = [];
+        for (const item of list.items) {
+            const point = readPoint(item);
+            if (!point)
+                return this.invalid(m.diagnostics.flow.penPoints, item, hints);
+            points.push(point);
+        }
+        if (extra)
+            return this.invalid(m.diagnostics.flow.unexpectedValue(form), extra, hints);
+        // A stroke has no sides for ports: `port` in its block is unknown, as in any block without it.
+        const { values: _values, ...blockFields } = this.elementBlock(stmt.block, this.profile.elementProperties, "Element", idToken, false);
+        this.addElement({
+            id: idToken.text,
+            kind: "pen",
+            label: "",
+            implicit: false,
+            ...blockFields,
+            source: null,
+            sourceRange: null,
+            labelWritten: false,
+            entity: null,
+            technology: null,
+            external: false,
+            shape: null,
+            line: null,
+            pen: { points },
+            list: null,
+            attachedTo: null,
+            attachedToRange: null,
+            typeKind: null,
+            data: {},
+            groupPath,
+            range: this.range(stmt),
+            idRange: this.range(idToken),
+            idToken,
+            node: stmt,
+        });
+    }
+    /**
+     * `sticky <id> "Text" [{ ... }]`: a square card whose text wraps to fit it. The text is required,
+     * `\n` breaking its lines; the block takes a box's: `description`, `class`, `layer`, `link`, `url`
+     * and ports. A sticky without its text is still declared, so that its uses resolve.
+     */
+    declareSticky(stmt, groupPath) {
+        const form = '`sticky <id> "Text"`';
+        const m = messages();
+        const [idArg, textArg, extra] = stmt.args;
+        const idToken = singleIdent(idArg);
+        if (!idToken) {
+            this.invalid(m.diagnostics.common.expected(form), idArg ?? stmt.keyword, [
+                m.hints.example('sticky idea "Cache the catalogue"'),
+            ]);
+            return;
+        }
+        if (textArg && textArg.kind !== "StringLiteral") {
+            return this.invalid(m.diagnostics.flow.quotedSource("text", idToken.text), textArg);
+        }
+        if (extra)
+            return this.invalid(m.diagnostics.flow.valueAfter("text", form), extra);
+        if (!textArg) {
+            this.invalid(m.diagnostics.flow.needsSource("sticky", idToken.text, form), stmt, [
+                m.hints.flow.form(form),
+            ]);
+        }
+        const { values: _values, ...blockFields } = this.elementBlock(stmt.block, this.profile.elementProperties, "Element", idToken);
+        this.addElement({
+            id: idToken.text,
+            kind: "sticky",
+            label: textArg ? textArg.value : idToken.text,
+            implicit: false,
+            ...blockFields,
+            source: null,
+            sourceRange: null,
+            labelWritten: textArg !== undefined,
+            entity: null,
+            technology: null,
+            external: false,
+            shape: null,
+            line: null,
+            pen: null,
+            list: null,
+            attachedTo: null,
+            attachedToRange: null,
+            typeKind: null,
+            data: {},
+            groupPath,
+            range: this.range(stmt),
+            idRange: this.range(idToken),
+            idToken,
+            node: stmt,
+        });
+    }
+    /** Whether a note must write its text: free compositions and views, where a note is no node. */
+    get notesNeedText() {
+        return this.free;
+    }
+    /**
+     * The target of a note's `on <element>`: `extra` holds the word `on` and one identifier (C4
+     * views read an entity path), nothing else. Undefined when it does not; a lone `on` is reported
+     * here, as the form is wanted.
+     */
+    attachmentOf(extra, form) {
+        if (!isWord(extra[0], "on"))
+            return undefined;
+        const arg = extra[1];
+        const token = singleIdent(arg);
+        if (!token || extra.length > 2) {
+            this.invalid(messages().diagnostics.common.expected(form), extra[1] ?? extra[0]);
+            return undefined;
+        }
+        return { arg: arg, target: token.text };
+    }
+    /**
+     * Resolves the targets of the notes' `on <element>`: an element of the diagram other than the
+     * note itself, of any kind. Renames follow the reference this records.
+     */
+    resolveAttachments() {
+        const m = messages();
+        for (const { note, arg, target, stmt } of this.attachments) {
+            const token = singleIdent(arg);
+            if (target === note) {
+                this.invalid(m.diagnostics.flow.attachSelf(note), token);
+            }
+            else if (this.elementsById.has(target)) {
+                this.reference(token, target, "element", "attachment", stmt);
+            }
+            else {
+                this.error("ref.unknown-element", m.diagnostics.common.unknownElement(target), token, {
+                    hints: [m.hints.flow.attachTarget(note)],
+                    data: {
+                        ids: [target],
+                        candidates: this.elements
+                            .filter((e) => e.id !== note && e.kind !== "line" && e.kind !== "pen")
+                            .map((e) => e.id),
+                    },
+                });
+            }
+        }
+    }
     addElement(element) {
         const existing = this.elementsById.get(element.id);
         if (existing) {
@@ -555,21 +880,36 @@ export class FlowAnalyzer {
         return true;
     }
     /**
-     * Reads an element or relation block: its description, applied classes, named ports, and the
-     * `layer` and `link` statements the profile accepts.
+     * Reads an element or relation block: its description, applied classes, named ports, the
+     * `layer` and `link` statements the profile accepts, and its `tag` statements where the table
+     * takes them (sequence messages and participants).
      */
-    elementBlock(block, table, owner, ownerToken) {
+    elementBlock(block, table, owner, ownerToken, 
+    /** False for an element without ports (a pen): `port` is then unknown in its block. */
+    takesPorts = true) {
         const empty = { layer: null, layerRange: null, link: null };
         if (!block)
-            return { description: null, url: null, classes: [], ports: [], values: {}, ...empty };
+            return {
+                description: null,
+                url: null,
+                classes: [],
+                ports: [],
+                tags: [],
+                values: {},
+                ...empty,
+            };
         const ports = [];
+        const tags = [];
         const extras = { ...empty };
         const seen = new Map();
+        const portable = owner === "Element" && takesPorts && this.profile.ports.length > 0;
+        // Tags repeat, each an annotation of the owner: read apart, never a `prop.duplicate` keyword.
+        const tagged = table.tag?.kind === "tag";
         const rest = block.statements.filter((stmt) => {
             if (stmt.kind !== "KeywordStatement")
                 return true;
             const keyword = stmt.keyword.text;
-            if (owner === "Element" && keyword === "port" && this.profile.ports.length > 0) {
+            if (portable && keyword === "port") {
                 if (!headerHasError(stmt))
                     this.port(stmt, ports);
                 return false;
@@ -579,22 +919,69 @@ export class FlowAnalyzer {
                     this.extra(stmt, extras, seen, ownerToken);
                 return false;
             }
+            if (tagged && keyword === "tag") {
+                if (!headerHasError(stmt))
+                    this.tag(stmt, tags);
+                return false;
+            }
             return true;
         });
-        const words = Object.keys(table).concat(owner === "Element" && this.profile.ports.length > 0 ? ["port"] : []);
-        const { values, classes } = this.readProperties({ ...block, statements: rest }, table, () => {
-            const m = messages().hints.flow;
-            return owner === "Element" ? m.elementBlock(words) : m.relationBlock(words);
-        }, owner.toLowerCase(), words);
+        const words = Object.keys(table).concat(portable ? ["port"] : []);
+        const { values, classes } = this.readProperties({ ...block, statements: rest }, table, () => this.blockHint(owner, words), owner.toLowerCase(), words);
         return {
             description: typeof values.description === "string" ? values.description : null,
             url: typeof values.url === "string" ? values.url : null,
             classes,
             ports,
+            tags,
             values,
             ...extras,
         };
     }
+    /** The hint of an unknown statement in an element or relation block, in the interface words. */
+    blockHint(owner, words) {
+        const m = messages().hints.flow;
+        return owner === "Element" ? m.elementBlock(words) : m.relationBlock(words);
+    }
+    /**
+     * Reads `tag "Text"` into the tags of a block: one line of text, not empty, and not a text the
+     * owner already has.
+     */
+    tag(stmt, tags) {
+        const m = messages();
+        const form = [m.hints.example('tag "PKCE"')];
+        if (stmt.block || stmt.chain) {
+            this.invalid(m.diagnostics.common.expected(TAG_FORM), stmt.block ?? stmt.chain, form);
+            return;
+        }
+        const [arg, extra] = stmt.args;
+        // The first value that breaks the form: an id before the text, a number, a second string.
+        const wrong = !arg ? stmt.keyword : arg.kind !== "StringLiteral" ? arg : extra;
+        if (!arg || wrong) {
+            this.invalid(m.diagnostics.common.expected(TAG_FORM), wrong ?? stmt.keyword, form);
+            return;
+        }
+        const checked = checkArg(arg, { kind: "tag" }, "tag");
+        if (!checked.ok || typeof checked.value !== "string") {
+            if (!checked.ok)
+                this.invalid(checked.message, arg, checked.hints);
+            return;
+        }
+        const text = checked.value;
+        const first = tags.find((t) => t.text === text);
+        if (first) {
+            this.error("prop.duplicate", m.diagnostics.sequence.tagRepeated(text), arg, {
+                related: [
+                    {
+                        message: m.related.firstWritten,
+                        at: { start: first.textRange.start.offset, end: first.textRange.end.offset },
+                    },
+                ],
+            });
+            return;
+        }
+        tags.push({ text, range: this.range(stmt), textRange: this.range(arg) });
+    }
     /** Reads `layer <name>` or `link <diagram>.<element>` into the extras of a block. */
     extra(stmt, extras, seen, ownerToken) {
         const keyword = stmt.keyword.text;
@@ -693,8 +1080,8 @@ export class FlowAnalyzer {
         });
     }
     /**
-     * Reads the `description`, `class`, `layer` and `link` properties of a group block; children are
-     * classified.
+     * Reads the `description`, `class`, `layer` and `link` properties of a group block, and in free
+     * diagrams the `layout`, `spacing` and `align` of a list; children are classified.
      */
     groupBlock(block, ownerToken) {
         let description = null;
@@ -702,8 +1089,9 @@ export class FlowAnalyzer {
         let classes = [];
         const extras = { layer: null, layerRange: null, link: null };
         if (!block)
-            return { description, url, classes, ...extras };
+            return { description, url, classes, list: null, ...extras };
         const seen = new Map();
+        const listed = {};
         for (const stmt of block.statements) {
             if (stmt.kind !== "KeywordStatement" || headerHasError(stmt))
                 continue;
@@ -712,8 +1100,14 @@ export class FlowAnalyzer {
                 this.extra(stmt, extras, seen, ownerToken);
                 continue;
             }
-            if (name !== "description" && name !== "url" && !(name === "class" && !stmt.block))
+            // Other profiles refuse the list properties when the block is classified.
+            const listProperty = isListProperty(name) && name in this.profile.groupProperties;
+            if (!listProperty &&
+                name !== "description" &&
+                name !== "url" &&
+                !(name === "class" && !stmt.block)) {
                 continue;
+            }
             const first = seen.get(name);
             if (first) {
                 const m = messages();
@@ -723,6 +1117,18 @@ export class FlowAnalyzer {
                 continue;
             }
             seen.set(name, stmt.keyword);
+            if (listProperty) {
+                const value = this.listValue(stmt, name);
+                if (value === undefined)
+                    continue;
+                if (name === "layout")
+                    listed.layout = value;
+                else if (name === "spacing")
+                    listed.spacing = value;
+                else
+                    listed.align = value;
+                continue;
+            }
             if (name === "class") {
                 classes = readClasses(stmt, this.lines, this.report) ?? [];
                 continue;
@@ -737,7 +1143,45 @@ export class FlowAnalyzer {
             if (typeof value === "string")
                 description = value;
         }
-        return { description, url, classes, ...extras };
+        return { description, url, classes, list: this.listOf(listed, seen), ...extras };
+    }
+    /**
+     * Reads `layout column|row`, `spacing <n>` or `align start|center|end|stretch` of a free group
+     * block. `layout auto`, `assisted` and `manual` are the diagram's statement, which the hint says.
+     */
+    listValue(stmt, name) {
+        const [arg] = stmt.args;
+        const word = singleIdent(arg);
+        if (name === "layout" &&
+            word &&
+            stmt.args.length === 1 &&
+            !stmt.block &&
+            !stmt.chain &&
+            LAYOUT_MODES.includes(word.text)) {
+            const m = messages();
+            this.invalid(m.diagnostics.values.invalidEnum(describeArg(arg), name, LIST_LAYOUTS), arg, [
+                m.hints.flow.groupLayout(word.text),
+            ]);
+            return undefined;
+        }
+        return this.readValue(stmt, this.profile.groupProperties[name], name);
+    }
+    /**
+     * The list a group block writes, or null without a valid `layout`. `spacing` and `align` without
+     * a `layout` are reported on their keywords.
+     */
+    listOf(listed, seen) {
+        if (!seen.has("layout")) {
+            const m = messages();
+            for (const name of ["spacing", "align"]) {
+                const token = seen.get(name);
+                if (token)
+                    this.invalid(m.diagnostics.flow.listNeedsLayout(name), token, [m.hints.flow.listLayout]);
+            }
+        }
+        if (listed.layout === undefined)
+            return null;
+        return { layout: listed.layout, spacing: listed.spacing ?? null, align: listed.align ?? null };
     }
     // ------------------------------------------------------------------ relations
     relation(stmt, groupPath) {
@@ -775,15 +1219,17 @@ export class FlowAnalyzer {
         if (this.profile.arrows[stmt.arrow.text] === undefined) {
             this.invalid(messages().diagnostics.flow.arrowUnavailable(stmt.arrow.text, Object.keys(this.profile.arrows)), stmt.arrow);
         }
-        const { description, classes, layer, layerRange, values } = this.elementBlock(stmt.block, this.profile.relationProperties, "Relation", undefined);
+        const { description, classes, tags, layer, layerRange, values } = this.elementBlock(stmt.block, this.profile.relationProperties, "Relation", undefined);
         const relation = {
             key: "",
             id,
             from,
             to,
             line: this.profile.arrows[stmt.arrow.text] ?? "solid",
-            twoWay: stmt.arrow.text.startsWith("<"),
+            heads: RELATION_ARROWS[stmt.arrow.text]?.heads ?? "end",
+            twoWay: RELATION_ARROWS[stmt.arrow.text]?.heads === "both",
             async: values.kind === "async",
+            returns: null,
             technology: null,
             sources: [],
             derived: false,
@@ -792,6 +1238,7 @@ export class FlowAnalyzer {
             assumption: typeof values.assumption === "string" ? values.assumption : null,
             data: this.declared ? dataOf(values, this.declared.relations.properties) : {},
             classes,
+            tags,
             layer,
             layerRange,
             groupPath,
@@ -830,6 +1277,7 @@ export class FlowAnalyzer {
             description: null,
             url: null,
             classes: [],
+            tags: [],
             ports: [],
             layer: null,
             layerRange: null,
@@ -841,6 +1289,11 @@ export class FlowAnalyzer {
             technology: null,
             external: false,
             shape: null,
+            line: null,
+            pen: null,
+            list: null,
+            attachedTo: null,
+            attachedToRange: null,
             typeKind: null,
             data: {},
             groupPath,
@@ -922,6 +1375,9 @@ export class FlowAnalyzer {
             case "autonumber":
                 this.properties.autonumber = Number(value);
                 break;
+            case "spacing":
+                this.properties.spacing = Number(value);
+                break;
         }
     }
     /** Reads `layers a, b, c`: back to front, `main` last unless listed. */
@@ -1048,8 +1504,9 @@ export class FlowAnalyzer {
         }
         return true;
     }
-    duplicatePlacement(stmt, target) {
-        const key = `${stmt.keyword.text}:${target}`;
+    /** Whether a placement of the same kind already names the target (on the same side, if any). */
+    duplicatePlacement(stmt, target, side = "") {
+        const key = `${stmt.keyword.text}:${target}${side === "" ? "" : `:${side}`}`;
         const first = this.placementSeen.get(key);
         if (first) {
             const m = messages();
@@ -1075,7 +1532,9 @@ export class FlowAnalyzer {
         if (extra)
             return this.shapeError(stmt, form, extra);
         const element = this.resolveElement(targetToken, "place", stmt);
-        if (!element || this.duplicatePlacement(stmt, element))
+        if (!element || this.lineRefused(element, "place", targetToken))
+            return;
+        if (this.duplicatePlacement(stmt, element))
             return;
         this.placement.push({
             statement: "place",
@@ -1102,7 +1561,9 @@ export class FlowAnalyzer {
         if (extra)
             return this.shapeError(stmt, form, extra);
         const element = this.resolveElement(targetToken, "size", stmt);
-        if (!element || this.duplicatePlacement(stmt, element))
+        if (!element || this.lineRefused(element, "size", targetToken))
+            return;
+        if (this.duplicatePlacement(stmt, element))
             return;
         this.placement.push({
             statement: "size",
@@ -1340,12 +1801,17 @@ export class FlowAnalyzer {
             if (extra)
                 return this.shapeError(stmt, form, extra);
         }
-        const relation = this.resolveRelation(targetToken, "label", stmt);
-        if (!relation || this.duplicatePlacement(stmt, relation.key))
+        // A free line's label pill moves as a relation's does.
+        const line = this.elementsById.get(targetToken.text);
+        if (line?.kind === "line")
+            this.reference(targetToken, line.id, "element", "label", stmt);
+        const relation = line?.kind === "line" ? undefined : this.resolveRelation(targetToken, "label", stmt);
+        const labelled = line?.kind === "line" ? line.id : relation?.key;
+        if (labelled === undefined || this.duplicatePlacement(stmt, labelled))
             return;
         this.placement.push({
             statement: "label",
-            target: relation.key,
+            target: labelled,
             at: at.value,
             offset: point,
             range: this.range(stmt),
@@ -1353,6 +1819,27 @@ export class FlowAnalyzer {
             node: stmt,
         });
     }
+    /**
+     * A free line or a pen takes no `place` or `size` (and a pen no `rotation`): its points are in its
+     * statement. Reports it.
+     */
+    lineRefused(id, statement, token) {
+        const kind = this.elementsById.get(id)?.kind;
+        if (kind !== "line" && kind !== "pen")
+            return false;
+        const m = messages();
+        if (kind === "pen") {
+            this.invalid(m.diagnostics.flow.penHasPoints(id, statement), token, [
+                m.hints.flow.penPointsWritten,
+            ]);
+        }
+        else {
+            this.invalid(m.diagnostics.flow.lineHasPoints(id, statement), token, [
+                m.hints.flow.linePointsWritten,
+            ]);
+        }
+        return true;
+    }
     resolveElement(token, statement, stmt) {
         const name = token.text;
         if (this.elementsById.has(name)) {
@@ -1410,7 +1897,7 @@ export class FlowAnalyzer {
         const table = kind === "style" ? this.profile.styleProperties : this.profile.animateProperties;
         const shapes = profileTakesShape(this.profile);
         const words = kind === "style"
-            ? Object.keys(table).filter((p) => p === "shape" ? shapes : this.free || !(p in FREE_PROFILE_ONLY))
+            ? Object.keys(table).filter((p) => p === "shape" ? shapes : this.free || !isFreeStyleProperty(p))
             : ["effect", "duration", "repeat"];
         const hint = () => {
             const m = messages().hints.flow;
@@ -1438,18 +1925,57 @@ export class FlowAnalyzer {
             const resolved = this.resolveStyleTarget(targetToken, kind, stmt);
             if (!resolved)
                 continue;
-            const misfit = kind === "style"
-                ? resolved.kind === "relation"
+            const element = resolved.kind === "element" ? this.elementsById.get(resolved.name) : undefined;
+            // A free line takes a relation's properties, and none of a box's but `opacity`; a pen takes
+            // its stroke's (`PEN_PROPERTIES`) and refuses the rest; a sticky takes a card's
+            // (`STICKY_PROPERTIES`).
+            const line = element?.kind === "line";
+            const pen = element?.kind === "pen";
+            const sticky = element?.kind === "sticky";
+            // Icons and images draw no text: the text properties do not apply to them.
+            const textless = element !== undefined && TEXTLESS_KINDS.includes(element.kind);
+            const misfit = kind !== "style"
+                ? []
+                : resolved.kind === "relation"
                     ? ELEMENT_ONLY_PROPERTIES
-                    : RELATION_ONLY_PROPERTIES
-                : [];
+                    : line
+                        ? LINE_REFUSED_PROPERTIES
+                        : pen
+                            ? [...PEN_REFUSED_PROPERTIES, "rotation"]
+                            : sticky
+                                ? STICKY_REFUSED_PROPERTIES
+                                : textless
+                                    ? [...RELATION_ONLY_PROPERTIES, ...TEXT_PROPERTIES]
+                                    : RELATION_ONLY_PROPERTIES;
             for (const name of misfit) {
                 const token = tokens[name];
-                // `shape` is reported below, with the kinds that take it.
-                if (!token || name === "shape" || misplaced.has(name))
+                // `shape` is reported below, with the kinds that take it; a pen names what it takes.
+                if (!token || (name === "shape" && !pen) || misplaced.has(name))
                     continue;
                 misplaced.add(name);
-                this.invalid(messages().diagnostics.flow.notForTargets(name, resolved.kind === "relation", resolved.name), token, [targetHint(name)]);
+                if (pen && name === "rotation") {
+                    this.lineRefused(resolved.name, "rotation", token);
+                    continue;
+                }
+                const m = messages();
+                this.invalid(pen
+                    ? m.diagnostics.flow.notForPens(name, resolved.name, PEN_PROPERTIES)
+                    : line
+                        ? m.diagnostics.flow.notForLines(name, resolved.name)
+                        : sticky
+                            ? m.diagnostics.flow.notForStickies(name, resolved.name)
+                            : m.diagnostics.flow.notForTargets(name, resolved.kind === "relation", resolved.name), token, line || pen
+                    ? []
+                    : sticky
+                        ? [m.hints.values.stickyProperties(STICKY_PROPERTIES)]
+                        : [targetHint(name)]);
+            }
+            // A pen is drawn one pixel wide at least: `width 0` is refused on it, not on a box.
+            const thin = kind === "style" && pen && values.width === 0;
+            if (thin && !misplaced.has("width")) {
+                misplaced.add("width");
+                const m = messages();
+                this.invalid(m.diagnostics.values.expects("width", describeSpec({ kind: "number", ...PEN_WIDTH_RANGE })), argumentOf(stmt.block, tokens.width) ?? tokens.width, [m.hints.values.penWidth]);
             }
             // `shape` is refused per target: a block may list a node and a decision.
             const shapeless = kind === "style" && tokens.shape ? this.shapeRefusal(resolved) : null;
@@ -1468,12 +1994,13 @@ export class FlowAnalyzer {
             const refused = [
                 ...(shapeless === null ? [] : ["shape"]),
                 ...(unturned === null ? [] : ["rotation"]),
+                ...(thin ? ["width"] : []),
             ];
             const excluded = refused.length === 0 ? misfit : [...misfit, ...refused];
             if (kind === "animate") {
                 // One effect per channel and target; different channels may share a target.
                 const effect = values.effect;
-                if (effect && !this.animationTargetFits(effect, resolved, targetToken))
+                if (effect && !this.animationTargetFits(effect, resolved, targetToken, stmt))
                     continue;
                 if (effect) {
                     const key = `${resolved.name}:${effect}`;
@@ -1597,19 +2124,29 @@ export class FlowAnalyzer {
         return { profile: false, kind: element.kind };
     }
     /** Whether an effect can run on a target; reports `animate.invalid-target` when not. */
-    animationTargetFits(effect, resolved, token) {
+    animationTargetFits(effect, resolved, token, stmt) {
         const element = resolved.kind === "element" ? this.elementsById.get(resolved.name) : undefined;
         const m = messages().diagnostics.flow;
         let reason = null;
-        if (effect === "flow" && resolved.kind !== "relation") {
+        // A free line or a pen runs effects as a relation does: it is a connector without ends, and its
+        // stroke is the outline a dash follows.
+        const connector = resolved.kind === "relation" || element?.kind === "line" || element?.kind === "pen";
+        if (effect === "flow" && !connector) {
             reason = m.flowTarget;
         }
-        else if (effect === "trace" && resolved.kind !== "relation") {
+        else if (effect === "trace" && !connector) {
             reason = m.traceTarget;
         }
         else if (effect === "dash") {
             if (resolved.kind === "event")
                 reason = m.dashOnEvent;
+            else if (element &&
+                (element.kind === "note" || element.kind === "text" || element.kind === "sticky")) {
+                // A note, a text or a sticky draws an outline when its styles say so, which a later
+                // statement may write: checked once every block is read (`checkOutlinedDashes`).
+                if (stmt)
+                    this.pendingDashes.push({ name: resolved.name, token, stmt });
+            }
             else if (element && NO_OUTLINE_KINDS.has(element.kind)) {
                 reason = m.dashWithoutOutline(resolved.name, element.kind);
             }
@@ -1646,9 +2183,22 @@ export class FlowAnalyzer {
     }
 }
 // -------------------------------------------------------------------- free helpers
-/** The declarations and statements of flow and free diagrams, as their hints list them. */
+/**
+ * The declarations and statements of flow and free diagrams, as their hints list them: the hints
+ * of free diagrams are built from `FREE_DECLARATIONS`, so a new kind is one word here.
+ */
 const FLOW_DECLARATIONS = ["node", "decision", "data", "group", "note", "tag"];
-const FREE_DECLARATIONS = ["box", "text", "icon", "image", "group"];
+const FREE_DECLARATIONS = [
+    "box",
+    "text",
+    "icon",
+    "image",
+    "note",
+    "sticky",
+    "line",
+    "pen",
+    "group",
+];
 const FLOW_STATEMENTS = [
     "direction",
     "layout",
@@ -1670,15 +2220,13 @@ const FREE_STATEMENTS = [
     "layers",
     ...FLOW_STATEMENTS.slice(8),
 ];
-/** Style properties that only free diagrams accept, for hints. */
-const FREE_PROFILE_ONLY = {
-    fontSize: true,
-    fontWeight: true,
-    textAlign: true,
-};
 function isWord(arg, word) {
     return singleIdent(arg)?.text === word;
 }
+/** Whether a statement of a group block is one of the properties of a list. */
+function isListProperty(keyword) {
+    return LIST_PROPERTIES.includes(keyword);
+}
 /** A tuple of exactly two numbers without units. */
 export function readPoint(arg) {
     if (arg?.kind !== "Tuple" || arg.items.length !== 2)