@draftably/editor 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,209 @@
+/**
+ * Diagram appearance: five preset themes, color families with numeric shades, and the overrides a
+ * file can set. `resolveAppearance` turns a saved appearance into the concrete colors, spacing and
+ * type that sizing, the canvas and both SVG exports read, so all of them agree.
+ *
+ * Diagram appearance is separate from the editor's light or dark mode.
+ */
+import type { Footnote } from './footnote';
+import type { Note } from './note';
+import { type FontRole, type TypeProfile } from './fonts';
+import type { FileConfig } from './link';
+export type ThemeId = 'drafting' | 'fieldnotes' | 'signal' | 'ink' | 'blueprint';
+export declare const THEME_IDS: ThemeId[];
+export declare const DEFAULT_THEME: ThemeId;
+/** Shade stops. Lower numbers are lighter and higher numbers darker, in every theme. */
+export declare const SHADES: readonly [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+export type Shade = (typeof SHADES)[number];
+export declare const isShade: (n: unknown) => n is Shade;
+/** Shade of a node that names a color without a shade. */
+export declare const NODE_SHADE: Shade;
+/**
+ * Shade of a group that names a color without a shade. Groups are quiet surfaces behind nodes, so
+ * this is a pale shade in light themes and a deep one in dark themes; the scale itself never flips.
+ */
+export declare const groupShadeFor: (theme: ThemeId) => Shade;
+/** Built-in color families, available in every theme. `primary` and `secondary` follow the theme. */
+export declare const BUILT_IN_FAMILIES: readonly ["primary", "secondary", "slate", "stone", "blue", "sky", "teal", "mint", "green", "amber", "orange", "red", "rose", "violet"];
+export declare const isBuiltInFamily: (name: string) => boolean;
+export interface Swatch {
+    fill: string;
+    stroke: string;
+    ink: string;
+}
+/** A file's color declaration: one shade of a family. Built-in shades may set some fields only. */
+export interface ColorDefinition {
+    family: string;
+    shade: Shade;
+    fill?: string;
+    stroke?: string;
+    ink?: string;
+}
+export interface AppearanceOverrides {
+    paddingX?: number;
+    paddingY?: number;
+    radius?: number;
+    titleFont?: FontRole;
+    annotationFont?: FontRole;
+    canvas?: string;
+    text?: string;
+    connection?: string;
+}
+export interface DiagramAppearance {
+    theme: ThemeId;
+    overrides: AppearanceOverrides;
+    colors: ColorDefinition[];
+    /** What the colors mean, from `legend` statements, drawn as a key beside the diagram. */
+    legend?: LegendEntry[];
+    /** Title and subtitle drawn above exported images, from `diagram` and `subtitle` statements. */
+    heading?: Heading;
+    /** Sentences drawn on the diagram without moving it, from `note` statements. */
+    notes?: Note[];
+    /** Entries of the block between the drawing and the key, from `footnote` statements. */
+    footnotes?: Footnote[];
+    /** Panel labels from a `compare` statement: draw the old and new versions side by side. */
+    compare?: {
+        /** Set by `draftably compare`: the changes the older panel draws in their new version. */
+        undrawn?: string;
+        before: string;
+        after: string;
+        /** `right` sets the panels side by side, `down` stacks them; chosen by `aspect` when unset. */
+        direction?: 'right' | 'down';
+        /** Width over height the whole image should come closest to; 1.6 when unset. */
+        aspect?: number;
+    };
+    /** File settings from `config` statements. */
+    config?: FileConfig;
+    /** Named emphasis states from `state` statements, in file order. */
+    states?: EmphasisState[];
+}
+/** One way to draw the diagram: these objects and connections in focus, the rest faded or plain. */
+export interface EmphasisState {
+    id: string;
+    label: string;
+    /** Objects (a group brings its members) and connections in focus. */
+    ids: string[];
+    /** How everything else draws: faded like a context line, or as usual. */
+    rest: 'dim' | 'plain';
+}
+export interface Heading {
+    title?: string;
+    subtitle?: string;
+    /** Width of the frame round the drawing, from `diagram width=`; never narrower than its content. */
+    width?: number;
+}
+/** The connection styles a `legend line` row can explain. */
+export declare const LEGEND_LINES: readonly ["dashed", "solid"];
+export type LegendLine = (typeof LEGEND_LINES)[number];
+/** One row of the key: a color swatch (`family`), or a short connection (`line`). */
+export interface LegendEntry {
+    family?: string;
+    line?: LegendLine;
+    /** Shade of the swatch; nodes' default when omitted. */
+    shade?: Shade;
+    label: string;
+}
+export declare const defaultAppearance: () => DiagramAppearance;
+/** Limits for numeric overrides, shared by the file parser and JSON validation. */
+export declare const OVERRIDE_LIMITS: {
+    readonly paddingX: {
+        readonly min: 4;
+        readonly max: 48;
+    };
+    readonly paddingY: {
+        readonly min: 4;
+        readonly max: 48;
+    };
+    readonly radius: {
+        readonly min: 0;
+        readonly max: 24;
+    };
+};
+export declare const HEX_COLOR: RegExp;
+interface Preset {
+    label: string;
+    description: string;
+    dark: boolean;
+    canvas: string;
+    text: string;
+    muted: string;
+    connection: string;
+    node: Swatch;
+    group: Swatch;
+    paddingX: number;
+    paddingY: number;
+    radius: number;
+    shadow: boolean;
+    titleFont: FontRole;
+    annotationFont: FontRole;
+    titleSize: number;
+    titleLine: number;
+    annotationSize: number;
+    /** Chroma multiplier for the built-in families: how saturated this theme's colors are. */
+    chroma: number;
+    /** Anchor colors for `primary` and `secondary`, at the shade they appear as. */
+    primary: [string, Shade];
+    secondary: [string, Shade];
+    /** Hue and chroma for built-in families this theme draws in its own way. */
+    hues?: Partial<Record<string, [number, number]>>;
+}
+export declare const PRESETS: Record<ThemeId, Preset>;
+export declare function contrast(a: string, b: string): number;
+/** Contrast targets (WCAG ratios) every generated color meets. */
+export declare const CONTRAST: {
+    /** Dark title text on a pale fill. */
+    readonly paleInk: 7;
+    /** White title text on a dark fill. */
+    readonly darkInk: 4.5;
+    /** A shape's outline against the canvas when its fill alone does not separate it. */
+    readonly outline: 3;
+    /** Connection lines and connection label text against the canvas. */
+    readonly connection: 4.5;
+    /** A group's frame against the canvas. */
+    readonly frame: 2;
+};
+/**
+ * Move a color's lightness away from `against` until it reaches `min` contrast with it. Colors
+ * that already meet the target are returned unchanged.
+ */
+export declare function ensureContrast(color: string, against: string, min: number): string;
+/** The built-in families of a preset on a canvas color, generated once. */
+export declare function builtInFamilies(theme: ThemeId, canvas?: string): Map<string, Map<Shade, Swatch>>;
+export interface ResolvedAppearance {
+    theme: ThemeId;
+    dark: boolean;
+    canvas: string;
+    text: string;
+    muted: string;
+    connection: string;
+    /** Default node and group colors when nothing names a family. */
+    node: Swatch;
+    group: Swatch;
+    paddingX: number;
+    paddingY: number;
+    radius: number;
+    shadow: boolean;
+    title: TypeProfile;
+    groupTitle: TypeProfile;
+    annotation: TypeProfile;
+    /** Space above a group's content; the group title sits in it. */
+    groupHeader: number;
+    /** Every family and the shades it defines: built-in ones plus the file's own. */
+    families: Map<string, Map<Shade, Swatch>>;
+    custom: Set<string>;
+    /** Strike a removed object's title through (`config strike-removed=on`). */
+    strikeRemoved: boolean;
+}
+/** Height of a group's title band, derived from the title's line height. */
+export declare const groupHeaderFor: (lineHeight: number) => number;
+/** Preset values, then file overrides. Omitted fields inherit from the preset. */
+export declare function resolveAppearance(appearance?: DiagramAppearance): ResolvedAppearance;
+/**
+ * Colors for an object. `family` is a family name, or `auto` for the theme's default surface; an
+ * omitted shade is 500 for nodes and 100 for groups. Unknown families or shades fall back to the
+ * default surface; the file parser reports them before they get here.
+ */
+export declare function swatchFor(r: ResolvedAppearance, family: string | undefined, shade: Shade | undefined, kind?: 'node' | 'group'): Swatch;
+/** Shades a family defines, in numeric order. */
+export declare const shadesOf: (r: ResolvedAppearance, family: string) => Shade[];
+export {};

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

@@ -0,0 +1,19 @@
+import type { VisibleGraph } from './graph';
+import type { Diagram, Point, Rect } from './types';
+/** How far a connection's ink reaches past its points: half the stroke plus the arrowhead's wings. */
+export declare const ROUTE_INK = 4;
+export interface BoundedRoute {
+    id?: string;
+    points: readonly Point[];
+    label: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+}
+/**
+ * Bounds of everything drawn: shapes with their labels, containers, every route point with its
+ * stroke and arrowhead, and every connection label box. `pad` adds a margin on each side.
+ */
+export declare function drawingBounds(doc: Diagram, vg: VisibleGraph, rects: ReadonlyMap<string, Rect>, routes: readonly BoundedRoute[], pad?: number): Rect;

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

@@ -0,0 +1,21 @@
+import type { Rect } from './types';
+/** A camera described by the world point at the viewport center and a zoom factor. */
+export interface ViewCamera {
+    cx: number;
+    cy: number;
+    k: number;
+}
+/** Camera that fits `bounds` inside `viewport` with padding, or null for a hidden viewport. */
+export declare function fitCamera(bounds: Rect, viewport: {
+    width: number;
+    height: number;
+} | undefined, padding?: number): ViewCamera | null;
+/**
+ * The zoom factor for one wheel event. A mouse notch (about 100px) zooms by about 18%; a pinch,
+ * which arrives as small Ctrl + wheel deltas, keeps its faster rate. `unit` converts line and
+ * page deltas to pixels.
+ */
+export declare function wheelZoomFactor(e: {
+    deltaY: number;
+    ctrlKey: boolean;
+}, unit?: number): number;

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

@@ -0,0 +1,22 @@
+/**
+ * The colors an object is drawn in. A file names a family and maybe a shade; drawing adds one
+ * rule on top, so nesting stays readable without the author doing shade arithmetic:
+ *
+ * - A container inside a container of the same family steps one shade toward emphasis per level
+ *   (lighter frames underneath, smaller and stronger ones on top), instead of repeating the fill.
+ * - A shape whose shade is within two steps of its container's, in the same family, moves three
+ *   steps past the container, so a member never melts into its frame.
+ *
+ * The canvas, the CLI's SVG and exports all draw through `drawnSwatch`.
+ */
+import { type ResolvedAppearance, type Shade, type Swatch } from './appearance';
+import type { Diagram } from './types';
+/** The shade an object is drawn at, or undefined for the theme's neutral surface. */
+export declare function drawnShade(doc: Diagram, look: ResolvedAppearance, id: string): Shade | undefined;
+/** The swatch an object is drawn with. */
+export declare function drawnSwatch(doc: Diagram, look: ResolvedAppearance, id: string, kind: 'node' | 'group'): Swatch;
+/**
+ * A sequence participant's accent: the fill its color would have, drawn as a thin stripe along
+ * its top. Undefined for anything else, and for a participant with no color of its own.
+ */
+export declare function participantAccent(doc: Diagram, look: ResolvedAppearance, id: string): string | undefined;

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

@@ -0,0 +1,24 @@
+import { type DiagramAppearance } from './appearance';
+import type { Diagram, DiagramSettings } from './types';
+export declare const MAX_NODES = 500;
+export declare const MAX_EDGES = 1200;
+export declare function uid(prefix?: string): string;
+export declare const DEFAULT_SETTINGS: DiagramSettings;
+export declare function emptyDiagram(title?: string): Diagram;
+type Raw = any;
+export declare const isLegacyDiagram: (input: Raw) => boolean;
+/**
+ * Validate a diagram from any source and return a complete, canonical copy.
+ * Throws a readable error for anything that cannot be repaired.
+ */
+export declare function normalize(input: unknown): Diagram;
+/** Validate a saved appearance. A missing appearance is the default theme. */
+export declare function normalizeAppearance(input: Raw): DiagramAppearance;
+/** The meaning of a document, ignoring where the camera happens to be. */
+export declare function documentIdentity(doc: Diagram): string;
+/**
+ * Inputs that affect connection routing. The editor store keeps the key order of the document it
+ * replaced, so the worker's freshly projected copy of the same document lists its keys differently.
+ */
+export declare function routingFingerprint(doc: Diagram): string;
+export {};

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/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;