@draftably/editor 0.0.0-stage → 0.1.0

package/dist/types/src/model/edits.d.ts

@@ -0,0 +1,133 @@
+import { emptyDiagram } from './document';
+import type { ContainerLayout, Diagram, DiagramEdge, DiagramGroup, DiagramNode, EdgeLayout, IntentPlacement, IntentRole, NodeLayout, NodeStyle, Point, PortSide, Rect, Side } from './types';
+export declare function moveObject(doc: Diagram, id: string, dx: number, dy: number, manual?: boolean): void;
+/** Bounds of a container's direct children, including shape labels. */
+export declare function contentBounds(doc: Diagram, id: string): Rect | null;
+export declare const containerPadding: (doc: Diagram, id: string) => number;
+/** Size a container around its contents. Without `shrink`, the frame only grows. */
+export declare function fitContainer(doc: Diagram, id: string, shrink?: boolean): void;
+/** Grow every enclosing container so the object stays inside. */
+export declare function ensureParentsFit(doc: Diagram, id: string): void;
+/** The deepest, smallest visible container under the center of `rect`. */
+export declare function dropTarget(doc: Diagram, id: string, rect: Rect, frames?: Map<string, Rect>): DiagramGroup | undefined;
+export type ResizeHandle = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
+/**
+ * Resize from a handle. Containers cannot shrink across their contents, and their children
+ * stay at the same world coordinates.
+ */
+export declare function resizedRect(doc: Diagram, id: string, start: NodeLayout, dx: number, dy: number, handle: ResizeHandle, keepAspect?: boolean): NodeLayout;
+export interface NewNode {
+    id?: string;
+    title?: string;
+    parentId?: string | null;
+    image?: string;
+    style?: Partial<NodeStyle>;
+    /** Top-left corner; defaults to centering the shape on `at`. */
+    position?: Point;
+    w?: number;
+    h?: number;
+}
+export declare function addNode(doc: Diagram, partial: NewNode, at: Point): string;
+export interface NewEdge {
+    id?: string;
+    from: string;
+    to: string;
+    label?: string;
+    directed?: boolean;
+    emphasis?: boolean;
+    dashed?: boolean;
+    fromSide?: PortSide;
+    toSide?: PortSide;
+}
+export declare function addEdge(doc: Diagram, partial: NewEdge): string;
+export interface ConnectedNode {
+    /** Connect from this shape. */
+    from?: string | null;
+    /** Create a sibling branch: connect from every source of this shape. */
+    siblingOf?: string | null;
+    side?: Side | null;
+    /** Center of the new shape; otherwise it is placed beside the reference shape. */
+    at?: Point | null;
+    title?: string;
+    /** Container for the new shape; `undefined` inherits the reference shape's container. */
+    parentId?: string | null;
+    style?: Partial<NodeStyle>;
+}
+/** Add a shape next to another one and connect it. `fallback` is used when nothing is referenced. */
+export declare function addConnectedNode(doc: Diagram, options: ConnectedNode, fallback: Point): string;
+/**
+ * Split a connection with a new shape. `routePoints` locates the longest segment
+ * when `at` is not given.
+ */
+export declare function insertStep(doc: Diagram, edgeId: string, routePoints: Point[] | undefined, at?: Point | null): string | undefined;
+export type BuildMode = 'chain' | 'branches' | 'none';
+export interface BuildOptions {
+    mode?: BuildMode;
+    /** Wrap the new shapes in a container with this title. */
+    title?: string;
+    /** Continue from this shape. */
+    source?: string | null;
+    parentId?: string | null;
+    /** Where to start when there is no source or container. */
+    origin: Point;
+    columns: number;
+}
+/** Create shapes from a list of titles. Returns the ids to select. */
+export declare function buildFromList(doc: Diagram, lines: string[], options: BuildOptions): string[];
+/** Delete objects. Containers release their contents unless `deep` is set. */
+export declare function deleteObjects(doc: Diagram, selected: Iterable<string>, deep?: boolean): void;
+export declare function createContainer(doc: Diagram, rect: Rect, { roots, parentId, title, fit, }?: {
+    roots?: string[];
+    parentId?: string | null;
+    title?: string;
+    fit?: boolean;
+}): string;
+/** Wrap the selected objects in a new container, or add an empty one at `fallback`. */
+export declare function wrapInContainer(doc: Diagram, roots: string[], fallback: Point): string;
+/** Draw a container: it adopts the objects it fully encloses inside the deepest enclosing container. */
+export declare function drawContainer(doc: Diagram, r: Rect): string;
+export declare function ungroup(doc: Diagram, selected: Iterable<string>): void;
+export type AlignKind = 'left' | 'top' | 'center' | 'middle' | 'distribute-x' | 'distribute-y';
+export declare function alignObjects(doc: Diagram, ids: string[], kind: AlignKind): void;
+export declare function nudge(doc: Diagram, ids: string[], dx: number, dy: number): void;
+export declare function toggleCollapsed(doc: Diagram, id: string): void;
+export declare function setTitle(doc: Diagram, id: string, title: string): void;
+export declare function setEdgeLabel(doc: Diagram, id: string, label: string): void;
+export declare function setGeometry(doc: Diagram, id: string, key: 'x' | 'y' | 'w' | 'h', value: number): void;
+export declare function setStyle(doc: Diagram, id: string, patch: Partial<NodeStyle>): void;
+export declare function setLabelMode(doc: Diagram, id: string, mode: NonNullable<Diagram['layout']['labels'][string]['mode']>): void;
+export declare function setParent(doc: Diagram, id: string, parentId: string | null): void;
+export declare function setContainer(doc: Diagram, id: string, patch: Partial<ContainerLayout>): void;
+export declare function setEdge(doc: Diagram, id: string, patch: Partial<Pick<DiagramEdge, 'directed' | 'dashed' | 'emphasis' | 'head' | 'tail'>>): void;
+export declare function setEdgeLayout(doc: Diagram, id: string, patch: Partial<EdgeLayout>): void;
+export declare function reverseEdge(doc: Diagram, id: string): void;
+export declare function useAutomaticPorts(doc: Diagram, edgeIds: string[]): void;
+/** True when the point is too close to a shape to hold a connection bend. */
+export declare const bendInsideShape: (doc: Diagram, p: Point) => boolean;
+export declare function addWaypoint(doc: Diagram, id: string, p: Point): void;
+export declare function removeWaypoint(doc: Diagram, id: string, index: number): void;
+export declare const INTENT_LABELS: Record<IntentPlacement, string>;
+/** Placements offered for a role; only a start can sit in the center. */
+export declare const intentPlacements: (role: IntentRole) => IntentPlacement[];
+/** Mark a shape as the preferred start or end, or clear the role when `id` is null. */
+export declare function setIntent(doc: Diagram, role: IntentRole, id: string | null, placement?: IntentPlacement): void;
+export interface ClipboardFragment {
+    kind: 'diagram-studio/clipboard';
+    nodes: DiagramNode[];
+    groups: DiagramGroup[];
+    edges: DiagramEdge[];
+    layout: Partial<Record<'nodes' | 'edges' | 'labels' | 'containers', Record<string, unknown>>>;
+    styles: Record<string, NodeStyle>;
+}
+/** Copy the selection, including container contents and connections between copied shapes. */
+export declare function copyFragment(doc: Diagram, selected: Iterable<string>): ClipboardFragment;
+export declare const isClipboardFragment: (value: unknown) => value is ClipboardFragment;
+/**
+ * Return a validated document with the fragment pasted at an offset, plus the new ids to select.
+ * The fragment is untrusted, so the whole result goes through `normalize`.
+ */
+export declare function pasteFragment(doc: Diagram, part: ClipboardFragment): {
+    doc: Diagram;
+    selected: string[];
+};
+export { emptyDiagram };

