eidosmd 0.1.0 → 0.2.0

package/dist/src/core/server.js

@@ -1,25 +1,33 @@
 // The local browser's server: a plain Node http server on 127.0.0.1 serving
-// one HTML page and a small JSON API. Every write the page can make goes
-// through the same core function the matching command uses (`new` scaffolds,
-// `index` rebuilds, `check` validates), so nothing is possible here that is
-// not possible from the shell. The root is re-read on every request; files
-// change on disk while the page is open.
+// the built page (browser/dist) and a JSON API. Every write the page can make
+// goes through the same core function the matching command uses (`new`
+// scaffolds, `index` rebuilds, `check` validates), so nothing is possible
+// here that is not possible from the shell. Reads come from the store, which
+// keeps the parsed root until a file changes and indexes it for search.
 import { createServer as createHttpServer } from 'node:http';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { marked } from 'marked';
-import { loadRoot } from '../context.js';
 import { checkRoot } from './check.js';
 import { buildIndexes } from './index-leaf.js';
-import { frameworkToDocument } from './framework-structured.js';
-import { listRoles, meFile, readActor } from './me.js';
+import { embeddedIndexOf, frameworkToDocument, parseFrameworkStructured, serializeDocument, withEmbeddedIndex } from './framework-structured.js';
+import { FRAMEWORK_DIR, FrameworkError, propertiesFor } from './framework.js';
+import { readVersions, recordVersion, VersionError } from './versions.js';
+import { gitHead, gitLog, gitShowFile, gitUser } from './git.js';
+import { actingUser, matchesIdentity, readSettings, writeSettings } from './settings.js';
+import { formatFrontmatter } from './frontmatter.js';
+import { findRole, isRoleName, listRoles, meFile, readActor, renderActor, roleFile, writeActor } from './me.js';
 import { scaffoldBlueprint, ScaffoldError } from './scaffold.js';
-import { blueprintId, blueprintTitle, propertyString, resolveFlavor } from './blueprint.js';
-import { loadShape } from './shape.js';
-import { CliError } from '../output.js';
+import { blueprintId, blueprintTitle, propertyString, resolveVariant } from './blueprint.js';
+import { loadTemplate, stripFrontmatter } from './template.js';
+import { unitOf } from './framework-model.js';
+import { Store } from './store.js';
+import { CliError, today } from '../output.js';
 import { browserDir, packageVersion, readStandard, standardVersion } from '../paths.js';
 import { guideText, GUIDES } from '../commands/instructions.js';
