@meltemi/diagrams-editor 1.10.0 → 1.10.18

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" | "line" | "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 {
@@ -130,6 +162,35 @@ export interface ElementInfo {
         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 {
@@ -152,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 {
@@ -161,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;
@@ -237,6 +321,12 @@ export interface CanvasRender {
         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;
@@ -252,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;
@@ -306,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
@@ -315,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" | "sketch" | "textAlign" | "verticalAlign";
+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. */
@@ -368,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;
@@ -421,6 +542,12 @@ export interface PresencePerson {
      * 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;
@@ -429,8 +556,43 @@ export interface PresencePerson {
             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;
@@ -541,6 +703,12 @@ export type HostMessage = ({
     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;
@@ -551,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
@@ -587,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";
@@ -651,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.
@@ -700,6 +937,31 @@ export type CanvasAction = MoveAction | ResizeAction | {
     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;
@@ -740,6 +1002,19 @@ export type CanvasAction = MoveAction | ResizeAction | {
      * 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
@@ -884,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";
@@ -939,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";
@@ -953,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";
 } | {
@@ -1021,6 +1352,11 @@ 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`.
@@ -1089,6 +1425,13 @@ export type CanvasMessage = {
         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: {