package/dist/types/src/model/embed.d.ts

@@ -0,0 +1,17 @@
+export declare const SOURCE_KEYWORD = "draftably";
+export declare const VERSION_KEYWORD = "draftably-version";
+export declare const DRAFTABLY_VERSION: string;
+/** The PNG with `source` in a `draftably` chunk before its end, replacing any earlier one. */
+export declare function embedPngSource(png: Uint8Array, source: string): Promise<Uint8Array>;
+/** The source in a PNG's `draftably` chunk, or null when it has none. */
+export declare function readPngSource(png: Uint8Array): Promise<string | null>;
+/** The `<metadata>` element that carries `source` in an SVG. */
+export declare const svgSourceElement: (source: string) => string;
+/** The SVG with `source` in a metadata element just inside its root. */
+export declare const embedSvgSource: (svg: string, source: string) => string;
+/** The source in an SVG's `draftably-source` metadata, or null when it has none. */
+export declare function readSvgSource(svg: string): string | null;
+/** The source embedded in PNG or SVG bytes, or null when there is none. */
+export declare function readImageSource(bytes: Uint8Array): Promise<string | null>;
+/** True for a file name the CLI and viewer read source out of. */
+export declare const isImageName: (name: string) => boolean;

package/dist/types/src/model/examples.d.ts

