@meltemi/diagrams-model 1.10.0 → 1.10.18

package/dist/flow.js

@@ -1,8 +1,8 @@
 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_ARROWS, 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([
@@ -153,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. */
@@ -264,7 +265,8 @@ export class FlowAnalyzer {
     }
     /**
      * 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, and the dash is refused and dropped.
+     * 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 = {
@@ -276,7 +278,13 @@ export class FlowAnalyzer {
             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: [messages().hints.flow.dashOutline] });
+            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);
@@ -363,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 },
@@ -392,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);
@@ -402,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. */
@@ -427,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) {
@@ -449,6 +480,8 @@ export class FlowAnalyzer {
                 external: false,
                 shape: data ? "cylinder" : null,
                 line: null,
+                pen: null,
+                list: null,
                 attachedTo: null,
                 attachedToRange: null,
                 typeKind: null,
@@ -485,6 +518,10 @@ export class FlowAnalyzer {
         }
         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) {
@@ -546,11 +583,14 @@ export class FlowAnalyzer {
             }
         }
         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,
@@ -565,6 +605,8 @@ export class FlowAnalyzer {
             external: false,
             shape: null,
             line: null,
+            pen: null,
+            list,
             attachedTo: attachment?.target ?? null,
             attachedToRange: attachment ? this.range(attachment.arg) : null,
             typeKind,
@@ -643,6 +685,123 @@ export class FlowAnalyzer {
             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,
@@ -694,7 +853,7 @@ export class FlowAnalyzer {
                     data: {
                         ids: [target],
                         candidates: this.elements
-                            .filter((e) => e.id !== note && e.kind !== "line")
+                            .filter((e) => e.id !== note && e.kind !== "line" && e.kind !== "pen")
                             .map((e) => e.id),
                     },
                 });
@@ -721,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;
@@ -745,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;
@@ -859,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;
@@ -868,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;
@@ -878,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();
@@ -889,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;
@@ -903,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) {
@@ -941,7 +1219,7 @@ 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,
@@ -951,6 +1229,7 @@ export class FlowAnalyzer {
             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,
@@ -959,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,
@@ -997,6 +1277,7 @@ export class FlowAnalyzer {
             description: null,
             url: null,
             classes: [],
+            tags: [],
             ports: [],
             layer: null,
             layerRange: null,
@@ -1009,6 +1290,8 @@ export class FlowAnalyzer {
             external: false,
             shape: null,
             line: null,
+            pen: null,
+            list: null,
             attachedTo: null,
             attachedToRange: null,
             typeKind: null,
@@ -1092,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. */
@@ -1218,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();
@@ -1532,14 +1819,25 @@ export class FlowAnalyzer {
             node: stmt,
         });
     }
-    /** A free line takes no `place` or `size`: its points are in its statement. Reports it. */
+    /**
+     * 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) {
-        if (this.elementsById.get(id)?.kind !== "line")
+        const kind = this.elementsById.get(id)?.kind;
+        if (kind !== "line" && kind !== "pen")
             return false;
         const m = messages();
-        this.invalid(m.diagnostics.flow.lineHasPoints(id, statement), token, [
-            m.hints.flow.linePointsWritten,
-        ]);
+        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) {
@@ -1599,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;
@@ -1627,22 +1925,57 @@ export class FlowAnalyzer {
             const resolved = this.resolveStyleTarget(targetToken, kind, stmt);
             if (!resolved)
                 continue;
-            // A free line takes a relation's properties, and none of a box's.
-            const line = resolved.kind === "element" && this.elementsById.get(resolved.name)?.kind === "line";
-            const misfit = kind === "style"
-                ? resolved.kind === "relation" || line
+            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(line
-                    ? messages().diagnostics.flow.notForLines(name, resolved.name)
-                    : messages().diagnostics.flow.notForTargets(name, resolved.kind === "relation", resolved.name), token, line ? [] : [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;
@@ -1661,6 +1994,7 @@ export class FlowAnalyzer {
             const refused = [
                 ...(shapeless === null ? [] : ["shape"]),
                 ...(unturned === null ? [] : ["rotation"]),
+                ...(thin ? ["width"] : []),
             ];
             const excluded = refused.length === 0 ? misfit : [...misfit, ...refused];
             if (kind === "animate") {
@@ -1794,8 +2128,9 @@ export class FlowAnalyzer {
         const element = resolved.kind === "element" ? this.elementsById.get(resolved.name) : undefined;
         const m = messages().diagnostics.flow;
         let reason = null;
-        // A free line runs effects as a relation does: it is a connector without ends.
-        const connector = resolved.kind === "relation" || element?.kind === "line";
+        // 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;
         }
@@ -1805,9 +2140,10 @@ export class FlowAnalyzer {
         else if (effect === "dash") {
             if (resolved.kind === "event")
                 reason = m.dashOnEvent;
-            else if (element && (element.kind === "note" || element.kind === "text")) {
-                // A note or a text draws an outline when its styles say so, which a later statement may
-                // write: checked once every block is read (`checkOutlinedDashes`).
+            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 });
             }
@@ -1847,7 +2183,10 @@ 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",
@@ -1855,7 +2194,9 @@ const FREE_DECLARATIONS = [
     "icon",
     "image",
     "note",
+    "sticky",
     "line",
+    "pen",
     "group",
 ];
 const FLOW_STATEMENTS = [
@@ -1879,16 +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,
-    verticalAlign: 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)