@zuilib/text-editor 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -4,7 +4,33 @@ import { LexicalEditor, TextFormatType, ElementNode, NodeKey, EditorConfig, Seri
 import { TableNode } from '@lexical/table';
 import { MultilineElementTransformer, ElementTransformer } from '@lexical/markdown';
 
+/**
+ * Horizontal sizing of a block that would otherwise span the editor:
+ *
+ * - `full` — the container width (the content pane, minus its gutters).
+ *   The default; omitted when serialised.
+ * - `text` — the text column: the block's edges align with the paragraphs
+ *   around it. Only differs from `full` when a measure is set
+ *   (`--zui-text-editor-measure` / the `measure` prop); otherwise the two
+ *   are visually identical.
+ * - `content` — shrinks to fit what is inside (table columns, drawing
+ *   shapes), left-aligned with the text and never wider than the column.
+ */
+type BlockWidth = 'full' | 'text' | 'content';
+declare const BLOCK_WIDTHS: readonly BlockWidth[];
+declare function isBlockWidth(value: unknown): value is BlockWidth;
+/**
+ * Width written into the markdown when a new table / drawing is inserted
+ * (`MarkdownEditor.Root`'s `defaultBlockWidth`). Only affects insertion:
+ * existing markdown without a width marker always means `full`.
+ */
+type BlockWidthDefaults = Readonly<{
+    table?: BlockWidth;
+    drawing?: BlockWidth;
+}>;
+
 type EditorMode = 'edit-raw' | 'edit-md' | 'view';
+
 type EditorRootProps = Readonly<{
     value?: string;
     onChange?: (value: string) => void;
@@ -12,6 +38,22 @@ type EditorRootProps = Readonly<{
     className?: string;
     mode?: EditorMode;
     autoFocus?: boolean;
+    /**
+     * Text measure: the maximum width of the text column, as a CSS length
+     * (`'48rem'` recommended). Text blocks are capped at this width and
+     * centred; tables and drawings choose per block whether to align with
+     * the column (`text`), span the pane (`full`) or hug their content.
+     * Sugar for setting `--zui-text-editor-measure` on the root; the
+     * variable can equally be set from a stylesheet. Unset: no measure, every
+     * block spans the pane.
+     */
+    measure?: string;
+    /**
+     * Width written into the markdown when the toolbar or
+     * `useMarkdownEditor()` inserts a new table / drawing. Only affects
+     * insertion — markdown without a width marker always means `full`.
+     */
+    defaultBlockWidth?: BlockWidthDefaults;
     children: ReactNode;
 }>;
 /**
@@ -19,7 +61,7 @@ type EditorRootProps = Readonly<{
  * beneath it (`Content`, `Toolbar`, `Outline`, or your own components using
  * `useMarkdownEditor`) shares the same editor instance.
  */
-declare function EditorRoot({ value, onChange, readOnly, className, mode, autoFocus, children, }: EditorRootProps): ReactElement;
+declare function EditorRoot({ value, onChange, readOnly, className, mode, autoFocus, measure, defaultBlockWidth, children, }: EditorRootProps): ReactElement;
 
 type EditorContentProps = Readonly<{
     placeholder?: string;
@@ -41,13 +83,6 @@ declare function EditorContent({ placeholder, foldable, children, }: EditorConte
  */
 declare function OutlinePlugin(): ReactElement;
 
-/**
- * Horizontal sizing of a block that would otherwise span the editor:
- * `full` stretches to the content column, `content` shrinks to fit what is
- * inside (table columns, drawing shapes) and left-aligns with the text.
- */
-type BlockWidth = 'full' | 'content';
-
 /** Cell padding / font size preset */
 type TableDensity = 'compact' | 'comfortable' | 'spacious';
 type TableSettings = Readonly<{
@@ -55,8 +90,14 @@ type TableSettings = Readonly<{
     density: TableDensity;
 }>;
 declare const DEFAULT_TABLE_SETTINGS: TableSettings;
+type TableSettingsOptions = Readonly<{
+    /** Persist the width even when it is `full` */
+    explicitWidth?: boolean;
+}>;
 declare function $getTableSettings(table: TableNode): TableSettings;
-declare function $setTableSettings(table: TableNode, settings: Partial<TableSettings>): void;
+declare function $setTableSettings(table: TableNode, settings: Partial<TableSettings>, options?: TableSettingsOptions): void;
+/** Whether the table's width should be persisted even when it is `full` */
+declare function $isTableWidthExplicit(table: TableNode): boolean;
 declare function $getTableWidth(table: TableNode): BlockWidth;
 declare function $setTableWidth(table: TableNode, width: BlockWidth): void;
 declare function $getTableDensity(table: TableNode): TableDensity;
@@ -65,10 +106,17 @@ declare function $setTableDensity(table: TableNode, density: TableDensity): void
 declare function $getSelectedTable(): TableNode | null;
 /** @deprecated Use `formatTableSettingsMarker({ ...DEFAULT_TABLE_SETTINGS, width: 'content' })` */
 declare const TABLE_WIDTH_MARKER = "<!-- width: content -->";
-/** Settings encoded in a marker line, or null if the text is not a marker */
+/**
+ * Settings encoded in a marker line, or null if the text is not a marker.
+ * A marker naming a known setting with an unknown value yields that setting
+ * omitted (possibly an empty object): the line is still a settings marker.
+ */
 declare function parseTableSettingsMarker(text: string): Partial<TableSettings> | null;
-/** Marker line for the given settings, or null when everything is default */
-declare function formatTableSettingsMarker(settings: TableSettings): string | null;
+/**
+ * Marker line for the given settings, or null when everything is default.
+ * With `explicitWidth` the width is listed even when it is `full`.
+ */
+declare function formatTableSettingsMarker(settings: TableSettings, options?: TableSettingsOptions): string | null;
 
 type MarkdownEditorApi = Readonly<{
     /** The underlying Lexical editor, for dispatching your own commands */
@@ -76,14 +124,40 @@ type MarkdownEditorApi = Readonly<{
     /** Text formats active at the current selection */
     activeFormats: ReadonlySet<TextFormatType>;
     toggleFormat: (format: TextFormatType) => void;
+    /**
+     * Insert a table at the selection. `width` defaults to
+     * `defaultBlockWidth.table` (Root prop); when given it is written to the
+     * markdown explicitly, even when `full`.
+     */
     insertTable: (options?: {
         rows?: number;
         columns?: number;
+        width?: BlockWidth;
     }) => void;
-    insertDrawing: () => void;
-    /** Width of the table containing the selection; `null` outside tables */
+    /**
+     * Insert an empty drawing at the selection. `width` defaults to
+     * `defaultBlockWidth.drawing` (Root prop); when given it is written to
+     * the markdown explicitly, even when `full`.
+     */
+    insertDrawing: (options?: {
+        width?: BlockWidth;
+    }) => void;
+    /**
+     * Width of the block containing the selection — the focused drawing, or
+     * else the table the caret is in; `null` outside both.
+     */
+    blockWidth: BlockWidth | null;
+    /** Resize that block; no-op when `blockWidth` is `null` */
+    setBlockWidth: (width: BlockWidth) => void;
+    /**
+     * Width of the table containing the selection; `null` outside tables.
+     * @deprecated Use `blockWidth`, which also covers drawings.
+     */
     tableWidth: BlockWidth | null;
-    /** Resize the table containing the selection; no-op outside tables */
+    /**
+     * Resize the table containing the selection; no-op outside tables.
+     * @deprecated Use `setBlockWidth`, which also covers drawings.
+     */
     setTableWidth: (width: BlockWidth) => void;
     /** Density of the table containing the selection; `null` outside tables */
     tableDensity: TableDensity | null;
@@ -210,14 +284,39 @@ declare function $isFrontmatterNode(node: LexicalNode | null | undefined): node
  */
 declare const FRONTMATTER: MultilineElementTransformer;
 
-type DrawingShapeType = 'rect' | 'ellipse' | 'triangle' | 'pentagon' | 'arrow' | 'line' | 'text';
+/** Card-like shapes: fillable, bindable, carrying the three text slots */
+type BoxType = 'rect' | 'ellipse' | 'diamond' | 'note' | 'cylinder' | 'cloud' | 'queue' | 'actor';
+type ConnectorType = 'arrow' | 'line';
+type DrawingShapeType = BoxType | ConnectorType | 'text';
+declare const BOX_TYPES: readonly BoxType[];
+declare const CONNECTOR_TYPES: readonly ConnectorType[];
+declare const SHAPE_TYPES: readonly DrawingShapeType[];
+type Point = Readonly<{
+    x: number;
+    y: number;
+}>;
+type BindingSide = 'top' | 'right' | 'bottom' | 'left';
+/**
+ * Where a connector endpoint attaches to a box.
+ *
+ * `fixedPoint` is a ratio inside the box's bounding box (`[0,0]` top-left,
+ * `[1,1]` bottom-right). Omitted = the box center, which makes the endpoint
+ * auto-aim at the other end. `mode: 'inside'` pins the endpoint exactly on
+ * the fixed point; the default (`'orbit'`) projects it onto the outline with
+ * a small gap.
+ */
+type Binding = Readonly<{
+    id: string;
+    fixedPoint?: readonly [number, number];
+    mode?: 'orbit' | 'inside';
+}>;
 type DrawingShape = Readonly<{
     id: string;
     type: DrawingShapeType;
-    /** Top-left corner (rect/ellipse/text) or start point (arrow/line) */
+    /** Top-left corner (boxes/text) or start point (connectors) */
     x: number;
     y: number;
-    /** Size (rect/ellipse) or delta to the end point (arrow/line) */
+    /** Size (boxes/text) or delta to the end point (connectors) */
     w: number;
     h: number;
     stroke: string;
@@ -229,44 +328,64 @@ type DrawingShape = Readonly<{
     label?: string;
     /** Small line rendered at the bottom of a box */
     footer?: string;
-    /** Arrow/line: id of the box the start point is attached to */
-    startBinding?: string;
-    /** Arrow/line: id of the box the end point is attached to */
-    endBinding?: string;
-    /** Arrow: render arrowheads on both ends */
+    /** Connector: box the start point is attached to */
+    startBinding?: Binding;
+    /** Connector: box the end point is attached to */
+    endBinding?: Binding;
+    /** Arrow: arrowheads on both ends */
     bidirectional?: boolean;
-    /** Connector routing: right-angled elbow path instead of a straight line */
+    /** Connector routing: right-angled auto-routed path instead of a straight line */
     routing?: 'elbow';
-    /** Elbow middle-segment position as a fraction of the span (default 0.5) */
+    /**
+     * Elbow override: position of the middle segment as a fraction of the
+     * span, applied only when the routed path is a simple three-segment Z.
+     */
     elbow?: number;
     /**
      * Connector: intermediate path points between start and end (absolute
      * canvas coordinates). Takes precedence over `routing`.
      */
-    waypoints?: ReadonlyArray<{
-        x: number;
-        y: number;
-    }>;
+    waypoints?: readonly Point[];
 }>;
 type DrawingData = Readonly<{
-    version: 1;
-    height: number;
+    version: 2;
+    /**
+     * Logical canvas width. When set the drawing is scaled to fit narrower
+     * layouts (SVG viewBox); when omitted the canvas is fluid and shapes are
+     * in CSS pixels.
+     */
+    canvasWidth?: number;
+    canvasHeight: number;
     /**
-     * Canvas width: `full` (default, omitted when serialized) spans the editor;
-     * `content` fits the shapes' horizontal extent.
+     * Block width: `full` (default) spans the editor; `text` aligns with the
+     * text column; `content` fits the shapes' horizontal extent. The editor
+     * omits `full` unless it was written explicitly (an insertion default or
+     * the source payload); unknown values are dropped.
      */
     width?: BlockWidth;
     shapes: readonly DrawingShape[];
 }>;
+declare const EMPTY_DRAWING: DrawingData;
+declare const STROKE_COLORS: readonly ["#1e1e1e", "#e03131", "#2f9e44", "#1971c2", "#f08c00", "#7048e8"];
+declare const FILL_COLORS: readonly ["transparent", "#ffc9c9", "#b2f2bb", "#a5d8ff", "#ffec99", "#d0bfff"];
+/** Edge midpoints, used by the ```diagram skeleton's `side` option */
+declare const SIDE_FIXED_POINTS: Record<BindingSide, readonly [number, number]>;
 declare function serializeDrawingData(data: DrawingData): string;
+/**
+ * Parse a ```drawing payload. Exactly one format is accepted: version 2 as
+ * written by the editor (the ```diagram skeleton is a separate block type,
+ * see skeleton.ts). Shapes that fail validation are dropped and a malformed
+ * document yields an empty canvas. Never throws.
+ */
 declare function parseDrawingData(json: string): DrawingData;
+declare function normalizeDrawingData(parsed: unknown): DrawingData;
 
 type SerializedDrawingNode = Spread<{
     data: string;
 }, SerializedLexicalNode>;
 /**
- * A block-level decorator node embedding a vector drawing (rectangles,
- * ellipses, arrows, lines, text) edited on an Excalidraw-style canvas.
+ * A block-level decorator node embedding a vector diagram (cards, connectors,
+ * text) edited on a canvas.
  *
  * The drawing is stored as a JSON string and round-trips through markdown as
  * a ```drawing fenced code block, so documents remain plain markdown.
@@ -295,44 +414,62 @@ declare function $isDrawingNode(node: LexicalNode | null | undefined): node is D
  * claims the fence first on import.
  */
 declare const DRAWING: MultilineElementTransformer;
+/**
+ * Import-only transformer for ```diagram blocks: a compact skeleton
+ * (boxes, connectors by id, auto layout) that expands into a full drawing.
+ * Once in the editor the node is a regular drawing and exports as
+ * ```drawing, so the expansion is one-way.
+ */
+declare const DIAGRAM: MultilineElementTransformer;
 
 /**
  * Markdown transformer for GFM tables. Adapted from the Lexical playground.
  * Rows are matched line-by-line on import and stitched into a single
  * TableNode; the divider row promotes the row above it to a header row.
- * A `<!-- width: content; density: compact -->` settings line directly
+ * A `<!-- width: text; density: compact -->` settings line directly
  * above the table (see tableSettings.ts) is consumed on import and
  * re-emitted on export.
  */
 declare const TABLE: ElementTransformer;
 
 /**
- * JSON Schema (draft-07) for the payload of a ```drawing fenced block.
+ * JSON Schema (draft-07) for the payload of a ```drawing fenced block
+ * (format version 2).
  *
  * Use it to validate LLM- or tool-generated drawings before embedding them,
  * or pass it as a structured-output / tool schema so a model is forced to
- * emit valid payloads. Kept in sync with `parseDrawingData` / `isValidShape`
- * in drawingTypes.ts — update both together.
+ * emit valid payloads. Kept in sync with `parseDrawingData` /
+ * `normalizeShape` in types.ts; update both together.
+ *
+ * For generation prefer the ```diagram skeleton
+ * (`DRAWING_SKELETON_JSON_SCHEMA`): it needs no coordinates and expands into
+ * this format on import.
  */
 declare const DRAWING_DATA_JSON_SCHEMA: {
     readonly $schema: "http://json-schema.org/draft-07/schema#";
     readonly title: "DrawingData";
-    readonly description: "Vector drawing embedded in markdown as a ```drawing fenced code block";
+    readonly description: "Vector drawing embedded in markdown as a ```drawing fenced code block (format version 2)";
     readonly type: "object";
-    readonly required: readonly ["version", "height", "shapes"];
+    readonly required: readonly ["version", "canvasHeight", "shapes"];
     readonly additionalProperties: false;
     readonly properties: {
         readonly version: {
-            readonly const: 1;
+            readonly const: 2;
+            readonly description: "Format version; always 2";
         };
-        readonly height: {
+        readonly canvasHeight: {
             readonly type: "number";
             readonly minimum: 80;
-            readonly description: "Canvas height in pixels";
+            readonly description: "Canvas height in pixels. Make it large enough to contain every shape plus ~20px margin.";
+        };
+        readonly canvasWidth: {
+            readonly type: "number";
+            readonly minimum: 120;
+            readonly description: "Optional logical canvas width in pixels. When set, the drawing is scaled down to fit narrower layouts (SVG viewBox) so coordinates can assume this width. When omitted the canvas is fluid and coordinates are CSS pixels.";
         };
         readonly width: {
-            readonly enum: readonly ["full", "content"];
-            readonly description: "Canvas width: \"full\" (default) spans the editor; \"content\" fits the shapes' horizontal extent and left-aligns with the text";
+            readonly enum: readonly ["full", "text", "content"];
+            readonly description: "Block width: \"full\" (default, omit it) spans the editor; \"text\" aligns the block with the text column (same as \"full\" unless the app sets a text measure); \"content\" fits the shapes' horizontal extent and left-aligns with the text";
         };
         readonly shapes: {
             readonly type: "array";
@@ -350,9 +487,38 @@ declare const DRAWING_DATA_JSON_SCHEMA: {
             readonly properties: {
                 readonly x: {
                     readonly type: "number";
+                    readonly description: "Absolute canvas x";
                 };
                 readonly y: {
                     readonly type: "number";
+                    readonly description: "Absolute canvas y";
+                };
+            };
+        };
+        readonly binding: {
+            readonly type: "object";
+            readonly description: "Where a connector endpoint attaches to a box. Omit fixedPoint to let the endpoint auto-aim from the box center at the other end.";
+            readonly required: readonly ["id"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly description: "Id of the box this endpoint is attached to";
+                };
+                readonly fixedPoint: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "number";
+                        readonly minimum: 0;
+                        readonly maximum: 1;
+                    };
+                    readonly minItems: 2;
+                    readonly maxItems: 2;
+                    readonly description: "Attach point as a ratio of the box's bounding box: [0,0] top-left, [1,1] bottom-right, [0.5,0] top edge midpoint, [1,0.5] right edge midpoint. Omitted: the endpoint auto-aims from the box center at the other end.";
+                };
+                readonly mode: {
+                    readonly enum: readonly ["orbit", "inside"];
+                    readonly description: "\"orbit\" (default): the endpoint is projected onto the box outline with a 6px gap. \"inside\": the endpoint sits exactly on the fixed point.";
                 };
             };
         };
@@ -366,7 +532,8 @@ declare const DRAWING_DATA_JSON_SCHEMA: {
                     readonly description: "Unique within the drawing; connector bindings reference it";
                 };
                 readonly type: {
-                    readonly enum: readonly ["rect", "ellipse", "triangle", "pentagon", "arrow", "line", "text"];
+                    readonly enum: readonly ["rect", "ellipse", "diamond", "note", "cylinder", "cloud", "queue", "actor", "arrow", "line", "text"];
+                    readonly description: "Boxes (cards with label/text/footer slots): rect, ellipse, diamond, note (sticky note with a folded corner), cylinder (database), cloud, queue (horizontal cylinder), actor (stick figure; only the text slot, rendered as a name under the figure). Connectors: arrow (head at the end), line. Free-floating annotation: text.";
                 };
                 readonly x: {
                     readonly type: "number";
@@ -386,11 +553,11 @@ declare const DRAWING_DATA_JSON_SCHEMA: {
                 };
                 readonly stroke: {
                     readonly type: "string";
-                    readonly description: "CSS color of the outline (and of any text)";
+                    readonly description: "CSS color of the outline (and of any text). Palette: #1e1e1e (default), #e03131 red, #2f9e44 green, #1971c2 blue, #f08c00 orange, #7048e8 purple.";
                 };
                 readonly fill: {
                     readonly type: "string";
-                    readonly description: "CSS color of the interior; \"transparent\" for none";
+                    readonly description: "CSS color of the interior; \"transparent\" for none. Palette: #ffc9c9 red, #b2f2bb green, #a5d8ff blue, #ffec99 yellow, #d0bfff purple.";
                 };
                 readonly strokeWidth: {
                     readonly type: "number";
@@ -398,23 +565,23 @@ declare const DRAWING_DATA_JSON_SCHEMA: {
                 };
                 readonly text: {
                     readonly type: "string";
-                    readonly description: "Standalone text content; center content of a box; midpoint label of a connector";
+                    readonly description: "Standalone text content; center content of a box (the name under an actor); midpoint label of a connector";
                 };
                 readonly label: {
                     readonly type: "string";
-                    readonly description: "Boxes only: small bold heading at the top";
+                    readonly description: "Boxes only (not actor): small bold heading at the top";
                 };
                 readonly footer: {
                     readonly type: "string";
-                    readonly description: "Boxes only: small dim line at the bottom";
+                    readonly description: "Boxes only (not actor): small dim line at the bottom";
                 };
                 readonly startBinding: {
-                    readonly type: "string";
-                    readonly description: "Connectors only: id of the box the start attaches to. The editor re-anchors the endpoint onto that box’s border.";
+                    readonly $ref: "#/definitions/binding";
+                    readonly description: "Connectors only: box the start point attaches to. The editor re-anchors the endpoint onto that box and keeps it attached as the box moves.";
                 };
                 readonly endBinding: {
-                    readonly type: "string";
-                    readonly description: "Connectors only: id of the box the end attaches to";
+                    readonly $ref: "#/definitions/binding";
+                    readonly description: "Connectors only: box the end point attaches to";
                 };
                 readonly bidirectional: {
                     readonly type: "boolean";
@@ -422,24 +589,390 @@ declare const DRAWING_DATA_JSON_SCHEMA: {
                 };
                 readonly routing: {
                     readonly const: "elbow";
-                    readonly description: "Connectors only: orthogonal (right-angled) auto-routing. Ignored when waypoints are present.";
+                    readonly description: "Connectors only: right-angled auto-routed path. It leaves the box perpendicular to the attach side, avoids every box on the canvas and minimises bends. Ignored when waypoints are present.";
                 };
                 readonly elbow: {
                     readonly type: "number";
                     readonly minimum: 0;
                     readonly maximum: 1;
-                    readonly description: "Elbow middle-segment position as a fraction of the span (default 0.5)";
+                    readonly description: "Elbow override: position of the middle segment as a fraction of the span. Applied only when the routed path is a simple three-segment Z.";
                 };
                 readonly waypoints: {
                     readonly type: "array";
                     readonly items: {
                         readonly $ref: "#/definitions/point";
                     };
-                    readonly description: "Connectors only: intermediate path points in canvas coordinates, ordered start→end. Takes precedence over routing.";
+                    readonly description: "Connectors only: intermediate path points in canvas coordinates, ordered start to end. Takes precedence over routing.";
+                };
+            };
+        };
+    };
+};
+
+type Rect = Readonly<{
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}>;
+
+declare function boxOutline(box: DrawingShape): Point[];
+/** Topmost box under a point, if any; smaller boxes win over enclosing ones */
+declare function findBoxAt(shapes: readonly DrawingShape[], point: Point, excludeId?: string, tolerance?: number): DrawingShape | null;
+/** The point a binding refers to: its fixed point, or the box center */
+declare function anchorPoint(box: DrawingShape, binding?: Binding): Point;
+/**
+ * Fixed point for a drop at `point`: undefined (auto-aim) for drops near
+ * the center, otherwise a ratio snapped onto the nearest bounding-box edge.
+ */
+declare function fixedPointFor(box: DrawingShape, point: Point): [number, number] | undefined;
+/**
+ * Recompute the endpoints of every bound connector from the current
+ * positions of the boxes they're attached to, and drop bindings whose box
+ * no longer exists. Idempotent, so it can run after every shape update.
+ */
+declare function resolveBindings(shapes: readonly DrawingShape[]): readonly DrawingShape[];
+/** Attach a freshly drawn connector to the boxes under its endpoints */
+declare function bindEndpoints(shape: DrawingShape, shapes: readonly DrawingShape[]): DrawingShape;
+declare function makeBinding(box: DrawingShape, point: Point): Binding;
+
+/** Vertices of a connector's path, start to end */
+declare function connectorPoints(shape: DrawingShape, shapes?: readonly DrawingShape[]): Point[];
+
+/**
+ * Orthogonal route for an elbow connector: leaves each bound box
+ * perpendicular to its attach side, avoids every box on the canvas, and
+ * takes the path with the fewest bends (then the shortest). Falls back to
+ * a plain L when the grid search fails.
+ */
+declare function routeElbow(shape: DrawingShape, shapes: readonly DrawingShape[]): Point[];
+
+type TextField = 'text' | 'label' | 'footer';
+/**
+ * Geometry of a box type, kept free of React so the router, bindings,
+ * skeleton expansion and exporters can use it without a DOM.
+ */
+type BoxDefinition = Readonly<{
+    type: BoxType;
+    label: string;
+    /** Size used when a shape is created without explicit dimensions */
+    defaultSize: Readonly<{
+        w: number;
+        h: number;
+    }>;
+    /** Text slots the shape renders (and offers for editing) */
+    textSlots: readonly TextField[];
+    /** Fill applied when the tool is picked with the default (transparent) fill */
+    defaultFill?: string;
+    /** Closed outline used for hit-testing and binding endpoints */
+    outline: (shape: DrawingShape) => Point[];
+    /** Area the text slots lay out in */
+    textArea: (shape: DrawingShape) => Rect;
+}>;
+declare const BOX_DEFINITIONS: Record<BoxType, BoxDefinition>;
+
+/**
+ * Skeleton (intent) layer: a compact, LLM-friendly description of a diagram
+ * — boxes, connectors between them and loose texts — that expands into a
+ * full `DrawingData` document. Sizes, positions and connector geometry are
+ * derived, so a generator only needs to say *what* is on the canvas.
+ */
+
+type ColorName = 'gray' | 'red' | 'green' | 'blue' | 'orange' | 'purple';
+declare const COLOR_PRESETS: Record<ColorName, {
+    stroke: string;
+    fill: string;
+}>;
+type SkeletonBox = Readonly<{
+    id: string;
+    /** Default `'rect'` */
+    type?: BoxType;
+    label?: string;
+    text?: string;
+    footer?: string;
+    /** Omitted → auto layout */
+    x?: number;
+    y?: number;
+    /** Omitted → measured from the text, never smaller than the type's default size */
+    w?: number;
+    h?: number;
+    /** Preset → stroke + fill (fill only when `fill` isn't given) */
+    color?: ColorName;
+    stroke?: string;
+    fill?: string;
+}>;
+type SkeletonEnd = string | Readonly<{
+    id: string;
+    side?: BindingSide;
+}>;
+type SkeletonConnector = Readonly<{
+    id?: string;
+    /** Default `'arrow'` */
+    type?: ConnectorType;
+    from: SkeletonEnd;
+    to: SkeletonEnd;
+    text?: string;
+    bidirectional?: boolean;
+    /** Default `'straight'` */
+    routing?: 'elbow' | 'straight';
+    color?: ColorName;
+    stroke?: string;
+}>;
+type SkeletonText = Readonly<{
+    id?: string;
+    x: number;
+    y: number;
+    text: string;
+    color?: ColorName;
+    stroke?: string;
+}>;
+type DrawingSkeleton = Readonly<{
+    /** Auto-layout flow direction, default `'right'` */
+    direction?: 'right' | 'down';
+    canvasWidth?: number;
+    canvasHeight?: number;
+    /** Block width of the expanded drawing; omit for `full` */
+    width?: BlockWidth;
+    boxes: readonly SkeletonBox[];
+    connectors?: readonly SkeletonConnector[];
+    texts?: readonly SkeletonText[];
+}>;
+/** Structural check: an object with a `boxes` array */
+declare function isDrawingSkeleton(value: unknown): value is DrawingSkeleton;
+/**
+ * Parse a skeleton JSON payload into drawing data. Lenient: invalid boxes,
+ * connectors and texts are dropped individually, and a malformed document
+ * yields an empty canvas. Never throws.
+ */
+declare function parseDrawingSkeleton(json: string): DrawingData;
+declare function expandSkeleton(skeleton: DrawingSkeleton): DrawingData;
+declare const DRAWING_SKELETON_JSON_SCHEMA: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly title: "DrawingSkeleton";
+    readonly description: "Compact intent description of a diagram. Boxes are sized from their text and laid out automatically along the connector flow; connectors are drawn between box outlines. Only say what is on the canvas — geometry is derived";
+    readonly type: "object";
+    readonly required: readonly ["boxes"];
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly direction: {
+            readonly enum: readonly ["right", "down"];
+            readonly description: "Auto-layout flow direction. Boxes connected a→b are placed in successive ranks along this axis (\"right\" = columns left to right, \"down\" = rows top to bottom). Default \"right\"";
+        };
+        readonly canvasWidth: {
+            readonly type: "number";
+            readonly minimum: 120;
+            readonly description: "Logical canvas width in px. Omit for a fluid canvas in CSS pixels";
+        };
+        readonly canvasHeight: {
+            readonly type: "number";
+            readonly minimum: 80;
+            readonly description: "Canvas height in px. Omit to fit the content";
+        };
+        readonly width: {
+            readonly enum: readonly ["full", "text", "content"];
+            readonly description: "Block width: \"text\" aligns the drawing with the text column (same as \"full\" unless the app sets a text measure); \"content\" fits the drawing to its shapes and left-aligns it with the text; omit to span the editor";
+        };
+        readonly boxes: {
+            readonly type: "array";
+            readonly items: {
+                readonly $ref: "#/definitions/box";
+            };
+            readonly description: "Card-like shapes carrying up to three text slots. Order is the render order and the stacking order within a layout rank";
+        };
+        readonly connectors: {
+            readonly type: "array";
+            readonly items: {
+                readonly $ref: "#/definitions/connector";
+            };
+            readonly description: "Arrows and lines between boxes. Connectors whose from/to id does not match a box are dropped";
+        };
+        readonly texts: {
+            readonly type: "array";
+            readonly items: {
+                readonly $ref: "#/definitions/text";
+            };
+            readonly description: "Free-floating annotations not attached to any box. Prefer box slots (label/text/footer) when the text belongs to a box";
+        };
+    };
+    readonly definitions: {
+        readonly box: {
+            readonly type: "object";
+            readonly required: readonly ["id"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly description: "Unique within the drawing; connectors reference it";
+                };
+                readonly type: {
+                    readonly enum: readonly BoxType[];
+                    readonly description: "Shape: rect (default), ellipse, diamond (decision), note (sticky note, yellow by default), cylinder (database), cloud (external system), queue (message queue), actor (stick figure; only the \"text\" slot renders, below the figure)";
+                };
+                readonly label: {
+                    readonly type: "string";
+                    readonly description: "Small bold heading at the top of the box";
+                };
+                readonly text: {
+                    readonly type: "string";
+                    readonly description: "Main content, centered. Wraps automatically; \"\\n\" forces a line break";
+                };
+                readonly footer: {
+                    readonly type: "string";
+                    readonly description: "Small dim line at the bottom of the box";
+                };
+                readonly x: {
+                    readonly type: "number";
+                    readonly description: "Top-left x in px. Omit (with y) to let the layout place the box";
+                };
+                readonly y: {
+                    readonly type: "number";
+                    readonly description: "Top-left y in px. Omit (with x) to let the layout place the box";
+                };
+                readonly w: {
+                    readonly type: "number";
+                    readonly exclusiveMinimum: 0;
+                    readonly description: "Width in px. Omit to size from the text (never smaller than the type default)";
+                };
+                readonly h: {
+                    readonly type: "number";
+                    readonly exclusiveMinimum: 0;
+                    readonly description: "Height in px. Omit to size from the text (never smaller than the type default)";
+                };
+                readonly color: {
+                    readonly enum: readonly ColorName[];
+                    readonly description: "Named color preset. Sets the stroke (outline + text) and, for boxes, a matching pastel fill. Omit for the default gray on transparent";
+                };
+                readonly stroke: {
+                    readonly type: "string";
+                    readonly description: "CSS color of the outline and text; overrides the preset";
+                };
+                readonly fill: {
+                    readonly type: "string";
+                    readonly description: "CSS color of the interior (\"transparent\" for none); overrides the preset";
+                };
+            };
+        };
+        readonly connector: {
+            readonly type: "object";
+            readonly required: readonly ["from", "to"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly description: "Optional; generated when omitted";
+                };
+                readonly type: {
+                    readonly enum: readonly ConnectorType[];
+                    readonly description: "arrow (default; arrowhead at \"to\") or line (no arrowheads)";
+                };
+                readonly from: {
+                    readonly oneOf: readonly [{
+                        readonly type: "string";
+                        readonly description: "Id of a box. The connector attaches to its outline, aimed at the other end";
+                    }, {
+                        readonly type: "object";
+                        readonly required: readonly ["id"];
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                                readonly description: "Id of a box";
+                            };
+                            readonly side: {
+                                readonly enum: readonly ["top", "right", "bottom", "left"];
+                                readonly description: "Pin the endpoint to the middle of this side of the box instead of auto-aiming";
+                            };
+                        };
+                    }];
+                    readonly description: "Box a connector end attaches to: a bare box id, or {id, side} to pick the attach edge";
+                };
+                readonly to: {
+                    readonly oneOf: readonly [{
+                        readonly type: "string";
+                        readonly description: "Id of a box. The connector attaches to its outline, aimed at the other end";
+                    }, {
+                        readonly type: "object";
+                        readonly required: readonly ["id"];
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                                readonly description: "Id of a box";
+                            };
+                            readonly side: {
+                                readonly enum: readonly ["top", "right", "bottom", "left"];
+                                readonly description: "Pin the endpoint to the middle of this side of the box instead of auto-aiming";
+                            };
+                        };
+                    }];
+                    readonly description: "Box a connector end attaches to: a bare box id, or {id, side} to pick the attach edge";
+                };
+                readonly text: {
+                    readonly type: "string";
+                    readonly description: "Label rendered at the middle of the connector";
+                };
+                readonly bidirectional: {
+                    readonly type: "boolean";
+                    readonly description: "Arrow only: arrowheads on both ends";
+                };
+                readonly routing: {
+                    readonly enum: readonly ["straight", "elbow"];
+                    readonly description: "straight (default) draws a direct line; elbow draws a right-angled path routed around the boxes";
+                };
+                readonly color: {
+                    readonly enum: readonly ColorName[];
+                    readonly description: "Named color preset. Sets the stroke (outline + text) and, for boxes, a matching pastel fill. Omit for the default gray on transparent";
+                };
+                readonly stroke: {
+                    readonly type: "string";
+                    readonly description: "CSS color of the line and label; overrides the preset";
+                };
+            };
+        };
+        readonly text: {
+            readonly type: "object";
+            readonly required: readonly ["x", "y", "text"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly description: "Optional; generated when omitted";
+                };
+                readonly x: {
+                    readonly type: "number";
+                    readonly description: "Top-left x of the first line, in px";
+                };
+                readonly y: {
+                    readonly type: "number";
+                    readonly description: "Top-left y of the first line, in px";
+                };
+                readonly text: {
+                    readonly type: "string";
+                    readonly description: "Content; \"\\n\" forces a line break";
+                };
+                readonly color: {
+                    readonly enum: readonly ColorName[];
+                    readonly description: "Named color preset. Sets the stroke (outline + text) and, for boxes, a matching pastel fill. Omit for the default gray on transparent";
+                };
+                readonly stroke: {
+                    readonly type: "string";
+                    readonly description: "CSS color of the text; overrides the preset";
                 };
             };
         };
     };
 };
 
