@weasel-js/diagram-formats 1.15.0 → 1.15.1

package/README.md

@@ -17,9 +17,19 @@ npm install @weasel-js/diagram-formats
 ## The interchange document
 
 A `DiagramDocument` is a diagram's pages and its theme. Each page has an id,
-an optional name, a sheet size, and a `DiagramData` whose places, boxes,
-waypoints, and label points run from the page's top-left corner. Ids share one
-namespace across the document. Edges whose ends are on different pages sit in
+an optional name, a sheet size, and a `kind` saying what it holds. A `'graph'`
+page holds a `DiagramData` whose places, boxes, waypoints, and label points run
+from the page's top-left corner, and may name its `notation` (`'class'`,
+`'state'`, …) for a format that writes graphs in several notations. A `'sequence'`
+page holds a `SequenceData` (see `@weasel-js/diagram`), which carries no places:
+it is laid out whenever it is drawn, and its `name` is the diagram's title. A
+`'plot'` page holds one chart, a `PlotData` from `@weasel-js/plot`, which fills
+the page. Ids share one namespace across the document. Every format lists the
+page `kinds` it holds; a writer leaves out a page of another kind with a
+warning, and `formatHolds` says whether a format can write a whole document.
+`scenePageKinds(scene)` says which kinds a scene would export as from its
+top-level nodes alone, and `formatTakes(format, kinds)` whether a format holds
+them: what a menu asks on every render. Edges whose ends are on different pages sit in
 `crossPageEdges`, with no waypoints, since they draw as two stubs and their
 off-page tags.
 
