@meltemi/diagrams-editor 1.9.0 → 1.10.17

package/dist/canvas/protocol.d.ts

@@ -2,7 +2,7 @@ import type { StoryTimeline, StoryViewData } from "@meltemi/diagrams-motion";
 import type { AlignEdge } from "./arrange.js";
 import type { Box, Point } from "./geometry.js";
 import type { Side } from "./routes.js";
-export type ElementKind = "node" | "decision" | "data" | "group" | "note" | "tag" | "box" | "text" | "icon" | "image" | "participant" | "actor" | "boundary" | "control" | "entity" | "database" | "collections" | "queue" | "person" | "system" | "container" | "datastore" | "component";
+export type ElementKind = "node" | "decision" | "data" | "group" | "note" | "tag" | "box" | "text" | "icon" | "image" | "line" | "pen" | "sticky" | "participant" | "actor" | "boundary" | "control" | "entity" | "database" | "collections" | "queue" | "person" | "system" | "container" | "datastore" | "component";
 /** The profile of a diagram, which sets the palette, the keys and the drags. */
 export type CanvasProfile = "flow" | "free" | "sequence" | "c4";
 export type FragmentOperator = "alt" | "opt" | "loop" | "par" | "break" | "critical" | "region";
@@ -52,6 +52,12 @@ export interface TextPlace {
     /** The CSS font stack. */
     readonly font: string;
     readonly size: number;
+    /**
+     * A sticky note's: the size its words are drawn at before they shrink to fit the card (its
+     * `fontSize`, or 1.2 times the theme's label size), which `size` is when they fit. The editor
+     * types from it, so a long text shortened is typed at the size the card will draw it.
+     */
+    readonly fullSize?: number;
     readonly weight: number;
     readonly color: string;
     /** The distance between two lines. */
@@ -63,6 +69,32 @@ export interface TextPlace {
      * is typed, as it does not cross the drawn label. Absent for the others: they have none.
      */
     readonly background?: string;
+    /**
+     * How the drawing wraps the text in `area`, for an editor that wraps as it does; absent when the
+     * drawing does not wrap it. `shrink`: a sticky's text, wrapped at the area's width and shrunk to
+     * fit the card (from `fullSize`). `grow`: the label of a sequence message whose participants are
+     * pulled closer than their natural distance (`MessageText.wraps`), wrapped at the area's width
+     * (the room between its lifelines) at `size`, never shrunk; the block keeps its top (`area.y`,
+     * the top of the first line) and grows down by `line` with each line, as the row grows. A
+     * message at its natural distance (its label pushes the pair apart) and a self-call have none.
+     */
+    readonly wrap?: "shrink" | "grow";
+}
+/**
+ * A tag of a sequence participant or message (`tag "Text"` in its block), as drawn: a pill of the
+ * owner, which a press selects and a drag drags with it.
+ */
+export interface TagInfo {
+    /** The text written in the tag. */
+    readonly text: string;
+    /** The pill, in diagram coordinates. */
+    readonly box: Box;
+    /**
+     * Where the pill's text is drawn, for the inline editor of the tag: its mono font, size, weight
+     * and colour, centred on the pill, the pill's fill as its background. Absent when the drawing
+     * holds no such pill.
+     */
+    readonly place?: TextPlace;
 }
 /** What the canvas knows about an element. */
 export interface ElementInfo {
@@ -119,6 +151,46 @@ export interface ElementInfo {
      * it connects to the element, whose connector ends on the square).
      */
     readonly labelBox?: Box;
+    /**
+     * A free `line`: its points in diagram coordinates (`from`, its bends, `to`), the polyline it
+     * is drawn with (rounded corners, a curve's samples, heads cut out), and its bends alone. Its
+     * `box` is the bounding box of its points; it has no frame, resize, rotation or connection
+     * handles, but a handle at each point and at the middle of each stretch.
+     */
+    readonly line?: {
+        readonly points: readonly Point[];
+        readonly drawn: readonly Point[];
+        readonly via: readonly Point[];
+    };
+    /**
+     * A `pen` stroke: its points where they are drawn, in diagram coordinates (its written points
+     * moved by its group's interior origin), the box of the points grown by half its width (its
+     * `box` too, which its frame and its resize handles use), and its drawn width. It has no
+     * rotation, connection, point or label handles; moving or scaling it writes every point
+     * (`setPenPoints`).
+     */
+    readonly pen?: {
+        readonly points: readonly Point[];
+        readonly bounds: Box;
+        readonly width: number;
+    };
+    /**
+     * A group of a free diagram that arranges its children (`layout column` or `layout row`): its
+     * layout, its spacing and its alignment as the layout applies them (defaults filled in), and the
+     * children it places in source order, its lines and pens left out. A `move` or a `create` with
+     * an `index` counts among these children.
+     */
+    readonly list?: {
+        readonly layout: "column" | "row";
+        readonly spacing: number;
+        readonly align: "start" | "center" | "end" | "stretch";
+        readonly children: readonly string[];
+    };
+    /**
+     * Sequence diagrams: the tags of a participant, in source order, each with its badge as drawn
+     * over the head; absent when it has none.
+     */
+    readonly tags?: readonly TagInfo[];
 }
 /** What the canvas knows about a relation. */
 export interface RelationInfo {
@@ -141,6 +213,20 @@ export interface RelationInfo {
     readonly layer: string | null;
     /** Where its label is drawn, or goes: the middle of its line when it has none. */
     readonly text?: TextPlace;
+    /** Sequence diagrams: the key of the call a `return` answers; absent on other messages. */
+    readonly returns?: string;
+    /**
+     * Sequence diagrams: the tags of a message, in source order, each with its pill as drawn on the
+     * arrow next to the source end; absent when it has none.
+     */
+    readonly tags?: readonly TagInfo[];
+    /**
+     * Sequence diagrams: whether the message's receiver is activated after it: `written` when the
+     * next event of its block is `activate <receiver>` (Alt+A and **Activate** remove that pair),
+     * `block` when the message is a call whose block activates the receiver (they refuse); absent
+     * otherwise.
+     */
+    readonly activation?: "written" | "block";
 }
 /** What the canvas knows about an event of a sequence diagram. */
 export interface EventInfo {
@@ -150,9 +236,18 @@ export interface EventInfo {
     /** The row of the event, in diagram coordinates. */
     readonly y: number;
     readonly height: number;
-    /** The frame of a note or a fragment, in diagram coordinates. */
+    /**
+     * The frame of a note or a fragment, or the bar an `activate` opens (`activate#1`), which a
+     * press on it selects and its outline is; in diagram coordinates. Null for the others.
+     */
     readonly box: Box | null;
-    /** The fragment around the event, or null. */
+    /**
+     * The other end of an activation: an `activate`'s `deactivate`, a `deactivate`'s `activate`.
+     * Null for an `activate` open to the end, a `deactivate` that closes nothing and every other
+     * event.
+     */
+    readonly pair: string | null;
+    /** The fragment or the call around the event, or null. */
     readonly parent: string | null;
     /** The participant of an activation or a lifecycle event. */
     readonly participant: string | null;
@@ -204,6 +299,11 @@ export interface CanvasRender {
     readonly effects: number;
     /** True while the canvas shows the effects running. */
     readonly playing: boolean;
+    /**
+     * The document belongs to a project, whose assets the canvas may add to (the Add icon dialog);
+     * absent outside one.
+     */
+    readonly project?: boolean;
     /** C4 views: the entities of the model the view may draw and does not. */
     readonly entities: readonly {
         readonly path: string;
@@ -213,12 +313,20 @@ export interface CanvasRender {
     readonly selection: readonly string[];
     /**
      * The colours of the canvas's selection and of its guides, from the diagram's theme: its
-     * `selection` and `guide`, else its `accent`.
+     * `selection` and `guide`, else its `accent`; and the `accent` itself, the colour of the Pointer
+     * tool's trail when the host names no colour of the person's own.
      */
     readonly colors?: {
         readonly selection: string;
         readonly guide: string;
+        readonly accent: string;
     };
+    /**
+     * The colour tokens of the diagram's theme with the colours they resolve to, in the theme's
+     * order (the strip's swatches): the pen menu's colour row, and the colour a stroke in progress
+     * is drawn in when its colour is a token (`@ink`, `@highlight`).
+     */
+    readonly swatches?: readonly ColorSwatch[];
 }
 export interface CanvasSettings {
     readonly grid: number;
@@ -234,7 +342,13 @@ export interface CanvasSettings {
      */
     readonly readOnly?: boolean;
 }
-export type FieldType = "id" | "text" | "multiline" | "number" | "enum" | "color" | "icon" | "classes" | "ports";
+/**
+ * The control of a field. `boolean` is a checkbox whose value is `on` when checked and `off` when
+ * not; checking or clearing it sends `setField` with `on` or `off`. `font` is a font stack chosen
+ * in the canvas's font picker (`listFonts`): its value is the written stack, its placeholder the
+ * family that applies, and its `options` the families the picker lists.
+ */
+export type FieldType = "id" | "text" | "multiline" | "number" | "enum" | "color" | "icon" | "classes" | "ports" | "boolean" | "font";
 /** One editable property in the inspector. */
 export interface InspectorField {
     readonly name: string;
@@ -255,6 +369,11 @@ export interface InspectorField {
     readonly readonly?: boolean;
     /** Fields of the style strip, which the inspector shows first and draws compactly. */
     readonly section?: "strip";
+    /**
+     * Strip fields that belong to a card: the name of the toggle field whose card holds this one
+     * (`effect.trace` for `effect.trace.color`), so a canvas groups them without knowing the effects.
+     */
+    readonly group?: string;
     /** Colour fields: the effective theme's colour tokens with the colours they resolve to. */
     readonly swatches?: readonly ColorSwatch[];
     /** Values offered in one click beside the control, such as a theme's dark counterpart. */
@@ -283,6 +402,11 @@ export interface InspectorField {
         readonly max: number;
         readonly step: number;
     };
+    /**
+     * Number fields with values offered in a list beside the field, which its − and + buttons step
+     * along: the text size's common sizes. Any number in the property's bounds may still be typed.
+     */
+    readonly list?: readonly number[];
     /**
      * Icon fields (`style.icon`, the `source` of an icon object): the icon they show, the written
      * one or else the one that applies (`placeholder`), with its readable name and a 24 px SVG
@@ -292,19 +416,36 @@ export interface InspectorField {
     readonly thumbnail?: IconChoiceInfo;
     /**
      * A button the canvas draws beside the field, which sends `action`: Convert to container
-     * beside Inside. Canvases that only show leave it out.
+     * beside Inside, **Remove** beside a tag (`removeTag`). Canvases that only show leave it out.
      */
     readonly button?: {
         readonly label: string;
         readonly action: CanvasAction;
     };
+    /**
+     * A sentence the canvas shows under the field, such as why it is read-only: "The block of `pay`
+     * activates `api`." under a call's **Activates the receiver**.
+     */
+    readonly note?: string;
 }
 /**
  * The picture family of a field: see `InspectorField.glyphs`. `iconPosition` pictures the five
  * places of an icon in its box (`ICON_POSITIONS`), `labelPosition` the four edges a label takes
  * around a centred icon (`LABEL_POSITIONS`).
  */
-export type FieldGlyphs = "line" | "route" | "corners" | "arrowStart" | "arrowEnd" | "shape" | "iconPosition" | "labelPosition";
+export type FieldGlyphs = "line" | "route" | "corners" | "arrowStart" | "arrowEnd" | "shape" | "iconPosition" | "labelPosition" | "sketch" | "textAlign" | "verticalAlign" | "fontWeight";
+/**
+ * A family the font picker lists: its name and group, the weights it has files for, and the
+ * `@font-face` rules that draw its row ("<Family> Aa") in its own face, empty while its files are
+ * on their way or when it cannot be shown. A restricted project font measures text only.
+ */
+export interface FontOption {
+    readonly family: string;
+    readonly group: "sans" | "serif" | "mono" | "hand" | "project";
+    readonly weights: readonly number[];
+    readonly faces: readonly string[];
+    readonly restricted?: boolean;
+}
 /** The panel that edits a theme block: its tokens by group, written or inherited. */
 export interface ThemePanelModel {
     /** The theme's id in its file. */
@@ -345,8 +486,11 @@ export interface StoryPlaybackInfo {
     /** `@font-face` rules for the text of the views. */
     readonly fontFaces: readonly string[];
 }
-/** Actions a scene can run, which **Add to scene** inserts. */
-export type SceneActionKind = "reveal" | "hide" | "highlight" | "focus" | "camera" | "trace" | "hold";
+/**
+ * Actions a scene can run, which **Add to scene** inserts. `draw` replays pens, free lines and
+ * named relations (`story-language`); the edit refuses it on anything else.
+ */
+export type SceneActionKind = "reveal" | "hide" | "highlight" | "focus" | "camera" | "trace" | "draw" | "hold";
 /** Statements that would be removed with an element, listed for confirmation. */
 export interface DependentInfo {
     readonly kind: string;
@@ -364,8 +508,9 @@ export interface LibraryInfo {
 }
 /**
  * Another person's selection, drawn over the scene with an outline in `colour` and a tag holding
- * `name` (as text). It is never selectable, saved, copied or exported, and nothing of it is sent
- * back to the host; ids the diagram does not have are ignored.
+ * `name` (as text), and their pointer, drawn as a cursor in `colour` with the name at its tail. It is
+ * never selectable, saved, copied or exported, and nothing of it is sent back to the host; ids the
+ * diagram does not have are ignored.
  */
 export interface PresencePerson {
     /** Shown verbatim in the tag as a text node, so markup in it shows as its characters. */
@@ -382,7 +527,72 @@ export interface PresencePerson {
      * several people on one id are stacked in the order of the list.
      */
     readonly selection: readonly string[];
+    /**
+     * Where the person's pointer is over their canvas, in diagram units of the diagram shown: a
+     * cursor in `colour` whose tip is at that point at every zoom, keeping its size on screen, and
+     * gliding to the next point in 200 ms. Ignored unless it is two finite numbers.
+     */
+    readonly pointer?: {
+        readonly x: number;
+        readonly y: number;
+    };
+    /**
+     * The points of the person's Pointer trail since their last batch (`live-collaboration`): `batch`
+     * grows by one with each batch of that person, so the canvas draws a batch once, and `points` are
+     * at most 64 entries, `x` and `y` in diagram units and `t` the milliseconds since the batch's
+     * first point, 0 to 1000. The trail is drawn in `colour`, point by point at its own pace, and
+     * fades as the person's own does. A batch that does not fit those bounds is not drawn.
+     *
+     * A batch with `pen` holds the points of a stroke the person is drawing with the pen or the
+     * highlighter (`diagram-canvas` "Strokes of others"): drawn in the pen's width, colour and
+     * opacity, the batches of one `stroke` number growing one stroke that does not fade, until the
+     * next `render` after its last batch or ten seconds, or at once on its `cancel` batch. A batch
+     * whose `pen` does not fit `isPresencePen` is not drawn.
+     */
+    readonly laser?: {
+        readonly batch: number;
+        readonly points: readonly {
+            readonly x: number;
+            readonly y: number;
+            readonly t: number;
+        }[];
+        readonly pen?: PresencePen;
+    };
+}
+/**
+ * How a stroke being drawn looks, as a laser batch carries it to the others, and which of the
+ * person's strokes it is: `width` a whole number of pixels from 1 to 64, `colour` a CSS colour of
+ * at most 32 characters (the resolved colour, not a token), `opacity` from 0 to 1, `stroke` an
+ * integer from 0 to 2,147,483,647 that the person's canvas increases with each stroke (the batches
+ * of one stroke carry the same number, and a stroke is never joined to another), and `cancel`,
+ * only ever `true`, on the batch that ends a stroke cancelled with Escape (its points may be none):
+ * the others drop that stroke at once.
+ */
+export interface PresencePen {
+    readonly width: number;
+    readonly colour: string;
+    readonly opacity: number;
+    readonly stroke: number;
+    readonly cancel?: true;
 }
+/** The bounds of `PresencePen`, which the canvas, the page and the room apply alike. */
+export declare const PRESENCE_PEN_LIMITS: {
+    readonly width: {
+        readonly min: 1;
+        readonly max: 64;
+    };
+    readonly colour: 32;
+    readonly opacity: {
+        readonly min: 0;
+        readonly max: 1;
+    };
+    readonly stroke: {
+        readonly min: 0;
+        readonly max: 2147483647;
+    };
+};
+/** Whether a value is a `PresencePen` within its bounds (`PRESENCE_PEN_LIMITS`). */
+export declare function isPresencePen(v: unknown): v is PresencePen;
 /** An element of a library with its thumbnail, null while its pack is still loading. */
 export interface LibraryItemInfo {
     readonly library: string;
@@ -422,6 +632,38 @@ export interface IconGroupInfo {
     readonly title: string;
     readonly items: readonly IconChoiceInfo[];
 }
+/** A file the Add icon dialog sends: its own name, the icon name it is to get, and its text. */
+export interface IconFileInput {
+    /** The file's name as the person picked it, such as `My Logo.svg`. */
+    readonly file: string;
+    /** The icon's name in the pack; without one, the session offers one made of the file's name. */
+    readonly name?: string;
+    readonly svg: string;
+}
+/** What the session says of a file of the Add icon dialog. */
+export interface IconFileCheck {
+    readonly file: string;
+    /** The name the icon gets: the one asked for, or the one offered. */
+    readonly name: string;
+    /** Why it cannot be added as it is (an unsafe SVG, a name taken or invalid); absent when it can. */
+    readonly problem?: string;
+    /** A 48 px preview of the icon as the sanitiser keeps it, or null when it refuses the file. */
+    readonly svg: string | null;
+}
+/** What the session says of the prefix of the Add icon dialog. */
+export interface IconPrefixCheck {
+    readonly prefix: string;
+    /** Why the icons cannot go into a pack of that prefix; absent when they can. */
+    readonly problem?: string;
+    /** A pack of the project has the prefix already: the icons join it. */
+    readonly existing: boolean;
+    /** The pack has a licence, so the dialog asks for none. */
+    readonly licensed: boolean;
+}
+/** An icon the Add icon dialog wrote, with the file it came from. */
+export interface AddedIconInfo extends IconChoiceInfo {
+    readonly file: string;
+}
 export type HostMessage = ({
     readonly type: "render";
 } & CanvasRender) | {
@@ -459,6 +701,14 @@ export type HostMessage = ({
     readonly width?: number;
     readonly height?: number;
     readonly offset?: Point;
+    /** For a rotation, the turned element's box in the drawing, in diagram coordinates. */
+    readonly box?: Box;
+    /**
+     * Without a drawing, why the drop would be refused, when the session knows it: the order
+     * rule a `moveActivation` breaks ("`b` is not active here."). The canvas says it while the
+     * gesture goes on, and its drop writes nothing.
+     */
+    readonly reason?: string;
 } | {
     readonly type: "rejected";
     readonly code: string;
@@ -469,9 +719,16 @@ export type HostMessage = ({
 } | {
     readonly type: "highlight";
     readonly ids: readonly string[];
-} | {
+}
+/**
+ * The selection after an edit. One id alone opens the inline editor of what was just created;
+ * with `tag`, the editor opens on the pill at that index of the selected participant or
+ * message (`TagInfo.place`), the tag that `addTag` just wrote, instead of its label.
+ */
+ | {
     readonly type: "select";
     readonly ids: readonly string[];
+    readonly tag?: number;
 }
 /**
  * The other people of a shared project and what each has selected (`live-collaboration`). Each
@@ -483,6 +740,13 @@ export type HostMessage = ({
  | {
     readonly type: "presence";
     readonly people: readonly PresencePerson[];
+    /**
+     * The colour of the person at this canvas, as the others see them: the Pointer tool's trail
+     * and cursor are drawn in it while it is set, and in the theme's accent when it is not.
+     */
+    readonly me?: {
+        readonly colour: string;
+    };
 } | {
     readonly type: "settings";
     readonly settings: CanvasSettings;
@@ -498,6 +762,17 @@ export type HostMessage = ({
     readonly type: "themePanel";
     readonly panel: ThemePanelModel | null;
 }
+/**
+ * The answer to `listFonts`, with its `token`: the families the font picker lists, bundled ones
+ * by group, then the project's. A family whose faces are empty is drawn in the interface's font
+ * until a later answer brings them: the canvas asks again when a render arrives while the
+ * picker is open.
+ */
+ | {
+    readonly type: "fonts";
+    readonly token: number;
+    readonly families: readonly FontOption[];
+}
 /** The element libraries of the document, for the libraries panel. */
  | {
     readonly type: "libraries";
@@ -524,6 +799,29 @@ export type HostMessage = ({
     readonly token: number;
     readonly groups: readonly IconGroupInfo[];
 }
+/**
+ * The answer to `checkIcons`, with its `token`: the prefix and each file as the Add icon dialog
+ * shows them, with a preview, the name offered and what is wrong, if anything.
+ */
+ | {
+    readonly type: "iconsChecked";
+    readonly token: number;
+    readonly prefix: IconPrefixCheck;
+    readonly files: readonly IconFileCheck[];
+}
+/**
+ * The answer to `addIcons`, with its `token`: the icons whose files the host is to write (the
+ * steps over files of the same result), and the files refused with the reason.
+ */
+ | {
+    readonly type: "iconsAdded";
+    readonly token: number;
+    readonly added: readonly AddedIconInfo[];
+    readonly refused: readonly {
+        readonly file: string;
+        readonly reason: string;
+    }[];
+}
 /**
  * The stories of the file for the picker, and the playback of the story the canvas plays, or
  * null outside story mode.
@@ -539,24 +837,75 @@ export type HostMessage = ({
 };
 /** The kinds of diagram the canvas creates: C4 views need a model, written in text. */
 export type CreatableDiagram = "flow" | "free" | "sequence";
-/** Moves elements by a delta in diagram coordinates. */
+/**
+ * Moves elements by a delta in diagram coordinates, or into a list group at a position. A child
+ * of a list stays where its list puts it: a move by a delta that leaves it in its list (a nudge,
+ * an Alt-drag) is refused with a status that says how to move it.
+ */
 export interface MoveAction {
     readonly kind: "move";
     readonly ids: readonly string[];
-    readonly delta: Point;
+    /**
+     * How far the elements move, in diagram coordinates. Absent only with `index`, whose drop
+     * writes no position; a pen or a line moved with it keeps its points.
+     */
+    readonly delta?: Point;
     /**
      * The group the moved elements land in, or null for the diagram's top level: each one whose
      * parent differs is declared in it, placed where it is dropped (flow and free diagrams).
-     * Absent, every element keeps its parent, as nudges and Alt-drags do.
+     * Absent, every element keeps its parent, as nudges and Alt-drags do. A list group places them
+     * itself: they are declared at the end of it, or at `index`, and lose their `place`.
      */
     readonly parent?: string | null;
+    /**
+     * With `parent` a list group: where the elements go among its children (`ElementInfo.list`)
+     * once the moved ones are taken out, before the child at that index, after the last when it is
+     * the count. Several elements go there one after another in the order of `ids`; moving a child
+     * within its own list reorders it. A whole number from 0.
+     */
+    readonly index?: number;
 }
-/** Gives an element a new box in diagram coordinates. */
+/**
+ * Gives an element a new box in diagram coordinates. A child of a list writes its size alone; a
+ * pen stroke's points are scaled from its bounds to the box (`scalePenPoints`), its width kept,
+ * so its resize handles preview and drop as a box's do.
+ */
 export interface ResizeAction {
     readonly kind: "resize";
     readonly id: string;
     readonly box: Box;
 }
+/**
+ * Sequence diagrams: an end of a written activation bar dragged to the boundary below an event
+ * row (a bar handle's drop). `id` is the bar's `activate` (its `deactivate` is taken as its
+ * `activate`); `row` is the key of the event whose row the handle snapped below. The session writes
+ * it as `moveEvent` with a destination: `start` puts the `activate` right after `row`, or first in
+ * the block of `row` when it is a call with a block, so the bar starts at that call's arrow; `end`
+ * puts the `deactivate` right after `row`, and on a bar open to the end writes `deactivate
+ * <participant>` there. A move the order rules forbid is refused with the rule's reason.
+ */
+export interface MoveActivationAction {
+    readonly kind: "moveActivation";
+    readonly id: string;
+    readonly end: "start" | "end";
+    readonly row: string;
+}
+/**
+ * The styles a new pen stroke writes in its `style` statement; what is absent keeps the default
+ * (the theme's `ink`, 3 wide, opaque, no heads).
+ */
+export interface PenStyle {
+    /** A colour token such as `@highlight`, or a colour such as `#e03131`. */
+    readonly stroke?: string;
+    /** 1 to 64. */
+    readonly width?: number;
+    /** 0 to 1. */
+    readonly opacity?: number;
+    /** A head at the last point, by its name in the language (`triangle`). */
+    readonly arrowhead?: string;
+    /** A head at the first point. */
+    readonly arrowtail?: string;
+}
 /**
  * A change requested by the canvas; each becomes one edit plan, but `preview`, which asks for the
  * drawing of a move or a resize without writing it.
@@ -569,6 +918,50 @@ export type CanvasAction = MoveAction | ResizeAction | {
     readonly kind: "setVia";
     readonly relation: string;
     readonly via: readonly Point[];
+} | {
+    /**
+     * Draws a free line from `from` to `to`, in diagram coordinates, inside `parent` when given;
+     * `line` and `heads` are the armed kind's, which the session writes as styles with the
+     * effective theme's head.
+     */
+    readonly kind: "createLine";
+    readonly from: Point;
+    readonly to: Point;
+    readonly parent?: string;
+    readonly line: "solid" | "dashed";
+    readonly heads: "end" | "both" | "none";
+} | {
+    /** Moves the points of a free line, in diagram coordinates. */
+    readonly kind: "setLinePoints";
+    readonly element: string;
+    readonly from: Point;
+    readonly to: Point;
+    readonly via: readonly Point[];
+} | {
+    /**
+     * Draws a pen stroke through `points`, in diagram coordinates as the pointer gave them
+     * (simplified, not snapped). `parent` is the innermost group under the first point, where
+     * the session starts looking for the stroke's group: from it outwards, the first group that
+     * is not a list and whose drawn box holds the whole stroke (its points grown by half its
+     * width), else the top level, so that a stroke never grows a list nor moves its cards. The
+     * points are written in that group's interior, and a group without `size` gets the size it
+     * is drawn with, so that it stays as drawn. `style` holds only what differs from a stroke's
+     * defaults (`penStyleFor`). The new pen is not selected and no editor opens, so the next
+     * stroke starts at once.
+     */
+    readonly kind: "createPen";
+    readonly points: readonly Point[];
+    readonly parent?: string;
+    readonly style?: PenStyle;
+} | {
+    /**
+     * Moves the points of a pen stroke, in diagram coordinates: a drag of its stroke or a scale.
+     * A pen in a list goes out to the nearest group around it that is not a list and holds it,
+     * else to the top level, as `createPen` chooses.
+     */
+    readonly kind: "setPenPoints";
+    readonly element: string;
+    readonly points: readonly Point[];
 } | {
     readonly kind: "setEnd";
     readonly relation: string;
@@ -601,13 +994,45 @@ export type CanvasAction = MoveAction | ResizeAction | {
      * icon the shape (the picker's **Icon**) and any other shape puts it in a box.
      */
     readonly shape?: ShapeName;
+    /**
+     * A new note attached to an element, written as `on <element>` after its text: the id of an
+     * element of the diagram, or the entity path a C4 view draws. With it `at` is the point the
+     * note's centre is put at when the tool was dropped on the element; the session places the
+     * note beside the element instead, at its east edge plus the theme's `groupPadding`, aligned
+     * to its top.
+     */
+    readonly attachedTo?: string;
+    /**
+     * The fill of a new sticky, written as `style <id> { fill … }` in the same edit: a colour
+     * such as `#f8bbd0`, or a colour token as `@sticky`.
+     */
+    readonly fill?: string;
+    /** A new group that is a list (the group menu's Column and Row): `{ layout column }`. */
+    readonly layout?: "column" | "row";
+    /**
+     * With `parent` a list group: where the new element goes among its children
+     * (`ElementInfo.list`), before the child at that index, at the end when it is the count;
+     * the list places it, so it gets no `place`.
+     */
+    readonly index?: number;
+} | {
+    /**
+     * Writes, changes or removes the `on <element>` clause of a note (the inspector's **Attached
+     * to** field): `element` is an element id (the entity path in a view), null for none.
+     */
+    readonly kind: "attachNote";
+    readonly note: string;
+    readonly element: string | null;
 } | {
     readonly kind: "connect";
     readonly from: string;
     readonly to: string;
     readonly line: "solid" | "dashed";
-    /** A head at both ends: `<->`, or `<-->` when dashed. Not in C4 views. */
-    readonly twoWay?: boolean;
+    /**
+     * `both` for a head at both ends (`<->`, `<-->`), `none` for a line without heads (`--`,
+     * `---`); a head at the end otherwise. Neither in C4 views.
+     */
+    readonly heads?: "none" | "both";
     /**
      * The ends pinned to a port or a point of a side, each on its own: the start when the line
      * was dragged from a border or a handle, the end when it was dropped on the target's border.
@@ -656,6 +1081,18 @@ export type CanvasAction = MoveAction | ResizeAction | {
     readonly field: string;
     readonly value: string | number | null;
 }
+/**
+ * Several fields of the same targets written in one edit, one undo step: the alignment
+ * picker's `style.textAlign` and `style.verticalAlign` when both change.
+ */
+ | {
+    readonly kind: "setFields";
+    readonly ids: readonly string[];
+    readonly fields: readonly {
+        readonly field: string;
+        readonly value: string | number | null;
+    }[];
+}
 /**
  * Writes `style <id> { icon "<icon>" }` on each of `ids` that takes an icon
  * (`ElementInfo.takesIcon`), in one edit; the others are left as they are, and the session
@@ -722,6 +1159,58 @@ export type CanvasAction = MoveAction | ResizeAction | {
     readonly kind: "toggleActivation";
     readonly ids: readonly string[];
 }
+/**
+ * The text size of every item of `ids` that takes `fontSize`, one step of the common sizes up
+ * (1) or down (-1) from what each draws, in one edit; nothing at the ends of the list.
+ */
+ | {
+    readonly kind: "stepTextSize";
+    readonly ids: readonly string[];
+    readonly step: 1 | -1;
+}
+/** Sequence diagrams: an end of an activation bar to another event row. */
+ | MoveActivationAction
+/**
+ * Sequence diagrams: `tag "Tag"` (the word in the interface language, "Tag 2" when the owner has
+ * "Tag" already) added last to the selected message, else to the selected participant; the
+ * session selects the owner and opens the editor on the new pill (`select` with `tag`). Refused
+ * with a reason when neither is selected.
+ */
+ | {
+    readonly kind: "addTag";
+    readonly ids: readonly string[];
+}
+/**
+ * Sequence diagrams: the text of the tag at `index` (from 0) of the selected message, else the
+ * selected participant; an empty text removes the tag (`removeTag`).
+ */
+ | {
+    readonly kind: "setTag";
+    readonly ids: readonly string[];
+    readonly index: number;
+    readonly text: string;
+}
+/** Sequence diagrams: removes the tag at `index` of the selected message, else participant. */
+ | {
+    readonly kind: "removeTag";
+    readonly ids: readonly string[];
+    readonly index: number;
+}
+/** Sequence diagrams: the selected events into the block of the call right before them. */
+ | {
+    readonly kind: "nestInCall";
+    readonly ids: readonly string[];
+}
+/** Sequence diagrams: the events of the selected call, or of the call around the selection, out. */
+ | {
+    readonly kind: "unnestCall";
+    readonly ids: readonly string[];
+}
+/** Sequence diagrams: a `return` at the end of the selected call, or of the call around it. */
+ | {
+    readonly kind: "addReturn";
+    readonly ids: readonly string[];
+}
 /** Sequence diagrams: a note, divider or delay after the selection, or at the end. */
  | {
     readonly kind: "insertEvent";
@@ -777,7 +1266,8 @@ export type CanvasAction = MoveAction | ResizeAction | {
 /**
  * The drawing the move, resize or rotation `action` would give on the drop, while the gesture
  * goes on. Nothing is written: no plan, no history, no new revision. The session answers with a
- * `preview` host message carrying the same `token` (flow and free diagrams and C4 views).
+ * `preview` host message carrying the same `token` (flow and free diagrams and C4 views; on
+ * sequence diagrams, a bar handle's `moveActivation`, with the reason when it is refused).
  */
  | {
     readonly kind: "preview";
@@ -791,8 +1281,11 @@ export interface RotationAction {
     readonly field: "style.rotation";
     readonly value: number | null;
 }
-/** The gestures a canvas previews: moves, resizes and rotations. */
-export type PreviewedAction = MoveAction | ResizeAction | RotationAction;
+/**
+ * The gestures a canvas previews: moves, resizes and rotations, and the end of an activation bar
+ * dragged on a sequence diagram.
+ */
+export type PreviewedAction = MoveAction | ResizeAction | RotationAction | MoveActivationAction;
 export type CanvasMessage = {
     readonly type: "ready";
 } | {
@@ -859,6 +1352,34 @@ export type CanvasMessage = {
     readonly query: string;
     readonly token: number;
 }
+/** The font picker's families, answered by a `fonts` message with the same `token`. */
+ | {
+    readonly type: "listFonts";
+    readonly token: number;
+}
+/**
+ * The Add icon dialog's files and prefix, checked as they are typed: answered by `iconsChecked`
+ * with the same `token`.
+ */
+ | {
+    readonly type: "checkIcons";
+    readonly token: number;
+    readonly prefix: string;
+    readonly files: readonly IconFileInput[];
+}
+/**
+ * Adds icons to the project: each file as `assets/icons/<prefix>/<name>.svg`, the pack's licence
+ * when it has none, the icons in the project's library, and the first icon on `targets`, in one
+ * step; answered by `iconsAdded`.
+ */
+ | {
+    readonly type: "addIcons";
+    readonly token: number;
+    readonly prefix: string;
+    readonly licence?: string;
+    readonly files: readonly IconFileInput[];
+    readonly targets: readonly string[];
+}
 /**
  * Creates a theme that extends the diagram's: in the file, used by the diagram, or for the
  * project, as its default theme in `themes/<id>.meltemi`.
@@ -878,6 +1399,44 @@ export type CanvasMessage = {
     readonly type: "themeToken";
     readonly token: string;
     readonly value: string | number | null;
+}
+/**
+ * Where the person's pointer is over the canvas, in diagram units of the diagram shown
+ * (`diagram`), or `null` once it left the canvas or a story plays: for the host to share as
+ * presence (`live-collaboration`). The canvas sends it only to a host that has sent `presence`,
+ * at most every 50 ms while the pointer moves. It changes nothing of the document.
+ */
+ | {
+    readonly type: "presencePointer";
+    readonly point: Point | null;
+    readonly diagram?: string;
+}
+/**
+ * The points a Pointer stroke added since the last batch, for the host to share in the same
+ * presence message as the pointer (`live-collaboration`): `t` is the milliseconds since the
+ * batch's first point, so a batch starts at 0. Sent only to a host that has sent `presence`, at
+ * most every 50 ms while a stroke is drawn. It changes nothing of the document.
+ */
+ | {
+    readonly type: "presenceLaser";
+    readonly points: readonly {
+        readonly x: number;
+        readonly y: number;
+        readonly t: number;
+    }[];
+    readonly diagram?: string;
+    /**
+     * Set while the points are a stroke of the pen or the highlighter, for the others to draw it
+     * as it grows: its width, its resolved colour, its opacity and its number, within
+     * `PRESENCE_PEN_LIMITS`, with `cancel` on the batch (maybe of no points) that ends a stroke
+     * cancelled with Escape. The Pointer's batches carry none.
+     */
+    readonly pen?: PresencePen;
+};
+/** How many files the Add icon dialog sends at once, and the longest SVG text it sends. */
+export declare const ADD_ICON_LIMITS: {
+    readonly files: 50;
+    readonly svg: 300000;
 };
 /** Whether a value from the webview is a well-formed canvas message. */
 export declare function isCanvasMessage(m: unknown): m is CanvasMessage;