-import { today } from '../output.js';
+import { ANCHORS, EDGE_CAPS, CanvasError, createCanvas, findEndpoint, findNode, FRAME_REF, findPage, listCanvases, loadCanvas, nextCommentId, nextNodeId, renderComments, renderPage, replacePageContents, saveCanvas, toJsonCanvas, canvasProperties, readBox, readStyle, sketchValues } from './canvas.js';
 class HttpError extends Error {
     status;
     constructor(status, message) {
@@ -34,9 +42,11 @@ function json(response, status, body) {
 }
 async function readBody(request) {
     const chunks = [];
+    let size = 0;
     for await (const chunk of request) {
         chunks.push(chunk);
-        if (chunks.reduce((size, part) => size + part.length, 0) > 8 * 1024 * 1024) {
+        size += chunk.length;
+        if (size > 8 * 1024 * 1024) {
             throw new HttpError(413, 'request body too large');
         }
     }
@@ -55,15 +65,16 @@ async function readBody(request) {
 function rel(root, file) {
     return path.relative(root, file).split(path.sep).join('/');
 }
+const str = (value) => (typeof value === 'string' && value.trim() !== '' ? value.trim() : null);
 function blueprintSummary(blueprint) {
-    const { flavor, declared } = resolveFlavor(blueprint);
+    const { variant, declared } = resolveVariant(blueprint);
     return {
         id: blueprintId(blueprint),
         title: blueprintTitle(blueprint),
         summary: propertyString(blueprint, 'summary'),
         collection: blueprint.collection.name,
         group: blueprint.group,
-        flavor: flavor?.name ?? declared,
+        variant: variant?.name ?? declared,
         path: blueprint.rel,
     };
 }
@@ -79,35 +90,155 @@ function findByPath(context, relPath) {
 function findingsFor(context, blueprint) {
     return checkRoot(context.framework, context.blueprints, { only: new Set([blueprint.path]), standardVersion: standardVersion() }).findings.filter((finding) => finding.path === blueprint.rel);
 }
+function propertyView(property) {
+    return { name: property.name, type: property.type, core: property.core, owner: property.owner, meaning: property.meaning, applies_to: property.appliesTo, canvas: property.canvas ?? null, tools: property.tools ?? {} };
+}
+// The values a Text property already takes across a collection, for the
+// editor to offer; a canvas hint's keys count as values too.
+function knownValues(context, collectionName) {
+    const out = {};
+    for (const property of propertiesFor(context.framework, collectionName)) {
+        if (property.type !== 'Text' || ['id', 'title', 'summary'].includes(property.name))
+            continue;
+        const values = new Set();
+        for (const key of [...Object.keys(property.canvas?.shape ?? {}), ...Object.keys(property.canvas?.color ?? {})])
+            values.add(key);
+        for (const blueprint of context.blueprints) {
+            if (blueprint.collection.name !== collectionName)
+                continue;
+            const value = propertyString(blueprint, property.name);
+            if (value)
+                values.add(value);
+        }
+        if (values.size > 0)
+            out[property.name] = values;
+    }
+    return Object.fromEntries(Object.entries(out).map(([name, values]) => [name, [...values].sort((a, b) => a.localeCompare(b))]));
+}
 function blueprintDetail(context, blueprint) {
     const raw = readFileSync(blueprint.path, 'utf8');
-    const { flavor } = resolveFlavor(blueprint);
-    const shape = flavor ? loadShape(context.framework, flavor) : null;
+    const { variant } = resolveVariant(blueprint);
+    const template = variant ? loadTemplate(context.framework, variant) : null;
     return {
         ...blueprintSummary(blueprint),
         properties: blueprint.properties ?? {},
         frontmatter_error: blueprint.frontmatterError,
+        schema: propertiesFor(context.framework, blueprint.collection.name).map(propertyView),
+        known_values: knownValues(context, blueprint.collection.name),
         sections: blueprint.sections.map((section) => section.heading.text),
-        shape_sections: shape?.sections ?? [],
+        template_sections: template?.sections ?? [],
+        body: blueprint.body,
         html: marked.parse(blueprint.body, { async: false }),
         raw,
         findings: findingsFor(context, blueprint),
     };
 }
-function rootSnapshot(context) {
+// Whether git is read at all here: the root's switch, and then whether the
+// root sits in a repository and who git says is here.
+function gitInfo(root, shared = readSettings(root).shared) {
+    const enabled = shared.features.git;
+    const head = enabled ? gitHead(root) : null;
+    return { enabled, available: head !== null, head, user: head === null ? null : gitUser(root) };
+}
+// A top-level document: README.md or one the framework declares, addressed
+// by its path from the root. Nothing else at the root is served as a doc.
+function topLevelFile(context, relPath) {
+    const wanted = decodeURIComponent(relPath).replace(/\\/g, '/').replace(/^\/+/, '');
+    const file = path.resolve(context.root, wanted);
+    const declared = new Set([path.resolve(context.root, 'README.md'), ...context.framework.topLevel.map((doc) => path.resolve(path.dirname(context.framework.file), doc.path))]);
+    if (!file.startsWith(context.root + path.sep) || !file.endsWith('.md') || !declared.has(file)) {
+        throw new HttpError(404, `no top-level document at ${wanted}`);
+    }
+    const doc = context.framework.topLevel.find((entry) => path.resolve(path.dirname(context.framework.file), entry.path) === file);
+    return { file, rel: rel(context.root, file), title: doc?.title ?? path.basename(file, '.md') };
+}
+function docView(context, relPath) {
+    const { file, rel: relative, title } = topLevelFile(context, relPath);
+    if (!existsSync(file))
+        throw new HttpError(404, `${relative} does not exist`);
+    const raw = readFileSync(file, 'utf8');
+    return { path: relative, title, html: marked.parse(raw, { async: false }), raw, history: gitInfo(context.root).available ? gitLog(context.root, relative, 20) : [] };
+}
+function rootSnapshot(context, store) {
     const actor = readActor(context.root);
+    const settings = readSettings(context.root);
+    const git = gitInfo(context.root, settings.shared);
     return {
         root: context.root,
         name: path.basename(context.root),
         cli_version: packageVersion(),
         standard_version: standardVersion(),
+        search_engine: store.engine,
+        git_head: git.head,
+        git,
+        settings,
         framework: { file: rel(context.root, context.framework.file), format: context.framework.format, problems: context.framework.problems, ...frameworkToDocument(context.framework) },
         blueprints: context.blueprints.map(blueprintSummary),
         roles: listRoles(context.root).map((role) => ({ name: role.name, title: role.title, summary: role.summary })),
+        // the health check's totals, for the sidebar's badge
+        check: (() => {
+            const report = checkRoot(context.framework, context.blueprints, { standardVersion: standardVersion() });
+            return { errors: report.errors, warnings: report.warnings };
+        })(),
+        canvases: listCanvases(context.framework).map((canvas) => ({ id: canvas.id, title: canvas.title, pages: canvas.pages.length })),
         actor: { exists: actor.exists, role: actor.actor.role, ownership: actor.actor.ownership, experience: actor.actor.experience, capacity: actor.actor.capacity, path: rel(context.root, meFile(context.root)) },
         guides: GUIDES,
     };
 }
+// One collection as a table: the schema's properties for this collection as
+// columns, one row per blueprint with everything its frontmatter holds.
+function collectionTable(context, name) {
+    const collection = context.framework.collections.find((candidate) => candidate.name.toLowerCase() === name.toLowerCase());
+    if (!collection) {
+        throw new HttpError(404, `no collection '${name}'`);
+    }
+    const report = checkRoot(context.framework, context.blueprints, { standardVersion: standardVersion() });
+    const counts = new Map();
+    for (const finding of report.findings) {
+        if (!finding.path)
+            continue;
+        const entry = counts.get(finding.path) ?? { errors: 0, warnings: 0 };
+        if (finding.level === 'error')
+            entry.errors += 1;
+        else
+            entry.warnings += 1;
+        counts.set(finding.path, entry);
+    }
+    const rows = context.blueprints
+        .filter((blueprint) => blueprint.collection === collection)
+        .map((blueprint) => ({
+        ...blueprintSummary(blueprint),
+        properties: blueprint.properties ?? {},
+        frontmatter_error: blueprint.frontmatterError,
+        findings: counts.get(blueprint.rel) ?? { errors: 0, warnings: 0 },
+    }));
+    return {
+        collection: {
+            name: collection.name,
+            description: collection.description,
+            unit: unitOf(collection),
+            framing: collection.framing,
+            variants: collection.variants.map((variant) => ({ name: variant.name, default: variant.isDefault, description: variant.description })),
+            grouping: collection.grouping ? { label: collection.grouping.label, property: collection.grouping.property, groups: collection.grouping.groups } : null,
+        },
+        columns: propertiesFor(context.framework, collection.name).map(propertyView),
+        known_values: knownValues(context, collection.name),
+        rows,
+    };
+}
+// The values a Text property takes anywhere in the root, for a sketch's fields.
+function knownValuesAll(context, name) {
+    const values = new Set();
+    const property = context.framework.schema.custom.find((candidate) => candidate.name === name);
+    for (const key of [...Object.keys(property?.canvas?.shape ?? {}), ...Object.keys(property?.canvas?.color ?? {})])
+        values.add(key);
+    for (const blueprint of context.blueprints) {
+        const value = propertyString(blueprint, name);
+        if (value !== null && value !== '')
+            values.add(value);
+    }
+    return [...values];
+}
 function checkSnapshot(context) {
     const report = checkRoot(context.framework, context.blueprints, { standardVersion: standardVersion() });
     return {
@@ -128,6 +259,66 @@ function indexRebuild(context) {
         missing_summary: results.flatMap((result) => result.missingSummary),
     };
 }
+// --- the framework, templates, and me.md, for the settings panel -----------
+function templatesView(context) {
+    const out = [];
+    for (const collection of context.framework.collections) {
+        for (const variant of collection.variants) {
+            const template = loadTemplate(context.framework, variant);
+            out.push({ collection: collection.name, variant: variant.name, path: variant.template, exists: template !== null, sections: template?.sections ?? [] });
+        }
+    }
+    return out;
+}
+function frameworkView(context) {
+    const { framework } = context;
+    return {
+        file: rel(context.root, framework.file),
+        format: framework.format,
+        problems: framework.problems,
+        document: frameworkToDocument(framework),
+        templates: templatesView(context),
+    };
+}
+// The whole document replaced, the generated index carried over untouched.
+// A document that cannot be read at all is refused; one with problems is
+// written and the problems returned, as `check` would report them.
+function saveFramework(context, body) {
+    const given = (typeof body['document'] === 'object' && body['document'] !== null ? body['document'] : body);
+    if (!Array.isArray(given['collections'])) {
+        throw new HttpError(400, 'expected { document } with a collections list');
+    }
+    const document = { ...given };
+    delete document['index'];
+    let text = serializeDocument(document);
+    const current = readFileSync(context.framework.file, 'utf8');
+    const index = embeddedIndexOf(current);
+    if (index) {
+        text = withEmbeddedIndex(text, index);
+    }
+    let parsed;
+    try {
+        parsed = parseFrameworkStructured(text, context.root, context.framework.file);
+    }
+    catch (cause) {
+        if (cause instanceof FrameworkError)
+            throw new HttpError(400, cause.message);
+        throw cause;
+    }
+    writeFileSync(context.framework.file, text, 'utf8');
+    return { file: rel(context.root, context.framework.file), problems: parsed.problems };
+}
+// A template file, addressed relative to `.eidos/` as the framework declares it.
+function templateFile(context, relPath) {
+    const wanted = decodeURIComponent(relPath).replace(/\\/g, '/');
+    const base = path.join(context.root, FRAMEWORK_DIR);
+    const file = path.resolve(base, wanted);
+    if (!file.startsWith(base + path.sep) || !file.endsWith('.md')) {
+        throw new HttpError(400, `a template lives under ${FRAMEWORK_DIR}/ and ends in .md`);
+    }
+    return file;
+}
+// --- blueprint writes -----------------------------------------------------------
 function createBlueprint(context, body) {
     const text = (value) => (typeof value === 'string' && value.trim() !== '' ? value : null);
     const set = {};
@@ -143,7 +334,7 @@ function createBlueprint(context, body) {
         result = scaffoldBlueprint(context.framework, context.blueprints, {
             collection: text(body['collection']) ?? '',
             title: text(body['title']) ?? '',
-            flavor: text(body['flavor']),
+            variant: text(body['variant']),
             group: text(body['group']),
             id: text(body['id']),
             summary: text(body['summary']),
@@ -159,67 +350,1058 @@ function createBlueprint(context, body) {
     }
     mkdirSync(path.dirname(result.path), { recursive: true });
     writeFileSync(result.path, result.content, 'utf8');
-    return { path: result.rel, id: result.id, collection: result.collection.name, group: result.group, flavor: result.flavor.name, notes: result.notes };
+    return { path: result.rel, id: result.id, collection: result.collection.name, group: result.group, variant: result.variant.name, notes: result.notes };
+}
+// `{ text }` replaces the file; `{ properties, body }` writes the frontmatter
+// in the house style from an ordered list of [key, value] pairs (or an object,
+// in its key order) above the given body.
+function blueprintText(body, rules = []) {
+    if (typeof body['text'] === 'string') {
+        return body['text'].replace(/\r\n?/g, '\n');
+    }
+    const properties = body['properties'];
+    const bodyText = typeof body['body'] === 'string' ? body['body'].replace(/\r\n?/g, '\n') : null;
+    if (properties === undefined || bodyText === null) {
+        throw new HttpError(400, 'expected { text } or { properties, body }');
+    }
+    let entries;
+    if (Array.isArray(properties)) {
+        entries = properties
+            .filter((pair) => Array.isArray(pair) && typeof pair[0] === 'string' && pair[0].trim() !== '')
+            .map((pair) => [String(pair[0]).trim(), pair[1]]);
+    }
+    else if (typeof properties === 'object' && properties !== null) {
+        entries = Object.entries(properties);
+    }
+    else {
+        throw new HttpError(400, 'properties must be a list of [key, value] pairs or an object');
+    }
+    // The root's on-save rules: a named property takes the date or the time,
+    // added at the end when the file lacked it.
+    for (const rule of rules) {
+        const value = rule.set === 'today' ? today() : localMinute();
+        const at = entries.findIndex(([key]) => key === rule.property);
+        if (at === -1)
+            entries.push([rule.property, value]);
+        else
+            entries[at] = [rule.property, value];
+    }
+    const frontmatter = formatFrontmatter(entries);
+    return frontmatter + (bodyText.startsWith('\n') ? bodyText : '\n' + bodyText);
+}
+// `YYYY-MM-DDTHH:mm` in local time, the Date & time form the standard names.
+function localMinute() {
+    const now = new Date();
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}T${pad(now.getHours())}:${pad(now.getMinutes())}`;
+}
+// --- canvas maps ---------------------------------------------------------------
+function canvasSummary(context, canvas) {
+    return {
+        id: canvas.id,
+        title: canvas.title,
+        path: rel(context.root, canvas.file),
+        pages: canvas.pages.map((page) => ({ id: page.id, title: page.title, nodes: page.nodes.length, edges: page.edges.length })),
+        problems: canvas.problems,
+    };
+}
+// The comment author: the user this machine acts as, else the user the git
+// identity matches (by email, then name), else the git name with the me.md
+// role beside it, else that role alone, else "me". Yes, it can be faked;
+// it is attribution, not authentication.
+function commentAuthor(context) {
+    const settings = readSettings(context.root);
+    const meRole = readActor(context.root).actor.role;
+    const acting = actingUser(settings);
+    if (acting)
+        return { name: acting.name, role: acting.role ?? meRole, user: acting.alias ?? acting.name };
+    const git = gitInfo(context.root, settings.shared);
+    if (git.user) {
+        const identity = git.user;
+        const match = settings.shared.users.find((user) => matchesIdentity(user, identity));
+        if (match)
+            return { name: match.name, role: match.role ?? meRole, user: match.alias ?? match.name };
+        return { name: git.user.name, role: meRole, user: null };
+    }
+    return { name: meRole ?? 'me', role: null, user: null };
+}
+const signed = (author) => ({ author: author.name, ...(author.role ? { role: author.role } : {}), ...(author.user ? { user: author.user } : {}) });
+function pageView(context, canvas, page) {
+    const nodes = renderPage(context.framework, context.blueprints, page);
+    return {
+        canvas: canvasSummary(context, canvas),
+        // `raw` is the page as the file holds it: what the browser's undo puts back
+        page: { id: page.id, title: page.title, frames: page.frames, edges: page.edges, raw: { frames: page.frames, nodes: page.nodes, edges: page.edges, layout: page.layout, comments: page.comments } },
+        nodes,
+        comments: renderComments(page, nodes),
+        author: commentAuthor(context),
+        palette: canvasProperties(context.framework).map((property) => ({ property: property.name, type: property.type, applies_to: property.appliesTo, shape: property.canvas.shape ?? null, color: property.canvas.color ?? null, show: property.canvas.show === true })),
+        // schema properties a sketch may hold: those applying to every collection, with the values the root uses
+        sketch_properties: propertiesFor(context.framework, '')
+            .filter((property) => !property.core && property.appliesTo === 'all')
+            .map((property) => ({ ...propertyView(property), values: knownValuesAll(context, property.name) })),
+        collections: context.framework.collections.map((collection) => ({
+            name: collection.name,
+            variants: collection.variants.map((variant) => ({ name: variant.name, default: variant.isDefault })),
+            groups: collection.grouping?.groups.map((group) => group.name) ?? [],
+        })),
+        git: gitInfo(context.root).available,
+    };
+}
+function mutateCanvas(context, canvasId, change) {
+    const canvas = loadCanvas(context.framework, canvasId);
+    change(canvas);
+    saveCanvas(canvas);
+    return loadCanvas(context.framework, canvasId);
+}
+const slug = (title, fallback) => title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || fallback;
+// Every canvas route, dispatched on the rest of the path after /api/canvas.
+async function handleCanvas(store, method, segments, request, response) {
+    const [canvasId, ...rest] = segments;
+    if (canvasId === undefined || canvasId === '') {
+        if (method === 'GET') {
+            const current = store.context();
+            json(response, 200, listCanvases(current.framework).map((canvas) => canvasSummary(current, canvas)));
+            return;
+        }
+        if (method === 'POST') {
+            const body = await readBody(request);
+            const current = store.context();
+            json(response, 201, canvasSummary(current, createCanvas(current.framework, str(body['title']) ?? '')));
+            return;
+        }
+        throw new HttpError(404, 'not found');
+    }
+    let current = store.context();
+    // GET    /api/canvas/<id>            the canvas and its first page
+    // PUT    /api/canvas/<id>            { title }
+    // DELETE /api/canvas/<id>
+    if (rest.length === 0) {
+        if (method === 'GET') {
+            const canvas = loadCanvas(current.framework, canvasId);
+            const page = canvas.pages[0];
+            json(response, 200, page ? pageView(current, canvas, page) : { canvas: canvasSummary(current, canvas), page: null, nodes: [] });
+            return;
+        }
+        if (method === 'PUT') {
+            const body = await readBody(request);
+            const canvas = mutateCanvas(current, canvasId, (draft) => {
+                const title = str(body['title']);
+                if (!title)
+                    throw new CanvasError('a canvas needs a title');
+                draft.title = title;
+            });
+            json(response, 200, canvasSummary(current, canvas));
+            return;
+        }
+        if (method === 'DELETE') {
+            const canvas = loadCanvas(current.framework, canvasId);
+            rmSync(canvas.file);
+            json(response, 200, { deleted: canvas.id });
+            return;
+        }
+        throw new HttpError(404, 'not found');
+    }
+    if (rest[0] === 'export' && method === 'GET') {
+        const canvas = loadCanvas(current.framework, canvasId);
+        const page = findPage(canvas, rest[1] ?? canvas.pages[0]?.id ?? '');
+        const text = JSON.stringify(toJsonCanvas(current.framework, current.blueprints, page), null, 2);
+        response.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'content-disposition': `attachment; filename="${canvas.id}-${page.id}.canvas"` });
+        response.end(text);
+        return;
+    }
+    if (rest[0] === 'pages' && rest.length === 1 && method === 'POST') {
+        const body = await readBody(request);
+        const title = str(body['title']) ?? 'Untitled';
+        const canvas = mutateCanvas(current, canvasId, (draft) => {
+            const id = str(body['id']) ?? slug(title, `page-${draft.pages.length + 1}`);
+            if (draft.pages.some((page) => page.id === id))
+                throw new CanvasError(`page '${id}' already exists`, 409);
+            draft.pages.push({ id, title, frames: [], nodes: [], edges: [], layout: {}, comments: [] });
+        });
+        json(response, 201, canvasSummary(current, canvas));
+        return;
+    }
+    if (rest[0] !== 'pages' || rest[1] === undefined) {
+        throw new HttpError(404, 'not found');
+    }
+    const pageId = rest[1];
+    const tail = rest.slice(2);
+    if (tail.length === 0 && method === 'GET') {
+        const canvas = loadCanvas(current.framework, canvasId);
+        json(response, 200, pageView(current, canvas, findPage(canvas, pageId)));
+        return;
+    }
+    const body = method === 'GET' ? {} : await readBody(request);
+    // PUT pages/<p> { title } renames; { page: { frames, nodes, edges, layout, comments } } replaces the contents whole (undo, multi-select edits)
+    if (tail.length === 0 && method === 'PUT') {
+        const canvas = mutateCanvas(current, canvasId, (draft) => {
+            const page = findPage(draft, pageId);
+            const title = str(body['title']);
+            if (title)
+                page.title = title;
+            if (typeof body['page'] === 'object' && body['page'] !== null)
+                replacePageContents(page, body['page']);
+        });
+        json(response, 200, pageView(current, canvas, findPage(canvas, pageId)));
+        return;
+    }
+    if (tail.length === 0 && method === 'DELETE') {
+        const canvas = mutateCanvas(current, canvasId, (draft) => {
+            findPage(draft, pageId);
+            if (draft.pages.length === 1)
+                throw new CanvasError('a canvas keeps at least one page');
+            draft.pages = draft.pages.filter((page) => page.id !== pageId);
+        });
+        json(response, 200, canvasSummary(current, canvas));
+        return;
+    }
+    let changed = null;
+    // POST   nodes                one of { sketch: { label, note?, properties? } } | { sticky: { text, color? } } | { text: { text, size?, font? } } | { annotation: { text, color? } } | { blueprint }  + frame?, link?, locked?, style?, box?, x?, y?
+    // PUT    nodes/<n>            the same fields, replacing what is given; { x, y } stores a layout override; { x: null } clears it
+    // DELETE nodes/<n>            removes the node, its edges, and its comments
+    // POST   nodes/<n>/promote    { collection, title?, variant?, group?, summary? }
+    // POST   edges                { from, to, from_anchor?, to_anchor? };  PUT edges { from, to, label?, label_at?, bend?, anchors, color?, style?, start?, end? };  DELETE edges { from, to }
+    // POST   frames               { title, id?, x?, y?, w?, h?, color?, members? };  PUT frames/<f> { title?, x?, y?, w?, h?, color?, locked?, frame? };  DELETE frames/<f>?contents=delete
+    // PUT    layout               { positions: { <node>: { x, y } } } pins several at once;  DELETE layout clears every override
+    // POST   comments             { x, y, node?, text };  POST comments/<c>/replies { text };  PUT comments/<c> { resolved?, x?, y?, node? };  DELETE comments/<c>
+    // PUT    comments/<c>/messages/<i> { text };  DELETE comments/<c>/messages/<i>
+    if (tail[0] === 'nodes' && tail.length === 1 && method === 'POST') {
+        let created = '';
+        changed = mutateCanvas(current, canvasId, (draft) => {
+            const page = findPage(draft, pageId);
+            const node = { id: str(body['id']) ?? nextNodeId(page) };
+            if (page.nodes.some((candidate) => candidate.id === node.id))
+                throw new CanvasError(`node '${node.id}' already exists`, 409);
+            applyNodeFields(node, body);
+            if (!node.blueprint && !node.sketch && !node.sticky && !node.text && !node.annotation)
+                throw new CanvasError('a node is { blueprint }, { sketch: { label } }, { sticky: { text } }, { text: { text } }, or { annotation: { text } }');
+            page.nodes.push(node);
+            if (typeof body['x'] === 'number' && typeof body['y'] === 'number')
+                page.layout[node.id] = { x: body['x'], y: body['y'] };
+            created = node.id;
+        });
+        const page = findPage(changed, pageId);
+        json(response, 201, { node: renderPage(current.framework, current.blueprints, page).find((node) => node.id === created) ?? null, ...pageView(current, changed, page) });
+        return;
+    }
+    if (tail[0] === 'nodes' && tail[1] !== undefined && tail.length === 2 && method === 'PUT') {
+        changed = mutateCanvas(current, canvasId, (draft) => {
+            const page = findPage(draft, pageId);
+            const node = findNode(page, tail[1] ?? '');
+            applyNodeFields(node, body);
+            if (body['x'] === null)
+                delete page.layout[node.id];
+            else if (typeof body['x'] === 'number' && typeof body['y'] === 'number')
+                page.layout[node.id] = { x: body['x'], y: body['y'] };
+        });
+    }
+    else if (tail[0] === 'nodes' && tail[1] !== undefined && tail.length === 2 && method === 'DELETE') {
+        changed = mutateCanvas(current, canvasId, (draft) => {
+            const page = findPage(draft, pageId);
+            findNode(page, tail[1] ?? '');
+            removeNodes(page, [tail[1] ?? '']);
+        });
+    }
+    else if (tail[0] === 'nodes' && tail[1] !== undefined && tail[2] === 'promote' && method === 'POST') {
+        const canvas = loadCanvas(current.framework, canvasId);
+        const node = findNode(findPage(canvas, pageId), tail[1]);
+        if (!node.sketch)
+            throw new HttpError(400, `node '${node.id}' is already a blueprint`);
+        const sketch = node.sketch;
+        const set = sketchValues(current.framework, sketch);
+        const created = createBlueprint(current, {
+            collection: str(body['collection']) ?? '',
+            title: str(body['title']) ?? (sketch.label.trim() === '' ? '' : sketch.label),
+            variant: str(body['variant']) ?? undefined,
+            group: str(body['group']) ?? undefined,
+            summary: str(body['summary']) ?? sketch.note ?? undefined,
+            set,
+        });
+        changed = mutateCanvas(current, canvasId, (draft) => {
+            const target = findNode(findPage(draft, pageId), tail[1] ?? '');
+            target.blueprint = String(created['id']);
+            delete target.sketch;
+        });
+        store.invalidate();
+        current = store.context();
+    }
+    else if (tail[0] === 'edges' && (method === 'POST' || method === 'PUT')) {
+        changed = mutateCanvas(current, canvasId, (draft) => {
+            const page = findPage(draft, pageId);
+            const from = str(body['from']);
+            const to = str(body['to']);
+            if (!from || !to)
+                throw new CanvasError('an edge needs from and to');
+            if (from === to)
+                throw new CanvasError('an edge needs two different ends');
+            findEndpoint(page, from);
+            findEndpoint(page, to);
+            const existing = page.edges.find((edge) => edge.from === from && edge.to === to);
+            const label = str(body['label']);
+            const edge = existing ?? { from, to };
+            if (label)
+                edge.label = label;
+            else if (body['label'] === null || body['label'] === '')
+                delete edge.label;
+            if (typeof body['bend'] === 'number')
+                edge.bend = Math.round(body['bend']);
+            else if (body['bend'] === null)
+                delete edge.bend;
+            for (const key of ['from_anchor', 'to_anchor']) {
+                const given = body[key];
+                if (given === null)
+                    delete edge[key];
+                else if (typeof given === 'string' && ANCHORS.includes(given))
+                    edge[key] = given;
+            }
+            // the look: a color, dashed or solid, a cap at either end, the label's place along the line
+            if (typeof body['label_at'] === 'number')
+                edge.label_at = Math.round(Math.min(1, Math.max(0, body['label_at'])) * 100) / 100;
+            else if (body['label_at'] === null)
+                delete edge.label_at;
+            const color = str(body['color']);
+            if (color)
+                edge.color = color;
+            else if (body['color'] === null || body['color'] === '')
+                delete edge.color;
+            if (body['style'] === 'dashed')
+                edge.style = 'dashed';
+            else if (body['style'] === 'solid' || body['style'] === null)
+                delete edge.style;
+            for (const key of ['start', 'end']) {
+                const given = body[key];
+                if (given === null)
+                    delete edge[key];
+                else if (typeof given === 'string' && EDGE_CAPS.includes(given))
+                    edge[key] = given;
+            }
+            if (!existing)
+                page.edges.push(edge);
+        });
+    }
+    else if (tail[0] === 'edges' && method === 'DELETE') {
+        changed = mutateCanvas(current, canvasId, (draft) => {
+            const page = findPage(draft, pageId);
+            page.edges = page.edges.filter((edge) => !(edge.from === body['from'] && edge.to === body['to']));
+        });
+    }
+    else if (tail[0] === 'frames' && tail.length === 1 && method === 'POST') {
+        let created = '';
+        changed = mutateCanvas(current, canvasId, (draft) => {
+            const page = findPage(draft, pageId);
+            const title = str(body['title']) ?? `Frame ${page.frames.length + 1}`;
+            let id = str(body['id']) ?? slug(title, `frame-${page.frames.length + 1}`);
+            let n = 1;
+            while (page.frames.some((frame) => frame.id === id))
+                id = `${slug(title, 'frame')}-${(n += 1)}`;
+            const frame = { id, title };
+            applyFrameFields(frame, body);
+            page.frames.push(frame);
+            // Nodes inside a drawn frame belong to it.
+            if (frame.x !== undefined) {
+                const members = Array.isArray(body['members']) ? new Set(body['members'].map(String)) : null;
+                for (const node of page.nodes) {
+                    if (members?.has(node.id))
+                        node.frame = id;
+                }
+            }
+            created = id;
+        });
+        const page = findPage(changed, pageId);
+        json(response, 200, { frame: page.frames.find((frame) => frame.id === created) ?? null, ...pageView(current, changed, page) });
+        return;
+    }
+    else if (tail[0] === 'frames' && tail[1] !== undefined && method === 'PUT') {
+        changed = mutateCanvas(current, canvasId, (draft) => {
+            const page = findPage(draft, pageId);
+            const frame = page.frames.find((candidate) => candidate.id === tail[1]);
+            if (!frame)
+                throw new CanvasError(`no frame '${tail[1]}'`, 404);
+            applyFrameFields(frame, body);
+        });
+    }
+    else if (tail[0] === 'frames' && tail[1] !== undefined && method === 'DELETE') {
+        // ?contents=delete takes the attached nodes with it; otherwise they stay, unattached.
+        const withContents = new URL(request.url ?? '/', 'http://127.0.0.1').searchParams.get('contents') === 'delete';
+        changed = mutateCanvas(current, canvasId, (draft) => {
+            const page = findPage(draft, pageId);
+            const id = tail[1] ?? '';
+            if (!page.frames.some((frame) => frame.id === id))
+                throw new CanvasError(`no frame '${id}' on page '${page.id}'`, 404);
+            if (withContents)
+                removeNodes(page, page.nodes.filter((node) => node.frame === id).map((node) => node.id));
+            page.frames = page.frames.filter((frame) => frame.id !== id);
+            for (const node of page.nodes)
+                if (node.frame === id)
+                    delete node.frame;
+            for (const frame of page.frames)
+                if (frame.frame === id)
+                    delete frame.frame;
+            page.edges = page.edges.filter((edge) => edge.from !== `${FRAME_REF}${id}` && edge.to !== `${FRAME_REF}${id}`);
+            dropUnpointedAnnotations(page);
+        });
+    }
+    else if (tail[0] === 'layout' && method === 'PUT') {
+        changed = mutateCanvas(current, canvasId, (draft) => {
+            const page = findPage(draft, pageId);
+            const positions = typeof body['positions'] === 'object' && body['positions'] !== null ? body['positions'] : {};
+            for (const [id, at] of Object.entries(positions)) {
+                findNode(page, id);
+                if (at === null)
+                    delete page.layout[id];
+                else if (typeof at === 'object' && at !== null && typeof at['x'] === 'number' && typeof at['y'] === 'number') {
+                    page.layout[id] = { x: Math.round(at.x), y: Math.round(at.y) };
+                }
+            }
+        });
+    }
+    else if (tail[0] === 'layout' && method === 'DELETE') {
+        changed = mutateCanvas(current, canvasId, (draft) => {
+            findPage(draft, pageId).layout = {};
+        });
+    }
+    else if (tail[0] === 'comments' && tail.length === 1 && method === 'POST') {
+        const text = str(body['text']);
+        if (!text)
+            throw new HttpError(400, 'a comment needs text');
+        if (typeof body['x'] !== 'number' || typeof body['y'] !== 'number')
+            throw new HttpError(400, 'a comment needs a point { x, y }');
+        let created = '';
+        const author = commentAuthor(current);
+        changed = mutateCanvas(current, canvasId, (draft) => {
+            const page = findPage(draft, pageId);
+            const comment = { id: nextCommentId(page), x: Math.round(body['x']), y: Math.round(body['y']), messages: [{ ...signed(author), text, at: new Date().toISOString() }] };
+            const node = str(body['node']);
+            if (node) {
+                findNode(page, node);
+                comment.node = node;
+            }
+            page.comments.push(comment);
+            created = comment.id;
+        });
+        const page = findPage(changed, pageId);
+        json(response, 201, { comment: page.comments.find((comment) => comment.id === created) ?? null, ...pageView(current, changed, page) });
+        return;
+    }
+    else if (tail[0] === 'comments' && tail[1] !== undefined && tail[2] === 'replies' && method === 'POST') {
+        const text = str(body['text']);
+        if (!text)
+            throw new HttpError(400, 'a reply needs text');
+        const author = commentAuthor(current);
+        changed = mutateCanvas(current, canvasId, (draft) => {
+            const comment = findComment(findPage(draft, pageId), tail[1] ?? '');
+            comment.messages.push({ ...signed(author), text, at: new Date().toISOString() });
+            delete comment.resolved;
+        });
+    }
+    else if (tail[0] === 'comments' && tail[1] !== undefined && tail[2] === 'messages' && tail[3] !== undefined && (method === 'PUT' || method === 'DELETE')) {
+        // One message of a thread, rewritten or removed; a thread whose last
+        // message goes is gone itself.
+        const index = Number.parseInt(tail[3], 10);
+        changed = mutateCanvas(current, canvasId, (draft) => {
+            const page = findPage(draft, pageId);
+            const comment = findComment(page, tail[1] ?? '');
+            const message = comment.messages[index];
+            if (!Number.isInteger(index) || !message)
+                throw new CanvasError(`comment ${comment.id} has no message ${tail[3]}`, 404);
+            if (method === 'PUT') {
+                const text = str(body['text']);
+                if (!text)
+                    throw new HttpError(400, 'a message needs text');
+                message.text = text;
+                return;
+            }
+            comment.messages.splice(index, 1);
+            if (comment.messages.length === 0)
+                page.comments = page.comments.filter((candidate) => candidate.id !== comment.id);
+        });
+    }
+    else if (tail[0] === 'comments' && tail[1] !== undefined && tail.length === 2 && method === 'PUT') {
+        changed = mutateCanvas(current, canvasId, (draft) => {
+            const page = findPage(draft, pageId);
+            const comment = findComment(page, tail[1] ?? '');
+            if (body['resolved'] === true)
+                comment.resolved = true;
+            else if (body['resolved'] === false)
+                delete comment.resolved;
+            if (typeof body['x'] === 'number' && typeof body['y'] === 'number') {
+                comment.x = Math.round(body['x']);
+                comment.y = Math.round(body['y']);
+            }
+            if (body['node'] === null)
+                delete comment.node;
+            else if (typeof body['node'] === 'string' && body['node'] !== '') {
+                findNode(page, body['node']);
+                comment.node = body['node'];
+            }
+        });
+    }
+    else if (tail[0] === 'comments' && tail[1] !== undefined && tail.length === 2 && method === 'DELETE') {
+        changed = mutateCanvas(current, canvasId, (draft) => {
+            const page = findPage(draft, pageId);
+            findComment(page, tail[1] ?? '');
+            page.comments = page.comments.filter((comment) => comment.id !== tail[1]);
+        });
+    }
+    else {
+        throw new HttpError(404, 'not found');
+    }
+    json(response, 200, pageView(current, changed, findPage(changed, pageId)));
+}
+function findComment(page, id) {
+    const comment = page.comments.find((candidate) => candidate.id === id);
+    if (!comment)
+        throw new CanvasError(`no comment '${id}' on page '${page.id}'`, 404);
+    return comment;
 }
-function saveBlueprint(context, blueprint, body) {
-    const text = body['text'];
-    if (typeof text !== 'string') {
-        throw new HttpError(400, 'expected { text }');
+// Nodes gone from a page take their place, their edges, and the comments
+// pinned to them; an annotation left pointing at nothing goes too.
+function removeNodes(page, ids) {
+    const gone = new Set(ids);
+    page.nodes = page.nodes.filter((node) => !gone.has(node.id));
+    page.edges = page.edges.filter((edge) => !gone.has(edge.from) && !gone.has(edge.to));
+    page.comments = page.comments.filter((comment) => !comment.node || !gone.has(comment.node));
+    for (const id of gone)
+        delete page.layout[id];
+    dropUnpointedAnnotations(page);
+}
+function dropUnpointedAnnotations(page) {
+    const unpointed = page.nodes.filter((node) => node.annotation && !page.edges.some((edge) => edge.from === node.id)).map((node) => node.id);
+    if (unpointed.length > 0)
+        removeNodes(page, unpointed);
+}
+function applyFrameFields(frame, body) {
+    const title = str(body['title']);
+    if (title)
+        frame.title = title;
+    if (typeof body['x'] === 'number' && typeof body['y'] === 'number' && typeof body['w'] === 'number' && typeof body['h'] === 'number') {
+        frame.x = Math.round(body['x']);
+        frame.y = Math.round(body['y']);
+        frame.w = Math.max(40, Math.round(body['w']));
+        frame.h = Math.max(40, Math.round(body['h']));
+    }
+    else if (body['x'] === null) {
+        delete frame.x;
+        delete frame.y;
+        delete frame.w;
+        delete frame.h;
     }
-    writeFileSync(blueprint.path, text.replace(/\r\n?/g, '\n'), 'utf8');
-    const fresh = loadRoot({ root: context.root }, context.cwd);
-    const reloaded = fresh.blueprints.find((candidate) => candidate.rel === blueprint.rel);
-    return { path: blueprint.rel, findings: reloaded ? findingsFor(fresh, reloaded) : [] };
+    if (body['color'] === null || body['color'] === '')
+        delete frame.color;
+    else if (typeof body['color'] === 'string')
+        frame.color = body['color'];
+    if (body['frame'] === null || body['frame'] === '')
+        delete frame.frame;
+    else if (typeof body['frame'] === 'string' && body['frame'] !== frame.id)
+        frame.frame = body['frame'];
+    if (body['locked'] === true)
+        frame.locked = true;
+    else if (body['locked'] === false)
+        delete frame.locked;
+}
+function applyNodeFields(node, body) {
+    if (typeof body['blueprint'] === 'string' && body['blueprint'].trim() !== '') {
+        node.blueprint = body['blueprint'].trim();
+        delete node.sketch;
+        delete node.sticky;
+        delete node.text;
+        delete node.annotation;
+    }
+    if (typeof body['sticky'] === 'object' && body['sticky'] !== null) {
+        const given = body['sticky'];
+        const sticky = node.sticky ?? { text: '' };
+        if (typeof given['text'] === 'string')
+            sticky.text = given['text'];
+        if (given['color'] === null || given['color'] === '')
+            delete sticky.color;
+        else if (typeof given['color'] === 'string')
+            sticky.color = given['color'];
+        node.sticky = sticky;
+        delete node.blueprint;
+        delete node.sketch;
+        delete node.text;
+        delete node.annotation;
+    }
+    if (typeof body['text'] === 'object' && body['text'] !== null) {
+        const given = body['text'];
+        const item = node.text ?? { text: '' };
+        if (typeof given['text'] === 'string')
+            item.text = given['text'];
+        if (given['size'] === 'small' || given['size'] === 'medium' || given['size'] === 'large')
+            item.size = given['size'];
+        else if (given['size'] === null)
+            delete item.size;
+        if (typeof given['font'] === 'number' && given['font'] >= 8 && given['font'] <= 64)
+            item.font = Math.round(given['font']);
+        else if (given['font'] === null)
+            delete item.font;
+        node.text = item;
+        delete node.blueprint;
+        delete node.sketch;
+        delete node.sticky;
+        delete node.annotation;
+    }
+    if (typeof body['annotation'] === 'object' && body['annotation'] !== null) {
+        const given = body['annotation'];
+        const item = node.annotation ?? { text: '' };
+        if (typeof given['text'] === 'string')
+            item.text = given['text'];
+        if (given['color'] === null || given['color'] === '')
+            delete item.color;
+        else if (typeof given['color'] === 'string')
+            item.color = given['color'];
+        node.annotation = item;
+        delete node.blueprint;
+        delete node.sketch;
+        delete node.sticky;
+        delete node.text;
+    }
+    if (body['locked'] === true)
+        node.locked = true;
+    else if (body['locked'] === false)
+        delete node.locked;
+    if (typeof body['sketch'] === 'object' && body['sketch'] !== null) {
+        const given = body['sketch'];
+        const sketch = node.sketch ?? { label: '' };
+        if (typeof given['label'] === 'string')
+            sketch.label = given['label'];
+        for (const key of ['kind', 'status', 'note']) {
+            if (given[key] === null || given[key] === '')
+                delete sketch[key];
+            else if (typeof given[key] === 'string')
+                sketch[key] = given[key];
+        }
+        if (typeof given['properties'] === 'object' && given['properties'] !== null) {
+            const properties = { ...(sketch.properties ?? {}) };
+            for (const [key, value] of Object.entries(given['properties'])) {
+                if (value === null || value === '')
+                    delete properties[key];
+                else if (typeof value === 'string')
+                    properties[key] = value;
+            }
+            // the legacy pair is superseded by a value held by name
+            if (sketch.kind !== undefined && Object.keys(properties).length > 0)
+                delete sketch.kind;
+            if (sketch.status !== undefined && Object.keys(properties).length > 0)
+                delete sketch.status;
+            if (Object.keys(properties).length > 0)
+                sketch.properties = properties;
+            else
+                delete sketch.properties;
+        }
+        node.sketch = sketch;
+        delete node.blueprint;
+        delete node.sticky;
+        delete node.text;
+        delete node.annotation;
+    }
+    if (body['style'] === null) {
+        delete node.style;
+        delete node.styled;
+    }
+    else if (typeof body['style'] === 'object' && body['style'] !== null) {
+        const given = body['style'];
+        const style = { ...(node.style ?? {}) };
+        for (const key of ['shape', 'color', 'fill', 'fill_color', 'size']) {
+            if (given[key] === null || given[key] === '')
+                delete style[key];
+            else if (given[key] !== undefined)
+                style[key] = given[key];
+        }
+        const read = readStyle(style);
+        if (read)
+            node.style = read;
+        else
+            delete node.style;
+    }
+    if (body['styled'] === true)
+        node.styled = true;
+    else if (body['styled'] === false)
+        delete node.styled;
+    if (body['box'] === null)
+        delete node.box;
+    else if (typeof body['box'] === 'object' && body['box'] !== null) {
+        const box = readBox(body['box']);
+        if (box)
+            node.box = box;
+    }
+    if (body['frame'] === null || body['frame'] === '')
+        delete node.frame;
+    else if (typeof body['frame'] === 'string')
+        node.frame = body['frame'];
+    if (body['link'] === null)
+        delete node.link;
+    else if (typeof body['link'] === 'object' && body['link'] !== null) {
+        const given = body['link'];
+        const link = {};
+        if (typeof given['page'] === 'string' && given['page'] !== '')
+            link.page = given['page'];
+        if (typeof given['canvas'] === 'string' && given['canvas'] !== '')
+            link.canvas = given['canvas'];
+        if (Object.keys(link).length > 0)
+            node.link = link;
+        else
+            delete node.link;
+    }
+}
+// --- the page itself ----------------------------------------------------------
+const distDir = path.join(browserDir, 'dist');
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.ico': 'image/x-icon',
+    '.json': 'application/json; charset=utf-8',
+    '.woff2': 'font/woff2',
+    '.woff': 'font/woff',
+    '.map': 'application/json',
+};
+// A file from the built bundle, or the page for any route the app owns.
+function serveStatic(pathname, response) {
+    const wanted = path.normalize(decodeURIComponent(pathname)).replace(/^(\.\.[/\\])+/, '');
+    let file = path.join(distDir, wanted);
+    if (!file.startsWith(distDir) || !existsSync(file) || statSync(file).isDirectory()) {
+        file = path.join(distDir, 'index.html');
+    }
+    if (!existsSync(file)) {
+        throw new HttpError(500, `the browser page is missing at ${file}; in a checkout, build it with \`pnpm build\``);
+    }
+    const body = readFileSync(file);
+    const type = MIME[path.extname(file)] ?? 'application/octet-stream';
+    const cache = file.endsWith('index.html') ? 'no-cache' : 'public, max-age=31536000, immutable';
+    response.writeHead(200, { 'content-type': type, 'content-length': body.length, 'cache-control': cache });
+    response.end(body);
 }
 export function createServer(options) {
-    const page = path.join(browserDir, 'index.html');
-    const context = () => loadRoot({ root: options.root }, options.cwd);
+    const store = new Store({ root: options.root, cwd: options.cwd, watch: options.watch ?? true });
     const handle = async (request, response) => {
         const url = new URL(request.url ?? '/', 'http://127.0.0.1');
         const method = request.method ?? 'GET';
         const segments = url.pathname.split('/').filter((segment) => segment !== '');
-        if (segments.length === 0 || (segments[0] !== 'api' && !url.pathname.includes('.'))) {
-            if (!existsSync(page)) {
-                throw new HttpError(500, `the browser page is missing at ${page}`);
-            }
-            const html = readFileSync(page);
-            response.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'content-length': html.length });
-            response.end(html);
-            return;
-        }
         if (segments[0] !== 'api') {
-            throw new HttpError(404, 'not found');
+            serveStatic(url.pathname, response);
+            return;
         }
         const resource = segments[1] ?? '';
         const rest = segments.slice(2).join('/');
         if (resource === 'root' && method === 'GET') {
-            json(response, 200, rootSnapshot(context()));
+            json(response, 200, rootSnapshot(store.context(), store));
+            return;
+        }
+        if (resource === 'events' && method === 'GET') {
+            response.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+            response.write(': connected\n\n');
+            const off = store.onChange(() => response.write('data: {"type":"change"}\n\n'));
+            request.on('close', off);
+            return;
+        }
+        if (resource === 'search' && method === 'GET') {
+            const query = url.searchParams.get('q') ?? '';
+            const limit = Math.min(50, Math.max(1, Number(url.searchParams.get('limit') ?? 20) || 20));
+            json(response, 200, { query, hits: query.trim() === '' ? [] : store.search(query, limit) });
+            return;
+        }
+        if (resource === 'collections' && rest !== '' && method === 'GET') {
+            json(response, 200, collectionTable(store.context(), decodeURIComponent(rest)));
             return;
         }
         if (resource === 'blueprints' && rest === '' && method === 'GET') {
-            json(response, 200, context().blueprints.map(blueprintSummary));
+            json(response, 200, store.context().blueprints.map(blueprintSummary));
             return;
         }
         if (resource === 'blueprints' && rest === '' && method === 'POST') {
-            json(response, 201, createBlueprint(context(), await readBody(request)));
+            const created = createBlueprint(store.context(), await readBody(request));
+            store.invalidate();
+            json(response, 201, created);
+            return;
+        }
+        // GET /api/blueprints/<path>/history: the commits that touched the file, newest first; empty without git.
+        if (resource === 'blueprints' && rest.endsWith('/history') && method === 'GET') {
+            const current = store.context();
+            const blueprint = findByPath(current, rest.slice(0, -'/history'.length));
+            const git = gitInfo(current.root);
+            json(response, 200, { path: blueprint.rel, git: git.available, history: git.available ? gitLog(current.root, blueprint.rel) : [] });
+            return;
+        }
+        // POST /api/blueprints/<path>/diff { sha }: open the configured diff viewer on the file then and now.
+        if (resource === 'blueprints' && rest.endsWith('/diff') && method === 'POST') {
+            const current = store.context();
+            const blueprint = findByPath(current, rest.slice(0, -'/diff'.length));
+            const body = await readBody(request);
+            const sha = typeof body['sha'] === 'string' ? body['sha'].trim() : '';
+            if (!/^[0-9a-f]{4,40}$/i.test(sha))
+                throw new HttpError(400, 'expected { sha }');
+            const git = gitInfo(current.root);
+            if (!git.enabled)
+                throw new HttpError(400, 'git features are off for this root (Plugins → Git)');
+            if (!git.available)
+                throw new HttpError(400, 'this root is not in a git repository');
+            const viewer = readSettings(current.root).local.diff_viewer;
+            if (!viewer)
+                throw new HttpError(400, 'no diff viewer set; name one under Plugins (a command with {a} and {b})');
+            const then = gitShowFile(current.root, sha, blueprint.rel);
+            if (then === null)
+                throw new HttpError(404, `${sha.slice(0, 7)} has no ${blueprint.rel}`);
+            const temp = path.join(tmpdir(), `eidos-${sha.slice(0, 7)}-${path.basename(blueprint.path)}`);
+            writeFileSync(temp, then, 'utf8');
+            const quote = (file) => `"${file.replace(/"/g, '\\"')}"`;
+            const command = viewer.replace(/\{a\}/g, quote(temp)).replace(/\{b\}/g, quote(blueprint.path));
+            const child = spawn(command, { cwd: current.root, shell: true, detached: true, stdio: 'ignore' });
+            child.on('error', () => undefined);
+            child.unref();
+            json(response, 200, { launched: command, then: temp });
             return;
         }
         if (resource === 'blueprints' && rest !== '' && method === 'GET') {
-            const current = context();
+            const current = store.context();
             json(response, 200, blueprintDetail(current, findByPath(current, rest)));
             return;
         }
         if (resource === 'blueprints' && rest !== '' && method === 'PUT') {
-            const current = context();
-            json(response, 200, saveBlueprint(current, findByPath(current, rest), await readBody(request)));
+            const current = store.context();
+            const blueprint = findByPath(current, rest);
+            writeFileSync(blueprint.path, blueprintText(await readBody(request), readSettings(current.root).shared.on_save), 'utf8');
+            store.invalidate();
+            const fresh = store.context();
+            const reloaded = fresh.blueprints.find((candidate) => candidate.rel === blueprint.rel);
+            json(response, 200, { path: blueprint.rel, findings: reloaded ? findingsFor(fresh, reloaded) : [] });
+            return;
+        }
+        if (resource === 'blueprints' && rest !== '' && method === 'DELETE') {
+            const current = store.context();
+            const blueprint = findByPath(current, rest);
+            rmSync(blueprint.path);
+            store.invalidate();
+            json(response, 200, { deleted: blueprint.rel });
+            return;
+        }
+        // GET /api/files?dir=<root-relative>&ext=md: the folders and files under one folder of the root, for a picker.
+        if (resource === 'files' && method === 'GET') {
+            const current = store.context();
+            const wanted = (url.searchParams.get('dir') ?? '').replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
+            const dir = path.resolve(current.root, wanted);
+            if (dir !== current.root && !dir.startsWith(current.root + path.sep))
+                throw new HttpError(400, 'a folder inside the root');
+            if (!existsSync(dir) || !statSync(dir).isDirectory())
+                throw new HttpError(404, `no folder ${wanted || '/'}`);
+            const ext = url.searchParams.get('ext');
+            const entries = readdirSync(dir, { withFileTypes: true })
+                .filter((entry) => !entry.name.startsWith('.') && entry.name !== 'node_modules')
+                .filter((entry) => entry.isDirectory() || !ext || entry.name.toLowerCase().endsWith(`.${ext.toLowerCase()}`))
+                .map((entry) => ({ name: entry.name, path: rel(current.root, path.join(dir, entry.name)), kind: entry.isDirectory() ? 'dir' : 'file' }))
+                .sort((a, b) => (a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind === 'dir' ? -1 : 1));
+            json(response, 200, { dir: wanted, entries });
+            return;
+        }
+        // The CLI's own settings: two YAML files under .eidos/plugins/eidosmd/.
+        if (resource === 'settings' && method === 'GET') {
+            json(response, 200, readSettings(store.context().root));
+            return;
+        }
+        if (resource === 'settings' && method === 'PUT') {
+            const body = await readBody(request);
+            json(response, 200, writeSettings(store.context().root, { shared: body['shared'], local: body['local'] }));
+            return;
+        }
+        if (resource === 'git' && method === 'GET') {
+            json(response, 200, gitInfo(store.context().root));
+            return;
+        }
+        // Top-level documents: README.md and what ## Top-Level declares, read and written as text.
+        if (resource === 'docs' && rest !== '' && method === 'GET') {
+            json(response, 200, docView(store.context(), rest));
+            return;
+        }
+        // POST /api/docs { path, title }: a new markdown file at the root, for ## Top-Level to declare.
+        if (resource === 'docs' && rest === '' && method === 'POST') {
+            const current = store.context();
+            const body = await readBody(request);
+            const name = typeof body['path'] === 'string' ? body['path'].trim().replace(/\\/g, '/') : '';
+            if (!/^[^/]+\.md$/i.test(name) || name.startsWith('.'))
+                throw new HttpError(400, 'a top-level document is one <name>.md straight under the root');
+            const file = path.join(current.root, name);
+            if (existsSync(file))
+                throw new HttpError(409, `${name} already exists`);
+            const title = typeof body['title'] === 'string' && body['title'].trim() !== '' ? body['title'].trim() : path.basename(name, '.md');
+            writeFileSync(file, `# ${title}\n\n`, 'utf8');
+            store.invalidate();
+            json(response, 201, { path: name, title });
+            return;
+        }
+        if (resource === 'docs' && rest !== '' && method === 'PUT') {
+            const current = store.context();
+            const { file, rel: relative } = topLevelFile(current, rest);
+            const body = await readBody(request);
+            if (typeof body['text'] !== 'string')
+                throw new HttpError(400, 'expected { text }');
+            writeFileSync(file, body['text'].replace(/\r\n?/g, '\n'), 'utf8');
+            store.invalidate();
+            json(response, 200, docView(store.context(), relative));
+            return;
+        }
+        if (resource === 'versions' && method === 'GET') {
+            json(response, 200, { versions: readVersions(store.context().root), git_head: gitInfo(store.context().root).head });
+            return;
+        }
+        // POST /api/versions { version, commit?, tag? }: a snapshot of the root, only because someone asked.
+        if (resource === 'versions' && method === 'POST') {
+            const current = store.context();
+            const body = await readBody(request);
+            let recorded;
+            try {
+                recorded = recordVersion(current.root, { version: str(body['version']) ?? '', commit: str(body['commit']), tag: body['tag'] === true });
+            }
+            catch (cause) {
+                if (cause instanceof VersionError)
+                    throw new HttpError(400, cause.message);
+                throw cause;
+            }
+            store.invalidate();
+            json(response, 201, { ...recorded.version, tagged: recorded.tagged, versions: readVersions(current.root) });
+            return;
+        }
+        if (resource === 'framework' && method === 'GET') {
+            json(response, 200, frameworkView(store.context()));
+            return;
+        }
+        if (resource === 'framework' && method === 'PUT') {
+            const saved = saveFramework(store.context(), await readBody(request));
+            store.invalidate();
+            json(response, 200, { ...saved, ...frameworkView(store.context()) });
+            return;
+        }
+        // A finding's fix, by code: the one so far strips the frontmatter block a template must not carry.
+        if (resource === 'fix' && method === 'POST') {
+            const current = store.context();
+            const body = await readBody(request);
+            const code = body['code'];
+            const target = body['path'];
+            if (typeof code !== 'string' || typeof target !== 'string')
+                throw new HttpError(400, 'expected { code, path }');
+            if (code !== 'template-frontmatter')
+                throw new HttpError(400, `no fix for ${code}`);
+            const templatesDir = path.join(current.root, FRAMEWORK_DIR, 'templates');
+            const file = path.resolve(current.root, target);
+            if (!file.startsWith(templatesDir + path.sep) || !existsSync(file))
+                throw new HttpError(400, 'not a template of this root');
+            writeFileSync(file, stripFrontmatter(readFileSync(file, 'utf8')), 'utf8');
+            store.invalidate();
+            json(response, 200, { fixed: target });
+            return;
+        }
+        // The roles: one response contract per file under .eidos/roles/, the framework's own,
+        // read, written, and removed by name (its kebab-case file name).
+        if (resource === 'roles' && rest === '' && method === 'GET') {
+            const current = store.context();
+            json(response, 200, listRoles(current.root).map((role) => ({ name: role.name, title: role.title, summary: role.summary, path: rel(current.root, role.file) })));
+            return;
+        }
+        if (resource === 'roles' && rest !== '') {
+            const current = store.context();
+            const name = decodeURIComponent(rest);
+            if (!isRoleName(name))
+                throw new HttpError(400, 'a role name is kebab-case: letters, digits, and dashes');
+            const file = roleFile(current.root, name);
+            if (method === 'GET') {
+                json(response, 200, { name, path: rel(current.root, file), exists: existsSync(file), text: existsSync(file) ? readFileSync(file, 'utf8') : '' });
+                return;
+            }
+            if (method === 'PUT') {
+                const body = await readBody(request);
+                if (typeof body['text'] !== 'string')
+                    throw new HttpError(400, 'expected { text }');
+                mkdirSync(path.dirname(file), { recursive: true });
+                writeFileSync(file, body['text'].replace(/\r\n?/g, '\n'), 'utf8');
+                store.invalidate();
+                json(response, 200, { name, path: rel(current.root, file) });
+                return;
+            }
+            if (method === 'DELETE') {
+                if (!existsSync(file))
+                    throw new HttpError(404, `no role '${name}'`);
+                unlinkSync(file);
+                store.invalidate();
+                json(response, 200, { deleted: rel(current.root, file) });
+                return;
+            }
+        }
+        if (resource === 'templates' && rest === '' && method === 'GET') {
+            json(response, 200, templatesView(store.context()));
+            return;
+        }
+        if (resource === 'templates' && rest !== '' && method === 'GET') {
+            const current = store.context();
+            const file = templateFile(current, rest);
+            json(response, 200, { path: rel(path.join(current.root, FRAMEWORK_DIR), file), exists: existsSync(file), text: existsSync(file) ? readFileSync(file, 'utf8') : '' });
+            return;
+        }
+        if (resource === 'templates' && rest !== '' && method === 'PUT') {
+            const current = store.context();
+            const file = templateFile(current, rest);
+            const body = await readBody(request);
+            if (typeof body['text'] !== 'string')
+                throw new HttpError(400, 'expected { text }');
+            mkdirSync(path.dirname(file), { recursive: true });
+            writeFileSync(file, body['text'].replace(/\r\n?/g, '\n'), 'utf8');
+            store.invalidate();
+            json(response, 200, { path: rel(path.join(current.root, FRAMEWORK_DIR), file) });
+            return;
+        }
+        if (resource === 'me' && method === 'GET') {
+            const current = store.context();
+            const actor = readActor(current.root);
+            json(response, 200, { exists: actor.exists, text: actor.text, actor: actor.actor, path: rel(current.root, meFile(current.root)), roles: listRoles(current.root).map((role) => ({ name: role.name, title: role.title, summary: role.summary })) });
+            return;
+        }
+        // me.md as text, or built from its parts: a role (by name, else a custom
+        // one as written), a note, and the three calibration axes.
+        if (resource === 'me' && method === 'PUT') {
+            const current = store.context();
+            const body = await readBody(request);
+            if (typeof body['text'] === 'string') {
+                writeActor(current.root, body['text'].replace(/\r\n?/g, '\n'));
+            }
+            else {
+                const field = (name) => (typeof body[name] === 'string' && body[name].trim() !== '' ? body[name].trim() : null);
+                const wanted = field('role');
+                const role = wanted ? findRole(current.root, wanted) : null;
+                writeActor(current.root, renderActor(role, role ? null : wanted, { ownership: field('ownership'), experience: field('experience'), capacity: field('capacity') }, field('note')));
+            }
+            json(response, 200, { path: rel(current.root, meFile(current.root)) });
+            return;
+        }
+        // A file of the root opened in the external editor from Preferences, else the system's default app.
+        if (resource === 'open' && method === 'POST') {
+            const current = store.context();
+            const body = await readBody(request);
+            const target = typeof body['path'] === 'string' ? body['path'] : '';
+            const file = path.resolve(current.root, target);
+            if (target === '' || !file.startsWith(current.root + path.sep) || !existsSync(file) || !statSync(file).isFile())
+                throw new HttpError(400, 'not a file of this root');
+            const editor = readSettings(current.root).local.editor;
+            const quote = (given) => `"${given.replace(/"/g, '\\"')}"`;
+            const command = editor ? editor.replace(/\{file\}/g, quote(file)) : process.platform === 'darwin' ? `open ${quote(file)}` : process.platform === 'win32' ? `start "" ${quote(file)}` : `xdg-open ${quote(file)}`;
+            const child = spawn(command, { cwd: current.root, shell: true, detached: true, stdio: 'ignore' });
+            child.on('error', () => undefined);
+            child.unref();
+            json(response, 200, { launched: command });
+            return;
+        }
+        if (resource === 'canvas') {
+            await handleCanvas(store, method, segments.slice(2), request, response);
             return;
         }
         if (resource === 'check' && method === 'GET') {
-            json(response, 200, checkSnapshot(context()));
+            json(response, 200, checkSnapshot(store.context()));
             return;
         }
         if (resource === 'index' && method === 'POST') {
-            json(response, 200, indexRebuild(context()));
+            const result = indexRebuild(store.context());
+            store.invalidate();
+            json(response, 200, result);
             return;
         }
         if (resource === 'standard' && method === 'GET') {
@@ -236,9 +1418,9 @@ export function createServer(options) {
         }
         throw new HttpError(404, 'not found');
     };
-    return createHttpServer((request, response) => {
+    const server = createHttpServer((request, response) => {
         handle(request, response).catch((cause) => {
-            if (cause instanceof HttpError) {
+            if (cause instanceof HttpError || cause instanceof CanvasError) {
                 json(response, cause.status, { error: cause.message });
             }
             else if (cause instanceof CliError) {
@@ -249,6 +1431,8 @@ export function createServer(options) {
             }
         });
     });
+    server.on('close', () => store.close());
+    return server;
 }
 // The first free port at or after `preferred`, on the loopback interface.
 export function listen(server, preferred) {