-export { $createDrawingNode, $createFrontmatterNode, $getSelectedTable, $getTableDensity, $getTableSettings, $getTableWidth, $isDrawingNode, $isFrontmatterNode, $setTableDensity, $setTableSettings, $setTableWidth, type BlockWidth, DEFAULT_TABLE_SETTINGS, DRAWING, DRAWING_DATA_JSON_SCHEMA, type DrawingData, DrawingNode, type DrawingShape, type DrawingShapeType, type EditorContentProps, type EditorMode, type EditorRootProps, FRONTMATTER, FormatButtons, FrontmatterNode, HistoryButtons, InsertButtons, MarkdownEditor, type MarkdownEditorApi, type Props as MarkdownEditorProps, type SerializedDrawingNode, type SerializedFrontmatterNode, TABLE, TABLE_WIDTH_MARKER, type TableDensity, type TableSettings, Toolbar, ToolbarButton, ToolbarDivider, type ToolbarItems, formatTableSettingsMarker, parseDrawingData, parseTableSettingsMarker, serializeDrawingData, useMarkdownEditor };
+type MermaidDirection = 'LR' | 'TD';
+type MermaidOptions = Readonly<{
+    direction?: MermaidDirection;
+}>;
+/**
+ * Export a drawing as a Mermaid `flowchart`. Boxes become nodes (in shape
+ * order), connectors bound at both ends become edges; unbound connectors
+ * are dropped and free text shapes are kept as `%% note:` comments so
+ * nothing is silently lost.
+ */
+declare function drawingToMermaid(data: DrawingData, options?: MermaidOptions): string;
+
+export { $createDrawingNode, $createFrontmatterNode, $getSelectedTable, $getTableDensity, $getTableSettings, $getTableWidth, $isDrawingNode, $isFrontmatterNode, $isTableWidthExplicit, $setTableDensity, $setTableSettings, $setTableWidth, BLOCK_WIDTHS, BOX_DEFINITIONS, BOX_TYPES, type Binding, type BindingSide, type BlockWidth, type BlockWidthDefaults, type BoxDefinition, type BoxType, COLOR_PRESETS, CONNECTOR_TYPES, type ColorName, type ConnectorType, DEFAULT_TABLE_SETTINGS, DIAGRAM, DRAWING, DRAWING_DATA_JSON_SCHEMA, DRAWING_SKELETON_JSON_SCHEMA, type DrawingData, DrawingNode, type DrawingShape, type DrawingShapeType, type DrawingSkeleton, EMPTY_DRAWING, type EditorContentProps, type EditorMode, type EditorRootProps, FILL_COLORS, FRONTMATTER, FormatButtons, FrontmatterNode, HistoryButtons, InsertButtons, MarkdownEditor, type MarkdownEditorApi, type Props as MarkdownEditorProps, type MermaidDirection, type MermaidOptions, type Point, SHAPE_TYPES, SIDE_FIXED_POINTS, STROKE_COLORS, type SerializedDrawingNode, type SerializedFrontmatterNode, type SkeletonBox, type SkeletonConnector, type SkeletonEnd, type SkeletonText, TABLE, TABLE_WIDTH_MARKER, type TableDensity, type TableSettings, type TableSettingsOptions, type TextField, Toolbar, ToolbarButton, ToolbarDivider, type ToolbarItems, anchorPoint, bindEndpoints, boxOutline, connectorPoints, drawingToMermaid, expandSkeleton, findBoxAt, fixedPointFor, formatTableSettingsMarker, isBlockWidth, isDrawingSkeleton, makeBinding, normalizeDrawingData, parseDrawingData, parseDrawingSkeleton, parseTableSettingsMarker, resolveBindings, routeElbow, serializeDrawingData, useMarkdownEditor };