@@ -0,0 +1,15 @@
+export interface ExampleInfo {
+    id: string;
+    title: string;
+    /** The first comment in the file. */
+    summary: string;
+    source: string;
+    nodes: number;
+    groups: number;
+    edges: number;
+    /** Deepest container nesting: 0 for a flat diagram. */
+    depth: number;
+}
+/** All examples, flattest first, so the list reads as a ladder of nesting depth. */
+export declare const EXAMPLES: ExampleInfo[];
+export declare const findExample: (id: string) => ExampleInfo | undefined;

package/dist/types/src/model/font-faces.d.ts

@@ -0,0 +1,24 @@
+/** SHA-256 prefix of the metric table and its four WOFF2 files, in declared face order. */
+export declare const fontMetricsVersion = "269b2d3580f4";
+export declare const FACES: {
+    'sans-500': {
+        family: string;
+        weight: number;
+        file: string;
+    };
+    'sans-600': {
+        family: string;
+        weight: number;
+        file: string;
+    };
+    'serif-600': {
+        family: string;
+        weight: number;
+        file: string;
+    };
+    'mono-500': {
+        family: string;
+        weight: number;
+        file: string;
+    };
+};

package/dist/types/src/model/fonts.d.ts

@@ -0,0 +1,47 @@
+export type FontRole = 'sans' | 'serif' | 'mono';
+export declare const FONT_ROLES: FontRole[];
+export interface FontFace {
+    /** Registered family name; unique so an installed copy of the font is never used instead. */
+    family: string;
+    weight: number;
+    file: string;
+}
+export { FACES } from './font-faces';
+import { FACES } from './font-faces';
+export type FaceId = keyof typeof FACES;
+/** Face used for each role: titles are a little heavier than annotations in sans-serif. */
+export declare const faceFor: (role: FontRole, title: boolean) => FaceId;
+export declare const fontStack: (role: FontRole) => string;
+/** A text style: which face, at what size and line height. */
+export interface TypeProfile {
+    role: FontRole;
+    face: FaceId;
+    family: string;
+    weight: number;
+    size: number;
+    lineHeight: number;
+}
+export declare function typeProfile(role: FontRole, title: boolean, size: number, lineHeight: number): TypeProfile;
+/**
+ * Width of `text` in `profile`, from the stored advance widths. Kerning is ignored, which only
+ * ever overstates a width slightly, so measured text fits where this says it fits.
+ */
+export declare function measureText(text: string, profile: Pick<TypeProfile, 'face' | 'size'>): number;
+/**
+ * The pieces an identifier reads in, so a long one can break where a reader would: after a
+ * separator (`/`, `.`, `_`, `-`, `:`) or between a lower-case letter or digit and a capital
+ * (camelCase). `annotationCommands` → `annotation`, `Commands`; `src/viz/Treemap.tsx` → `src/`,
+ * `viz/`, `Treemap.tsx`. A word with none of these is one piece.
+ */
+export declare function wordPieces(word: string): string[];
+/** Width of the widest piece of any word in `text`: the narrowest line it wraps into whole. */
+export declare function widestPiece(text: string, profile: Pick<TypeProfile, 'face' | 'size'>): number;
+/**
+ * Break text into lines no wider than `width`, starting a new line at each `\n`. A word longer
+ * than a line breaks between its pieces (`wordPieces`), and only a piece that is itself too long
+ * breaks by character. With `balance`, a paragraph that wraps keeps its line count but its lines
+ * run near equal (`even`), so no word sits alone on the last line when a better break exists.
+ */
+export declare function wrapLines(text: string, width: number, profile: TypeProfile, balance?: boolean): string[];
+/** Shorten text with an ellipsis so it fits in `width`. */
+export declare function truncateText(text: string, width: number, profile: TypeProfile): string;

