@zuilib/text-editor 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog — @zuilib/text-editor
 
+## 0.7.0
+
+**Themed drawing canvas.** The canvas chrome now follows the host theme
+instead of shipping its own look.
+
+- Tool row and contextual property row are a flat header in the editor's
+  own toolbar idiom (in flow, no floating panels over the drawing)
+- Every color, radius, shadow and font of the canvas is a
+  `--zui-drawing-*` custom property defaulting to the core theme tokens
+  (`--primary`, `--foreground`, `--border`, `--popover`, `--radius`,
+  `--shadow-medium`, …), so light and dark mode come from the tokens;
+  override them on `.zui-drawing-canvas` or an ancestor. See README,
+  "Theming the canvas"
+- Selection frame, handles, marquee, bind highlight and connector label
+  plates are drawn in `currentColor`/theme variables; the table selection
+  tint uses `--primary` too, so the editor shares one accent
+- `--zui-drawing-dark-filter` exposes the dark-mode inversion of the
+  drawing area (`none` opts out)
+
+## 0.6.0
+
+**Text measure and `text` block width.** Additive: markdown, JSON, class
+names and props keep their meaning; with no configuration the layout is
+unchanged.
+
+- **Measure** (opt in): `measure="48rem"` on `MarkdownEditor` /
+  `MarkdownEditor.Root`, or `--zui-text-editor-measure: 48rem` in a
+  stylesheet — the CSS custom property is the contract, the prop is sugar.
+  Text blocks (paragraphs, headings, lists, quotes, code, frontmatter) are
+  capped at the measure and centred in the content pane; the placeholder
+  and fold chevrons follow the column. The pane itself is never capped and
+  full-width blocks stop short of the outline sidebar
+- **`BlockWidth` gains `'text'`**: `'full' | 'text' | 'content'`. `text`
+  aligns a table or drawing with the text column; without a measure it is
+  visually identical to `full` (resolved in CSS through the variable's
+  fallback). `full` (default, omitted) and `content` (shrink to fit) are
+  unchanged
+- **Persistence**: tables `<!-- width: text -->` (combinable with
+  `density`); drawings and ` ```diagram ` skeletons `"width":"text"`.
+  `DRAWING_DATA_JSON_SCHEMA`, `DRAWING_SKELETON_JSON_SCHEMA` and
+  `DRAWING_FORMAT.md` updated. Unknown width values are ignored (treated as
+  `full`) instead of being rejected, so documents from newer versions still
+  open — `parseTableSettingsMarker` now returns `{}` (rather than `null`)
+  for a marker whose only known key carries an unknown value, and the
+  transformer consumes that line
+- **Insertion defaults**: `defaultBlockWidth={{ table?, drawing? }}` on
+  Root applies when the toolbar / `useMarkdownEditor()` inserts a new table
+  or drawing. The chosen width is written to the markdown explicitly, even
+  `full`, so the document reads the same in an app with other defaults; a
+  width named in the source (`<!-- width: full -->`, `"width":"full"`) is
+  preserved on round trip
+- **UI / headless**: the floating table toolbar and the drawing toolbar
+  offer all three widths with distinct icons (`BLOCK_WIDTH_OPTIONS`).
+  `useMarkdownEditor()` gains `blockWidth` / `setBlockWidth` for the block
+  containing the selection — the focused drawing or the table the caret is
+  in; `insertTable` / `insertDrawing` accept a `width` option. `tableWidth`
+  / `setTableWidth` keep working and are deprecated
+- **CSS**: the new layout lives in zero-specificity `:where()` rules. The
+  content pane exposes `--zui-text-editor-gutter` and
+  `--zui-text-editor-bleed`; every top-level block reads
+  `--zui-text-editor-block-bleed`, so one class rule overrides any block
+  kind. New block classes (added next to the existing utility classes):
+  `.zui-paragraph`, `.zui-heading` / `.zui-heading-1`…`6`, `.zui-list` /
+  `.zui-list-ordered` / `.zui-list-unordered`, `.zui-quote`, `.zui-code`;
+  `.zui-drawing-canvas` gains `.is-text-width`. Nothing is renamed
+- New exports: `BLOCK_WIDTHS`, `isBlockWidth`, `BlockWidthDefaults`,
+  `TableSettingsOptions`, `$isTableWidthExplicit`; `$setTableSettings` and
+  `formatTableSettingsMarker` take an optional `{ explicitWidth }`
+- **Adopting**: set `measure` (or the CSS variable) and delete any external
+  `max-width` / `margin-inline` overrides on `.zui-text-editor-content > *`
+
 ## 0.5.0
 
 **Diagram builder rewrite.** The drawing canvas, its payload format and the

package/DRAWING_FORMAT.md

@@ -41,9 +41,13 @@ skeleton, which is a separate block type.
   narrower layouts (SVG viewBox), so coordinates can assume that width.
   When omitted the canvas is fluid and as wide as the editor; keep shapes
   within roughly x in [0, 700] to be safe on typical layouts.
-- `"width":"content"` sizes the block to fit the rightmost shape (plus a
-  margin), left-aligned with the text. Use it for small diagrams that
-  should not stretch across the page. Default `"full"`, omit it.
+- `width` is the block's horizontal sizing in the page, independent of the
+  coordinates: `"full"` (default, omit it) spans the editor pane;
+  `"text"` aligns the block with the text column (the same as `"full"`
+  unless the app sets a text measure); `"content"` sizes the block to fit
+  the rightmost shape (plus a margin), left-aligned with the text. Use
+  `"content"` for small diagrams that should not stretch across the page.
+  Unknown values are ignored (treated as `"full"`).
 
 ## Top-level object
 
@@ -52,7 +56,7 @@ skeleton, which is a separate block type.
 | `version`      | `2`       | Literal `2`                                                  |
 | `canvasHeight` | `number`  | Canvas height in px (min 80)                                 |
 | `canvasWidth`  | `number`  | Optional logical width in px (min 120); scales to fit when set |
-| `width`        | `"full"` \| `"content"` | Optional; default `"full"`. `"content"` fits the shapes' extent |
+| `width`        | `"full"` \| `"text"` \| `"content"` | Optional; default `"full"`. `"text"` aligns with the text column, `"content"` fits the shapes' extent |
 | `shapes`       | `Shape[]` | Render order: later shapes draw on top                       |
 
 ## Shape object
@@ -197,7 +201,7 @@ one-way: once opened, the document stores the concrete ```drawing block.
 ```
 {
   "direction"?: "right" | "down",          // auto-layout flow, default right
-  "canvasWidth"?: n, "canvasHeight"?: n, "width"?: "content",
+  "canvasWidth"?: n, "canvasHeight"?: n, "width"?: "full" | "text" | "content",
   "boxes": [ { "id", "type"?: <box type, default rect>, "label"?, "text"?, "footer"?,
                "x"?, "y"?,            // omitted: auto layout by connector rank
                "w"?, "h"?,            // omitted: sized to fit the text
@@ -224,6 +228,8 @@ Rules:
   them. Boxes without `w`/`h` are sized to fit their text. `canvasHeight`
   is computed when omitted.
 - `texts` are free annotations and need explicit coordinates.
+- `width` is copied to the expanded drawing (see [Coordinate
+  system](#coordinate-system)); omit it for `"full"`.
 
 A three-box flow:
 

package/README.md

@@ -13,8 +13,9 @@ document outline, and collapsible sections.
   blockquotes, links, fenced code (with syntax highlighting), tables
 - **Tables**: GFM pipe tables, edited in place (tab between cells, ranges,
   inline formatting), styled like Claude artifacts
-- **Table settings**: full/content width and row density per table;
-  diagrams switch between full and content width too — Slab-style
+- **Text measure and block width**: an opt-in readable text column
+  (`measure="48rem"`); each table and diagram picks *full* / *text* /
+  *content* width, Slab-style; row density per table
 - **Diagrams**: a drawing canvas embedded in the document. Eight box
   shapes (rectangle, ellipse, diamond, note, database, cloud, queue, actor)
   with attached text slots, bound arrows that follow their boxes and attach
@@ -73,6 +74,8 @@ emits. The emitted string is always plain markdown.
 | `toolbar` | `boolean \| (items) => ReactNode` | `true` | Formatting/insert toolbar (`edit-md`); function form customises it |
 | `outline` | `boolean` | `false` | Table-of-contents sidebar |
 | `foldable` | `boolean` | `true` | Collapse sections under headings |
+| `measure` | `string` | — | Max width of the text column, a CSS length (`'48rem'` recommended). Sugar for `--zui-text-editor-measure` |
+| `defaultBlockWidth` | `{ table?, drawing? }` | — | `BlockWidth` written when the toolbar inserts a table / drawing |
 
 ### Modes
 
@@ -101,16 +104,12 @@ Editing is in place: Tab/arrows between cells, cell range selection, inline
 formatting inside cells. Cell content is single-line in markdown; newlines
 are escaped as `\n`.
 
-### Table settings: width and density
+### Table density
 
 Place the caret in a table and a small toolbar floats at its top-right
-corner:
-
-- **Width** — *full* (default: columns share the editor width) or
-  *content* (the table shrinks to fit its columns, left-aligned with the
-  text, never wider than the editor).
-- **Density** — *compact*, *comfortable* (default), or *spacious* cell
-  padding and font size.
+corner with the table's width (see [Block width and text
+measure](#block-width-and-text-measure)) and its **density** — *compact*,
+*comfortable* (default), or *spacious* cell padding and font size.
 
 Non-default settings are persisted as one HTML comment on the line directly
 above the table — other markdown renderers hide it:
@@ -122,12 +121,70 @@ above the table — other markdown renderers hide it:
 | Region | eu-west-1 |
 ```
 
