@eventcatalog/core 5.0.0-beta.8 → 5.0.0

package/eventcatalog/src/features/mcp/mcp-server.ts

@@ -41,6 +41,8 @@ type McpServerOptions = {
   catalogUrl: string;
   /** The MCP client's user agent, to name agents that join a canvas */
   userAgent?: string;
+  /** Offer the canvas tools (by default when Studio is on, for the whole catalog) */
+  canvases?: boolean;
 };
 
 const catalogDirectory = process.env.PROJECT_DIR || process.cwd();
@@ -120,7 +122,10 @@ function getServerInstructions(scope?: McpScope) {
 }
 
 // Create MCP Server with tools that access Astro collections
-function createMcpServer(scope: McpScope | undefined, { catalogUrl, userAgent }: McpServerOptions) {
+function createMcpServer(
+  scope: McpScope | undefined,
+  { catalogUrl, userAgent, canvases = !scope && isCanvasEnabled() }: McpServerOptions
+) {
   const server = new McpServer(
     {
       name: scope ? `EventCatalog MCP Server — ${scope.name} ${scope.ref.kind}` : 'EventCatalog MCP Server',
@@ -837,7 +842,7 @@ function createMcpServer(scope: McpScope | undefined, { catalogUrl, userAgent }:
   }
 
   // Collaborative canvases (when the collaboration server runs in this process)
-  if (!scope && isCanvasEnabled()) registerCanvasTools(server, { catalogUrl, userAgent });
+  if (canvases) registerCanvasTools(server, { catalogUrl, userAgent });
 
   return server;
 }
@@ -993,11 +998,22 @@ const handleMcpRequest = async (c: Context, kind?: McpScopeKind) => {
     }
 
     const scope = await resolveRequestScope(c, kind);
-    // Canvas tools work on Studio's canvases: started (storage loaded) before they're listed
-    if (!scope && isCanvasEnabled()) await startStudio();
+    // Canvas tools work on Studio's canvases: started (storage loaded) before they're listed, and left out when
+    // Studio isn't available (the rest of the catalog's tools still work)
+    const canvases =
+      !scope &&
+      isCanvasEnabled() &&
+      (await startStudio().then(
+        () => true,
+        (error) => {
+          console.error(`[studio] Canvas tools are off: ${(error as Error).message}`);
+          return false;
+        }
+      ));
     const server = createMcpServer(scope, {
       catalogUrl: new URL(c.req.url).origin,
       userAgent: c.req.header('user-agent'),
+      canvases,
     });
     const transport = new WebStandardStreamableHTTPServerTransport({
       sessionIdGenerator: undefined,

package/eventcatalog/src/features/server/start.ts

@@ -0,0 +1,25 @@
+import type { APIRoute } from 'astro';
+import { isCanvasEnabled } from '@utils/feature';
+import { startStorage } from '../storage/database';
+import { startStudio } from '../studio/server/runtime';
+import { isSignedIn } from '../studio/server/sign-in';
+
+/**
+ * What the server starts before anyone asks for it: `eventcatalog start` calls this once the server listens. Each
+ * feature that needs starting has its own start function, called here in order: the storage configured is opened and
+ * migrated first (features keep their state in it), then Studio (so tabs reconnecting after a restart find it
+ * ready). Under /_eventcatalog, which sign-in lets through (the server calls it without a session); it says nothing
+ * about what's stored.
+ */
+export const GET: APIRoute = async () => {
+  try {
+    await startStorage();
+  } catch (error) {
+    console.error(`[eventcatalog] Could not open the database: ${(error as Error).message}`);
+  }
+  // Studio says why if it can't start
+  if (isCanvasEnabled()) await startStudio({ isSignedIn }).catch(() => {});
+  return new Response(null, { status: 204 });
+};
+
+export const prerender = false;

package/eventcatalog/src/features/storage/database.ts

@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import config from '../../utils/eventcatalog-config/source';
+import type { Config } from '../../../../src/eventcatalog.config';
+import { migrate, type Database } from './migrations';
+import { namedStatements } from './sql';
+import databaseSql from './sql/database.sql?raw';
+
+/** `storage` in eventcatalog.config.js: memory (the default), or one SQLite database for the whole catalog */
+export type StorageConfig = NonNullable<Config['storage']>;
+export type StorageType = StorageConfig['type'];
+export type { Database };
+
+export const DEFAULT_STORAGE: StorageConfig = { type: 'memory' };
+const DEFAULT_DATABASE_PATH = '.eventcatalog/eventcatalog.db';
+
+const SQL = namedStatements(databaseSql, ['useWriteAheadLog']);
+
+/** The database file a config asks for (relative to the catalog), or undefined when state is kept in memory */
+export const getDatabasePath = (storage: StorageConfig | undefined, projectDirectory: string) => {
+  const chosen = storage ?? DEFAULT_STORAGE;
+  switch (chosen.type) {
+    case 'memory':
+      return undefined;
+    case 'sqlite':
+      return path.resolve(projectDirectory, chosen.path ?? DEFAULT_DATABASE_PATH);
+    default:
+      throw new Error(`Unknown storage type "${(chosen as { type?: string }).type}": use "memory" or "sqlite"`);
+  }
+};
+
+const open = async (file: string): Promise<Database> => {
+  // Node's built-in SQLite (no native package to install), asked of Node itself: the dev server loads this through
+  // Vite, which doesn't know node:sqlite and fails to import it
+  type Sqlite = { DatabaseSync: new (file: string) => Database };
+  const getBuiltinModule = (process as { getBuiltinModule?: (id: string) => unknown }).getBuiltinModule;
+  let sqlite: Sqlite | undefined;
+  try {
+    sqlite = getBuiltinModule
+      ? (getBuiltinModule('node:sqlite') as Sqlite | undefined)
+      : await import(/* @vite-ignore */ ['node', 'sqlite'].join(':'));
+  } catch (error) {
+    throw new Error(`Could not load node:sqlite (${(error as Error).message})`);
+  }
+  if (!sqlite?.DatabaseSync) {
+    throw new Error(
+      `SQLite storage needs Node.js 22.13 or later (it uses node:sqlite); this is Node.js ${process.versions.node}`
+    );
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const database = new sqlite.DatabaseSync(file);
+  database.exec(SQL.useWriteAheadLog);
+  migrate(database);
+  return database;
+};
+
+// Opened once per process, by file (kept on globalThis: the dev server's integrations and the app load this module
+// separately, and code reloads in dev keep globalThis)
+const DATABASES = Symbol.for('eventcatalog.databases');
+const store = globalThis as typeof globalThis & { [DATABASES]?: Map<string, Promise<Database>> };
+
+/**
+ * The database in `file`, brought up to date by the migrations: opened the first time it's asked for, then shared by
+ * every feature. Rejects (every time) if it can't be opened or migrated, e.g. when a newer EventCatalog updated it.
+ */
+export const openDatabase = (file: string): Promise<Database> => {
+  const databases = (store[DATABASES] ??= new Map());
+  let database = databases.get(file);
+  if (!database) {
+    database = open(file);
+    databases.set(file, database);
+  }
+  return database;
+};
+
+/**
+ * Opens the storage configured, running the migrations it needs. Called as the dev server and `eventcatalog start`
+ * start (not on build: builds often run somewhere other than where the database lives), so it's ready before any
+ * feature uses it. Returns the database file, or undefined when state is kept in memory.
+ */
+export const startStorage = async (projectDirectory = process.env.PROJECT_DIR || process.cwd()) => {
+  if ((config as { studio?: { storage?: unknown } }).studio?.storage) {
+    console.warn('[eventcatalog] studio.storage is no longer used: set storage in eventcatalog.config.js instead');
+  }
+  const file = getDatabasePath(config.storage, projectDirectory);
+  if (file) await openDatabase(file);
+  return file;
+};

package/eventcatalog/src/features/storage/migrations.ts

@@ -0,0 +1,85 @@
+import { namedStatements } from './sql';
+import runnerSql from './sql/migrations.sql?raw';
+
+/**
+ * Changes to the database's schema, for every feature that keeps state, as .sql files in ./sql/migrations named
+ * `NNNN-what-it-does.sql` (one numbered order for the whole catalog; tables are named for their feature, e.g.
+ * `studio_canvases`). They run in order when the database opens, each once, recorded in its `migrations` table. To
+ * change the schema, add a file with the next number: never change one that has shipped, since databases out there have
+ * already run it.
+ */
+export type Migration = { version: number; name: string; sql: string };
+
+/** The parts of node:sqlite's DatabaseSync EventCatalog uses */
+export type Database = {
+  exec: (sql: string) => void;
+  prepare: (sql: string) => { run: (...values: unknown[]) => unknown; all: () => unknown[] };
+};
+
+// Built into the server code (no files to find at runtime, wherever it's deployed)
+const files = import.meta.glob<string>('./sql/migrations/*.sql', { query: '?raw', import: 'default', eager: true });
+const SQL = namedStatements(runnerSql, ['createMigrationsTable', 'appliedVersions', 'recordMigration']);
+
+/** Migrations from their files, in order (an error if a file is misnamed or two have the same number) */
+export const toMigrations = (sources: Record<string, string>): Migration[] => {
+  const migrations = Object.entries(sources).map(([file, sql]) => {
+    const name = file
+      .split('/')
+      .pop()!
+      .replace(/\.sql$/, '');
+    const version = Number(/^(\d{4})-[a-z0-9-]+$/.exec(name)?.[1]);
+    if (!version) throw new Error(`Migration "${file}" should be named like 0003-what-it-does.sql`);
+    return { version, name, sql };
+  });
+  migrations.sort((a, b) => a.version - b.version);
+  migrations.forEach((migration, index) => {
+    if (migration.version !== index + 1) {
+      throw new Error(`Migrations should be numbered 1, 2, 3...: expected ${index + 1} before ${migration.name}`);
+    }
+  });
+  return migrations;
+};
+
+export const MIGRATIONS = toMigrations(files);
+
+/**
+ * The database was updated by a newer EventCatalog. Features don't fall back to memory for this (changes would quietly
+ * stop being saved): they aren't available until EventCatalog is updated. Told by its code, as the dev server's
+ * integrations and the app load this module separately.
+ */
+const DATABASE_TOO_NEW = 'EVENTCATALOG_DATABASE_TOO_NEW';
+export const isDatabaseTooNew = (error: unknown) => (error as { code?: unknown } | null)?.code === DATABASE_TOO_NEW;
+
+/**
+ * Brings a database up to date: runs the migrations it hasn't run yet, each in a transaction (all of it or none).
+ * Refuses a database that has run migrations this version doesn't know (made by a newer EventCatalog).
+ */
+export const migrate = (database: Database, migrations: Migration[] = MIGRATIONS) => {
+  database.exec(SQL.createMigrationsTable);
+  const applied = new Set(
+    (database.prepare(SQL.appliedVersions).all() as { version: number }[]).map((row) => Number(row.version))
+  );
+  const latest = migrations.at(-1)?.version ?? 0;
+  const newer = [...applied].filter((version) => version > latest);
+  if (newer.length) {
+    throw Object.assign(
+      new Error(
+        `The EventCatalog database has been updated by a newer EventCatalog (migration ${Math.max(...newer)}; this version knows up to ${latest}). Update EventCatalog to use it.`
+      ),
+      { code: DATABASE_TOO_NEW }
+    );
+  }
+  const record = database.prepare(SQL.recordMigration);
+  for (const migration of migrations) {
+    if (applied.has(migration.version)) continue;
+    database.exec('BEGIN');
+    try {
+      database.exec(migration.sql);
+      record.run(migration.version, migration.name, Date.now());
+      database.exec('COMMIT');
+    } catch (error) {
+      database.exec('ROLLBACK');
+      throw new Error(`Could not run migration ${migration.name}: ${(error as Error).message}`);
+    }
+  }
+};

package/eventcatalog/src/features/storage/sql/database.sql

@@ -0,0 +1,5 @@
+-- Statements run as the database opens (see database.ts), each named by the `-- name:` line above it.
+
+-- name: useWriteAheadLog
+-- Readers don't wait for writers (set as the database opens: it can't be changed inside a migration's transaction)
+PRAGMA journal_mode = WAL;

package/eventcatalog/src/features/storage/sql/migrations/0001-studio-canvases.sql

@@ -0,0 +1,12 @@
+-- Studio's canvases: each one's whole Yjs document (Y.encodeStateAsUpdate), and when it last changed.
+CREATE TABLE studio_canvases (
+  name TEXT PRIMARY KEY,
+  state BLOB NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+-- Studio canvases that were deleted, so a browser that still has one open can't bring it back.
+CREATE TABLE studio_deleted_canvases (
+  name TEXT PRIMARY KEY,
+  deleted_at INTEGER NOT NULL
+);

package/eventcatalog/src/features/storage/sql/migrations.sql

@@ -0,0 +1,15 @@
+-- The statements the migration runner runs (see migrations.ts), each named by the `-- name:` line above it. Its own
+-- table is made here rather than in a migration: it records which migrations have run, so it's needed before any do.
+
+-- name: createMigrationsTable
+CREATE TABLE IF NOT EXISTS migrations (
+  version INTEGER PRIMARY KEY,
+  name TEXT NOT NULL,
+  applied_at INTEGER NOT NULL
+);
+
+-- name: appliedVersions
+SELECT version FROM migrations;
+
+-- name: recordMigration
+INSERT INTO migrations (version, name, applied_at) VALUES (?, ?, ?);

package/eventcatalog/src/features/storage/sql.ts

@@ -0,0 +1,28 @@
+/**
+ * Statements kept in .sql files (./sql), each named by a `-- name: <name>` line above it. A file's statements are
+ * looked up by the names the code expects: a missing one is an error when the module loads, not when it's first run.
+ */
+export const namedStatements = <Name extends string>(source: string, names: readonly Name[]): Record<Name, string> => {
+  const statements = new Map<string, string>();
+  let current: { name: string; lines: string[] } | undefined;
+  const finish = () => {
+    if (current) statements.set(current.name, current.lines.join('\n').trim());
+  };
+  for (const line of source.split('\n')) {
+    const name = /^--\s*name:\s*(\S+)\s*$/.exec(line)?.[1];
+    if (name) {
+      finish();
+      current = { name, lines: [] };
+    } else {
+      current?.lines.push(line);
+    }
+  }
+  finish();
+  return Object.fromEntries(
+    names.map((name) => {
+      const statement = statements.get(name);
+      if (!statement) throw new Error(`No SQL statement named "${name}"`);
+      return [name, statement];
+    })
+  ) as Record<Name, string>;
+};

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

@@ -9,11 +9,16 @@ import {
   fitContainersAround,
   getCanvasMaps,
   moveNode,
-  resizeNode,
+  placeNode,
+  setEdgeRoutes,
   setMeta,
   type Author,
   type CommentAnchor,
-} from './canvas-doc';
+  getAbsolutePosition,
+  sizeOf,
+  type LayoutResult,
+  getNodeName,
+} from '@eventcatalog/visualiser/studio';
 import {
   describeNode,
   nodeCenter,
@@ -27,9 +32,6 @@ import {
   type NodeUpdate,
 } from './canvas-actions';
 import { getRelatedEdges } from './catalog';
-import { getAbsolutePosition, sizeOf } from './grouping';
-import type { LayoutResult } from './layout';
-import { getNodeName } from './node-types';
 
 /**
  * Agents work on a canvas like a person would: their cursor travels to where they're going, they drop one node,
@@ -292,13 +294,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/agents.ts

@@ -0,0 +1,28 @@
+/**
+ * Who an agent is, named after its client when it doesn't say, in its brand's colour: on the server (MCP tools) and
+ * in a chat's canvas view (which joins as the chat's agent). Their logos are in the visualiser's ClientLogos.
+ */
+export type AgentIdentity = { name: string; color: string };
+
+const AGENT_COLORS: Record<string, string> = {
+  ChatGPT: '#10a37f',
+  Codex: '#10a37f',
+  Claude: '#d97757',
+  'Claude Code': '#d97757',
+  Cursor: '#111827',
+};
+
+/** Agents' clients, by what's in their user agent or host name (most specific first) */
+const CLIENTS: [RegExp, string][] = [
+  [/claude[-_ ]?code/i, 'Claude Code'],
+  [/claude|anthropic/i, 'Claude'],
+  [/codex/i, 'Codex'],
+  [/openai|chatgpt/i, 'ChatGPT'],
+  [/cursor/i, 'Cursor'],
+];
+
+/** Who the agent is, from the name it gives, else its client's user agent (or a chat's host name) */
+export const getAgent = (agentName: string | undefined, client = ''): AgentIdentity => {
+  const name = agentName?.trim() || CLIENTS.find(([pattern]) => pattern.test(client))?.[1] || 'AI agent';
+  return { name, color: AGENT_COLORS[name] ?? '#8b5cf6' };
+};

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

@@ -0,0 +1,219 @@
+import { Hono, type Context } from 'hono';
+import { z } from 'zod';
+import { paginate } from '@features/tools/catalog-tools';
+import { type CanvasContent, type CanvasStatus } from '@eventcatalog/visualiser/studio';
+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';
+
+/**
+ * The Studio API: canvases as a whole (listing, creating, reading and deleting them). What's on a canvas is changed
+ * over the collaboration connection, or by agents through the MCP tools, never here: they're live documents that
+ * people and agents edit together.
+ *
+ *   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, "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 }
+ *   DELETE /api/studio/canvases/:id    Deletes it for everyone (anyone who has it open is told), for good
+ *
+ * Errors are `{ "error": "..." }` with the HTTP status. With sign-in on, only signed-in people can use it (401
+ * otherwise), and canvases are created by whoever is signed in. Requests that change something (POST, DELETE) from
+ * outside a browser send `Content-Type: application/json`: Astro refuses ones with no content type that don't come
+ * from the catalog's own pages.
+ */
+export const CANVASES_API_PATH = '/api/studio/canvases';
+
+const CANVAS_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const MAX_PAGE_SIZE = 100;
+
+/** A canvas, as the API gives it */
+export type ApiCanvas = {
+  id: string;
+  title: string | null;
+  status: CanvasStatus;
+  /** ISO 8601 */
+  createdAt: string | null;
+  /** Who started it (a person, or an agent) */
+  createdBy: string | null;
+  /** When anyone (a person, or an agent) last changed it (ISO 8601) */
+  updatedAt: string | null;
+  nodeCount: number;
+  edgeCount: number;
+  openComments: number;
+  /** Where people open it */
+  url: string;
+};
+
+export type CanvasesApiEnv = {
+  Bindings: {
+    runtime: StudioRuntime;
+    /** Who's signed in (sign-in on) */
+    signedInAs?: SignedInUser;
+    /** A canvas's page */
+    canvasUrl: (canvasId: string) => string;
+  };
+};
+
+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(),
+});
+
+const iso = (time?: number) => (time ? new Date(time).toISOString() : null);
+const toApiCanvas = (canvas: CanvasSummary, canvasUrl: (canvasId: string) => string): ApiCanvas => ({
+  id: canvas.canvasId,
+  title: canvas.title ?? null,
+  status: canvas.status,
+  createdAt: iso(canvas.createdAt),
+  createdBy: canvas.createdBy ?? null,
+  updatedAt: iso(canvas.updatedAt),
+  nodeCount: canvas.nodeCount,
+  edgeCount: canvas.edgeCount,
+  openComments: canvas.openComments,
+  url: canvasUrl(canvas.canvasId),
+});
+const describeIssues = (error: z.ZodError) =>
+  error.issues.map((issue) => (issue.path.length ? `${issue.path.join('.')}: ${issue.message}` : issue.message)).join('; ');
+
+type ApiContext = Context<CanvasesApiEnv>;
+const noCanvas = (c: ApiContext, id: string) => c.json({ error: `No canvas "${id}"` }, 404);
+
+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);
+  }
+  try {
+    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 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) */
+export const createCanvasesApi = (basePath: string) => {
+  const app = new Hono<CanvasesApiEnv>({ strict: false }).basePath(basePath);
+
+  app.get('/', (c) => {
+    const query = ListQuery.safeParse(c.req.query());
+    if (!query.success) return c.json({ error: describeIssues(query.error) }, 400);
+    const { runtime, canvasUrl } = c.env;
+    const page = paginate(runtime.listCanvases(), query.data.cursor, query.data.pageSize);
+    if ('error' in page) return c.json({ error: page.error }, 400);
+    return c.json({
+      canvases: page.items.map((canvas) => toApiCanvas(canvas, canvasUrl)),
+      totalCount: page.totalCount,
+      ...(page.nextCursor && { nextCursor: page.nextCursor }),
+    });
+  });
+
+  /** A canvas just made, as created */
+  const created = (c: ApiContext, canvasId: string) => {
+    c.header('Location', `${basePath}/${canvasId}`);
+    return c.json({ canvas: toApiCanvas(c.env.runtime.getCanvas(canvasId)!, c.env.canvasUrl) }, 201);
+  };
+
+  app.post('/', async (c) => {
+    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 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);
+  });
+
+  app.get('/:id', (c) => {
+    const id = c.req.param('id');
+    const canvas = CANVAS_ID.test(id) ? c.env.runtime.getCanvas(id) : undefined;
+    if (!canvas) return noCanvas(c, id);
+    return c.json({ canvas: toApiCanvas(canvas, c.env.canvasUrl) });
+  });
+
+  app.delete('/:id', (c) => {
+    const id = c.req.param('id');
+    if (!CANVAS_ID.test(id)) return noCanvas(c, id);
+    try {
+      if (!c.env.runtime.deleteCanvas(id)) return noCanvas(c, id);
+    } catch (error) {
+      console.error(`[studio] Could not delete canvas ${id}`, error);
+      return c.json({ error: `Could not delete the canvas: ${(error as Error).message}` }, 500);
+    }
+    return c.body(null, 204);
+  });
+
+  app.notFound((c) => c.json({ error: 'Not found' }, 404));
+  return app;
+};

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

@@ -0,0 +1,25 @@
+import type { APIRoute } from 'astro';
+import { buildUrl } from '@utils/url-builder';
+import { startStudio } from '../server/runtime';
+import { getSignedInUser, isSignedIn } from '../server/sign-in';
+import { CANVASES_API_PATH, createCanvasesApi } from './canvases-api';
+
+// The Studio API (see canvases-api.ts)
+const api = createCanvasesApi(buildUrl(CANVASES_API_PATH, true));
+
+export const ALL: APIRoute = async ({ request, locals, url }) => {
+  let runtime: Awaited<ReturnType<typeof startStudio>>;
+  try {
+    runtime = await startStudio({ isSignedIn });
+  } catch (error) {
+    // Its storage can't be used (e.g. the database was updated by a newer EventCatalog)
+    return Response.json({ error: `Studio isn't available: ${(error as Error).message}` }, { status: 503 });
+  }
+  return api.fetch(request, {
+    runtime,
+    signedInAs: getSignedInUser(locals),
+    canvasUrl: (canvasId: string) => `${url.origin}${buildUrl(`/studio/${canvasId}`)}`,
+  });
+};
+
+export const prerender = false;