package/dist/types/src/model/footnote.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Footnotes: a block of short entries between the drawing and the key, from `footnote`
+ * statements, in file order, at body text size and wrapped to the frame. An entry may carry a
+ * marker (`1`, `a`, `*`) that a label can point at, and links in `[label](href)` form. The viewer,
+ * `inspect --svg`, PDF and the editor's exports all lay it out here.
+ */
+import { type ResolvedAppearance } from './appearance';
+import { type Run } from './rich-text';
+export interface Footnote {
+    text: string;
+    /** A short marker drawn before the entry, which labels can point at as `[1]`. */
+    mark?: string;
+}
+/** The block's entries, wrapped to `width`, with their offsets from its top-left corner. */
+export declare function footnoteSize(look: ResolvedAppearance, notes: readonly Footnote[], width: number): {
+    type: import("./fonts").TypeProfile;
+    gutter: number;
+    items: {
+        note: Footnote;
+        lines: Run[][];
+        y: number;
+    }[];
+    h: number;
+};
+export type FootnoteLayout = ReturnType<typeof footnoteSize>;
+/** Where each line of every entry is drawn, from the block's top-left corner at (x, y). */
+export declare function footnoteLines(layout: FootnoteLayout, x: number, y: number): {
+    entry: number;
+    runs: Run[];
+    x: number;
+    y: number;
+}[];
+/** SVG markup for the block: a short rule, then each entry's marker and wrapped text. */
+export declare function footnoteMarkup(look: ResolvedAppearance, layout: FootnoteLayout, x: number, y: number, write?: (href: string) => string | null): string;