-Programmatic access: `useMarkdownEditor().tableWidth` / `setTableWidth` and
-`tableDensity` / `setTableDensity` (for custom toolbars), or
-`$getTableSettings(node)` / `$setTableSettings(node, { width, density })`
-inside `editor.update`. `parseTableSettingsMarker` /
-`formatTableSettingsMarker` convert between the comment line and a
-`TableSettings` object.
+Programmatic access: `useMarkdownEditor().tableDensity` / `setTableDensity`
+(for custom toolbars), or `$getTableSettings(node)` /
+`$setTableSettings(node, { width, density })` inside `editor.update`.
+`parseTableSettingsMarker` / `formatTableSettingsMarker` convert between
+the comment line and a `TableSettings` object.
+
+## Block width and text measure
+
+By default every block spans the content pane. Set a **measure** to get a
+readable text column instead: paragraphs, headings, lists, quotes, code,
+frontmatter are capped at that width and centred in the pane, while each
+table and drawing chooses its own width.
+
+```tsx
+<MarkdownEditor value={value} onChange={setValue} measure="48rem" />
+```
+
+The prop is sugar for the CSS custom property `--zui-text-editor-measure`,
+which is the actual contract — set it in a stylesheet on `.zui-text-editor`
+(or any ancestor) and never touch the prop:
+
+```css
+.zui-text-editor { --zui-text-editor-measure: 48rem; }
+```
+
+**Adopting:** set `measure` (or the variable) and delete any external
+`max-width` / `margin-inline` overrides on `.zui-text-editor-content > *`;
+the library now owns that layout.
+
+Every table and drawing has a `BlockWidth`, picked from the floating table
+toolbar or the right end of the drawing toolbar:
+
+| `BlockWidth` | Layout | Markdown |
+|--------------|--------|----------|
+| `full` | The content pane, edge to edge (never under the outline sidebar). The default | Omitted |
+| `text` | The text column: edges align with the paragraphs. Identical to `full` until a measure is set | `<!-- width: text -->` / `"width":"text"` |
+| `content` | Shrinks to its columns / shapes, left-aligned with the text, never wider than the column | `<!-- width: content -->` / `"width":"content"` |
+
+Absence of a marker always means `full`, in every app. `defaultBlockWidth`
+only changes what the toolbar / `insertTable` / `insertDrawing` write into
+*new* blocks — and that value is written explicitly, even when it is
+`full`, so the document reads the same elsewhere:
+
+```tsx
+<MarkdownEditor measure="48rem" defaultBlockWidth={{ table: 'text', drawing: 'text' }} … />
+```
+
+Headless: `useMarkdownEditor().blockWidth` / `setBlockWidth` act on the
+block containing the selection — the focused drawing, or else the table
+the caret is in. (`tableWidth` / `setTableWidth` still work and are
+deprecated in favour of these.)
+
+Styling: the layout is driven by low-specificity `:where()` rules and two
+derived custom properties on `.zui-text-editor-main` —
+`--zui-text-editor-gutter` (the pane padding, `2rem` without a measure)
+and `--zui-text-editor-bleed` (how far a full-width block extends past the
+column, `0` without a measure). Each top-level block reads
+`--zui-text-editor-block-bleed`, so a single class rule overrides any block
+kind: `.zui-code { --zui-text-editor-block-bleed: var(--zui-text-editor-bleed) }`
+makes code blocks full width; `.zui-table { --zui-text-editor-block-bleed: 0px }`
+keeps every table inside the column. Block classes: `.zui-paragraph`,
+`.zui-heading` (+ `.zui-heading-1`…`6`), `.zui-list` (+ `-ordered` /
+`-unordered`, `.zui-checklist`), `.zui-quote`, `.zui-code`,
+`.zui-frontmatter`, `.zui-table`, `.zui-drawing`.
 
 ## Toolbar & custom toolbars
 
