@eventcatalog/core 5.0.0-beta.11 → 5.0.0-beta.12

package/eventcatalog/src/features/studio/agent-choreography.ts

@@ -9,7 +9,8 @@ import {
   fitContainersAround,
   getCanvasMaps,
   moveNode,
-  resizeNode,
+  placeNode,
+  setEdgeRoutes,
   setMeta,
   type Author,
   type CommentAnchor,
@@ -292,13 +293,14 @@ export async function playLayout(stage: AgentStage, layout: LayoutResult) {
   hand.say('Done');
 }
 
-/** Moves nodes and resizes containers from a layout, in one change, and marks when it happened */
+/**
+ * Moves nodes, resizes containers and routes connections from a layout, in one change, and marks when it
+ * happened. Connections the layout didn't route lose their old route (drawn as a plain step instead).
+ */
 export const applyLayout = (doc: Y.Doc, layout: LayoutResult) =>
   doc.transact(() => {
-    layout.forEach(({ position, size }, id) => {
-      moveNode(doc, id, position);
-      if (size) resizeNode(doc, id, size);
-    });
+    layout.nodes.forEach(({ position, size }, id) => placeNode(doc, id, position, size));
+    setEdgeRoutes(doc, layout.routes);
     setMeta(doc, { layoutAt: Date.now() });
   });
 

package/eventcatalog/src/features/studio/api/canvases-api.ts

@@ -1,7 +1,10 @@
 import { Hono, type Context } from 'hono';
 import { z } from 'zod';
 import { paginate } from '@features/tools/catalog-tools';
-import { MAX_TITLE_LENGTH, type CanvasStatus } from '../canvas-doc';
+import type { CanvasContent, CanvasStatus } from '../canvas-doc';
+import { MAX_TITLE_LENGTH } from '../limits';
+import { diagramLevelsSchema, indexCatalog, newCanvasEdgesSchema, nodeSpecsSchema, planCanvas } from '../canvas-actions';
+import { getCatalogResources } from '../catalog-resources';
 import { MAX_NAME_LENGTH } from '../identity';
 import type { CanvasSummary, StudioRuntime } from '../server/runtime';
 import type { SignedInUser } from '../server/sign-in';
@@ -13,7 +16,13 @@ import type { SignedInUser } from '../server/sign-in';
  *
  *   GET    /api/studio/canvases        Canvases, most recently changed first (?pageSize=, ?cursor= for the next page)
  *                                       (not ones left empty and untitled: GET /:id still finds them)
- *   POST   /api/studio/canvases        Creates one: { "title"?: string, "createdBy"?: string }
+ *   POST   /api/studio/canvases        Creates one: { "title"?: string, "createdBy"?: string, "nodes"?: [...],
+ *                                       "edges"?: [...] }, starting with the nodes and edges given, if any (as the
+ *                                       add_to_canvas MCP tool takes them: catalog resources or new components, x/y
+ *                                       their centres, and only the connections in edges are made, each drawn
+ *                                       along its "route" if given: { "points": [{x, y}, ...], "label"?: {x, y} }),
+ *                                       and "levels" (L1 and L2 laid out, e.g. as a diagram shows them, by the
+ *                                       nodes' refs), shown as given until what's on the canvas changes
  *   GET    /api/studio/canvases/:id    One canvas
  *   POST   /api/studio/canvases/:id/copy   Copies its design (nodes and connections, not comments or status) to a new
  *                                         draft: { "title"?: string, "createdBy"?: string }
@@ -57,11 +66,23 @@ export type CanvasesApiEnv = {
   };
 };
 
+const MAX_NODES = 1000;
+const MAX_EDGES = 2000;
+
 const NewCanvas = z.object({
   title: z.string().trim().max(MAX_TITLE_LENGTH).optional(),
   // Ignored when someone's signed in: it's them
   createdBy: z.string().trim().max(MAX_NAME_LENGTH).optional(),
 });
+// A new canvas can start with nodes and edges; a copy starts with the original's
+const NewCanvasWithContent = NewCanvas.extend({
+  nodes: nodeSpecsSchema.max(MAX_NODES).optional(),
+  edges: newCanvasEdgesSchema.max(MAX_EDGES).optional(),
+  levels: diagramLevelsSchema.optional(),
+}).refine((canvas) => !canvas.edges?.length || canvas.nodes, {
+  message: 'Edges connect the nodes given with them: give nodes too',
+  path: ['edges'],
+});
 const ListQuery = z.object({
   cursor: z.string().optional(),
   pageSize: z.coerce.number().int().min(1).max(MAX_PAGE_SIZE).optional(),
@@ -86,26 +107,54 @@ const describeIssues = (error: z.ZodError) =>
 type ApiContext = Context<CanvasesApiEnv>;
 const noCanvas = (c: ApiContext, id: string) => c.json({ error: `No canvas "${id}"` }, 404);
 
-/** A new canvas's details from the request (optional), or the response saying what's wrong with them */
-const readNewCanvas = async (c: ApiContext): Promise<{ title?: string; createdBy?: string } | Response> => {
+type NewCanvasDetails = { title?: string; createdBy?: string };
+
+/** The request's JSON body (or {} without one), or the response saying what's wrong with it */
+const readJson = async (c: ApiContext): Promise<unknown> => {
   // JSON only: a page on another site can send a form or plain text here without asking first, but not JSON
   const body = await c.req.text();
   if (body && !c.req.header('content-type')?.toLowerCase().startsWith('application/json')) {
     return c.json({ error: 'Send the canvas as JSON (Content-Type: application/json)' }, 415);
   }
-  let json: unknown = {};
   try {
-    if (body) json = JSON.parse(body);
+    return body ? JSON.parse(body) : {};
   } catch {
     return c.json({ error: 'The body is not valid JSON' }, 400);
   }
+};
+
+const detailsOf = (c: ApiContext, canvas: z.output<typeof NewCanvas>): NewCanvasDetails => ({
+  title: canvas.title || undefined,
+  // Whoever's signed in, if anyone
+  createdBy: c.env.signedInAs?.name ?? (canvas.createdBy || undefined),
+});
+
+/** A copy's details from the request (optional), or the response saying what's wrong with them */
+const readCopy = async (c: ApiContext): Promise<NewCanvasDetails | Response> => {
+  const json = await readJson(c);
+  if (json instanceof Response) return json;
   const parsed = NewCanvas.safeParse(json);
   if (!parsed.success) return c.json({ error: describeIssues(parsed.error) }, 400);
-  return {
-    title: parsed.data.title || undefined,
-    // Whoever's signed in, if anyone
-    createdBy: c.env.signedInAs?.name ?? (parsed.data.createdBy || undefined),
-  };
+  return detailsOf(c, parsed.data);
+};
+
+/** A new canvas's details and what it starts with (all optional), or the response saying what's wrong with them */
+const readNewCanvas = async (c: ApiContext): Promise<{ details: NewCanvasDetails; content?: CanvasContent } | Response> => {
+  const json = await readJson(c);
+  if (json instanceof Response) return json;
+  const parsed = NewCanvasWithContent.safeParse(json);
+  if (!parsed.success) return c.json({ error: describeIssues(parsed.error) }, 400);
+  const details = detailsOf(c, parsed.data);
+  if (!parsed.data.nodes) return { details };
+  const { resources, relations } = await getCatalogResources();
+  const { content, errors } = planCanvas(
+    parsed.data.nodes,
+    parsed.data.edges ?? [],
+    indexCatalog(resources, relations),
+    parsed.data.levels
+  );
+  if (errors.length) return c.json({ error: errors.join('; ') }, 400);
+  return { details, content };
 };
 
 /** The API, served under `basePath` (the catalog's base URL, then CANVASES_API_PATH) */
@@ -132,15 +181,15 @@ export const createCanvasesApi = (basePath: string) => {
   };
 
   app.post('/', async (c) => {
-    const details = await readNewCanvas(c);
-    if (details instanceof Response) return details;
-    return created(c, await c.env.runtime.createCanvas(details));
+    const canvas = await readNewCanvas(c);
+    if (canvas instanceof Response) return canvas;
+    return created(c, await c.env.runtime.createCanvas(canvas.details, canvas.content));
   });
 
   app.post('/:id/copy', async (c) => {
     const id = c.req.param('id');
     if (!CANVAS_ID.test(id)) return noCanvas(c, id);
-    const details = await readNewCanvas(c);
+    const details = await readCopy(c);
     if (details instanceof Response) return details;
     const copyId = await c.env.runtime.copyCanvas(id, details);
     return copyId ? created(c, copyId) : noCanvas(c, id);

package/eventcatalog/src/features/studio/api/client.ts

@@ -1,4 +1,5 @@
 import type { ApiCanvas } from './canvases-api';
+import type { DiagramLevelsSpec, NewCanvasEdges, NodeSpecs } from '../canvas-actions';
 
 /** Using the Studio API from the browser (Studio's pages), at `apiUrl` (its address on this catalog) */
 
@@ -7,7 +8,11 @@ const errorOf = async (response: Response, fallback: string) => {
   return new Error(body?.error ?? `${fallback} (${response.status})`);
 };
 
-export const createCanvasThroughApi = async (apiUrl: string, canvas: { title?: string; createdBy?: string }) => {
+/** Creates a canvas, starting with the nodes and edges given, if any */
+export const createCanvasThroughApi = async (
+  apiUrl: string,
+  canvas: { title?: string; createdBy?: string; nodes?: NodeSpecs; edges?: NewCanvasEdges; levels?: DiagramLevelsSpec }
+) => {
   const response = await fetch(apiUrl, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json', Accept: 'application/json' },

package/eventcatalog/src/features/studio/canvas-actions.ts

@@ -1,7 +1,7 @@
 import type { Edge, Node, XYPosition } from '@xyflow/react';
 import type * as Y from 'yjs';
 import { z } from 'zod';
-import { buildNode, getCanvasMaps, getCanvasStatus, readCanvas, updateNodeData } from './canvas-doc';
+import { buildNode, getCanvasMaps, getCanvasStatus, readCanvas, updateNodeData, type CanvasContent } from './canvas-doc';
 import type { CatalogRelation, CatalogResource } from './catalog-resources';
 import {
   buildContainer,
@@ -12,10 +12,11 @@ import {
   getRelatedEdges,
   indexRelations,
 } from './catalog';
-import { findGroupAtPoint, getAbsolutePosition, sizeOf } from './grouping';
+import { containerFor, getAbsolutePosition, sizeOf } from './grouping';
 import { placeNodes, type Link } from './placement';
 import {
   canGoInContainer,
+  CATALOG_COLLECTIONS,
   COMPONENT_TYPES,
   getNodeDefinition,
   getNodeLabel,
@@ -34,17 +35,6 @@ import {
  * browser), so both describe and change a canvas the same way.
  */
 
-export const CATALOG_COLLECTIONS = [
-  'domains',
-  'systems',
-  'services',
-  'events',
-  'commands',
-  'queries',
-  'channels',
-  'containers',
-] as const;
-
 // ---- Inputs ----
 
 export const nodeSpecsSchema = z
@@ -71,6 +61,16 @@ export const nodeSpecsSchema = z
         .describe('A ref (or node id) of a container (a domain or system added as one) to put this node inside'),
       x: z.number().optional(),
       y: z.number().optional(),
+      width: z
+        .number()
+        .positive()
+        .optional()
+        .describe('For a container: its width to start with (it grows to fit what is put in it)'),
+      height: z
+        .number()
+        .positive()
+        .optional()
+        .describe('For a container: its height to start with (it grows to fit what is put in it)'),
     })
   )
   .min(1);
@@ -83,6 +83,83 @@ export const edgeSpecsSchema = z.array(
   })
 );
 
+const pointSchema = z.object({ x: z.number(), y: z.number() });
+
+/**
+ * Edges for a new canvas (through the Studio API): as add_to_canvas takes them, and how each is drawn, if known
+ * (e.g. copied from a diagram): the points it goes through (canvas coordinates, at right angles) and where its
+ * label goes. It follows its nodes when they're moved.
+ */
+const routeSchema = z.object({ points: z.array(pointSchema).min(2).max(200), label: pointSchema.optional() });
+export const newCanvasEdgesSchema = z.array(edgeSpecsSchema.element.extend({ route: routeSchema.optional() }));
+export type NewCanvasEdges = z.output<typeof newCanvasEdgesSchema>;
+
+const MAX_LEVEL_NODES = 1000;
+const levelSchema = z.object({
+  nodes: z
+    .array(
+      z.object({
+        ref: z.string().describe("The ref of the node it is on the canvas (or its own id, if it's only on this level)"),
+        type: z.string(),
+        data: z.record(z.string(), z.unknown()),
+        parent: z.string().optional().describe('The ref of the node it is shown in on this level'),
+        x: z.number().describe('Its top-left corner (relative to its parent)'),
+        y: z.number(),
+        width: z.number().positive().optional().describe('For a container: its size'),
+        height: z.number().positive().optional(),
+      })
+    )
+    .max(MAX_LEVEL_NODES),
+  edges: z
+    .array(
+      z.object({
+        from: z.string(),
+        to: z.string(),
+        label: z.string().optional(),
+        type: z.string().optional(),
+        style: z.record(z.string(), z.unknown()).optional(),
+        markerEnd: z.unknown().optional(),
+        data: z.record(z.string(), z.unknown()).optional().describe("The edge's data, e.g. its route"),
+      })
+    )
+    .max(MAX_LEVEL_NODES * 2),
+});
+
+/**
+ * L1 and L2 of the diagram a canvas is opened from, laid out as the diagram showed them (by refs of the nodes given
+ * for the canvas): shown as they are until the canvas's structure changes
+ */
+const unavailableReason = z.string().max(300).optional();
+export const diagramLevelsSchema = z.object({
+  1: levelSchema.optional(),
+  2: levelSchema.optional(),
+  unavailable: z
+    .object({ 1: unavailableReason, 2: unavailableReason })
+    .optional()
+    .describe("Levels the diagram doesn't have, and why"),
+});
+export type DiagramLevelsSpec = z.output<typeof diagramLevelsSchema>;
+
+/** A diagram's level, with refs swapped for the ids of the nodes made for them */
+const toDiagramLevel = (level: z.output<typeof levelSchema>, idOf: (ref: string) => string) => {
+  const shown = new Set(level.nodes.map((node) => node.ref));
+  return {
+    nodes: level.nodes.map(
+      ({ ref, type, data, parent, x, y, width, height }): Node => ({
+        id: idOf(ref),
+        type,
+        data,
+        position: { x, y },
+        ...(parent && shown.has(parent) && { parentId: idOf(parent) }),
+        ...(width && height && { style: { width, height } }),
+      })
+    ),
+    edges: level.edges
+      .filter((edge) => shown.has(edge.from) && shown.has(edge.to))
+      .map(({ from, to, ...edge }, index) => ({ ...edge, id: `diagram-${index}`, source: idOf(from), target: idOf(to) }) as Edge),
+  };
+};
+
 export const ADD_TO_CANVAS_DESCRIPTION = [
   'Adds nodes (and connections between them) to the canvas, live for everyone on it.',
   'A node is either a catalog resource (resource: { collection, id }), shown with its real name and summary and automatically connected to the related resources already on the canvas (e.g. a service to the events it publishes), or a new component (type, name, summary) for things that are not in the catalog yet, like a proposed service.',
@@ -199,6 +276,13 @@ export const planNodes = (existing: Node[], specs: NodeSpecs, catalog: CatalogIn
   const errors: string[] = [];
   const hasPosition = (spec: { x?: number; y?: number }) => spec.x !== undefined && spec.y !== undefined;
   const centerOf = (spec: { x?: number; y?: number }) => (hasPosition(spec) ? { x: spec.x!, y: spec.y! } : { x: 0, y: 0 });
+  // A container at the size asked for, still centred where asked
+  const sized = (node: Node, spec: { x?: number; y?: number; width?: number; height?: number }): Node => {
+    if (!isGroupType(node.type) || !spec.width || !spec.height) return node;
+    const center = centerOf(spec);
+    const { width, height } = spec;
+    return { ...node, width, height, position: { x: center.x - width / 2, y: center.y - height / 2 } };
+  };
 
   // Inside a container, at the canvas point asked for (relative to the container)
   const putInside = (node: Node, parent: Node, spec: { x?: number; y?: number }): Node => {
@@ -222,7 +306,7 @@ export const planNodes = (existing: Node[], specs: NodeSpecs, catalog: CatalogIn
       }
       const asContainer = spec.container && canBeContainer(resource);
       const node = asContainer
-        ? buildContainer(resource, centerOf(spec))
+        ? sized(buildContainer(resource, centerOf(spec)), spec)
         : buildNode(resource.node.type, catalogNodeData(resource), centerOf(spec));
       built = { node, name: resource.name, resource };
     } else {
@@ -238,7 +322,7 @@ export const planNodes = (existing: Node[], specs: NodeSpecs, catalog: CatalogIn
             ...(spec.summary && { summary: spec.summary }),
             ...(spec.version && isVersioned(definition.type) && { version: spec.version }),
           });
-      const node = buildNode(definition.type, data, centerOf(spec));
+      const node = sized(buildNode(definition.type, data, centerOf(spec)), spec);
       built = { node, name: String(getResource(node.type, node.data).name ?? definition.label) };
     }
 
@@ -297,11 +381,44 @@ export const planNodes = (existing: Node[], specs: NodeSpecs, catalog: CatalogIn
 };
 
 /** Edges given by refs (or ids of nodes already on the canvas), as node ids */
-export const resolveEdgeRefs = (edges: EdgeSpecs, planned: PlannedNode[]) => {
-  const refs = new Map(planned.flatMap((entry) => (entry.ref ? [[entry.ref, entry.node.id] as const] : [])));
+const refIds = (planned: PlannedNode[]) =>
+  new Map(planned.flatMap((entry) => (entry.ref ? [[entry.ref, entry.node.id] as const] : [])));
+
+export const resolveEdgeRefs = <Spec extends EdgeSpecs[number]>(edges: Spec[], planned: PlannedNode[]) => {
+  const refs = refIds(planned);
   return edges.map((edge) => ({ ...edge, from: refs.get(edge.from) ?? edge.from, to: refs.get(edge.to) ?? edge.to }));
 };
 
+/**
+ * A new canvas's content from nodes and edges given as add_to_canvas takes them. Only the connections asked for
+ * are made: related catalog resources aren't connected as well, so the canvas shows just what was asked for (e.g.
+ * a diagram's connections, which may go through channels). Says what's wrong if anything can't be followed.
+ */
+export const planCanvas = (
+  specs: NodeSpecs,
+  edges: NewCanvasEdges,
+  catalog: CatalogIndex,
+  levels?: DiagramLevelsSpec
+): { content: CanvasContent; errors: string[] } => {
+  const { planned, errors } = planNodes([], specs, catalog, edges);
+  const ids = new Set(planned.map((entry) => entry.node.id));
+  const connections = resolveEdgeRefs(edges, planned);
+  for (const end of connections.flatMap((connection) => [connection.from, connection.to])) {
+    if (!ids.has(end)) errors.push(`Edges connect nodes by their ref: no node has the ref "${end}"`);
+  }
+  const refs = refIds(planned);
+  const idOf = (ref: string) => refs.get(ref) ?? ref;
+  const diagramLevels = levels && {
+    ...(levels[1] && { 1: toDiagramLevel(levels[1], idOf) }),
+    ...(levels[2] && { 2: toDiagramLevel(levels[2], idOf) }),
+    ...(levels.unavailable && { unavailable: levels.unavailable }),
+  };
+  return {
+    content: { nodes: planned.map((entry) => entry.node), connections, ...(diagramLevels && { levels: diagramLevels }) },
+    errors: [...new Set(errors)],
+  };
+};
+
 export type NodeUpdate = { nodeId: string; name?: string; summary?: string; version?: string };
 
 /** Renames, re-describes or re-versions a node. Catalog resources keep their catalog name, summary and version. */
@@ -377,9 +494,9 @@ export const getCatalogConnections = (
 };
 
 /**
- * A catalog resource centred on a canvas point (inside the container there, if there is one), with the resources
- * it connects to placed around it like an architect would (what comes in before it, what goes out after it), and
- * the connections between them and to what's already on the canvas. A service's data stores go in its container
+ * A catalog resource centred on a canvas point (inside the container asked for, else the one there, if any), with
+ * the resources it connects to placed around it like an architect would (what comes in before it, what goes out
+ * after it), and the connections between them and to what's already on the canvas. A service's data stores go in its container
  * with it. Positions are relative to the containers they're in, as the canvas is now.
  */
 export const planWithConnections = (
@@ -387,9 +504,10 @@ export const planWithConnections = (
   resource: CatalogResource,
   center: XYPosition,
   include: CatalogResource[],
-  catalog: CatalogIndex
+  catalog: CatalogIndex,
+  inside?: string
 ): { nodes: Node[]; edges: Edge[] } => {
-  const container = findGroupAtPoint(center, existing);
+  const container = containerFor(center, existing, inside);
   const specOf = (entry: CatalogResource) => ({
     resource: { collection: entry.collection as (typeof CATALOG_COLLECTIONS)[number], id: entry.id },
   });

package/eventcatalog/src/features/studio/canvas-doc.ts

@@ -1,8 +1,9 @@
 import * as Y from 'yjs';
 import type { Connection, Edge, Node, XYPosition } from '@xyflow/react';
+import type { EdgeRoute } from '@eventcatalog/visualiser/layout';
 import { createEdge, getEdgeLabel } from './edges';
 import { fitGroup, getAbsolutePosition, withDescendants, withParent } from './grouping';
-import { getNodeDefinition, getNodeSize, isGroupType } from './node-types';
+import { getNodeDefinition, getNodeName, getNodeSize, isGroupType } from './node-types';
 
 /**
  * Everything a canvas holds, as operations on its Yjs document. The same functions run in the
@@ -35,6 +36,24 @@ export type CanvasMeta = {
   createdBy?: string;
   /** When the canvas was last laid out, so everyone's canvas glides the nodes into place */
   layoutAt?: number;
+  /** L1 and L2 as the diagram the canvas was opened from showed them (see DiagramLevels) */
+  diagramLevels?: DiagramLevels;
+};
+
+/** A level of detail as a diagram showed it: its nodes (laid out) and edges, by canvas node ids where they're the same */
+export type DiagramLevel = { nodes: Node[]; edges: Edge[] };
+
+/**
+ * L1 and L2 of the diagram a canvas was opened from (the visualiser's "Open in Studio"), shown as they were while the
+ * canvas's structure is what was opened (`structure`, from getStructureKey): moving nodes keeps them, changing what's
+ * on the canvas or how it's connected doesn't (the levels are then worked out from the canvas)
+ */
+export type DiagramLevels = {
+  structure: string;
+  1?: DiagramLevel;
+  2?: DiagramLevel;
+  /** Levels the diagram doesn't have, and why (as the diagram says) */
+  unavailable?: { 1?: string; 2?: string };
 };
 
 // Canvases' documents on the collaboration server are named `design:<canvasId>` (scripts and peers join by it)
@@ -52,8 +71,43 @@ export const getCanvasMaps = (doc: Y.Doc) => ({
   edges: doc.getMap<Edge>('edges'),
   threads: doc.getMap<Y.Map<unknown>>('threads'),
   meta: doc.getMap<unknown>('meta'),
+  /** Where things are on L1 and L2 (see LevelPlace), one entry per node and level (`1:<node id>`) */
+  levelLayouts: doc.getMap<LevelPlace>('levelLayouts'),
 });
 
+/**
+ * Where a node is on L1 or L2, as people arranged it there (or as the diagram it was opened from had it): its
+ * top-left corner, relative to the container it's shown in on that level, and a container's size
+ */
+export type LevelPlace = { x: number; y: number; width?: number; height?: number };
+
+/** The places on a level, by node id */
+export const readLevelLayout = (doc: Y.Doc, level: 1 | 2) => {
+  const prefix = `${level}:`;
+  const places = new Map<string, LevelPlace>();
+  getCanvasMaps(doc).levelLayouts.forEach((place, key) => {
+    if (key.startsWith(prefix)) places.set(key.slice(prefix.length), place);
+  });
+  return places;
+};
+
+const samePlace = (a: LevelPlace | undefined, b: LevelPlace) =>
+  !!a && a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+
+/**
+ * Puts nodes where they go on a level (in one transaction). Places that haven't changed aren't written: everyone
+ * looking at the level works out the same places for what's new on it, and each write re-arranges the level for
+ * everyone else.
+ */
+export const setLevelPlaces = (doc: Y.Doc, level: 1 | 2, places: ReadonlyMap<string, LevelPlace>) =>
+  doc.transact(() => {
+    const { levelLayouts } = getCanvasMaps(doc);
+    places.forEach((place, id) => {
+      const key = `${level}:${id}`;
+      if (!samePlace(levelLayouts.get(key), place)) levelLayouts.set(key, place);
+    });
+  });
+
 // Only the design is shared. Selection, measured sizes and drag state stay with each user.
 export const toSharedNode = ({ id, type, position, data, width, height, parentId, zIndex }: Node): Node => ({
   id,
@@ -84,9 +138,6 @@ export const buildNode = (type: string, data: Record<string, unknown>, center: X
 
 // ---- Meta ----
 
-/** Canvas titles are at most this long */
-export const MAX_TITLE_LENGTH = 200;
-
 export const readMeta = (doc: Y.Doc) => getCanvasMaps(doc).meta.toJSON() as CanvasMeta;
 
 export const setMeta = (doc: Y.Doc, meta: Partial<CanvasMeta>) =>
@@ -154,13 +205,23 @@ export const addNodes = (doc: Y.Doc, nodes: Node[], edges: Edge[] = []) =>
     edges.forEach((edge) => maps.edges.set(edge.id, edge));
   });
 
-export const moveNode = (doc: Y.Doc, id: string, position: XYPosition) => {
+/**
+ * Moves a node, and resizes it if a size is given, in one write. Nodes are only written when they change: every
+ * write is sent to everyone, re-renders the node for them, and is kept in the document (and the undo stack), even
+ * when it writes what was already there.
+ */
+export const placeNode = (doc: Y.Doc, id: string, position: XYPosition, size?: { width: number; height: number }) => {
   const { nodes } = getCanvasMaps(doc);
   const node = nodes.get(id);
-  if (node) nodes.set(id, { ...node, position });
-  return !!node;
+  if (!node) return false;
+  const moved = node.position.x !== position.x || node.position.y !== position.y;
+  const resized = !!size && (node.width !== size.width || node.height !== size.height);
+  if (moved || resized) nodes.set(id, { ...node, position, ...(size && { width: size.width, height: size.height }) });
+  return true;
 };
 
+export const moveNode = (doc: Y.Doc, id: string, position: XYPosition) => placeNode(doc, id, position);
+
 /** Resize a node: both sides, or just its width or height (e.g. text, whose height follows what's in it) */
 export const resizeNode = (
   doc: Y.Doc,
@@ -170,7 +231,9 @@ export const resizeNode = (
 ) => {
   const { nodes } = getCanvasMaps(doc);
   const node = nodes.get(id);
-  if (node)
+  const width = attributes !== 'height' && node?.width !== size.width;
+  const height = attributes !== 'width' && node?.height !== size.height;
+  if (node && (width || height))
     nodes.set(id, {
       ...node,
       ...(attributes !== 'height' && { width: size.width }),
@@ -235,6 +298,93 @@ export const updateNodeData = (doc: Y.Doc, id: string, updater: (data: Record<st
   return !!node;
 };
 
+/**
+ * How a connection is drawn, as the visualiser's layout routes it (in data.route, which the visualiser's edges
+ * are drawn along): the points it goes through, where its label goes, and where its nodes were (top-left) when
+ * it was routed, for it to follow them when they move
+ */
+export type { EdgeRoute };
+
+/** An edge's route, if it has one */
+export const getEdgeRoute = (edge: Pick<Edge, 'data'>) => (edge.data as { route?: EdgeRoute } | undefined)?.route;
+
+/** Routes connections (by edge id), in one transaction. Connections not in it lose any route they had. */
+export const setEdgeRoutes = (doc: Y.Doc, routes: ReadonlyMap<string, EdgeRoute>) =>
+  doc.transact(() => {
+    const { edges } = getCanvasMaps(doc);
+    edges.forEach((edge, id) => {
+      const route = routes.get(id);
+      if (route) edges.set(id, { ...edge, data: { ...edge.data, route } });
+      else if (getEdgeRoute(edge)) {
+        const { route: _, ...data } = edge.data!;
+        edges.set(id, { ...edge, data });
+      }
+    });
+  });
+
+/**
+ * What's on a canvas and how it's connected, not where: its nodes (not notes), what they're in and called, and its
+ * connections. The same for the same canvas wherever it's worked out (the server, any browser).
+ */
+export const getStructureKey = (nodes: Node[], edges: Edge[]) => {
+  const parts = [
+    ...nodes
+      .filter((node) => node.type !== 'note')
+      .map((node) => `${node.id}:${node.type}:${node.parentId ?? ''}:${getNodeName(node.type, node.data)}`)
+      .sort(),
+    '#',
+    ...edges.map((edge) => `${edge.source}>${edge.target}:${String(edge.label ?? '')}`).sort(),
+  ];
+  // FNV-1a, so it's short enough to keep in the canvas
+  let hash = 0x811c9dc5;
+  for (const char of parts.join('|')) hash = Math.imul(hash ^ char.charCodeAt(0), 0x01000193);
+  return `${parts.length}-${(hash >>> 0).toString(36)}`;
+};
+
+/** The diagram's L1 or L2 while the canvas still has the structure it was opened with (`structure`, its key now) */
+export const getDiagramLevel = (levels: DiagramLevels | undefined, level: 1 | 2, structure: string) =>
+  levels?.[level] && !levels.unavailable?.[level] && levels.structure === structure ? levels[level] : undefined;
+
+/** Why the diagram doesn't have a level, while the canvas still has the structure it was opened with */
+export const getDiagramLevelUnavailable = (levels: DiagramLevels | undefined, level: 1 | 2, structure: string) =>
+  levels?.unavailable?.[level] && levels.structure === structure ? levels.unavailable[level] : undefined;
+
+/** What a new canvas starts with: its nodes, the connections between them (by node id) with their routes, and the
+ * levels of the diagram it's opened from */
+export type CanvasContent = {
+  nodes: Node[];
+  connections: { from: string; to: string; label?: string; route?: Pick<EdgeRoute, 'points' | 'label'> }[];
+  levels?: Pick<DiagramLevels, 1 | 2 | 'unavailable'>;
+};
+
+/**
+ * Puts a new canvas's content on it (in one transaction), with its containers fitted to what's in them. Routes
+ * are from where the nodes are put.
+ */
+export const addCanvasContent = (doc: Y.Doc, { nodes, connections, levels }: CanvasContent) =>
+  doc.transact(() => {
+    addNodes(doc, nodes);
+    nodes.forEach((node) => node.parentId && fitContainersAround(doc, node.id));
+    const placed = new Map(getCanvasMaps(doc).nodes.entries());
+    const routes = new Map<string, EdgeRoute>();
+    connections.forEach(({ from, to, label, route }) => {
+      const edge = connectNodes(doc, { source: from, target: to }, label);
+      const [source, target] = [placed.get(from), placed.get(to)];
+      if (!route || 'error' in edge || !source || !target) return;
+      routes.set(edge.id, {
+        ...route,
+        source: getAbsolutePosition(source, placed),
+        target: getAbsolutePosition(target, placed),
+      });
+    });
+    if (routes.size) setEdgeRoutes(doc, routes);
+    if (levels) {
+      const maps = getCanvasMaps(doc);
+      const structure = getStructureKey(Array.from(maps.nodes.values()), Array.from(maps.edges.values()));
+      setMeta(doc, { diagramLevels: { structure, ...levels } });
+    }
+  });
+
 /** Connect two nodes with an EventCatalog-labelled edge. Returns the edge, or why it couldn't be made. */
 export const connectNodes = (
   doc: Y.Doc,
@@ -299,7 +449,7 @@ export const deleteEdges = (doc: Y.Doc, ids: string[]) =>
 /** Delete nodes (containers with what's in them), the edges to them, and leave their comments where they were */
 export const deleteNodes = (doc: Y.Doc, ids: string[]) =>
   doc.transact(() => {
-    const { nodes, edges, threads } = getCanvasMaps(doc);
+    const { nodes, edges, threads, levelLayouts } = getCanvasMaps(doc);
     const all = Array.from(nodes.values());
     const lookup = new Map(all.map((node) => [node.id, node]));
     const removed = withDescendants(ids, all);
@@ -313,7 +463,12 @@ export const deleteNodes = (doc: Y.Doc, ids: string[]) =>
       thread.delete('nodeId');
       thread.delete('offset');
     });
-    removed.forEach((id) => nodes.delete(id));
+    removed.forEach((id) => {
+      nodes.delete(id);
+      // Where it was on L1 and L2 (undoing the delete puts it back there)
+      levelLayouts.delete(`1:${id}`);
+      levelLayouts.delete(`2:${id}`);
+    });
     edges.forEach((edge, id) => {
       if (removed.has(edge.source) || removed.has(edge.target)) edges.delete(id);
     });