package/dist/types/src/model/frame.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The frame round a diagram: the heading above the drawing and the key under it. `inspect --svg`,
+ * the editor's exports and the viewer canvas all place them from here, so what the viewer shows is
+ * what an export draws.
+ */
+import type { Heading, LegendEntry, ResolvedAppearance } from './appearance';
+import { type Footnote } from './footnote';
+import type { PlacedNote } from './note';
+import type { Rect } from './types';
+import type { StatusCount } from './status';
+/** Space between the frame's edge and the drawing; the heading and the key align to it. */
+export declare const FRAME_PAD = 40;
+/** Narrowest frame a `diagram width=` line or a drag can set. */
+export declare const MIN_FRAME_WIDTH = 160;
+/**
+ * Lay out the frame round `area`, the drawing with `FRAME_PAD` already round it. The heading sits
+ * above the area and the key at its bottom, both left-aligned with the drawing; footnotes sit
+ * between the drawing and the key, wrapped to the frame. Frame notes stack
+ * under the heading, and the area grows to hold anchored notes (`placeNotes`). The frame is at
+ * least as wide as the heading, the notes, the key and the heading's `width`; extra width goes to
+ * the right.
+ */
+export declare function diagramFrame(look: ResolvedAppearance, heading: Heading | undefined, legend: LegendEntry[], statuses: StatusCount[], drawing: Rect, notes?: readonly PlacedNote[], footnotes?: readonly Footnote[]): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** Width without the heading's `width`, which a drag never narrows past. */
+    natural: number;
+    head: {
+        w: number;
+        h: number;
+    };
+    key: {
+        w: number;
+        h: number;
+        row: number;
+        items: {
+            x: number;
+            y: number;
+            legend?: LegendEntry;
+            status?: StatusCount;
+            label: string;
+        }[];
+    };
+    heading: {
+        x: number;
+        y: number;
+        wrap: number;
+    };
+    legend: {
+        x: number;
+        y: number;
+    };
+    /** The footnote block's top-left corner and layout. */
+    foot: {
+        x: number;
+        y: number;
+        type: import("./fonts").TypeProfile;
+        gutter: number;
+        items: {
+            note: Footnote;
+            lines: import("./rich-text").Run[][];
+            y: number;
+        }[];
+        h: number;
+    };
+    /** Every note, placed. */
+    notes: PlacedNote[];
+};
+export type DiagramFrame = ReturnType<typeof diagramFrame>;

package/dist/types/src/model/geometry.d.ts

@@ -0,0 +1,29 @@
+import type { Point, Rect } from './types';
+export declare const clamp: (n: number, min: number, max: number) => number;
+export declare const finite: (n: unknown) => n is number;
+/** Document coordinates are stored with one decimal place. */
+export declare const rounded: (n: number) => number;
+export declare const center: (r: Rect) => Point;
+export declare const manhattan: (a: Point, b: Point) => number;
+export declare const inside: (p: Point, r: Rect, pad?: number) => boolean;
+export declare const contains: (outer: Rect, inner: Rect) => boolean;
+export declare const overlaps: (a: Rect, b: Rect, pad?: number) => boolean;
+/** Bounding box of the given rectangles, or a placeholder area when there are none. */
+export declare function rectUnion(rects: readonly Rect[], pad?: number): Rect;
+/** Rectangle spanned by two corner points. */
+export declare const rectFromPoints: (a: Point, b: Point) => Rect;
+export type Segment = [Point, Point];
+export declare const segments: (points: readonly Point[]) => Segment[];
+export declare const shrink: (r: Rect, d: number) => Rect;
+/** Overlap of two rectangles larger than half a pixel on both axes. */
+export declare const covers: (a: Rect, b: Rect) => boolean;
+/** Length of a segment inside a rectangle (Liang–Barsky clipping). */
+export declare function segmentInside([a, b]: Segment, r: Rect): number;
+/** SVG path for an orthogonal polyline with rounded corners. */
+export declare function roundedPath(points: readonly Point[], radius: number): string;
+export declare const clone: <T>(value: T) => T;
+/**
+ * A rectangle whose left and right sides are zigzags, for a field of variable length: the reader
+ * sees it continue past what is drawn.
+ */
+export declare function brokenRectPath(r: Rect, step?: number, depth?: number): string;

package/dist/types/src/model/graph.d.ts

