eidosmd 0.1.0 → 0.3.0

package/dist/src/core/canvas.js

@@ -0,0 +1,732 @@
+// Canvas maps: the design tool. A canvas is one YAML file in this tool's own
+// folder, `.eidos/plugins/eidosmd/maps/`, a Figma-style file of pages; a node
+// on a page is either a sketch (a label and a kind, living only here) or a
+// blueprint, referenced by id, whose title, summary, and styled properties
+// are read from the file at render time. The canvas holds only what a
+// blueprint cannot: the flows between nodes, frames, and layout overrides.
+// A snapshot of the whole root is a version in the framework document.
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml, Document } from 'yaml';
+import { blueprintId, blueprintTitle, propertyString } from './blueprint.js';
+import { FRAMEWORK_DIR, PLUGINS_DIR, readValueStyle, TOOL_KEY } from './framework-model.js';
+import { kebab } from './naming.js';
+// Relative to `.eidos/`: the folder the standard reserves for this tool.
+export const MAPS_DIR = `${PLUGINS_DIR}/${TOOL_KEY}/maps`;
+// Where an edge meets a node: one of eight points on its border. Absent,
+// the browser picks the side that faces the other node.
+export const ANCHORS = ['top-left', 'top', 'top-right', 'right', 'bottom-right', 'bottom', 'bottom-left', 'left'];
+const isAnchor = (value) => typeof value === 'string' && ANCHORS.includes(value);
+// How an edge ends: nothing, an open arrowhead, a filled or open triangle,
+// an open circle, an open diamond, or a bar across the line. The end defaults
+// to an arrow, the start to nothing.
+export const EDGE_CAPS = ['none', 'arrow', 'triangle', 'triangle-open', 'circle', 'diamond', 'bar'];
+const isCap = (value) => typeof value === 'string' && EDGE_CAPS.includes(value);
+export const FRAME_REF = 'frame:';
+export const isFrameRef = (id) => id.startsWith(FRAME_REF);
+export class CanvasError extends Error {
+    status;
+    constructor(message, status = 400) {
+        super(message);
+        this.name = 'CanvasError';
+        this.status = status;
+    }
+}
+const isPlain = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const text = (value) => (value === undefined || value === null ? '' : String(value));
+const list = (value) => (Array.isArray(value) ? value : []);
+export function mapsDir(framework) {
+    return path.join(framework.root, FRAMEWORK_DIR, MAPS_DIR);
+}
+export function canvasFile(framework, id) {
+    return path.join(mapsDir(framework), `${id}.yaml`);
+}
+function readNode(value, where, problems) {
+    if (!isPlain(value) || text(value['id']) === '') {
+        problems.push(`${where}: a node needs an id`);
+        return null;
+    }
+    const node = { id: text(value['id']) };
+    if (text(value['blueprint']) !== '') {
+        node.blueprint = text(value['blueprint']);
+    }
+    else if (isPlain(value['sketch'])) {
+        const sketch = value['sketch'];
+        node.sketch = { label: text(sketch['label']) };
+        if (text(sketch['kind']) !== '')
+            node.sketch.kind = text(sketch['kind']);
+        if (text(sketch['status']) !== '')
+            node.sketch.status = text(sketch['status']);
+        if (text(sketch['note']) !== '')
+            node.sketch.note = text(sketch['note']);
+        if (isPlain(sketch['properties'])) {
+            const properties = {};
+            for (const [key, held] of Object.entries(sketch['properties']))
+                if (text(held) !== '')
+                    properties[key] = text(held);
+            if (Object.keys(properties).length > 0)
+                node.sketch.properties = properties;
+        }
+    }
+    else if (isPlain(value['sticky'])) {
+        const sticky = value['sticky'];
+        node.sticky = { text: text(sticky['text']) };
+        if (text(sticky['color']) !== '')
+            node.sticky.color = text(sticky['color']);
+    }
+    else if (isPlain(value['text'])) {
+        const given = value['text'];
+        node.text = { text: text(given['text']) };
+        if (given['size'] === 'small' || given['size'] === 'medium' || given['size'] === 'large')
+            node.text.size = given['size'];
+        if (typeof given['font'] === 'number' && given['font'] >= 8 && given['font'] <= 64)
+            node.text.font = Math.round(given['font']);
+    }
+    else if (isPlain(value['annotation'])) {
+        const given = value['annotation'];
+        node.annotation = { text: text(given['text']) };
+        if (text(given['color']) !== '')
+            node.annotation.color = text(given['color']);
+    }
+    else {
+        problems.push(`${where} (${node.id}): a node is a blueprint id, a sketch, a sticky, a text, or an annotation`);
+        return null;
+    }
+    if (text(value['frame']) !== '')
+        node.frame = text(value['frame']);
+    if (value['locked'] === true)
+        node.locked = true;
+    const style = readStyle(value['style']);
+    if (style)
+        node.style = style;
+    if (value['styled'] === true)
+        node.styled = true;
+    const box = readBox(value['box']);
+    if (box)
+        node.box = box;
+    if (isPlain(value['link'])) {
+        const link = value['link'];
+        node.link = {};
+        if (text(link['page']) !== '')
+            node.link.page = text(link['page']);
+        if (text(link['canvas']) !== '')
+            node.link.canvas = text(link['canvas']);
+    }
+    return node;
+}
+export function readBox(value) {
+    if (!isPlain(value) || typeof value['w'] !== 'number' || typeof value['h'] !== 'number')
+        return null;
+    return { w: Math.max(40, Math.round(value['w'])), h: Math.max(24, Math.round(value['h'])) };
+}
+export const readStyle = readValueStyle;
+function readPage(value, index, problems) {
+    const where = `pages[${index}]`;
+    if (!isPlain(value) || text(value['id']) === '') {
+        problems.push(`${where}: a page needs an id`);
+        return null;
+    }
+    const page = { id: text(value['id']), title: text(value['title']) || text(value['id']), frames: [], nodes: [], edges: [], layout: {}, comments: [] };
+    for (const frame of list(value['frames'])) {
+        if (isPlain(frame) && text(frame['id']) !== '') {
+            const item = { id: text(frame['id']), title: text(frame['title']) || text(frame['id']) };
+            if (typeof frame['x'] === 'number' && typeof frame['y'] === 'number' && typeof frame['w'] === 'number' && typeof frame['h'] === 'number') {
+                item.x = frame['x'];
+                item.y = frame['y'];
+                item.w = frame['w'];
+                item.h = frame['h'];
+            }
+            if (text(frame['color']) !== '')
+                item.color = text(frame['color']);
+            if (frame['locked'] === true)
+                item.locked = true;
+            if (text(frame['frame']) !== '' && text(frame['frame']) !== item.id)
+                item.frame = text(frame['frame']);
+            page.frames.push(item);
+        }
+    }
+    for (const comment of list(value['comments'])) {
+        if (!isPlain(comment) || text(comment['id']) === '' || typeof comment['x'] !== 'number' || typeof comment['y'] !== 'number')
+            continue;
+        const item = { id: text(comment['id']), x: comment['x'], y: comment['y'], messages: [] };
+        if (text(comment['node']) !== '')
+            item.node = text(comment['node']);
+        if (comment['resolved'] === true)
+            item.resolved = true;
+        for (const message of list(comment['messages'])) {
+            if (isPlain(message) && text(message['text']) !== '') {
+                const entry = { author: text(message['author']) || 'someone', text: text(message['text']), at: text(message['at']) };
+                if (text(message['role']) !== '')
+                    entry.role = text(message['role']);
+                if (text(message['user']) !== '')
+                    entry.user = text(message['user']);
+                item.messages.push(entry);
+            }
+        }
+        page.comments.push(item);
+    }
+    list(value['nodes']).forEach((node, position) => {
+        const read = readNode(node, `${where} (${page.id}) nodes[${position}]`, problems);
+        if (read)
+            page.nodes.push(read);
+    });
+    for (const edge of list(value['edges'])) {
+        if (isPlain(edge) && text(edge['from']) !== '' && text(edge['to']) !== '') {
+            const item = { from: text(edge['from']), to: text(edge['to']) };
+            if (text(edge['label']) !== '')
+                item.label = text(edge['label']);
+            if (typeof edge['label_at'] === 'number' && edge['label_at'] >= 0 && edge['label_at'] <= 1)
+                item.label_at = edge['label_at'];
+            if (typeof edge['bend'] === 'number')
+                item.bend = edge['bend'];
+            if (isAnchor(edge['from_anchor']))
+                item.from_anchor = edge['from_anchor'];
+            if (isAnchor(edge['to_anchor']))
+                item.to_anchor = edge['to_anchor'];
+            if (text(edge['color']) !== '')
+                item.color = text(edge['color']);
+            if (edge['style'] === 'dashed')
+                item.style = 'dashed';
+            if (isCap(edge['start']))
+                item.start = edge['start'];
+            if (isCap(edge['end']))
+                item.end = edge['end'];
+            page.edges.push(item);
+        }
+    }
+    if (isPlain(value['layout'])) {
+        for (const [id, position] of Object.entries(value['layout'])) {
+            if (isPlain(position) && typeof position['x'] === 'number' && typeof position['y'] === 'number') {
+                page.layout[id] = { x: position['x'], y: position['y'] };
+            }
+        }
+    }
+    return page;
+}
+export function parseCanvas(source, id, file) {
+    const problems = [];
+    let value;
+    try {
+        value = parseYaml(source);
+    }
+    catch (cause) {
+        problems.push(`not valid YAML: ${cause instanceof Error ? (cause.message.split('\n')[0] ?? '') : String(cause)}`);
+    }
+    const document = isPlain(value) ? value : {};
+    const pages = list(document['pages'])
+        .map((page, index) => readPage(page, index, problems))
+        .filter((page) => page !== null);
+    if (pages.length === 0 && problems.length === 0) {
+        problems.push('a canvas needs at least one page');
+    }
+    return { id, file, title: text(document['title']) || id, pages, problems };
+}
+export function listCanvases(framework) {
+    const dir = mapsDir(framework);
+    if (!existsSync(dir)) {
+        return [];
+    }
+    return readdirSync(dir)
+        .filter((entry) => /\.ya?ml$/i.test(entry))
+        .sort()
+        .map((entry) => loadCanvas(framework, entry.replace(/\.ya?ml$/i, '')));
+}
+export function loadCanvas(framework, id) {
+    const file = canvasFile(framework, id);
+    if (!existsSync(file)) {
+        throw new CanvasError(`no canvas '${id}' under .eidos/${MAPS_DIR}/`, 404);
+    }
+    return parseCanvas(readFileSync(file, 'utf8'), id, file);
+}
+export function saveCanvas(canvas) {
+    const document = { title: canvas.title };
+    document['pages'] = canvas.pages.map((page) => {
+        const item = { id: page.id, title: page.title };
+        if (page.frames.length > 0) {
+            item['frames'] = page.frames.map((frame) => {
+                const out = { id: frame.id, title: frame.title };
+                if (frame.x !== undefined && frame.y !== undefined && frame.w !== undefined && frame.h !== undefined) {
+                    out['x'] = frame.x;
+                    out['y'] = frame.y;
+                    out['w'] = frame.w;
+                    out['h'] = frame.h;
+                }
+                if (frame.color)
+                    out['color'] = frame.color;
+                if (frame.locked)
+                    out['locked'] = true;
+                if (frame.frame)
+                    out['frame'] = frame.frame;
+                return out;
+            });
+        }
+        item['nodes'] = page.nodes.map((node) => {
+            const out = { id: node.id };
+            if (node.blueprint)
+                out['blueprint'] = node.blueprint;
+            if (node.sketch)
+                out['sketch'] = node.sketch;
+            if (node.sticky)
+                out['sticky'] = node.sticky;
+            if (node.text)
+                out['text'] = node.text;
+            if (node.annotation)
+                out['annotation'] = node.annotation;
+            if (node.frame)
+                out['frame'] = node.frame;
+            if (node.link)
+                out['link'] = node.link;
+            if (node.locked)
+                out['locked'] = true;
+            if (node.style)
+                out['style'] = node.style;
+            if (node.styled)
+                out['styled'] = true;
+            if (node.box)
+                out['box'] = node.box;
+            return out;
+        });
+        item['edges'] = page.edges;
+        if (Object.keys(page.layout).length > 0)
+            item['layout'] = page.layout;
+        if (page.comments.length > 0) {
+            item['comments'] = page.comments.map((comment) => {
+                const out = { id: comment.id, x: comment.x, y: comment.y };
+                if (comment.node)
+                    out['node'] = comment.node;
+                if (comment.resolved)
+                    out['resolved'] = true;
+                out['messages'] = comment.messages;
+                return out;
+            });
+        }
+        return item;
+    });
+    const yamlDocument = new Document(document);
+    yamlDocument.commentBefore = ' A canvas map, authored in `eidos browser`. Nodes are sketches, stickies, or blueprints; the canvas holds the flows, frames, layout, and comment threads. Documented by `eidos canvas --help`.';
+    mkdirSync(path.dirname(canvas.file), { recursive: true });
+    writeFileSync(canvas.file, yamlDocument.toString({ lineWidth: 0 }), 'utf8');
+}
+export function createCanvas(framework, title) {
+    const id = kebab(title);
+    if (id === '') {
+        throw new CanvasError('a canvas needs a title');
+    }
+    const file = canvasFile(framework, id);
+    if (existsSync(file)) {
+        throw new CanvasError(`canvas '${id}' already exists`, 409);
+    }
+    const canvas = { id, file, title, pages: [{ id: 'overview', title: 'Overview', frames: [], nodes: [], edges: [], layout: {}, comments: [] }], problems: [] };
+    saveCanvas(canvas);
+    return canvas;
+}
+export function findPage(canvas, pageId) {
+    const page = canvas.pages.find((candidate) => candidate.id === pageId);
+    if (!page) {
+        throw new CanvasError(`no page '${pageId}' in canvas '${canvas.id}'`, 404);
+    }
+    return page;
+}
+export function findNode(page, nodeId) {
+    const node = page.nodes.find((candidate) => candidate.id === nodeId);
+    if (!node) {
+        throw new CanvasError(`no node '${nodeId}' on page '${page.id}'`, 404);
+    }
+    return node;
+}
+// What an edge may end on: a node, or a frame's border as `frame:<id>`.
+export function findEndpoint(page, id) {
+    if (isFrameRef(id)) {
+        if (!page.frames.some((frame) => frame.id === id.slice(FRAME_REF.length)))
+            throw new CanvasError(`no frame '${id.slice(FRAME_REF.length)}' on page '${page.id}'`, 404);
+        return;
+    }
+    findNode(page, id);
+}
+export function nextCommentId(page) {
+    let n = page.comments.length + 1;
+    while (page.comments.some((comment) => comment.id === `c${n}`))
+        n += 1;
+    return `c${n}`;
+}
+// A page's contents replaced whole, as the browser's undo does: what is
+// given is read the way a file is, so a bad shape is a problem, never a
+// crash, and ids are kept.
+export function replacePageContents(page, given) {
+    const problems = [];
+    const read = readPage({ id: page.id, title: page.title, ...(isPlain(given) ? given : {}) }, 0, problems);
+    if (!read || problems.length > 0) {
+        throw new CanvasError(`the page could not be read: ${problems.join('; ') || 'not a page'}`);
+    }
+    page.frames = read.frames;
+    page.nodes = read.nodes;
+    page.edges = read.edges;
+    page.layout = read.layout;
+    page.comments = read.comments;
+    return problems;
+}
+export function nextNodeId(page) {
+    let n = page.nodes.length + 1;
+    while (page.nodes.some((node) => node.id === `n${n}`))
+        n += 1;
+    return `n${n}`;
+}
+// --- rendering ---------------------------------------------------------------
+export const STICKY_SIZE = 176;
+export const NODE_WIDTH = 220;
+// The properties the framework marks for the canvas, in Schema order.
+export function canvasProperties(framework) {
+    return framework.schema.custom.filter((property) => property.canvas !== undefined);
+}
+// The style a property gives one value, matched without regard to case.
+export function valueStyle(hint, value) {
+    const key = Object.keys(hint.styles ?? {}).find((candidate) => candidate.toLowerCase() === value.toLowerCase());
+    return key ? (hint.styles?.[key] ?? null) : null;
+}
+// The default look a node's property values give it. Properties are read in
+// schema order and, field by field, the top-most that sets it for the value
+// wins, so the order of the custom block is the precedence.
+export function styleFor(framework, values) {
+    const found = {};
+    const shown = [];
+    for (const property of canvasProperties(framework)) {
+        const value = values[property.name];
+        if (value === undefined || value === '')
+            continue;
+        const style = valueStyle(property.canvas, value);
+        if (style) {
+            if (found.shape === undefined && style.shape)
+                found.shape = style.shape;
+            if (found.color === undefined && style.color)
+                found.color = style.color;
+            if (found.fill === undefined && style.fill)
+                found.fill = style.fill;
+            if (found.fill_color === undefined && style.fill_color)
+                found.fill_color = style.fill_color;
+            if (found.size === undefined && style.size)
+                found.size = style.size;
+        }
+        if (property.canvas.show)
+            shown.push({ property: property.name, value });
+    }
+    return { ...withLegacyShape(found), shown };
+}
+// Shapes that were really colors in the first canvases (dark, accent, text)
+// read as a box with the fill they meant.
+function withLegacyShape(style) {
+    const legacy = { dark: { fill: 'solid', fill_color: '#191b1f' }, accent: { fill: 'tint' }, text: { fill: 'none' } };
+    const meant = style.shape ? legacy[style.shape] : undefined;
+    return {
+        shape: meant ? 'box' : (style.shape ?? 'box'),
+        color: style.color ?? null,
+        fill: style.fill ?? meant?.fill ?? 'solid',
+        fill_color: style.fill_color ?? meant?.fill_color ?? null,
+        size: style.size ?? 'medium',
+    };
+}
+// The override laid over the default: each field the node sets itself, the
+// rest from the properties.
+function drawn(node, defaults) {
+    const style = node.style ?? {};
+    const own = withLegacyShape({
+        shape: style.shape ?? defaults.shape,
+        ...(style.color ?? defaults.color ? { color: style.color ?? defaults.color ?? '' } : {}),
+        fill: style.fill ?? defaults.fill,
+        ...(style.fill_color ?? defaults.fill_color ? { fill_color: style.fill_color ?? defaults.fill_color ?? '' } : {}),
+        size: style.size ?? defaults.size,
+    });
+    return { shape: own.shape, color: own.color, fill: own.fill, fill_color: own.fill_color, size: own.size };
+}
+// A simple layered layout from the edges: a node's column is the longest path
+// from a source to it, its row its order within the column. Frames are drawn
+// around their members by the page. Overrides win.
+export function computeLayout(page) {
+    const ids = page.nodes.map((node) => node.id);
+    const incoming = new Map(ids.map((id) => [id, []]));
+    const outgoing = new Map(ids.map((id) => [id, []]));
+    for (const edge of page.edges) {
+        if (incoming.has(edge.to) && outgoing.has(edge.from) && edge.from !== edge.to) {
+            incoming.get(edge.to)?.push(edge.from);
+            outgoing.get(edge.from)?.push(edge.to);
+        }
+    }
+    // Back edges (an edge into a node still on the DFS stack) close cycles;
+    // they are drawn but do not count for columns.
+    const back = new Set();
+    const state = new Map();
+    const visit = (id) => {
+        state.set(id, 1);
+        for (const next of outgoing.get(id) ?? []) {
+            const seen = state.get(next);
+            if (seen === 1)
+                back.add(`${id}|${next}`);
+            else if (seen === undefined)
+                visit(next);
+        }
+        state.set(id, 2);
+    };
+    for (const id of ids) {
+        if (!state.has(id))
+            visit(id);
+    }
+    const column = new Map(ids.map((id) => [id, 0]));
+    const remaining = new Map(ids.map((id) => [id, (incoming.get(id) ?? []).filter((parent) => !back.has(`${parent}|${id}`)).length]));
+    const queue = ids.filter((id) => remaining.get(id) === 0);
+    while (queue.length > 0) {
+        const id = queue.shift();
+        for (const next of outgoing.get(id) ?? []) {
+            if (back.has(`${id}|${next}`))
+                continue;
+            column.set(next, Math.max(column.get(next) ?? 0, (column.get(id) ?? 0) + 1));
+            remaining.set(next, (remaining.get(next) ?? 1) - 1);
+            if (remaining.get(next) === 0)
+                queue.push(next);
+        }
+    }
+    // Within a column, a frame's members sit together so frames stay contiguous.
+    const frameOf = new Map(page.nodes.map((node) => [node.id, node.frame ?? '']));
+    const ordered = [...ids].sort((a, b) => (column.get(a) ?? 0) - (column.get(b) ?? 0) || (frameOf.get(a) ?? '').localeCompare(frameOf.get(b) ?? '') || ids.indexOf(a) - ids.indexOf(b));
+    const rows = new Map();
+    const out = {};
+    for (const id of ordered) {
+        const col = column.get(id) ?? 0;
+        const row = rows.get(col) ?? 0;
+        rows.set(col, row + 1);
+        out[id] = { x: 40 + col * 270, y: 60 + row * 140 };
+    }
+    return out;
+}
+export function renderPage(framework, blueprints, page) {
+    const computed = computeLayout(page);
+    return page.nodes.map((node) => {
+        const override = page.layout[node.id];
+        const position = override ? { ...override, computed: false } : { ...(computed[node.id] ?? { x: 40, y: 40 }), computed: true };
+        if (node.blueprint) {
+            const blueprint = blueprints.find((candidate) => blueprintId(candidate) === node.blueprint) ?? null;
+            const values = {};
+            if (blueprint) {
+                for (const property of canvasProperties(framework)) {
+                    const value = propertyString(blueprint, property.name);
+                    if (value !== null)
+                        values[property.name] = value;
+                }
+            }
+            const style = styleFor(framework, values);
+            return {
+                id: node.id,
+                kind: 'blueprint',
+                locked: node.locked === true,
+                label: blueprint ? blueprintTitle(blueprint) : node.blueprint,
+                summary: blueprint ? propertyString(blueprint, 'summary') : null,
+                blueprint: node.blueprint,
+                path: blueprint?.rel ?? null,
+                frame: node.frame ?? null,
+                link: node.link ?? null,
+                values,
+                style: drawn(node, style),
+                font: null,
+                box: node.box ?? null,
+                defaults: { shape: style.shape, color: style.color, fill: style.fill, fill_color: style.fill_color, size: style.size },
+                override: node.style ?? null,
+                styled: node.styled === true,
+                shown: style.shown,
+                position,
+                missing: blueprint === null,
+            };
+        }
+        if (node.text) {
+            return {
+                id: node.id,
+                kind: 'text',
+                locked: node.locked === true,
+                label: node.text.text,
+                summary: null,
+                blueprint: null,
+                path: null,
+                frame: node.frame ?? null,
+                link: node.link ?? null,
+                values: {},
+                style: { shape: 'text', color: node.style?.color ?? null, fill: 'none', fill_color: null, size: node.text.size ?? 'medium' },
+                font: node.text.font ?? null,
+                box: node.box ?? null,
+                defaults: { shape: 'text', color: null, fill: 'solid', fill_color: null, size: 'medium' },
+                override: node.style ?? null,
+                styled: node.styled === true,
+                shown: [],
+                position,
+                missing: false,
+            };
+        }
+        if (node.annotation) {
+            return {
+                id: node.id,
+                kind: 'annotation',
+                locked: node.locked === true,
+                label: node.annotation.text,
+                summary: null,
+                blueprint: null,
+                path: null,
+                frame: node.frame ?? null,
+                link: node.link ?? null,
+                values: {},
+                style: { shape: 'annotation', color: node.annotation.color ?? null, fill: 'solid', fill_color: null, size: node.style?.size ?? 'medium' },
+                font: null,
+                box: node.box ?? null,
+                defaults: { shape: 'annotation', color: null, fill: 'solid', fill_color: null, size: 'medium' },
+                override: node.style ?? null,
+                styled: node.styled === true,
+                shown: [],
+                position,
+                missing: false,
+            };
+        }
+        if (node.sticky) {
+            return {
+                id: node.id,
+                kind: 'sticky',
+                locked: node.locked === true,
+                label: node.sticky.text,
+                summary: null,
+                blueprint: null,
+                path: null,
+                frame: node.frame ?? null,
+                link: node.link ?? null,
+                values: {},
+                style: { shape: 'sticky', color: node.sticky.color ?? null, fill: 'solid', fill_color: null, size: node.style?.size ?? 'medium' },
+                font: null,
+                box: node.box ?? null,
+                defaults: { shape: 'sticky', color: null, fill: 'solid', fill_color: null, size: 'medium' },
+                override: node.style ?? null,
+                styled: node.styled === true,
+                shown: [],
+                position,
+                missing: false,
+            };
+        }
+        const sketch = node.sketch ?? { label: node.id };
+        const values = sketchValues(framework, sketch);
+        const style = styleFor(framework, values);
+        return {
+            id: node.id,
+            kind: 'sketch',
+            locked: node.locked === true,
+            label: sketch.label,
+            summary: sketch.note ?? null,
+            blueprint: null,
+            path: null,
+            frame: node.frame ?? null,
+            link: node.link ?? null,
+            values,
+            style: drawn(node, style),
+            font: null,
+            box: node.box ?? null,
+            defaults: { shape: style.shape, color: style.color, fill: style.fill, fill_color: style.fill_color, size: style.size },
+            override: node.style ?? null,
+            styled: node.styled === true,
+            shown: style.shown,
+            position,
+            missing: false,
+        };
+    });
+}
+// A sketch's property values: the ones it holds by name, with the legacy
+// `kind` and `status` read as the first shape- and color-styled properties.
+export function sketchValues(framework, sketch) {
+    const values = {};
+    const styles = (property) => Object.values(property.canvas.styles ?? {});
+    const kindProperty = canvasProperties(framework).find((property) => styles(property).some((style) => style.shape));
+    const statusProperty = canvasProperties(framework).find((property) => styles(property).some((style) => style.color));
+    if (sketch.kind && kindProperty)
+        values[kindProperty.name] = sketch.kind;
+    if (sketch.status && statusProperty)
+        values[statusProperty.name] = sketch.status;
+    for (const [key, value] of Object.entries(sketch.properties ?? {}))
+        values[key] = value;
+    return values;
+}
+export function renderComments(page, nodes) {
+    return page.comments.map((comment) => {
+        const anchor = comment.node ? nodes.find((node) => node.id === comment.node) : undefined;
+        return { ...comment, at: anchor ? { x: anchor.position.x + comment.x, y: anchor.position.y + comment.y } : { x: comment.x, y: comment.y } };
+    });
+}
+// A frame's rectangle: the one it was drawn with, else a box around its
+// members, the way frames were before they could be drawn.
+export function frameRect(frame, nodes) {
+    if (frame.x !== undefined && frame.y !== undefined && frame.w !== undefined && frame.h !== undefined) {
+        return { x: frame.x, y: frame.y, w: frame.w, h: frame.h };
+    }
+    const members = nodes.filter((node) => node.frame === frame.id);
+    if (members.length === 0)
+        return null;
+    const size = (node) => (node.kind === 'sticky' ? { w: STICKY_SIZE, h: STICKY_SIZE } : node.kind === 'text' ? { w: 200, h: 40 } : { w: NODE_WIDTH, h: 112 });
+    const minX = Math.min(...members.map((node) => node.position.x)) - 20;
+    const minY = Math.min(...members.map((node) => node.position.y)) - 40;
+    const maxX = Math.max(...members.map((node) => node.position.x + size(node).w)) + 20;
+    const maxY = Math.max(...members.map((node) => node.position.y + size(node).h)) + 20;
+    return { x: minX, y: minY, w: maxX - minX, h: maxY - minY };
+}
+// --- export -------------------------------------------------------------------
+// JSON Canvas 1.0 (Obsidian): each frame a group, each node a text card, each
+// edge a directed edge. Positions come from the same layout the page shows.
+export function toJsonCanvas(framework, blueprints, page) {
+    const rendered = renderPage(framework, blueprints, page);
+    const W = 220;
+    const H = 80;
+    const nodes = [];
+    for (const node of rendered) {
+        const lines = [node.label, node.summary ?? ''].filter((line) => line !== '');
+        const sticky = node.kind === 'sticky';
+        const item = { id: node.id, type: node.path ? 'file' : 'text', x: node.position.x, y: node.position.y, width: sticky ? STICKY_SIZE : W, height: sticky ? STICKY_SIZE : node.kind === 'text' ? 40 : H };
+        if (node.path) {
+            item['file'] = node.path;
+        }
+        else {
+            item['text'] = lines.join('\n');
+        }
+        if (node.style.color)
+            item['color'] = node.style.color;
+        nodes.push(item);
+    }
+    for (const frame of page.frames) {
+        const rect = frameRect(frame, rendered);
+        if (!rect)
+            continue;
+        const group = { id: `frame-${frame.id}`, type: 'group', label: frame.title, x: rect.x, y: rect.y, width: rect.w, height: rect.h };
+        if (frame.color)
+            group['color'] = frame.color;
+        nodes.push(group);
+    }
+    const side = (anchor, fallback) => (anchor ? (anchor.includes('top') ? 'top' : anchor.includes('bottom') ? 'bottom' : anchor) : fallback);
+    const endpoint = (id) => (isFrameRef(id) ? `frame-${id.slice(FRAME_REF.length)}` : id);
+    const edges = page.edges.map((edge, index) => {
+        const item = { id: `e${index + 1}`, fromNode: endpoint(edge.from), fromSide: side(edge.from_anchor, 'right'), toNode: endpoint(edge.to), toSide: side(edge.to_anchor, 'left'), toEnd: edge.end === 'none' ? 'none' : 'arrow' };
+        if (edge.label)
+            item['label'] = edge.label;
+        return item;
+    });
+    return { nodes, edges };
+}
+// --- the software seed's default palette, written by init --------------------
+// The legend the owner already uses, as values of the seed's own properties.
+const shaped = (shape) => ({ shape });
+const colored = (color) => ({ color });
+export const DEFAULT_CANVAS_HINTS = {
+    type: {
+        show: true,
+        styles: { page: shaped('pill'), feature: shaped('box'), capability: shaped('box'), integration: shaped('box'), background: shaped('box'), module: shaped('box'), decision: shaped('parallelogram'), note: shaped('box') },
+    },
+    status: {
+        show: true,
+        // the browser's standard colors (PALETTE in the canvas model), so a default and a hand-picked swatch never clash
+        styles: { Draft: colored('#8b9099'), Intake: colored('#d3a53c'), 'In Progress': colored('#5f80cf'), Done: colored('#7fae6c'), Archived: colored('#8b9099'), Deprecated: colored('#cf7b8f'), 'needs-clarification': colored('#5f80cf'), maybe: colored('#e08a63'), visionary: colored('#4aa39f') },
+    },
+};
+export function applyDefaultCanvasHints(properties) {
+    for (const property of properties) {
+        const hint = DEFAULT_CANVAS_HINTS[property.name];
+        if (hint && !property.canvas) {
+            property.canvas = hint;
+        }
+    }
+}