@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/archimateExchangeFormat.js

@@ -0,0 +1,546 @@
+import {
+    parseXML, ARCHI_FOLDERS, archiFolderOf, archiVisualBoxes, archiBendpointLocations, relativizeArchiBendpoints,
+    parseArchiFont, archiFontString, typedArrayToProperties, toPascalType, escapeXml, escapeAttr,
+} from './archimateArchiFormat.js';
+import { ARCHI_TYPE_FEATURE } from './archimateArchiTypes.js';
+
+/**
+ * The Open Group ArchiMate Model Exchange File Format (3.1): the standard
+ * route between ArchiMate tools (Archi, Sparx EA, BiZZdesign, ...).
+ *
+ * Both directions go through the shapes the Archi format uses, so everything
+ * downstream is shared: `parseExchangeModel` gives what `parseArchiModel`
+ * gives (hand it to `toArchimateModel`), and `toExchangeXML` takes what
+ * `toArchiXML` takes (an editor's model and its views as `fromArchimateView`
+ * trees). The differences are the format's own:
+ *
+ * - A node's x/y and a bendpoint are on the view (Archi: relative to the parent
+ *   box, and offsets from the line's ends).
+ * - Colours are r/g/b with a 0-100 alpha; a font is a name, size and style.
+ * - Properties name a property definition.
+ * - Folders are organizations (an item per folder, holding item refs).
+ * - Only ArchiMate diagrams: the format has no canvases or sketches, which are
+ *   not written. A box with no ArchiMate meaning (note, picture, view
+ *   reference) is a Label; a group is a Container.
+ * - An element type Archi lacks is written as its nearest ArchiMate 3.2 type
+ *   with its own kept in the property EXCHANGE_TYPE_PROPERTY, which import reads back.
+ */
+
+export const EXCHANGE_NAMESPACE = 'http://www.opengroup.org/xsd/archimate/3.0/';
+const EXCHANGE_SCHEMA = 'http://www.opengroup.org/xsd/archimate/3.1/archimate3_Diagram.xsd';
+const XSI_NAMESPACE = 'http://www.w3.org/2001/XMLSchema-instance';
+
+/** The property that keeps an element's own type when it is written as another (as Archi's feature does). */
+export const EXCHANGE_TYPE_PROPERTY = ARCHI_TYPE_FEATURE;
+
+/** The format's viewpoint names; Archi's id for each is its name in lower case, without "and", joined by "_". */
+export const EXCHANGE_VIEWPOINTS = Object.freeze([
+    'Application Cooperation', 'Application Usage', 'Business Process Cooperation', 'Capability', 'Goal Realization',
+    'Implementation and Deployment', 'Implementation and Migration', 'Information Structure', 'Layered', 'Migration',
+    'Motivation', 'Organization', 'Outcome Realization', 'Physical', 'Product', 'Project', 'Requirements Realization',
+    'Resource', 'Service Realization', 'Stakeholder', 'Strategy', 'Technology', 'Technology Usage', 'Value Stream',
+]);
+const _viewpointId = (name) => name.toLowerCase().replace(/ and /g, ' ').replace(/ /g, '_');
+
+/** An access relationship's access: the format's names by Archi's accessType (absent: write). */
+const ACCESS_TYPES = Object.freeze({ 0: 'Write', 1: 'Read', 2: 'Access', 3: 'ReadWrite' });
+
+/** The format's two junction types, by whether Archi's junction is an "or". */
+const JUNCTION_TYPES = Object.freeze({ AndJunction: false, OrJunction: true });
+
+/** Node types, by the Archi visual type each is read as. */
+const NODE_VISUALS = Object.freeze({ Element: 'diagram-object', Container: 'diagram-model-group', Label: 'diagram-model-note' });
+
+// --- reading ---
+
+const _local = (el) => el.tagName.replace(/^.*:/, '');
+const _kids = (el, name) => (el?.children ?? []).filter(c => _local(c) === name);
+const _kid = (el, name) => _kids(el, name)[0];
+/** The text of the first child `name` (the first language given). */
+const _text = (el, name) => _kid(el, name)?.textContent ?? null;
+const _xsiType = (el) => (el.getAttribute('xsi:type') ?? '').replace(/^.*:/, '');
+const _number = (el, name) => Number(el.getAttribute(name) ?? 0);
+
+/**
+ * Parse an Exchange Format file into the shapes `parseArchiModel` gives, ready
+ * for `toArchimateModel`.
+ * @param {string|ArchiXMLElement} xml
+ * @returns {Object} {id, name, documentation, properties, elements, relationships, views}
+ */
+export function parseExchangeModel(xml) {
+    const root = typeof xml === 'string' ? parseXML(xml) : xml;
+    // Archi's own root is a <model> too: the namespace tells them apart (3.0 and 3.1 share it).
+    const inFormat = Object.entries(root.attributes ?? {}).some(([name, value]) => /^xmlns(:|$)/.test(name) && /opengroup\.org\/xsd\/archimate/.test(value));
+    if (_local(root) !== 'model' || !inFormat) throw new Error(`Not an ArchiMate Exchange Format model: the root is <${root.tagName}>`);
+
+    const definitions = new Map(_kids(_kid(root, 'propertyDefinitions'), 'propertyDefinition')
+        .map(d => [d.getAttribute('identifier'), _text(d, 'name') ?? d.getAttribute('name') ?? '']));
+    /** A concept's or view's properties as [{key, value}], in file order. */
+    const pairs = (el) => _kids(_kid(el, 'properties'), 'property').map(p => ({
+        key: definitions.get(p.getAttribute('propertyDefinitionRef') ?? p.getAttribute('identifierRef')) ?? '',
+        value: _text(p, 'value') ?? '',
+    }));
+    const folders = _organizationPaths(root);
+
+    const model = {
+        id: root.getAttribute('identifier'),
+        name: _text(root, 'name') ?? '',
+        documentation: _text(root, 'documentation'),
+        properties: pairs(root),
+        archi: null,
+        elements: [],
+        relationships: [],
+        views: [],
+    };
+    for (const el of _kids(_kid(root, 'elements'), 'element')) {
+        model.elements.push(_inFolder(_parseElement(el, pairs(el)), folders));
+    }
+    for (const el of _kids(_kid(root, 'relationships'), 'relationship')) {
+        model.relationships.push(_inFolder(_parseRelationship(el, pairs(el)), folders));
+    }
+    for (const el of _kids(_kid(_kid(root, 'views'), 'diagrams'), 'view')) {
+        if (_xsiType(el) !== 'Diagram') continue;
+        model.views.push(_inFolder(_parseView(el, pairs(el)), folders));
+    }
+    return model;
+}
+
+/** An item's folder path (`archiFolder`) from the organizations, when it has one. @private */
+function _inFolder(item, folders) {
+    const path = folders.get(item.id);
+    if (path?.length) item.archiFolder = path;
+    return item;
+}
+
+/**
+ * The folder path of every item the organizations hold, by its id: each
+ * labelled item it is in, outermost first. An outermost item named as one of
+ * Archi's top-level folders is that folder, not a sub-folder (Archi exports
+ * its folders so); any other is a sub-folder.
+ * @private
+ */
+function _organizationPaths(root) {
+    const topNames = new Set(ARCHI_FOLDERS.map(f => f.name));
+    const paths = new Map();
+    let made = 0;
+    const walk = (item, path, outermost) => {
+        for (const child of _kids(item, 'item')) {
+            const ref = child.getAttribute('identifierRef');
+            if (ref) { paths.set(ref, path); continue; }
+            const name = _text(child, 'label') ?? '';
+            if (outermost && topNames.has(name)) { walk(child, path, false); continue; }
+            const documentation = _text(child, 'documentation');
+            const step = { id: child.getAttribute('identifier') ?? `folder-${++made}`, name, ...(documentation && { documentation }) };
+            walk(child, [...path, step], false);
+        }
+    };
+    for (const organization of _kids(root, 'organizations')) walk(organization, [], true);
+    return paths;
+}
+
+/** An element as parseArchiModel gives it (type: Archi's class name). @private */
+function _parseElement(el, propertyPairs) {
+    const xsiType = _xsiType(el);
+    const properties = Object.fromEntries(propertyPairs.map(({ key, value }) => [key, value]));
+    const ownType = properties[EXCHANGE_TYPE_PROPERTY];
+    delete properties[EXCHANGE_TYPE_PROPERTY];
+    const attributes = {};
+    const elements = [];
+    if (JUNCTION_TYPES[xsiType]) attributes.type = 'or';
+    // Its own type as Archi keeps it, so the model reads both files alike.
+    if (ownType) elements.push({ tag: 'feature', text: '', attributes: { name: ARCHI_TYPE_FEATURE, value: ownType } });
+    return {
+        id: el.getAttribute('identifier'),
+        name: _text(el, 'name') ?? '',
+        type: xsiType in JUNCTION_TYPES ? 'Junction' : xsiType,
+        documentation: _text(el, 'documentation'),
+        properties,
+        ...((Object.keys(attributes).length || elements.length) && { archi: { attributes, elements } }),
+    };
+}
+
+/** A relationship as parseArchiModel gives it (type: Archi's class name). @private */
+function _parseRelationship(el, propertyPairs) {
+    const xsiType = _xsiType(el);
+    const attributes = {};
+    const access = Object.entries(ACCESS_TYPES).find(([, name]) => name === el.getAttribute('accessType'))?.[0];
+    if (access && access !== '0') attributes.accessType = access;
+    if (el.getAttribute('modifier')) attributes.strength = el.getAttribute('modifier');
+    return {
+        id: el.getAttribute('identifier'),
+        name: _text(el, 'name') ?? '',
+        type: `${xsiType}Relationship`,
+        source: el.getAttribute('source'),
+        target: el.getAttribute('target'),
+        ...(el.getAttribute('isDirected') === 'true' && { directed: true }),
+        documentation: _text(el, 'documentation'),
+        properties: Object.fromEntries(propertyPairs.map(({ key, value }) => [key, value])),
+        ...(Object.keys(attributes).length && { archi: { attributes, elements: [] } }),
+    };
+}
+
+/** A view as parseArchiModel gives it: a tree of Archi visuals, bounds relative to their parent. @private */
+function _parseView(el, properties) {
+    const viewpoint = EXCHANGE_VIEWPOINTS.find(name => name === el.getAttribute('viewpoint'));
+    const view = {
+        id: el.getAttribute('identifier'),
+        name: _text(el, 'name') ?? '',
+        type: 'archimate-diagram-model',
+        documentation: _text(el, 'documentation'),
+        properties,
+        archi: viewpoint ? { attributes: { viewpoint: _viewpointId(viewpoint) }, elements: [] } : null,
+        children: [],
+    };
+    const byId = new Map();
+    const walk = (parent, origin, into) => {
+        for (const node of _kids(parent, 'node')) {
+            const box = { x: _number(node, 'x'), y: _number(node, 'y'), width: _number(node, 'w'), height: _number(node, 'h') };
+            const visual = _nodeVisual(node, { ...box, x: box.x - origin.x, y: box.y - origin.y });
+            byId.set(visual.id, visual);
+            into.push(visual);
+            walk(node, box, visual.children);
+        }
+    };
+    walk(el, { x: 0, y: 0 }, view.children);
+    for (const line of _kids(el, 'connection')) {
+        // On its source box, as Archi keeps it (a line from a line has no box, and is not kept).
+        const source = byId.get(line.getAttribute('source'));
+        if (!source || !byId.has(line.getAttribute('target'))) continue;
+        const style = _styleOf(line);
+        const bendpoints = _kids(line, 'bendpoint').map(bp => ({ x: _number(bp, 'x'), y: _number(bp, 'y') }));
+        source.sourceConnections.push({
+            id: line.getAttribute('identifier'),
+            source: source.id,
+            target: line.getAttribute('target'),
+            relationship: line.getAttribute('relationshipRef') || null,
+            type: '',
+            archiType: 'diagram-model-connection',
+            connectionType: 0,
+            archi: { attributes: {}, elements: [], style },
+            name: _text(line, 'label') ?? '',
+            style,
+            features: {},
+            ...(bendpoints.length && { bendpoints }),
+        });
+    }
+    // Bendpoints are on the view here; Archi keeps them as offsets from the line's ends.
+    relativizeArchiBendpoints(view);
+    return view;
+}
+
+/** One node as an Archi visual: an element's box, a group (Container) or a note (Label). @private */
+function _nodeVisual(node, bounds) {
+    const kind = _xsiType(node);
+    const label = _text(node, 'label');
+    const style = _styleOf(node);
+    return {
+        id: node.getAttribute('identifier'),
+        type: NODE_VISUALS[kind] ?? NODE_VISUALS.Label,
+        archimateElement: node.getAttribute('elementRef') || null,
+        referencedModel: null,
+        imagePath: null,
+        name: kind === 'Container' ? label : null,
+        text: kind === 'Container' ? null : label,
+        notes: null,
+        bounds,
+        style,
+        archi: { attributes: {}, elements: [], style },
+        features: {},
+        properties: {},
+        sourceConnections: [],
+        children: [],
+    };
+}
+
+/** A colour element as Archi's "#rrggbb". @private */
+const _hex = (color) => `#${['r', 'g', 'b'].map(c => Math.max(0, Math.min(255, _number(color, c))).toString(16).padStart(2, '0')).join('')}`;
+
+/** A node's or line's <style> as Archi's style attributes (see archimateArchiFormat's STYLE_FIELDS). @private */
+function _styleOf(el) {
+    const styleEl = _kid(el, 'style');
+    const style = {};
+    if (!styleEl) return style;
+    const fill = _kid(styleEl, 'fillColor');
+    if (fill) {
+        style.fillColor = _hex(fill);
+        const alpha = fill.getAttribute('a');
+        if (alpha !== null && alpha !== undefined && Number(alpha) < 100) style.alpha = String(Math.round(Number(alpha) * 2.55));
+    }
+    const line = _kid(styleEl, 'lineColor');
+    if (line) {
+        style.lineColor = _hex(line);
+        if (line.getAttribute('a') === '0') style.lineAlpha = '0';
+    }
+    const font = _kid(styleEl, 'font');
+    if (font) {
+        if (_kid(font, 'color')) style.fontColor = _hex(_kid(font, 'color'));
+        const name = font.getAttribute('name');
+        const size = font.getAttribute('size');
+        if (name || size) {
+            const words = String(font.getAttribute('style') ?? '').toLowerCase();
+            style.font = archiFontString({
+                ...(name && { fontFamily: name }),
+                ...(size && { fontSize: `${Number(size)}pt` }),
+                ...(words.includes('bold') && { fontWeight: 'bold' }),
+                ...(words.includes('italic') && { fontStyle: 'italic' }),
+            });
+        }
+    }
+    if (styleEl.getAttribute('lineWidth')) style.lineWidth = styleEl.getAttribute('lineWidth');
+    return style;
+}
+
+// --- writing ---
+
+/** An xs:ID: a letter or underscore, then letters, digits, '.', '-', '_'. */
+const NCNAME = /^[A-Za-z_][\w.-]*$/;
+
+/**
+ * Identifiers for the file: every one unique, and each a valid xs:ID. An id
+ * that already is one is kept (so a round trip keeps them); others are made
+ * one. The same id asked for again by `ref` gets the same identifier.
+ * @private
+ */
+class ExchangeIds {
+    constructor() {
+        this.byId = new Map();
+        this.used = new Set();
+    }
+
+    /** The identifier for a concept or view id (the same each time). */
+    ref(id) {
+        if (!this.byId.has(id)) this.byId.set(id, this.fresh(id));
+        return this.byId.get(id);
+    }
+
+    /** A new identifier, made from `id`. */
+    fresh(id) {
+        let candidate = NCNAME.test(String(id)) ? String(id) : `id-${String(id).replace(/[^\w.-]/g, '_')}`;
+        while (this.used.has(candidate)) candidate += '_';
+        this.used.add(candidate);
+        return candidate;
+    }
+}
+
+/**
+ * Write a model as an Exchange Format file. Takes what `toArchiXML` takes.
+ * @param {Object} model - {id, name, documentation, properties, elements, relationships}
+ * @param {Array<Object>} views - Archi view trees (an editor's views via fromArchimateView); only
+ *   ArchiMate diagrams are written
+ * @returns {string}
+ */
+export function toExchangeXML(model, views = []) {
+    const ids = new ExchangeIds();
+    const definitions = new Map();   // property key -> its definition's identifier
+    const define = (key) => {
+        if (!definitions.has(key)) definitions.set(key, `propid-${definitions.size + 1}`);
+        return definitions.get(key);
+    };
+    const propertyLines = (pairs, indent) => pairs.length ? [
+        `${indent}<properties>`,
+        ...pairs.flatMap(({ key, value }) => [
+            `${indent}  <property propertyDefinitionRef="${define(key)}">`,
+            `${indent}    <value>${escapeXml(value ?? '')}</value>`,
+            `${indent}  </property>`,
+        ]),
+        `${indent}</properties>`,
+    ] : [];
+    const textLines = (tag, text, indent) => text ? [`${indent}<${tag}>${escapeXml(text)}</${tag}>`] : [];
+    const conceptPairs = (concept, extra = []) => [
+        ...Object.entries(typedArrayToProperties(concept.properties)).map(([key, value]) => ({ key, value })),
+        ...extra,
+    ];
+
+    const elements = model.elements ?? [];
+    const relationships = model.relationships ?? [];
+    const diagrams = (views ?? []).filter(v => !v.type || v.type === 'archimate-diagram-model');
+
+    const elementLines = elements.flatMap(el => {
+        const { type, original } = archiFolderOf(el);
+        let xsiType = toPascalType(type);
+        if (xsiType === 'Junction') xsiType = el.archi?.attributes?.type === 'or' ? 'OrJunction' : 'AndJunction';
+        return [
+            `    <element identifier="${ids.ref(el.id)}" xsi:type="${xsiType}">`,
+            `      <name>${escapeXml(el.name ?? '')}</name>`,
+            ...textLines('documentation', el.documentation, '      '),
+            ...propertyLines(conceptPairs(el, original ? [{ key: EXCHANGE_TYPE_PROPERTY, value: original }] : []), '      '),
+            '    </element>',
+        ];
+    });
+
+    const known = new Set(elements.map(e => e.id));
+    const relationshipLines = relationships.flatMap(rel => {
+        const directed = rel.kind === 'association-directed';
+        const kind = directed ? 'association' : (rel.kind || 'association');
+        const attrs = [`identifier="${ids.ref(rel.id)}"`, `source="${ids.ref(rel.source)}"`, `target="${ids.ref(rel.target)}"`, `xsi:type="${toPascalType(kind)}"`];
+        if (directed) attrs.push('isDirected="true"');
+        const access = ACCESS_TYPES[rel.archi?.attributes?.accessType ?? 0];
+        if (kind === 'access' && access && access !== 'Write') attrs.push(`accessType="${access}"`);
+        if (kind === 'influence' && rel.archi?.attributes?.strength) attrs.push(`modifier="${escapeAttr(rel.archi.attributes.strength)}"`);
+        const name = rel.label ?? rel.name;
+        const body = [
+            ...textLines('name', name, '      '),
+            ...textLines('documentation', rel.documentation, '      '),
+            ...propertyLines(conceptPairs(rel), '      '),
+        ];
+        known.add(rel.id);
+        return body.length
+            ? [`    <relationship ${attrs.join(' ')}>`, ...body, '    </relationship>']
+            : [`    <relationship ${attrs.join(' ')}/>`];
+    });
+
+    const viewLines = diagrams.flatMap(view => _viewLines(view, { ids, known, propertyLines, textLines }));
+    const organizationLines = _organizationLines({ elements, relationships, views: diagrams, ids });
+
+    // Read once every property is defined: the model's, the concepts' and the views'.
+    const modelLines = [
+        `  <name>${escapeXml(model.name || 'Untitled')}</name>`,
+        ...textLines('documentation', model.documentation, '  '),
+        ...propertyLines(Array.isArray(model.properties) ? model.properties : [], '  '),
+    ];
+    const section = (tag, lines) => lines.length ? [`  <${tag}>`, ...lines, `  </${tag}>`] : [];
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        `<model xmlns="${EXCHANGE_NAMESPACE}" xmlns:xsi="${XSI_NAMESPACE}" xsi:schemaLocation="${EXCHANGE_NAMESPACE} ${EXCHANGE_SCHEMA}" identifier="${ids.ref(model.id || 'model')}">`,
+        ...modelLines,
+        ...section('elements', elementLines),
+        ...section('relationships', relationshipLines),
+        ...section('organizations', organizationLines),
+        ...section('propertyDefinitions', [...definitions].flatMap(([key, id]) => [
+            `    <propertyDefinition identifier="${id}" type="string">`,
+            `      <name>${escapeXml(key)}</name>`,
+            '    </propertyDefinition>',
+        ])),
+        ...(viewLines.length ? ['  <views>', '    <diagrams>', ...viewLines, '    </diagrams>', '  </views>'] : []),
+        '</model>',
+    ].join('\n');
+}
+
+/** One view: its nodes on the view (x/y absolute), then its lines with their bendpoints on the view. @private */
+function _viewLines(view, { ids, known, propertyLines, textLines }) {
+    const boxes = archiVisualBoxes({ children: view.children ?? [] });
+    const nodeIds = new Map();   // visual id -> its identifier in this file
+    const visuals = [];
+    const collect = (visual) => { visuals.push(visual); (visual.children ?? []).forEach(collect); };
+    (view.children ?? []).forEach(collect);
+    for (const visual of visuals) if (boxes.has(visual.id)) nodeIds.set(visual.id, ids.fresh(visual.id));
+    // The format allows no negative x or y: the view moves right and down by its most negative (as Archi exports).
+    const pointsOf = new Map(visuals.flatMap(v => (v.sourceConnections ?? []).map(sc => [sc, sc.bendpoints?.length ? archiBendpointLocations(sc, boxes) : []])));
+    const all = [...boxes.values(), ...[...pointsOf.values()].flat()];
+    const shift = { x: Math.max(0, -Math.min(0, ...all.map(p => Math.round(p.x)))), y: Math.max(0, -Math.min(0, ...all.map(p => Math.round(p.y)))) };
+
+    const nodeLines = (visual, indent) => {
+        const box = boxes.get(visual.id);
+        if (!box) return [];
+        const attrs = [`identifier="${nodeIds.get(visual.id)}"`];
+        let label = null;
+        if (visual.archimateElement && known.has(visual.archimateElement)) {
+            attrs.push(`elementRef="${ids.ref(visual.archimateElement)}"`, 'xsi:type="Element"');
+        } else if (visual.type === 'diagram-model-group') {
+            attrs.push('xsi:type="Container"');
+            label = visual.name;
+        } else {
+            attrs.push('xsi:type="Label"');
+            label = visual.text ?? visual.name;
+        }
+        attrs.push(`x="${Math.round(box.x) + shift.x}"`, `y="${Math.round(box.y) + shift.y}"`, `w="${Math.round(box.width)}"`, `h="${Math.round(box.height)}"`);
+        const body = [
+            ...textLines('label', label, `${indent}  `),
+            ..._styleLines(visual.style, `${indent}  `),
+            ...(visual.children ?? []).flatMap(child => nodeLines(child, `${indent}  `)),
+        ];
+        return body.length ? [`${indent}<node ${attrs.join(' ')}>`, ...body, `${indent}</node>`] : [`${indent}<node ${attrs.join(' ')}/>`];
+    };
+
+    const lines = visuals.flatMap(visual => (visual.sourceConnections ?? []).flatMap(sc => {
+        if (!nodeIds.has(sc.source) || !nodeIds.has(sc.target)) return [];
+        if (sc.relationship && !known.has(sc.relationship)) return [];
+        const attrs = [`identifier="${ids.fresh(sc.id)}"`];
+        attrs.push(sc.relationship ? `relationshipRef="${ids.ref(sc.relationship)}" xsi:type="Relationship"` : 'xsi:type="Line"');
+        attrs.push(`source="${nodeIds.get(sc.source)}"`, `target="${nodeIds.get(sc.target)}"`);
+        const points = pointsOf.get(sc);
+        const body = [
+            ...(sc.relationship ? [] : textLines('label', sc.name, '          ')),
+            ..._styleLines(sc.style, '          '),
+            ...points.map(p => `          <bendpoint x="${Math.round(p.x) + shift.x}" y="${Math.round(p.y) + shift.y}"/>`),
+        ];
+        return body.length ? [`        <connection ${attrs.join(' ')}>`, ...body, '        </connection>'] : [`        <connection ${attrs.join(' ')}/>`];
+    }));
+
+    const viewpoint = EXCHANGE_VIEWPOINTS.find(name => _viewpointId(name) === view.archi?.attributes?.viewpoint);
+    return [
+        `      <view identifier="${ids.ref(view.id)}" xsi:type="Diagram"${viewpoint ? ` viewpoint="${viewpoint}"` : ''}>`,
+        `        <name>${escapeXml(view.name || 'View')}</name>`,
+        ...textLines('documentation', view.documentation, '        '),
+        ...propertyLines(Array.isArray(view.properties) ? view.properties : [], '        '),
+        ...(view.children ?? []).flatMap(visual => nodeLines(visual, '        ')),
+        ...lines,
+        '      </view>',
+    ];
+}
+
+/** Archi's "#rrggbb" as the format's r/g/b attributes. @private */
+function _rgb(hex) {
+    const m = /^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(String(hex ?? ''));
+    return m && `r="${parseInt(m[1], 16)}" g="${parseInt(m[2], 16)}" b="${parseInt(m[3], 16)}"`;
+}
+
+/** Archi's style attributes as a <style> element (nothing when there is no style). @private */
+function _styleLines(style = {}, indent) {
+    const inner = [];
+    const fill = _rgb(style.fillColor);
+    const alpha = style.alpha !== undefined ? Math.round(Number(style.alpha) / 2.55) : null;
+    if (fill) inner.push(`${indent}  <fillColor ${fill}${alpha !== null ? ` a="${alpha}"` : ''}/>`);
+    else if (alpha === 0) inner.push(`${indent}  <fillColor r="255" g="255" b="255" a="0"/>`);
+    const line = _rgb(style.lineColor ?? style.borderColor);
+    if (line) inner.push(`${indent}  <lineColor ${line}${style.lineAlpha === '0' ? ' a="0"' : ''}/>`);
+    const font = parseArchiFont(style.font);
+    const color = _rgb(style.fontColor);
+    if (style.font || color) {
+        const attrs = [];
+        if (font.fontFamily) attrs.push(`name="${escapeAttr(font.fontFamily)}"`);
+        if (font.fontSize) attrs.push(`size="${parseFloat(font.fontSize)}"`);
+        const words = [font.fontWeight === 'bold' && 'bold', font.fontStyle === 'italic' && 'italic'].filter(Boolean);
+        if (words.length) attrs.push(`style="${words.join(' ')}"`);
+        const open = `${indent}  <font${attrs.length ? ` ${attrs.join(' ')}` : ''}`;
+        inner.push(...(color ? [`${open}>`, `${indent}    <color ${color}/>`, `${indent}  </font>`] : [`${open}/>`]));
+    }
+    const width = style.lineWidth ? ` lineWidth="${Number(style.lineWidth)}"` : '';
+    if (!inner.length && !width) return [];
+    return inner.length ? [`${indent}<style${width}>`, ...inner, `${indent}</style>`] : [`${indent}<style${width}/>`];
+}
+
+/**
+ * The organizations: one item per Archi top-level folder that holds anything,
+ * each item's concepts or views in the sub-folders its `archiFolder` names.
+ * @private
+ */
+function _organizationLines({ elements, relationships, views, ids }) {
+    const inFolder = new Map(ARCHI_FOLDERS.map(f => [f.type, []]));
+    for (const el of elements) inFolder.get(archiFolderOf(el).folder.type).push(el);
+    inFolder.get('relations').push(...relationships);
+    inFolder.get('diagrams').push(...views);
+
+    const write = (items, indent) => {
+        const lines = [];
+        const groups = new Map();
+        for (const item of items.filter(i => i.archiFolder?.length)) {
+            const [step, ...rest] = item.archiFolder;
+            if (!groups.has(step.id)) groups.set(step.id, { step, items: [] });
+            groups.get(step.id).items.push({ ...item, archiFolder: rest });
+        }
+        for (const { step, items: inner } of groups.values()) {
+            lines.push(`${indent}<item identifier="${ids.fresh(step.id)}">`, `${indent}  <label>${escapeXml(step.name ?? '')}</label>`);
+            if (step.documentation) lines.push(`${indent}  <documentation>${escapeXml(step.documentation)}</documentation>`);
+            lines.push(...write(inner, `${indent}  `), `${indent}</item>`);
+        }
+        for (const item of items.filter(i => !i.archiFolder?.length)) lines.push(`${indent}<item identifierRef="${ids.ref(item.id)}"/>`);
+        return lines;
+    };
+    return ARCHI_FOLDERS.filter(f => inFolder.get(f.type).length).flatMap(folder => [
+        '    <item>',
+        `      <label>${escapeXml(folder.name)}</label>`,
+        ...write(inFolder.get(folder.type), '      '),
+        '    </item>',
+    ]);
+}