@@ -0,0 +1,53 @@
+import type { Diagram, DiagramEdge, DiagramGroup, DiagramNode, Direction, Entity, NodeLayout, NodeStyle, Rect } from './types';
+export declare const findNode: (doc: Diagram, id: string | null | undefined) => DiagramNode | undefined;
+export declare const findGroup: (doc: Diagram, id: string | null | undefined) => DiagramGroup | undefined;
+export declare const findEdge: (doc: Diagram, id: string | null | undefined) => DiagramEdge | undefined;
+export declare const findObject: (doc: Diagram, id: string | null | undefined) => DiagramNode | DiagramGroup | undefined;
+export declare const findEntity: (doc: Diagram, id: string | null | undefined) => Entity | undefined;
+export declare const isNode: (doc: Diagram, id: string) => boolean;
+export declare const isGroup: (doc: Diagram, id: string) => boolean;
+export declare const isEdge: (doc: Diagram, id: string) => boolean;
+export declare const styleOf: (doc: Diagram, id: string) => NodeStyle;
+/** Direct children (shapes and containers) of a container, or of the diagram root. */
+/** The title band of a `cells` group; undefined for any other group. */
+export declare const cellsBandOf: (doc: Diagram, id: string | null | undefined) => number | undefined;
+/** Whether a cell is a field of variable length in a byte or bit layout. */
+export declare const isOpenCell: (doc: Diagram, id: string) => boolean;
+/** Whether a node is a cell of a `cells` group, which holds it in place edge to edge. */
+export declare const isCell: (doc: Diagram, id: string) => boolean;
+export declare function childrenOf(doc: Diagram, parentId: string | null | undefined): (DiagramNode | DiagramGroup)[];
+export declare function descendants(doc: Diagram, id: string): string[];
+/** Containers enclosing an object, nearest first. */
+export declare function ancestors(doc: Diagram, id: string): string[];
+export declare const isCollapsed: (doc: Diagram, id: string) => boolean;
+export declare const isHiddenByCollapse: (doc: Diagram, id: string) => boolean;
+/** The visible object that stands in for `id`: its outermost collapsed container, if any. */
+export declare function visibleProxy(doc: Diagram, id: string): string;
+export interface VisibleEdge extends DiagramEdge {
+    /** Visible source, which may be a collapsed container. */
+    a: string;
+    /** Visible target, which may be a collapsed container. */
+    b: string;
+}
+export interface VisibleGraph {
+    nodes: DiagramNode[];
+    groups: DiagramGroup[];
+    edges: VisibleEdge[];
+}
+/** Objects and connections that are not hidden inside a collapsed container. */
+export declare function visibleGraph(doc: Diagram): VisibleGraph;
+/** Selected shapes and containers whose own container is not also selected. */
+export declare function selectionRoots(doc: Diagram, selected: Iterable<string>): string[];
+/** Layout direction for the contents of an object's container. */
+export declare function inheritedDirection(doc: Diagram, id: string): Direction;
+export declare const COLLAPSED_HEIGHT = 58;
+export declare const CONTAINER_HEADER = 28;
+/** Read geometry for an object, preferring a temporary override (preview, animation, brush). */
+export type GeometryLookup = (id: string) => NodeLayout;
+export declare function makeGeometry(doc: Diagram, override?: Record<string, NodeLayout> | null): (id: string) => NodeLayout;
+/**
+ * Container frame as drawn: collapsed containers shrink to their title band plus a line for the
+ * shape count, so the title stays where it was in the open frame.
+ */
+export declare function frameRect(doc: Diagram, geometry: GeometryLookup, id: string): NodeLayout;
+export declare const objectRect: (doc: Diagram, geometry: GeometryLookup, id: string) => Rect;

