@eventcatalog/core 5.0.0-beta.7 → 5.0.0-beta.9

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

@@ -11,7 +11,17 @@ import {
   CANVAS_VIEW_TOOL,
   type CanvasPayload,
 } from '@features/mcp/apps/canvas/shared';
-import { getCanvasMaps, readCanvas, readMeta, replyToThread, setMeta, setThreadResolved, type Author } from '../canvas-doc';
+import {
+  CANVAS_STATUSES,
+  getCanvasMaps,
+  readCanvas,
+  readMeta,
+  reopeningIfEdited,
+  replyToThread,
+  setCanvasStatus,
+  setThreadResolved,
+  type Author,
+} from '../canvas-doc';
 import { ADD_TO_CANVAS_DESCRIPTION, describeCanvas, edgeSpecsSchema, indexCatalog, nodeSpecsSchema } from '../canvas-actions';
 import { getCatalogResources } from '../catalog-resources';
 import { getLayoutPositions } from '../layout';
@@ -76,6 +86,7 @@ export const CANVAS_TOOL_NAMES = [
   'connectCanvasNodes',
   'removeFromCanvas',
   'layoutCanvas',
+  'setCanvasStatus',
   'commentOnCanvas',
   'replyToCanvasComment',
   'resolveCanvasComment',
@@ -92,12 +103,8 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
   const missing = (id: string) =>
     text({ error: `No canvas "${id}". Use listCanvases to find one, or openCanvas to start one.` }, true);
 
-  const createCanvas = async (title: string, name?: string) => {
-    const id = crypto.randomUUID();
-    const agent = getAgent(name, userAgent);
-    await runtime.withCanvas(id, (doc) => setMeta(doc, { title, createdAt: Date.now(), createdBy: agent.name }));
-    return id;
-  };
+  const createCanvas = (title: string, name?: string) =>
+    runtime.createCanvas({ title, createdBy: getAgent(name, userAgent).name });
 
   /**
    * Work on a canvas as an agent: changes are played out like a person would make them (see agent-choreography),
@@ -105,13 +112,15 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
    */
   const asAgent = (id: string, name: string | undefined) => {
     const agent = getAgent(name, userAgent);
+    const author = { ...agent, agent: true } as Author;
     const stage: AgentStage = {
-      change: (fn) => runtime.withCanvas(id, fn),
+      // An agent changing an accepted (or rejected) canvas makes it a draft again, like a person doing it
+      change: (fn) => runtime.withCanvas(id, (doc) => reopeningIfEdited(doc, author, () => fn(doc))),
       present: (presence) => runtime.setAgentPresence(id, agent, presence),
       lastPointer: runtime.getAgentPointer(id, agent),
       sharesMoves: true,
     };
-    return { stage, author: { ...agent, agent: true } as Author };
+    return { stage, author };
   };
 
   // ---- The canvas in the chat (MCP App) ----
@@ -168,9 +177,10 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
         const canvases = runtime
           .listCanvases()
           .sort((a, b) => (b.createdAt ?? 0) - (a.createdAt ?? 0))
-          .map(({ canvasId: id, title, people, nodeCount, openComments }) => ({
+          .map(({ canvasId: id, title, status, people, nodeCount, openComments }) => ({
             canvasId: id,
             title,
+            status,
             people,
             nodeCount,
             openComments,
@@ -205,7 +215,7 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
           title,
           url: canvasUrl(id),
           people: runtime.peopleOn(id),
-          note: 'Clients that support MCP Apps are showing the user this canvas, live. Work on it with them using the canvas tools (getCanvas, addToCanvas, commentOnCanvas...): they see your changes as you make them. Otherwise, share the url so they can open it.',
+          note: 'Clients that support MCP Apps are showing the user this canvas, live. Work on it with them using the canvas tools (getCanvas, addToCanvas...): they see your changes as you make them. Talk with them in the conversation, not in canvas comments (only comment when they ask you to). Otherwise, share the url so they can open it.',
         },
         label: `the canvas ${title ?? id}`,
         getPayload: async (): Promise<CanvasPayload> => payload,
@@ -301,6 +311,30 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
     }
   );
 
+  server.registerTool(
+    'setCanvasStatus',
+    {
+      title: 'Set a canvas status',
+      description: [
+        "Changes a canvas's status: draft (being worked on, where every canvas starts), proposed (ready for review), accepted (the agreed design) or rejected (decided against).",
+        'Only change it when the user asks you to. Changing the nodes or connections on an accepted or rejected canvas makes it a draft again.',
+      ].join(' '),
+      inputSchema: z.object({
+        canvasId,
+        status: z.enum(CANVAS_STATUSES),
+        note: z.string().optional().describe('Why, e.g. "Agreed in the architecture review"'),
+        agentName,
+      }),
+      annotations: writes,
+    },
+    async ({ canvasId: id, status, note, agentName: name }) => {
+      if (!runtime.exists(id)) return missing(id);
+      const { author } = asAgent(id, name);
+      const changed = await runtime.withCanvas(id, (doc) => setCanvasStatus(doc, status, author, note));
+      return text({ canvasId: id, status, ...(!changed && { note: `The canvas was already ${status}` }) });
+    }
+  );
+
   server.registerTool(
     'addToCanvas',
     {
@@ -322,12 +356,13 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
     {
       title: 'Update a node on a canvas',
       description:
-        'Renames, re-describes or moves a node on a canvas (x/y: its new centre). Catalog resources keep their catalog name and summary; change those in the catalog. For notes, summary is the note text.',
+        'Renames, re-describes, re-versions or moves a node on a canvas (x/y: its new centre). Catalog resources keep their catalog name, summary and version; change those in the catalog. For notes, summary is the note text.',
       inputSchema: z.object({
         canvasId,
         nodeId: z.string(),
         name: z.string().optional(),
         summary: z.string().optional(),
+        version: z.string().optional().describe('e.g. 1.0.0'),
         x: z.number().optional(),
         y: z.number().optional(),
         agentName,
@@ -401,7 +436,7 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
     {
       title: 'Comment on a canvas',
       description:
-        'Starts a comment thread on a canvas, pinned to a node (nodeId) or a spot (x, y). Use it to ask questions, flag concerns or explain your suggestions where people can see them.',
+        "Starts a comment thread on a canvas, pinned to a node (nodeId) or a spot (x, y). Only use it when the user asks you to comment (e.g. to review the canvas or leave notes for others on it). Don't use comments to greet people, introduce yourself or ask the user questions: talk to them in the conversation.",
       inputSchema: z.object({
         canvasId,
         text: z.string(),

package/eventcatalog/src/features/studio/server/runtime.ts

@@ -4,8 +4,20 @@ import * as Y from 'yjs';
 import { Awareness, applyAwarenessUpdate, encodeAwarenessUpdate, removeAwarenessStates } from 'y-protocols/awareness';
 import type { XYPosition } from '@xyflow/react';
 import type { AgentPresence } from '../agent-choreography';
-import { canvasDocumentName, canvasIdFromDocumentName, getCanvasMaps, readMeta } from '../canvas-doc';
+import {
+  canvasDocumentName,
+  canvasIdFromDocumentName,
+  getCanvasMaps,
+  readMeta,
+  setMeta,
+  getCanvasStatus,
+  type CanvasStatus,
+} from '../canvas-doc';
+import { getCanvasPreview, type CanvasPreview } from '../canvas-preview';
 import { fromBase64, toBase64, type SyncRequest, type SyncResponse } from '../tool-sync';
+import config from '../../../utils/eventcatalog-config/source';
+import { isAuthEnabled } from '../../../utils/feature';
+import { createStorage, memoryStorage, type CanvasStorage, type StudioStorageConfig } from './storage';
 
 export const STUDIO_SOCKET_PATH = '/_eventcatalog/studio';
 const SOCKET_PATH_PATTERN = /\/_eventcatalog\/studio\/?$/;
@@ -17,47 +29,92 @@ export type AgentIdentity = { name: string; color: string };
 export type CanvasSummary = {
   canvasId: string;
   title?: string;
+  status: CanvasStatus;
   createdAt?: number;
+  /** Who started it (a person, or an agent) */
+  createdBy?: string;
+  /** When anyone (a person, or an agent) last changed it */
+  updatedAt?: number;
   nodeCount: number;
   edgeCount: number;
   openComments: number;
   people: string[];
+  /** The canvas drawn small (asked for with `withPreview`, e.g. for the canvases page) */
+  preview?: CanvasPreview | null;
 };
 
 /**
- * What the collaboration server keeps for the life of the process: one Hocuspocus instance, and the canvases
- * in memory (a snapshot each time one is stored), so they last until the process restarts.
+ * What the collaboration server keeps for the life of the process: one Hocuspocus instance, and every canvas's
+ * latest snapshot in memory (read from storage when the server starts, and written through to it each time a
+ * canvas is stored), so listing canvases and opening one never wait on storage.
  */
 type RuntimeState = {
   server: Server;
   snapshots: Map<string, Uint8Array>;
+  /** When each canvas last changed (kept with it in storage) */
+  updatedAt: Map<string, number>;
   agents: Map<string, { awareness: Awareness; expires: ReturnType<typeof setTimeout> }>;
   attached: WeakSet<HttpServer>;
+  storage: CanvasStorage;
+  /** The storage config in use (to tell when it changes) */
+  storageKey?: string;
+  /** Settles once the stored canvases are in `snapshots` */
+  ready: Promise<void>;
+  /** Studio started (by startStudio): its storage loaded */
+  started?: Promise<void>;
+  savesOnExit: boolean;
+  /**
+   * Whether a collaboration connection comes from someone signed in, when sign-in is on. Given by the pages
+   * (see startStudio): Auth.js's config only loads in the app, not in the dev server's integration.
+   */
+  isSignedIn?: (request: Request) => Promise<boolean>;
 };
 
 const createState = (): RuntimeState => {
-  const snapshots = new Map<string, Uint8Array>();
-  return {
-    snapshots,
+  const state: RuntimeState = {
+    snapshots: new Map(),
+    updatedAt: new Map(),
     agents: new Map(),
     attached: new WeakSet(),
+    storage: memoryStorage(),
+    ready: Promise.resolve(),
+    savesOnExit: false,
     server: new Server({
       quiet: true,
+      // With sign-in on, only signed-in people can open a canvas (refused until the pages have said how to check)
+      onConnect: async ({ request }) => {
+        if (!isAuthEnabled()) return;
+        if (!(await state.isSignedIn?.(request).catch(() => false))) throw new Error('Sign in to open this canvas');
+      },
       onLoadDocument: async ({ documentName, document }) => {
-        const snapshot = snapshots.get(documentName);
-        if (!snapshot) return;
         // A hook that throws leaves the document half loaded in Hocuspocus (ueberdosis/hocuspocus#1156)
         try {
-          Y.applyUpdate(document, snapshot);
+          await state.ready;
+          const snapshot = state.snapshots.get(documentName);
+          if (snapshot) Y.applyUpdate(document, snapshot);
         } catch (error) {
           console.error(`[studio] Could not load canvas ${documentName}, starting it empty`, error);
         }
       },
-      onStoreDocument: async ({ documentName, document }) => {
-        snapshots.set(documentName, Y.encodeStateAsUpdate(document));
+      // Changes only: Hocuspocus starts listening once a canvas has loaded
+      onChange: async ({ documentName }) => {
+        state.updatedAt.set(documentName, Date.now());
       },
+      onStoreDocument: async ({ documentName, document }) => saveSnapshot(state, documentName, document),
     }),
   };
+  return state;
+};
+
+/** Keeps a canvas's snapshot, and writes it to storage (failing to store it doesn't lose it from memory) */
+const saveSnapshot = (state: RuntimeState, documentName: string, document: Y.Doc) => {
+  const snapshot = Y.encodeStateAsUpdate(document);
+  state.snapshots.set(documentName, snapshot);
+  try {
+    state.storage.save(documentName, snapshot, state.updatedAt.get(documentName));
+  } catch (error) {
+    console.error(`[studio] Could not store canvas ${documentName} (${state.storage.type} storage)`, error);
+  }
 };
 
 /**
@@ -80,6 +137,89 @@ class StudioRuntime {
     return this.state.attached;
   }
 
+  /** Where canvases are kept (memory: until the server restarts) */
+  get storage(): Pick<CanvasStorage, 'type' | 'location'> {
+    const { type, location } = this.state.storage;
+    return { type, location };
+  }
+
+  /**
+   * Keeps canvases in the storage configured (`studio.storage`, memory by default), and loads the ones
+   * stored there. Set once when the server starts; calling it again with the same config does nothing.
+   */
+  async useStorage(config: StudioStorageConfig | undefined, projectDirectory: string) {
+    const key = JSON.stringify({ config: config ?? null, projectDirectory });
+    if (this.state.storageKey === key) return this.state.ready;
+    const storage = createStorage(config, projectDirectory);
+    this.state.storageKey = key;
+    this.state.storage = storage;
+    this.state.ready = storage.loadAll().then((stored) => {
+      // Canvases already open here (e.g. the dev server reloading) are kept as they are
+      stored.forEach(({ state, updatedAt }, name) => {
+        if (this.snapshots.has(name)) return;
+        this.snapshots.set(name, state);
+        if (updatedAt) this.state.updatedAt.set(name, updatedAt);
+      });
+    });
+    this.saveOnExit();
+    return this.state.ready;
+  }
+
+  /**
+   * Starts Studio once: canvases kept in the storage configured (in memory if it can't be used), and in production the
+   * collaboration connection on the server `eventcatalog start` runs (the dev server's integration attaches it there).
+   */
+  start() {
+    this.state.started ??= (async () => {
+      const projectDirectory = process.env.PROJECT_DIR || process.cwd();
+      try {
+        await this.useStorage(config.studio?.storage, projectDirectory);
+      } catch (error) {
+        console.error(
+          `[studio] Could not use the Studio storage configured, keeping canvases in memory: ${(error as Error).message}`
+        );
+        await this.useStorage({ type: 'memory' }, projectDirectory);
+      }
+      const httpServer = (globalThis as Record<symbol, unknown>)[HTTP_SERVER_KEY] as HttpServer | undefined;
+      if (httpServer && !this.attached.has(httpServer)) {
+        this.attach(httpServer);
+        const { type, location } = this.storage;
+        console.log(
+          type === 'memory'
+            ? `[studio] Collaboration server ready at ${STUDIO_SOCKET_PATH}. Canvases are kept in memory and lost when the server restarts or redeploys: set studio.storage in eventcatalog.config.js to keep them.`
+            : `[studio] Collaboration server ready at ${STUDIO_SOCKET_PATH} (canvases stored in ${location})`
+        );
+      }
+    })();
+    return this.state.started;
+  }
+
+  /**
+   * Canvases change a moment before they're stored (Hocuspocus waits for edits to settle): as the process exits,
+   * the open ones are stored straight away so the last edits aren't lost. Storage writes are synchronous for this.
+   */
+  private saveOnExit() {
+    if (this.state.savesOnExit) return;
+    this.state.savesOnExit = true;
+    const saveOpenCanvases = () =>
+      this.server.hocuspocus.documents.forEach((document, name) => {
+        saveSnapshot(this.state, name, document);
+      });
+    process.once('exit', saveOpenCanvases);
+    for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+      process.once(signal, () => {
+        saveOpenCanvases();
+        // Stopping as it would have without this (unless something else handles the signal)
+        if (process.listenerCount(signal) === 0) process.kill(process.pid, signal);
+      });
+    }
+  }
+
+  /** How to tell whether a collaboration connection comes from someone signed in (checked when sign-in is on) */
+  useSignIn(isSignedIn: (request: Request) => Promise<boolean>) {
+    this.state.isSignedIn = isSignedIn;
+  }
+
   /** Handle collaboration WebSocket upgrades on an HTTP server (the dev server, or the production server) */
   attach(httpServer: HttpServer) {
     if (this.attached.has(httpServer)) return;
@@ -95,6 +235,15 @@ class StudioRuntime {
     return this.server.hocuspocus.documents.has(name) || this.snapshots.has(name);
   }
 
+  /** Starts a canvas with a title, recording when and by whom (a person, or an agent). Returns its id. */
+  async createCanvas({ title, createdBy }: { title?: string; createdBy?: string }) {
+    const canvasId = crypto.randomUUID();
+    await this.withCanvas(canvasId, (doc) =>
+      setMeta(doc, { ...(title && { title }), createdAt: Date.now(), ...(createdBy && { createdBy }) })
+    );
+    return canvasId;
+  }
+
   /** Read or change a canvas as the server. Changes sync to everyone on it, like anyone else's. */
   async withCanvas<T>(canvasId: string, fn: (doc: Y.Doc) => T): Promise<T> {
     const connection = await this.server.hocuspocus.openDirectConnection(canvasDocumentName(canvasId));
@@ -137,7 +286,7 @@ class StudioRuntime {
     return response;
   }
 
-  listCanvases(): CanvasSummary[] {
+  listCanvases({ withPreview = false }: { withPreview?: boolean } = {}): CanvasSummary[] {
     const names = new Set([...this.server.hocuspocus.documents.keys(), ...this.snapshots.keys()]);
     return [...names].flatMap((name) => {
       const canvasId = canvasIdFromDocumentName(name);
@@ -151,11 +300,15 @@ class StudioRuntime {
         {
           canvasId,
           title: meta.title,
+          status: getCanvasStatus(meta),
           createdAt: meta.createdAt,
+          ...(meta.createdBy && { createdBy: meta.createdBy }),
+          updatedAt: this.state.updatedAt.get(name) ?? meta.createdAt,
           nodeCount: nodes.size,
           edgeCount: edges.size,
           openComments: Array.from(threads.values()).filter((thread) => !thread.get('resolved')).length,
           people: live ? this.peopleOn(canvasId) : [],
+          ...(withPreview && { preview: getCanvasPreview(Array.from(nodes.values()), Array.from(edges.values())) }),
         },
       ];
     });
@@ -205,11 +358,37 @@ class StudioRuntime {
 const RUNTIME_KEY = Symbol.for('eventcatalog.studio.runtime');
 const store = globalThis as typeof globalThis & { [RUNTIME_KEY]?: RuntimeState };
 
+/**
+ * State kept from before a code change (the dev server reloads code but keeps globalThis) gets what's been added to it
+ * since. Hooks given to Hocuspocus when it was created (e.g. onChange, onConnect) only change on a restart.
+ */
+const upgrade = (state: RuntimeState) => {
+  state.updatedAt ??= new Map();
+  return state;
+};
+
 /** The process wide collaboration runtime (created on first use) */
-export const getStudioRuntime = (): StudioRuntime => new StudioRuntime((store[RUNTIME_KEY] ??= createState()));
+export const getStudioRuntime = (): StudioRuntime => new StudioRuntime(upgrade((store[RUNTIME_KEY] ??= createState())));
+
+/**
+ * In production, `eventcatalog start` leaves the HTTP server it runs here, so Studio's collaboration connection can be
+ * served on it (Astro's Node adapter doesn't expose it otherwise)
+ */
+const HTTP_SERVER_KEY = Symbol.for('eventcatalog.http-server');
+
+/**
+ * Studio, started: what pages and tools use before working with canvases. Pages say how to tell who's signed in,
+ * for the collaboration connection.
+ */
+export const startStudio = async ({ isSignedIn }: { isSignedIn?: (request: Request) => Promise<boolean> } = {}) => {
+  const runtime = getStudioRuntime();
+  if (isSignedIn) runtime.useSignIn(isSignedIn);
+  await runtime.start();
+  return runtime;
+};
 
 /** The runtime if the collaboration server is running in this process */
 export const findStudioRuntime = (): StudioRuntime | undefined => {
   const state = store[RUNTIME_KEY];
-  return state ? new StudioRuntime(state) : undefined;
+  return state ? new StudioRuntime(upgrade(state)) : undefined;
 };

package/eventcatalog/src/features/studio/server/sign-in.ts

@@ -0,0 +1,18 @@
+import { getSession } from '@utils/auth-astro/server';
+import type { NormalizedUser } from '@features/auth/middleware/middleware-auth';
+
+/** Someone signed in with the catalog's sign-in (SSO): Studio shows them by these, and they can't change them */
+export type SignedInUser = { name: string; picture?: string };
+
+/** For the collaboration connection (see startStudio): it has the same cookies as the pages */
+export const isSignedIn = async (request: Request) => Boolean(await getSession(request));
+
+/** Who's signed in, from what the sign-in middleware found (nobody when sign-in is off) */
+export const getSignedInUser = (locals: object): SignedInUser | undefined => {
+  const user = (locals as { user?: NormalizedUser }).user;
+  const name = user?.name || user?.email;
+  if (!user || !name) return undefined;
+  // Pictures are loaded from the provider (Auth.js calls it `image`), over HTTPS only
+  const picture = user.picture ?? user.raw?.user?.image;
+  return { name, ...(typeof picture === 'string' && picture.startsWith('https://') && { picture }) };
+};

package/eventcatalog/src/features/studio/server/storage.ts

@@ -0,0 +1,110 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Where Studio keeps canvases (`studio.storage` in eventcatalog.config.js). People and agents always work on the copy
+ * the collaboration server holds in memory, so storage is only read when the server starts, and written a moment
+ * after a canvas changes: it doesn't slow down editing. Canvases are stored as their whole Yjs document
+ * (Y.encodeStateAsUpdate), so nothing is lost between restarts.
+ */
+export type StudioStorageConfig =
+  /** Kept only while the server runs: canvases are lost when it restarts or redeploys (the default) */
+  | { type: 'memory' }
+  /**
+   * One SQLite database file (default `.eventcatalog/studio.db` in the catalog). Needs Node.js 22.13 or later. In a
+   * container, put it on a volume so it survives redeploys.
+   */
+  | { type: 'sqlite'; path?: string };
+
+export type StorageType = StudioStorageConfig['type'];
+
+export const DEFAULT_STORAGE: StudioStorageConfig = { type: 'memory' };
+const DEFAULT_SQLITE_PATH = '.eventcatalog/studio.db';
+
+/** A canvas as stored: its whole document, and when it last changed */
+export type StoredCanvas = { state: Uint8Array; updatedAt?: number };
+
+export type CanvasStorage = {
+  type: StorageType;
+  /** Where it is, for logs (e.g. the database file) */
+  location?: string;
+  /** Every stored canvas, by document name (read once, when the server starts) */
+  loadAll: () => Promise<Map<string, StoredCanvas>>;
+  /**
+   * Stores a canvas's document, with when it last changed (now when not known). Synchronous, so canvases can still
+   * be saved as the process exits.
+   */
+  save: (documentName: string, state: Uint8Array, updatedAt?: number) => void;
+};
+
+export const memoryStorage = (): CanvasStorage => ({
+  type: 'memory',
+  loadAll: async () => new Map(),
+  save: () => {},
+});
+
+type SqliteDatabase = {
+  exec: (sql: string) => void;
+  prepare: (sql: string) => { run: (...values: unknown[]) => unknown; all: () => unknown[] };
+};
+
+export const sqliteStorage = (file: string): CanvasStorage => {
+  let database: SqliteDatabase | undefined;
+  let upsert: ReturnType<SqliteDatabase['prepare']> | undefined;
+  return {
+    type: 'sqlite',
+    location: file,
+    loadAll: async () => {
+      // 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) => SqliteDatabase };
+      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 });
+      database = new sqlite.DatabaseSync(file);
+      database.exec('PRAGMA journal_mode = WAL');
+      database.exec(
+        'CREATE TABLE IF NOT EXISTS canvases (name TEXT PRIMARY KEY, state BLOB NOT NULL, updated_at INTEGER NOT NULL)'
+      );
+      upsert = database.prepare(
+        'INSERT INTO canvases (name, state, updated_at) VALUES (?, ?, ?) ON CONFLICT(name) DO UPDATE SET state = excluded.state, updated_at = excluded.updated_at'
+      );
+      const rows = database.prepare('SELECT name, state, updated_at FROM canvases').all() as {
+        name: string;
+        state: Uint8Array;
+        updated_at: number;
+      }[];
+      return new Map(rows.map((row) => [row.name, { state: new Uint8Array(row.state), updatedAt: Number(row.updated_at) }]));
+    },
+    save: (documentName, state, updatedAt = Date.now()) => {
+      if (!upsert) throw new Error('SQLite storage was used before it was opened');
+      upsert.run(documentName, state, updatedAt);
+    },
+  };
+};
+
+/** The storage a config asks for, with paths relative to the catalog. Unknown types are an error. */
+export const createStorage = (config: StudioStorageConfig | undefined, projectDirectory: string): CanvasStorage => {
+  const chosen = config ?? DEFAULT_STORAGE;
+  const resolve = (location: string | undefined, fallback: string) => path.resolve(projectDirectory, location ?? fallback);
+  switch (chosen.type) {
+    case 'memory':
+      return memoryStorage();
+    case 'sqlite':
+      return sqliteStorage(resolve(chosen.path, DEFAULT_SQLITE_PATH));
+    default:
+      throw new Error(`Unknown studio.storage type "${(chosen as { type?: string }).type}": use "memory" or "sqlite"`);
+  }
+};