@@ -212,10 +269,11 @@ function BoldButton() {
 ```
 
 It returns `editor` (the Lexical instance), `activeFormats`,
-`toggleFormat`, `insertTable`, `insertDrawing`, `tableWidth` /
-`setTableWidth` and `tableDensity` / `setTableDensity` (settings of the
-table containing the selection, `null` outside tables), `canUndo`,
-`canRedo`, `undo`, `redo`.
+`toggleFormat`, `insertTable`, `insertDrawing`, `blockWidth` /
+`setBlockWidth` (width of the table or drawing containing the selection,
+`null` outside both), `tableDensity` / `setTableDensity` (`null` outside
+tables), `canUndo`, `canRedo`, `undo`, `redo`. `tableWidth` /
+`setTableWidth` remain as deprecated aliases limited to tables.
 
 ## Diagrams (drawing canvas)
 
@@ -251,10 +309,12 @@ fully specified in **[DRAWING_FORMAT.md](./DRAWING_FORMAT.md)**.
 - **Canvas**: resizable height, dot grid, white surface that inverts
   Excalidraw-style in dark mode (`.dark` ancestor class). An optional
   `canvasWidth` scales the drawing to fit narrower layouts.
-- **Width**: the toggle at the right end of the canvas toolbar switches
-  between **full width** (spans the editor) and **content width** (the
-  canvas fits the rightmost shape and grows as shapes move). Stored as
-  `"width":"content"` in the payload; omitted when full.
+- **Width**: the buttons at the right end of the canvas toolbar switch
+  between **full** (spans the pane), **text** (aligns with the text column,
+  see [Block width and text measure](#block-width-and-text-measure)) and
+  **content** (the canvas fits the rightmost shape and grows as shapes
+  move). Stored as `"width":"text"` / `"width":"content"` in the payload;
+  omitted when full.
 
 A stored drawing looks like this:
 
@@ -293,6 +353,41 @@ The full skeleton spec (attach sides, explicit positions, free texts) is
 in [DRAWING_FORMAT.md](./DRAWING_FORMAT.md). Programmatic access:
 `parseDrawingSkeleton`, `expandSkeleton`, `DRAWING_SKELETON_JSON_SCHEMA`.
 
+### Theming the canvas
+
+The canvas chrome (header, property row, popover, selection handles) is
+styled entirely through `--zui-drawing-*` custom properties. They default
+to the ZUI core tokens (`--primary`, `--foreground`, `--border`,
+`--popover`, `--radius`, `--shadow-medium`, …), so the canvas follows the
+host theme in light and dark mode. Override any of them on
+`.zui-drawing-canvas` or an ancestor:
+
+```css
+.my-app .zui-drawing-canvas {
+  --zui-drawing-accent: #0f766e;        /* selection, active tool, handles */
+  --zui-drawing-surface: #fbfbf7;       /* drawing area (pre dark-mode filter) */
+  --zui-drawing-grid: rgba(0, 0, 0, 0.12);
+  --zui-drawing-grid-size: 16px;
+  --zui-drawing-font: 'Inter', sans-serif;
+}
+```
+
+| Variable | Default | Used for |
+|----------|---------|----------|
+| `--zui-drawing-accent` | `var(--primary)` | Selection frame and handles, active tool, focus ring, bind highlight |
+| `--zui-drawing-foreground` | `var(--foreground)` | Header text and icons |
+| `--zui-drawing-muted-foreground` | `var(--muted-foreground)` | Swatch labels, empty-state hint |
+| `--zui-drawing-border` | `var(--border)` | Block border, header divider, popover border |
+| `--zui-drawing-chrome` | `var(--background)` | Header and property row background |
+| `--zui-drawing-popover` / `-foreground` | `var(--popover)` / `var(--popover-foreground)` | "More shapes" menu |
+| `--zui-drawing-danger` / `--zui-drawing-success` | `var(--destructive)` / `var(--success)` | Delete button, "copied" state |
+| `--zui-drawing-radius` / `--zui-drawing-control-radius` | `var(--radius-lg)` / `var(--radius)` | Block corners / buttons and menus |
+| `--zui-drawing-shadow` | `var(--shadow-medium)` | Popover |
+| `--zui-drawing-font` | system sans | Shape text and the inline editor |
+| `--zui-drawing-surface` / `--zui-drawing-grid` / `--zui-drawing-grid-size` | white / 9% black / `20px` | Drawing area and its dot grid, before the dark filter |
+| `--zui-drawing-dark-filter` | `invert(93%) hue-rotate(180deg)` | Applied to the drawing area under `.dark`; set to `none` to opt out |
+| `--zui-drawing-hover` / `--zui-drawing-active` | `currentColor` 8% / 12% | Button hover and pressed backgrounds |
+
 ## Outline & section folding
 
 `outline` docks a collapsible table-of-contents sidebar: live heading list
@@ -335,8 +430,9 @@ diagrams:
 | `Toolbar`, `ToolbarButton`, `ToolbarDivider`, `FormatButtons`, `InsertButtons`, `HistoryButtons` | Toolbar primitives |
 | `@zuilib/text-editor/styles.css` | Editor chrome + theme styles (required) |
 | `TABLE` | GFM table markdown transformer |
-| `BlockWidth`, `TableDensity`, `TableSettings`, `DEFAULT_TABLE_SETTINGS` | Table setting types |
-| `$getTableSettings`, `$setTableSettings`, `$getTableWidth`, `$setTableWidth`, `$getTableDensity`, `$setTableDensity`, `$getSelectedTable` | Table setting helpers (inside `editor.update`/`read`) |
+| `BlockWidth`, `BLOCK_WIDTHS`, `isBlockWidth`, `BlockWidthDefaults` | Block width (`full` / `text` / `content`) type, values, guard, insertion defaults |
+| `TableDensity`, `TableSettings`, `TableSettingsOptions`, `DEFAULT_TABLE_SETTINGS` | Table setting types |
+| `$getTableSettings`, `$setTableSettings`, `$isTableWidthExplicit`, `$getTableWidth`, `$setTableWidth`, `$getTableDensity`, `$setTableDensity`, `$getSelectedTable` | Table setting helpers (inside `editor.update`/`read`) |
 | `parseTableSettingsMarker`, `formatTableSettingsMarker` | Marker comment ⇄ `TableSettings` |
 | `DRAWING`, `DIAGRAM`, `DrawingNode`, `$createDrawingNode`, `$isDrawingNode` | Drawing node + markdown transformers (` ```drawing ` and ` ```diagram `) |
 | `FRONTMATTER`, `FrontmatterNode`, `$createFrontmatterNode`, `$isFrontmatterNode` | Frontmatter node + transformer |

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;
@@ -283,8 +357,10 @@ type DrawingData = Readonly<{
     canvasWidth?: number;
     canvasHeight: number;
     /**
-     * Block 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[];
@@ -350,7 +426,7 @@ 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.
  */
@@ -392,8 +468,8 @@ declare const DRAWING_DATA_JSON_SCHEMA: {
             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: "Block width: \"full\" (default, omit it) 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";
@@ -595,6 +671,13 @@ type BoxDefinition = Readonly<{
 }>;
 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;
@@ -648,7 +731,8 @@ type DrawingSkeleton = Readonly<{
     direction?: 'right' | 'down';
     canvasWidth?: number;
     canvasHeight?: number;
-    width?: 'content';
+    /** Block width of the expanded drawing; omit for `full` */
+    width?: BlockWidth;
     boxes: readonly SkeletonBox[];
     connectors?: readonly SkeletonConnector[];
     texts?: readonly SkeletonText[];
@@ -685,8 +769,8 @@ declare const DRAWING_SKELETON_JSON_SCHEMA: {
             readonly description: "Canvas height in px. Omit to fit the content";
         };
         readonly width: {
-            readonly enum: readonly ["content"];
-            readonly description: "Block width: \"content\" fits the drawing to its shapes and left-aligns it with the text; omit to span the editor";
+            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";
@@ -891,4 +975,4 @@ type MermaidOptions = Readonly<{
  */
 declare function drawingToMermaid(data: DrawingData, options?: MermaidOptions): string;
 
-export { $createDrawingNode, $createFrontmatterNode, $getSelectedTable, $getTableDensity, $getTableSettings, $getTableWidth, $isDrawingNode, $isFrontmatterNode, $setTableDensity, $setTableSettings, $setTableWidth, BOX_DEFINITIONS, BOX_TYPES, type Binding, type BindingSide, type BlockWidth, 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 TextField, Toolbar, ToolbarButton, ToolbarDivider, type ToolbarItems, anchorPoint, bindEndpoints, boxOutline, connectorPoints, drawingToMermaid, expandSkeleton, findBoxAt, fixedPointFor, formatTableSettingsMarker, isDrawingSkeleton, makeBinding, normalizeDrawingData, parseDrawingData, parseDrawingSkeleton, parseTableSettingsMarker, resolveBindings, routeElbow, serializeDrawingData, useMarkdownEditor };
+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 };