package/dist/types/src/model/heading.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The title and subtitle drawn above an exported diagram, shared by `inspect --svg` and the
+ * editor's export, so a copied image still says what it shows.
+ */
+import type { Heading, ResolvedAppearance } from './appearance';
+/** Title type: the theme's title face, larger; subtitle type: its annotation face. */
+declare function types(look: ResolvedAppearance): {
+    title: import("./fonts").TypeProfile;
+    subtitle: import("./fonts").TypeProfile;
+};
+/**
+ * Width the subtitle wraps to over a drawing `room` wide: the drawing's width, held between 360px
+ * and about 70 characters, so a long subtitle wraps instead of widening the frame.
+ */
+export declare function subtitleMeasure(look: ResolvedAppearance, room: number): number;
+/** Size of the heading block, including the gap under it. Zero when there is nothing to draw. */
+export declare function headingSize(look: ResolvedAppearance, heading: Heading | undefined, wrap: number): {
+    w: number;
+    h: number;
+};
+/**
+ * Each line of the heading with its own type and box, top-left corner at (x, y). The title is one
+ * line; the subtitle wraps to `wrap` (`subtitleMeasure`).
+ */
+export declare function headingLines(look: ResolvedAppearance, heading: Heading | undefined, x: number, y: number, wrap: number): {
+    key: "title" | "subtitle";
+    text: string;
+    type: Type;
+    fill: string;
+    x: number;
+    y: number;
+}[];
+type Type = ReturnType<typeof types>['title'];
+/** SVG markup for the heading with its top-left corner at (x, y). */
+export declare function headingMarkup(look: ResolvedAppearance, heading: Heading | undefined, x: number, y: number, wrap: number): string;
+/** Title and subtitle type, for drawing and editing them in the viewer. */
+export declare const headingTypes: typeof types;
+export {};

package/dist/types/src/model/icons.d.ts

@@ -0,0 +1,2 @@
+/** SVG path data for interface and shape icons, drawn on a 24×24 grid. */
+export declare const ICONS: Record<string, string>;

package/dist/types/src/model/label-hits.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Where a drawing's text cannot be read: a connection label on another label, a shape, a group's
+ * title or a line, and a shape title too long for its shape. Compare counts these for each
+ * candidate and marks them on its card, so this has to stay cheap and read only the drawn scene.
+ */
+import { type ResolvedAppearance } from './appearance';
+import type { DrawnRoute } from './routes';
+import type { StaticScene } from './static-scene';
+import type { DiagramGroup, Rect } from './types';
+/** Connection labels as boxes. Labels are centred on their spot. */
+export declare const labelBoxes: (routes: readonly DrawnRoute[]) => {
+    route: DrawnRoute;
+    box: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}[];
+/** A group's title: its icon and text, as the canvas draws them. */
+export declare function groupTitleInk(g: DiagramGroup, r: Rect, look: ResolvedAppearance): Rect;
+export interface LabelHit {
+    /** What cannot be read, and where to mark it. */
+    box: Rect;
+    note: string;
+}
+export declare function labelHits(scene: StaticScene): LabelHit[];

package/dist/types/src/model/labels.d.ts