@@ -38,17 +48,39 @@ It keeps the colors the scene's theme would not give: those the author set by
 hand (the trait's `ownStyle`) and any that differ from the theme, as `colors`.
 A route or a port that layout chose, and an avoiding connector's computed
 route, are read as `routed` and `routedPorts`, not as waypoints, so they stay
-layout's. `theme` is what colors are compared against when the scene names
-none.
+layout's. An edge's end labels read back as `endLabels`, and a `field` row as
+a field while its text still starts with its label. `theme` is what colors are
+compared against when the scene names none. A page holding a plot root (one
+`plotSpecs` made) is a plot page of the spec the root holds, edits included;
+anything else on that page is left out. A graph page takes the `notation`, `layout`, and
+`direction` its `core:pages` page keeps under `meta['diagram:graph']`
+(`GRAPH_PAGE_META_KEY`, read with `graphPageSettingsOf`), where `documentSpecs`
+writes them.
 
 `documentSpecs(doc, { layer, theme, measure })` is the way back. Pages are
 placed with core's `layoutPages`, as `core:pages` places them. A page where a
-node has no `at`, or a pool has no box, is laid out first with `layered`,
-running the way its `direction` says, with whatever it places pinned; the
+node has no `at`, or a pool has no box, is laid out first with the layout its
+`layout` names (`{ name, options }`, a key of `LAYOUTS`, default `layered`), running the way its `direction` says, with whatever it places pinned; the
 result is kept as places and routes, a page that placed nothing is moved to sit
 40 inside its corner, and the page grows to hold it. Then one `diagramScene`
 call with no layout draws every page and the edges between them, so no layout
-runs again after an import.
+runs again after an import. A sequence page is drawn by `sequenceSpecs` as one
+root holding its data, 40 inside its corner, and the page grows to hold it;
+`documentFromScene` reads a page holding such a root back as a sequence page and
+leaves out its parts. A plot page is one plot root filling the page, its
+id `<page id>/plot`, its marks under it, drawn in the theme's roles: text in the
+label color, axes in the connector stroke, grid lines in the container stroke,
+series in the theme's `series` (`plotThemeOf`).
+
+A graph page with no `notation` of its own takes the one its scene's diagram type writes (`diagramNotationOf`), and
+`documentSpecs` sets `diagram:type` when every graph page's notation names one type, so an imported class diagram
+opens with the UML stencils.
+
+`PAGE_TEMPLATES` holds a new page of every kind: an empty graph page per diagram type, in its notation; a small
+sequence diagram; and a small chart of each plot kind, each with the `group` a menu lists it under. `templateSpecs`
+draws one as a new one-page document, the diagram type it names included, and `addTemplatePage(scene, template)`
+adds one as another page, what it draws with it, as one undo entry. `pageSpecs` draws any one page placed where a
+page list would place it.
 
 ## Formats
 
@@ -66,9 +98,9 @@ with it and rejects on a file nothing reads.
 
 | Format | Extensions | Reads | Writes |
 | --- | --- | --- | --- |
-| `DIAGRAM_JSON`, the document as JSON | `.diagram.json` | yes | the whole document |
+| `DIAGRAM_JSON`, the document as JSON | `.diagram.json` | yes, graph and plot pages | the whole document |
 | `DRAW_XML`, draw-style XML | `.xml` | yes, plain or compressed | every page, uncompressed |
-| `DIAGRAM_MERMAID`, a Mermaid flowchart | `.mmd`, `.mermaid` | yes | one page |
+| `DIAGRAM_MERMAID`, a Mermaid flowchart, class, state, ER, mind map, requirement, block, architecture, C4, kanban, or sequence diagram, or a chart | `.mmd`, `.mermaid` | yes | one page, a graph, a sequence, or a chart |
 | `DIAGRAM_DOT`, a Graphviz DOT graph | `.dot`, `.gv` | yes | one page |
 
 Not read, by decision (2026-10-20): packaged office-suite drawing formats,
@@ -87,13 +119,13 @@ The file is known by its root element, not its `.xml` extension.
 
 | Diagram | Draw-style XML |
 | --- | --- |
-| Outline | `rhombus` diamond, `ellipse`, `hexagon`, `parallelogram`, `trapezoid`; `rounded=1` with `arcSize` 50 or more is a stadium; any other shape reads as a rect, with a warning |
+| Outline | `rhombus` diamond, `ellipse`, `hexagon`, `parallelogram`, `trapezoid`; `startState`, `endState`, and `line` as `start`, `end`, and `bar`; `rounded=1` with `arcSize` 50 or more is a stadium; any other shape reads as a rect, with a warning |
 | Colors and font | `fillColor` (`none` is transparent), `strokeColor`, `fontColor`, `strokeWidth`, `dashed`; `fontSize`, `fontFamily`, and bold in `fontStyle` as label rows' style |
 | Text | `value`; with `html=1`, tags stripped and `<br>` and blocks kept as line breaks. Written plain. |
 | Router | `edgeStyle=orthogonalEdgeStyle` orthogonal, `curved=1` bezier, else straight; `avoid` writes as orthogonal along its route |
 | Route | the edge geometry's points: `waypoints`, else `routed`, read back as `waypoints` |
 | Ports | `exitX`/`exitY` and `entryX`/`entryY`, read as the nearest compass port |
-| Edge label | the edge's `value`, or a label cell on it; its geometry `x` (-1 to 1) is where along, `y` how far off the line |
+| Edge label | the edge's `value`, or a label cell on it; its geometry `x` (-1 to 1) is where along, `y` how far off the line. A label cell at `x` -1 or 1 is an end label (`endLabels`) |
 | Arrowheads | `startArrow`/`endArrow` and their `Fill` |
 | Container, pool, lane | `container=1` or a `swimlane` is a container; a swimlane whose swimlanes span its body is a pool of lanes, stacked in rows with `horizontal=0` |
 | Group | a `group` cell around its members |
@@ -130,6 +162,7 @@ cannot read.
 | parallelogram | `A[/text/]` | `shape=parallelogram` |
 | trapezoid | `A[/text\]` | `shape=trapezium` |
 | edge and label | `A -->\|text\| B`, `A -- text --> B` | `A -> B [label=…]` |
+| end labels | — | `taillabel`, `headlabel` |
 | no arrowhead, dashed, thick | `---`, `-.->`, `==>` | `dir`, `arrowhead`, `style=dashed`, `penwidth` |
 | container | `subgraph` | `subgraph cluster_*` |
 | page name | front matter `title` | the graph's `label`, else its name |
@@ -137,8 +170,7 @@ cannot read.
 | colors | `classDef`, `class`, `:::`, `style`, `linkStyle` | `fillcolor` with `style=filled`, `color`, `fontcolor` |
 | ports | — | `node:compass`, `n`, `e`, `s`, and `w` only |
 
-A Mermaid shape with no outline here reads as a rect, with a warning; a
-Mermaid diagram of another kind is refused with an error naming the kind. DOT
+A Mermaid shape with no outline here reads as a rect, with a warning. DOT
 reads its whole grammar: `strict`, `graph` and `digraph`, attribute
 statements and their scoping, edge chains, and subgraphs as edge ends. Its
 HTML labels read as their text, and the attributes it does not read are
@@ -154,6 +186,197 @@ ids that are keywords or not plain names are renamed, keeping their text.
 Bends, connectors to other pages, drawn outlines, and ports a format lacks
 are dropped with a warning.
 
+### Mermaid's other kinds
+
+`DIAGRAM_MERMAID` reads a diagram by its header and sets the page's `notation`
+to the kind it read; it writes a graph page in the kind its `notation` names,
+and as a flowchart when it names none (or one Mermaid has not, with a
+warning). Every kind reads front matter's `title` as the page name (else
+`accTitle`), skips `%%` comments, and drops `%%{…}%%` directives and
+`accDescr` with a warning. A Mermaid kind not read here (`zenuml`,
+`treemap`, …) is refused with an error naming it. Each reader throws an error
+naming the line on text it cannot read, and warns of what it drops.
+
+`classDiagram`, notation `'class'`:
+
+| Mermaid | Diagram |
+| --- | --- |
+| `class A`, `class A~T~`, `class A["Label"]` | a box: `<<annotation>>` rows, the name row (`A<T>`), a divider, attribute rows, a divider, method rows |
+| members in `class A { … }`, or `A : +member` | a member with parentheses is a method |
+| `<<interface>> A`, or inside the braces | an annotation row |
+| `<\|--` `*--` `o--` `-->` `--` | `triangle-hollow`, `diamond`, `diamond-hollow`, `arrow`, none, at the end the head is on |
+| `..>` `..\|>` `..` | dashed, with `arrow-open`, `triangle-hollow`, none |
+| `A "1" --> "*" B : label` | `endLabels` `{ from: '1', to: '*' }`, and the label |
+| `namespace N { … }` | a container |
+| `note "text"`, `note for A "text"` | a `note` shape, joined to `A` by a dashed unmarked edge |
+| `direction LR` | the page's `direction` |
+| `style`, `classDef`, `cssClass`, `:::` | colors |
+
+`stateDiagram-v2` and `stateDiagram`, notation `'state'`:
+
+| Mermaid | Diagram |
+| --- | --- |
+| `A`, `state "Name" as A`, `A : description` | a `roundRect` with the name, then each description, as lines |
+| `[*]` | a `start` where a transition leaves it and an `end` where one arrives, one each per scope |
+| `state A <<fork>>`, `<<join>>`, `<<choice>>` | a `bar` across the way the page runs, and an empty diamond |
+| `A --> B : label` | an edge and its label |
+| `state X { … }` | a container; divided by `--` into concurrent regions, a pool with a lane per region |
+| `note right of A : text`, `note left of A … end note` | a `note` shape joined to `A`; the side is dropped |
+| `classDef`, `class`, `:::` | colors |
+
+`erDiagram`, notation `'er'`:
+
+| Mermaid | Diagram |
+| --- | --- |
+| `A`, `A["Label"]` | a box of its name row |
+| `A { type name PK, FK "comment" }` | a divider, then a `field` row per attribute: the type as its label; the name, keys, and comment as its value |
+| `\|o` `\|\|` `}o` `}\|` (and mirrored) | `crow-zero-one`, `crow-one`, `crow-zero-many`, `crow-one-many` at that end |
+| `--`, `..` | solid, dashed |
+| `A \|\|--o{ B : label` | the label |
+| `style`, `classDef`, `class` | colors |
+
+`mindmap`, notation `'mindmap'`:
+
+| Mermaid | Diagram |
+| --- | --- |
+| an indented line | a node, joined to the line it is indented under by an unmarked edge |
+| `text`, `id[text]`, `id(text)`, `id((text))`, `id))text((`, `id)text(`, `id{{text}}` | no outline of its own, `rect`, `roundRect`, `ellipse`, `cloud`, `cloud`, `hexagon` |
+| no id | `n` and its place in the file: `n2`, `n3`, … |
+| the whole map | laid out by `radial`, the root in the middle and its branches to both sides (the page's `layout`) |
+| `::icon(…)`, `:::class` | dropped, with a warning |
+
+`requirementDiagram`, notation `'requirement'`:
+
+| Mermaid | Diagram |
+| --- | --- |
+| `requirement name { … }`, its five other kinds, and `element name { … }` | a box: a `<<kind>>` row, the name row, a divider, a `field` row per `key: value` |
+| `a - satisfies -> b`, `b <- satisfies - a` | a dashed arrow from `a` to `b` labeled `<<satisfies>>` |
+| `style`, `classDef`, `class` | colors |
+
+`block-beta`, notation `'block'`, laid out by `grid` (the page's `layout`):
+
+| Mermaid | Diagram |
+| --- | --- |
+| `a`, `a["text"]`, and the flowchart's other brackets | a node: its text (else its id) in the flowchart's outline for those brackets |
+| `columns 3` | the grid's `columns`, or a group's under `groupColumns`; `columns auto` leaves it unset |
+| `a:2`, `block:g:2` | `spans` |
+| `space`, `space:2` | `skips` on the next block; spaces after a level's last block are dropped, with a warning |
+| `block:g … end`, `block … end` | a container holding its blocks in order; an unnamed one is `block-1`, `block-2`, … |
+| `a --> b`, `a --- b`, `a -.-> b`, `a ==> b`, `a <--> b`, `a -- "text" --> b` | an edge: its heads, dashed or 3 wide, and its label |
+| `style`, `classDef`, `class` | colors |
+| `a<["text"]>(right)` | a rect, its direction dropped with a warning |
+
+`architecture-beta`, notation `'architecture'`, laid out running right:
+
+| Mermaid | Diagram |
+| --- | --- |
+| `service a(icon)[Title] in g` | a node of its title (else its id): `cloud`, `database`, `disk`, `internet`, and `server` as the `cloud`, `cylinder`, `disk`, `globe`, and `server` outlines; no icon, or any other with a warning, as `roundRect` |
+| `junction j in g` | a 12-wide `start` dot with no text |
+| `group g(icon)[Title] in parent` | a container titled with its title; its icon is dropped with a warning |
+| `a:R --> L:b`, `--`, `<--`, `<-->` | an edge leaving `a`'s `e` port and meeting `b`'s `w` (`L`, `R`, `T`, `B` as `w`, `e`, `n`, `s`), with its heads |
+| `a{group}:R --> L:b` | an edge from `a`'s group, meeting its box where layout chooses |
+
+`C4Context`, `C4Container`, `C4Component`, `C4Dynamic`, and `C4Deployment`, notations `'c4-context'` through `'c4-deployment'`:
+
+| Mermaid | Diagram |
+| --- | --- |
+| `Person`, `System`, `Container`, `Component`, their `Db` and `Queue` kinds, and each one's `_Ext` | a node 200 wide: a `<<kind>>` row (`<<external_system_db>>`), its name in bold, a container's or component's `[technology]`, and its description wrapped; outline `person`, `cylinder`, `queue`, or `roundRect`; role `muted` when external, else `accent` |
+| `Enterprise_Boundary`, `System_Boundary`, `Container_Boundary`, `Boundary`, `Deployment_Node`, `Node` | a container titled `Name [enterprise]`, `[system]`, `[container]`, or the type it gives |
+| `Rel(a, b, "label", "technology")`, `BiRel`, `Rel_Back` | an edge labeled `label [technology]`; heads at both ends; a head at `a` only |
+| `Rel_U`, `Rel_D`, `Rel_L`, `Rel_R` | ports: `n` to `s`, `s` to `n`, `w` to `e`, `e` to `w` |
+| `UpdateElementStyle(a, $bgColor, $fontColor, $borderColor)`, `UpdateRelStyle(a, b, $textColor, $lineColor)` | colors |
+| `title` | the page name |
+| sprites, tags, links, a relationship's description, offsets, and layout settings | dropped, with a warning |
+
+Written back, a box with no `<<kind>>` row is a system, a person, store, or queue by its outline, and external when its role is `muted`.
+
+`kanban`, notation `'kanban'`:
+
+| Mermaid | Diagram |
+| --- | --- |
+| the board | one pool, `board`, whose lanes run along `x`, sized to hold its longest column |
+| `todo[Todo]`, a line at the shallowest indent | a lane 220 wide; one with no id is `column-` and its place |
+| `id[text]`, a line indented under it | a node 180 wide in that lane: its text wrapped into rows; one with no id is `card-` and its place |
+| `@{ ticket: MC-1, assigned: 'kim', priority: 'High' }` | a `field` row per pair |
+
+Writing a kind writes what its reader reads, so text read and written reads
+back as the same page. A page from elsewhere writes as near as the kind
+allows, with a warning for each thing it cannot carry: an end a class diagram
+has no head for is an arrow, one an ER diagram has no crow's foot for is
+exactly one, an unlabeled relationship is `traces`, and a mind map keeps the
+first root's tree.
+### Mermaid xychart
+
+`xychart-beta`, or `xychart`, reads onto one 800 by 500 plot page holding an
+`xychart` (`readMermaidXychart`), and a plot page holding one writes back as
+`xychart-beta` (`writeMermaidXychart`). Errors name the line.
+
+| `XyChartData` | Mermaid |
+| --- | --- |
+| `orientation: 'horizontal'` | `xychart-beta horizontal` |
+| `title`, and the page name | `title "…"`, else the front matter's `title` |
+| `x`, a band axis | `x-axis "title" [a, "b c"]` |
+| `x`, a range axis | `x-axis "title" 1 --> 10` |
+| `y` | `y-axis "title" 0 --> 100`; one end alone is dropped on writing, with a warning |
+| a series | `bar "name" [1, 2]`, `line [1, 2]` |
+
+Reading drops other front matter, `%%{init}%%` directives, `accTitle` and
+`accDescr`, with a warning each, and warns of values past the last category.
+
+### Mermaid charts
+
+Each of these reads onto one plot page holding the chart kind named, and a
+plot page holding that kind writes back as it; the writer picks the Mermaid
+kind from the chart's kind. Each reader names the line of an error (a score
+out of range, a field that overlaps another, a checkout of a branch that does
+not exist) and warns of what it drops; each writer warns of what Mermaid
+cannot hold.
+
+| Mermaid | Chart | What is read |
+| --- | --- | --- |
+| `gantt` | `gantt` | `title`, `dateFormat`, `axisFormat`, `excludes`, `todayMarker`, `section`; tasks `Name :tags, id, start, end` with `done`/`active`/`crit`/`milestone`, a start that is a date or `after a b`, an end that is a date, a duration (`3d`, `2w`, `5h`, `1M`, …) or `until a`, each kept as written |
+| `timeline` | `timeline` | `title`, `section`, `period : event : event`, and `: event` lines continuing the period above |
+| `pie` | `pie` | `pie showData title …`, `title`, `"label" : value` |
+| `quadrantChart` | `quadrant` | `title`, `x-axis Low --> High`, `y-axis`, `quadrant-1` to `quadrant-4`, points `Name: [x, y]` with `:::class` and `radius`, `color`, `stroke-color`, `stroke-width`, `classDef` |
+| `journey` | `journey` | `title`, `section`, `Task: score: Actor, Actor` |
+| `gitGraph` | `gitgraph` | `gitGraph LR:`/`TB:`/`BT:`, `commit` (`id`, `type`, `tag`, `msg`), `branch` (`order`), `checkout`/`switch`, `merge` (`id`, `type`, `tag`), `cherry-pick` (`id`, `tag`, `parent`); the title from front matter |
+| `sankey-beta` | `sankey` | CSV `source,target,value` lines, quoted as CSV quotes; the title from front matter |
+| `packet-beta` | `packet` | `title`, `0-15: "label"`, `16: "label"`, `+8: "label"` |
+| `radar-beta` | `radar` | `title`, `axis a["Label"], b`, `curve c["Label"]{1, 2}` and `curve c{ a: 1, b: 2 }`, `max`, `min`, `graticule`, `ticks`, `showLegend` |
+
+Dropped on reading, with a warning: Gantt `click`, `call`, `inclusiveEndDates`,
+`topAxis`, `tickInterval`, `weekday`, `displayMode`, and `vert` tasks; a
+timeline's direction; configuration such as a packet's bits per row or a git
+graph's main branch name. Gantt dates are read and written in UTC.
+
+### Mermaid sequence diagrams
+
+A `sequenceDiagram` reads into one sequence page, and a sequence page writes
+back as one. The reader throws an error naming the line on what it cannot read,
+including an `end` that closes nothing and a fragment never closed.
+
+| Sequence | Mermaid |
+| --- | --- |
+| participant and label | `participant A as Text`, `actor A` |
+| outline | `participant A@{ "type" : "boundary" }`: `boundary`, `control`, `entity`, `database` (the cylinder), `collections`, `queue` |
+| message `line`, `head`, `both` | `->`, `-->`, `->>`, `-->>`, `-x`, `--x`, `-)`, `--)`, `<<->>`, `<<-->>` |
+| `activate: 'to'`, `deactivate: 'from'` | `A->>+B`, `B-->>-A` |
+| activate, deactivate | `activate A`, `deactivate A` |
+| note | `Note left of A`, `Note right of A`, `Note over A,B` |
+| fragment | `loop`, `alt`/`else`, `opt`, `par`/`and`, `critical`/`option`, `break`; `rect <color>` is a `region` |
+| box | `box <color> Label` … `end` |
+| create, destroy | `create participant B`, `destroy B` |
+| `autonumber` | `autonumber`, `autonumber 10` |
+| page name | `title`, or the front matter's `title` |
+
+A participant a message or note names before any declaration is added in the
+order it is first named. Configuration, accessibility text, participant menus
+(`link`, `links`, `properties`, `details`), and an autonumber step other than 1
+are dropped with a warning. Writing, colors and roles on participants and
+fragments, a region's label, and a second head on a message whose head is not
+an arrow are dropped with a warning; an activation Mermaid has no shorthand for
+is written as its own `activate` or `deactivate` line.
+
 ## Exporting a page
 
 A page is a rect in world space; a `PlacedPage` from core's `placedPagesOf` is
@@ -187,6 +410,7 @@ annotation layers are left out.
 | A shape's outline (`diagram.outline`) | A path of that outline in the shape's box, with its fill and stroke; a container's divider under its header as a second path. A container's members follow inside its group. |
 | A connector, or any node that derives its path | One path along the route, with its stroke and its `marker-start` and `marker-end`. A path made of parts writes one path per part. |
 | A drawn mark | Its unit-square path stretched over its box. |
+| A plot's mark | Its path or its text, in the plot root's frame. |
 | Rows, labels, text marks, and off-page tags | Text, laid out in the lines the canvas lays it into; a tag's background is a rect behind it. |
 | Anything else | What `@weasel-js/svg`'s `svgLeafFromKit` writes for it. |
 
@@ -234,5 +458,6 @@ register, as for the PNG, and this needs WebGL2 and `OffscreenCanvas`.
 
 ## Scenes it reads
 
-Poses are read as world-space `RectPose`s, which is what a diagram scene
-holds. A scene that composes child poses into a parent's frame is not one.
+Poses are `RectPose`s. A child stores its pose in its parent's frame, and both
+the reader and the page exports fold it through that frame, so each sees a node
+where the canvas draws it.

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { DiagramData, LayoutDirection, DataEdge, DiagramTheme, DiagramSpec, MeasureRowText } from '@weasel-js/diagram';
-import { Scene, SerializedDoc, RectPose } from '@weasel-js/core';
+import { DiagramData, LayoutDirection, LayoutOptions, SequenceData, DataEdge, DiagramTheme, MeasureRowText, DiagramSpec, DiagramType } from '@weasel-js/diagram';
+import { PlotData, PlotTheme } from '@weasel-js/plot';
+import { Page, Scene, SerializedDoc, PlacedPage, RectPose } from '@weasel-js/core';
 import { SvgNode, SerializeOptions } from '@weasel-js/svg';
 import { PdfSkip } from '@weasel-js/pdf';
 
@@ -10,19 +11,44 @@ import { PdfSkip } from '@weasel-js/pdf';
  * once for a chart and for a data-backed host alike.
  */
 
-/**
- * One page: its sheet size, and what is on it in coordinates from the page's
- * top-left corner. Ids share one namespace across the whole document.
- */
-interface DocumentPage {
+/** What every page has: its sheet size. Ids share one namespace across the whole document. */
+interface PageBase {
     id: string;
     name?: string;
     width: number;
     height: number;
+}
+/** A page of nodes and edges, in coordinates from the page's top-left corner. */
+interface GraphPage extends PageBase {
+    kind: 'graph';
     data: DiagramData;
     /** The way layout runs when the page is laid out on import, which it is when a node has no `at`. */
     direction?: LayoutDirection;
+    /** The layout that runs when the page is laid out on import. Unset, `layered`. */
+    layout?: PageLayout;
+    /** What the graph models, such as `'class'` or `'state'`: a format with a notation of that name writes it in
+     *  that notation. Unset, a plain flowchart. */
+    notation?: string;
+}
+/** A layout by its name in `@weasel-js/diagram`'s `LAYOUTS`, and the options a file can carry for it. */
+interface PageLayout {
+    name: 'layered' | 'tree' | 'force' | 'chain' | 'radial' | 'grid';
+    options?: Pick<LayoutOptions, 'nodeGap' | 'rankGap' | 'order' | 'chainSide' | 'grid'>;
 }
+/** A page holding one chart, which fills it. */
+interface PlotPage extends PageBase {
+    kind: 'plot';
+    data: PlotData;
+}
+/** A sequence diagram, laid out from its data whenever it is drawn. Its `name` is the diagram's title. */
+interface SequencePage extends PageBase {
+    kind: 'sequence';
+    data: SequenceData;
+}
+/** One page of a document; `kind` says what its `data` is. */
+type DocumentPage = GraphPage | SequencePage | PlotPage;
+/** The kinds of page a document can hold. */
+type PageKind = DocumentPage['kind'];
 /** A diagram as every format reads and writes it. */
 interface DiagramDocument {
     pages: readonly DocumentPage[];
@@ -65,9 +91,19 @@ interface DiagramFormat {
     write?(doc: DiagramDocument, opts?: WriteOptions): ExportResult;
     /** Whether {@link write} writes one page rather than the whole document. */
     onePage?: boolean;
+    /** The kinds of page it reads and writes. A writer leaves out a page of any other kind, with a warning. */
+    kinds: readonly PageKind[];
 }
 /** The page a one-page format writes: the one `opts.page` names, else the first. `null` for a document with none. */
 declare function writtenPage(doc: DiagramDocument, opts?: WriteOptions): DocumentPage | null;
+/** `page` as a graph, for a format that writes graphs only. Throws on a page of any other kind. */
+declare function graphPageOf(page: DocumentPage, format: string): GraphPage;
+/** The graph pages of `doc`, warning once for each page of another kind left out. */
+declare function graphPagesOf(doc: DiagramDocument, format: string, warn: (message: string) => void): GraphPage[];
+/** Whether `format` can write every page of `doc`. */
+declare function formatHolds(format: DiagramFormat, doc: DiagramDocument): boolean;
+/** Whether `format` reads and writes every kind in `kinds`: what a menu asks of `scenePageKinds`. */
+declare function formatTakes(format: DiagramFormat, kinds: ReadonlySet<PageKind>): boolean;
 
 /** The formats a diagram reads from and writes to, and how a file finds its format. */
 
@@ -97,19 +133,35 @@ declare const DIAGRAM_JSON: DiagramFormat;
  */
 declare const DRAW_XML: DiagramFormat;
 
-/** Mermaid as a {@link DiagramFormat}. */
-
-/**
- * A Mermaid flowchart, one page per file, laid out on import. Any Mermaid
- * diagram is recognized, so reading another kind says which kind it is.
- */
+/** Mermaid diagrams, one page per file, laid out on import. Any Mermaid diagram is recognized, so reading a kind not read says which it is. */
 declare const DIAGRAM_MERMAID: DiagramFormat;
 
+/** Reads a Mermaid `xychart-beta` (or `xychart`) diagram. Throws, naming the line, on text that is not one. */
+declare function readMermaidXychart(text: string): ImportResult;
+
+/** Writes `page`'s xychart as Mermaid. Throws on a page holding another kind of chart. */
+declare function writeMermaidXychart(page: PlotPage): ExportResult;
+
+/** Plot pages to and from a scene: one plot root per page, which the plot package compiles and keeps. */
+
+/** A diagram theme's colors by the roles a chart draws in: text in the label color, axes in the connector stroke,
+ *  grid lines in the container stroke, series in its series, in its face. */
+declare function plotThemeOf(theme: DiagramTheme): PlotTheme;
+
 /** Graphviz DOT as a {@link DiagramFormat}. */
 
 /** A Graphviz DOT graph, one page per file, laid out on import unless every node has a `pos`. */
 declare const DIAGRAM_DOT: DiagramFormat;
 
+/** A graph page's notation, layout, and direction, kept on its scene page so they survive the scene. */
+
+/** The key a scene page's `meta` holds a graph page's {@link GraphPageSettings} under. */
+declare const GRAPH_PAGE_META_KEY = "diagram:graph";
+/** What a graph page says beyond its data: how it is laid out and what it models. */
+type GraphPageSettings = Pick<GraphPage, 'direction' | 'layout' | 'notation'>;
+/** The graph settings scene page `page` keeps; empty when it keeps none. */
+declare function graphPageSettingsOf(page: Pick<Page, 'meta'>): GraphPageSettings;
+
 /** A diagram scene as a {@link DiagramDocument}: what every format writes from. */
 
 /** Options for {@link documentFromScene}. */
@@ -121,16 +173,30 @@ interface DocumentFromSceneOptions {
  * Reads a diagram scene into a document: one page per page in its `core:pages`
  * (one page around everything when it has none), each holding the shapes,
  * connectors, containers and pools, and groups on it, in coordinates from the
- * page's corner. A shape belongs to the page its outermost container does, and
+ * page's corner; a page holding a plot root is a plot page of its spec, and
+ * whatever else is on it is left out. A shape belongs to the page its outermost container does, and
  * that is the one its box overlaps most, or the nearest one when it overlaps
  * none. A connector the scene splits off-page, or whose ends export to
  * different pages, goes in `crossPageEdges`: without waypoints when split,
  * with them in world coordinates when not. Colors are kept
  * where the scene's theme would not give them: the author's own, and any a
- * theme never set.
+ * theme never set. A page holding a sequence's root is a sequence page holding
+ * its data; the parts drawn from it, and anything else on that page, are not read.
+ * A graph page takes the notation, layout, and direction its scene page keeps; with no notation there, the one the
+ * scene's diagram type writes (`diagramNotationOf`).
  */
 declare function documentFromScene<TData, TLayer extends string, TPose>(scene: Scene<TData, TLayer, TPose>, opts?: DocumentFromSceneOptions): DiagramDocument;
 
+/** Which kinds of page a scene would export as, read from its top-level nodes alone. */
+
+/**
+ * The kinds of page `documentFromScene` would make of `scene`, without making
+ * them: a page holding a plot's root is a plot page, one holding a sequence's
+ * root a sequence page, any other a graph page. Cheap enough to ask on every
+ * menu render.
+ */
+declare function scenePageKinds<TData, TLayer extends string, TPose>(scene: Scene<TData, TLayer, TPose>): ReadonlySet<PageKind>;
+
 /** A {@link DiagramDocument} as scene specs and document values: what every import draws from. */
 
 /** Options for {@link documentSpecs}. */
@@ -142,21 +208,84 @@ interface DocumentSpecsOptions<TLayer extends string = 'main'> {
     /** Measures text. Default an estimate from character count. */
     measure?: MeasureRowText;
 }
-/** What {@link documentSpecs} returns: the nodes, and the `core:pages` and `diagram:theme` document values. */
+/** What {@link documentSpecs} returns: the nodes, and the `core:pages`, `diagram:theme`, and `diagram:type` document values. */
 interface DocumentScene<TLayer extends string = 'main'> {
     specs: DiagramSpec<TLayer>[];
     doc: SerializedDoc;
 }
 /**
  * The scene a document draws as. Its pages are placed with core's
- * `layoutPages`, as a scene's `core:pages` places them. A page whose nodes
- * all have a place is drawn where they say; any other page is laid out first,
- * with `layered`, its placed nodes pinned (and grows to hold the result). Then
- * every page, moved to its place, and the edges between pages are drawn by one
- * `diagramScene` call with no layout, so the scene holds places and routes and
- * no layout runs again.
+ * `layoutPages`, as a scene's `core:pages` places them. A graph page whose
+ * nodes all have a place is drawn where they say; any other is laid out
+ * first, with `layered`, its placed nodes pinned (and grows to hold the
+ * result). A sequence page is drawn from its data, one root holding it, and
+ * grows to hold its layout. A plot page is one plot root filling its page, its
+ * marks under it (`plotSpecs`), drawn in the theme's colors. A graph page's
+ * notation, layout, and direction go on its `core:pages` page, under
+ * `meta['diagram:graph']`, where `documentFromScene` reads them back. When
+ * every graph page's notation is one a diagram type claims, the scene opens as
+ * that type (`diagram:type`), its stencils with it.
  */
 declare function documentSpecs<TLayer extends string = 'main'>(document: DiagramDocument, opts?: DocumentSpecsOptions<TLayer>): DocumentScene<TLayer>;
+/**
+ * One more page for a scene: `page` as its `core:pages` lists it, and the nodes it draws as once placed where
+ * `placeAt` puts it, as `documentSpecs` draws a page. A graph page with no place for a node is laid out first; a
+ * sequence page grows to hold its layout.
+ */
+declare function pageSpecs<TLayer extends string = 'main'>(page: DocumentPage, placeAt: (page: Page) => PlacedPage, opts?: DocumentSpecsOptions<TLayer>): {
+    page: Page;
+    specs: DiagramSpec<TLayer>[];
+};
+
+/** Templates: a new page of every kind a document holds, from an empty graph of each diagram type to a small chart. */
+
+/** Where a menu lists a template: with the diagrams, as a sequence diagram, or with the charts. */
+type PageTemplateGroup = 'diagram' | 'sequence' | 'chart';
+/** A new page of one kind. */
+interface PageTemplate {
+    id: string;
+    label: string;
+    icon?: DiagramType['icon'];
+    group: PageTemplateGroup;
+    /** The diagram type a document made from it takes: the one a graph template draws. */
+    diagramType?: string;
+    /** The page, under `id`. `size` is a graph page's; a sequence or a chart takes the size its content needs. */
+    page(id: string, size?: {
+        width: number;
+        height: number;
+    }): DocumentPage;
+}
+/** A graph page's size when none is asked for: letter, landscape, at 96 per inch. */
+declare const TEMPLATE_PAGE_SIZE: {
+    readonly width: 1056;
+    readonly height: 816;
+};
+/** Every template, by id, in menu order: each diagram type's, the sequence diagram's, then each chart kind's. */
+declare const PAGE_TEMPLATES: Readonly<Record<string, PageTemplate>>;
+
+/** A template as a new scene, or as one more page of one. */
+
+/** A new document of one page made from `template`, as {@link documentSpecs} draws it, with the diagram type the
+ *  template names. */
+declare function templateSpecs<TLayer extends string = 'main'>(template: PageTemplate, opts?: DocumentSpecsOptions<TLayer> & {
+    size?: {
+        width: number;
+        height: number;
+    };
+}): DocumentScene<TLayer>;
+/** Options for {@link addTemplatePage}. */
+interface AddTemplatePageOptions<TLayer extends string = 'main'> extends DocumentSpecsOptions<TLayer> {
+    /** Where the page goes in the page order. Default last. */
+    index?: number;
+    /** A graph page's size. Default the template's. */
+    size?: {
+        width: number;
+        height: number;
+    };
+}
+/** Adds a page made from `template` to `scene`, and what it draws on it, as one undo entry, `Add page`. Returns the new
+ *  page's id. */
+declare function addTemplatePage<TData, TLayer extends string, TPose>(scene: Scene<TData, TLayer, TPose>, template: PageTemplate, opts?: AddTemplatePageOptions<TLayer>): string;
 
 /**
  * One page of a diagram scene as `SvgNode`s: the nodes whose box meets the
@@ -245,4 +374,4 @@ declare function exportPagesPdf(scene: PageExportScene, pages: readonly PageRect
     skipped: readonly PdfSkip[];
 }>;
 
-export { DIAGRAM_DOT, DIAGRAM_FORMATS, DIAGRAM_JSON, DIAGRAM_MERMAID, DRAW_XML, type DiagramDocument, type DiagramFormat, type DocumentFromSceneOptions, type DocumentPage, type DocumentScene, type DocumentSpecsOptions, type ExportPagePngOptions, type ExportPageSvgOptions, type ExportPagesPdfOptions, type ExportResult, type ImportResult, type PageExportScene, type PageRect, type WriteOptions, detectFormat, documentFromScene, documentSpecs, exportPagePng, exportPageSvg, exportPagesPdf, pageSvgNodes, readDocument, writtenPage };
+export { type AddTemplatePageOptions, DIAGRAM_DOT, DIAGRAM_FORMATS, DIAGRAM_JSON, DIAGRAM_MERMAID, DRAW_XML, type DiagramDocument, type DiagramFormat, type DocumentFromSceneOptions, type DocumentPage, type DocumentScene, type DocumentSpecsOptions, type ExportPagePngOptions, type ExportPageSvgOptions, type ExportPagesPdfOptions, type ExportResult, GRAPH_PAGE_META_KEY, type GraphPage, type GraphPageSettings, type ImportResult, PAGE_TEMPLATES, type PageBase, type PageExportScene, type PageKind, type PageLayout, type PageRect, type PageTemplate, type PageTemplateGroup, type PlotPage, type SequencePage, TEMPLATE_PAGE_SIZE, type WriteOptions, addTemplatePage, detectFormat, documentFromScene, documentSpecs, exportPagePng, exportPageSvg, exportPagesPdf, formatHolds, formatTakes, graphPageOf, graphPageSettingsOf, graphPagesOf, pageSpecs, pageSvgNodes, plotThemeOf, readDocument, readMermaidXychart, scenePageKinds, templateSpecs, writeMermaidXychart, writtenPage };