@@ -0,0 +1,88 @@
+import { type ResolvedAppearance } from './appearance';
+import { type TypeProfile } from './fonts';
+import type { Diagram, LabelMode, Rect, ShapeKind } from './types';
+/**
+ * Room for a shape's title. Every size, wrap and overflow decision goes through these functions,
+ * in the compiler, the canvas and the CLI alike.
+ */
+export interface TitleArea {
+    /** Line width available to the title. */
+    width: number;
+    /** Tallest text block that fits inside the shape at its current height. */
+    maxHeight: number;
+}
+export declare function titleArea(shape: ShapeKind, w: number, h: number, r: ResolvedAppearance, icon?: boolean): TitleArea;
+/** Height a shape needs for `lines` title lines; never less than `base`. */
+export declare function titleHeight(shape: ShapeKind, lines: number, base: number, r: ResolvedAppearance): number;
+/** A shape's title in balanced lines no wider than `width` (see `wrapLines`). */
+export declare const wrapTitle: (text: string, width: number, r: ResolvedAppearance) => string[];
+/**
+ * Line width for a diamond's title, `s` its side. A text block W wide and H tall fits inside a
+ * square diamond when W + H <= s, so this takes the widest measure whose wrapped lines still fit:
+ * the title reads in as few lines as the shape allows. Undefined when no measure fits.
+ */
+export declare function diamondMeasure(title: string, s: number, r: ResolvedAppearance): number | undefined;
+/** Most lines a group title wraps to; past that the frame widens instead. */
+export declare const GROUP_TITLE_LINES = 3;
+/** A group's header height when its title takes `lines` lines. */
+export declare const groupHeaderFor: (r: ResolvedAppearance, lines?: number) => number;
+/**
+ * A group title as drawn in a frame `w` wide: wrapped to at most `lines` lines (the compiler
+ * reserves that many), the last shortened with an ellipsis if the text runs on.
+ */
+export declare function groupTitleLines(title: string, w: number, r: ResolvedAppearance, lines?: number): string[];
+export interface NodeLabel {
+    /** Center of the label, relative to the shape's top-left corner. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    lines: string[];
+    mode: LabelMode;
+    lineHeight: number;
+    leader: boolean;
+}
+/** Where a shape's title is drawn, relative to the shape. */
+export declare function nodeLabel(doc: Diagram, id: string, title: string, r: Rect): NodeLabel;
+/** Bounds of a shape together with its label. */
+export declare function visualBounds(doc: Diagram, id: string, title: string, r: Rect): Rect;
+/** Text width a sequence message's label wraps to; the gap between participants follows it. */
+export declare const MESSAGE_WRAP = 168;
+/**
+ * The type a connection label is set in: the annotation type, or a step larger for a sequence
+ * message (`message`), whose label is the main thing to read.
+ */
+export declare const edgeLabelType: (r: ResolvedAppearance, message?: boolean) => TypeProfile;
+/**
+ * Text width a flow line's label wraps to: about 24 characters of the annotation type, so a short
+ * phrase stays on one line and a sentence stacks instead of widening its gap.
+ */
+export declare const LABEL_WRAP = 140;
+/**
+ * A connection label's lines: split at each `\n` and wrapped to `LABEL_WRAP`, or a sequence
+ * message's to `MESSAGE_WRAP`.
+ */
+export declare const edgeLabelLines: (label: string, r: ResolvedAppearance, message?: boolean) => string[];
+/**
+ * A self-message's loop: its run out to the right of the lifeline and its drop. Its label sits
+ * `label` past the loop, centred on the drop.
+ */
+export declare const SELF_LOOP: {
+    out: number;
+    down: number;
+    label: number;
+};
+/** Box for a connection label in the diagram's annotation type. */
+export declare function edgeLabelSize(label: string, r?: ResolvedAppearance, message?: boolean): {
+    w: number;
+    h: number;
+};
+/**
+ * What a self-message draws, measured from where its row meets the lifeline: how far right, how
+ * far above the row and how far below it.
+ */
+export declare function selfMessageInk(label: string | undefined, r: ResolvedAppearance): {
+    right: number;
+    above: number;
+    below: number;
+};

package/dist/types/src/model/legend.d.ts

@@ -0,0 +1,25 @@
+/** The color key drawn under an exported diagram, shared by `inspect --svg` and the editor's export. */
+import { type LegendEntry, type ResolvedAppearance } from './appearance';
+import { type StatusCount } from './status';
+/** The removed marker, a minus in a disc of radius `r`, centred at (x, y). */
+export declare const markerMarkup: (x: number, y: number, ink: string, canvas: string, r?: number) => string;
+/**
+ * Lay out the key: every `legend` entry, then every change mark used with its count, left to
+ * right, starting a new row only where the next entry would pass `max`. A short key is one row
+ * under the drawing. Zero size when there is nothing to show.
+ */
+export declare function legendSize(look: ResolvedAppearance, legend?: LegendEntry[], statuses?: StatusCount[], max?: number): {
+    w: number;
+    h: number;
+    row: number;
+    items: {
+        x: number;
+        y: number;
+        legend?: LegendEntry;
+        status?: StatusCount;
+        label: string;
+    }[];
+};
+export type LegendLayout = ReturnType<typeof legendSize>;
+/** SVG markup for the key laid out by `legendSize`, with its top-left corner at (x, y). */
+export declare function legendMarkup(look: ResolvedAppearance, key: LegendLayout, x: number, y: number): string;