@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/archimateArchiFormat.js

@@ -0,0 +1,1693 @@
+import { ArchimateNotation } from './archimate.js';
+import { archiElementType, typeProfileId, typeDisplayName, ARCHI_TYPE_FEATURE, ARCHI_TYPE_PROFILE_PREFIX } from './archimateArchiTypes.js';
+import { ArchimateModel } from './charting/diagrams/ArchimateModel.js';
+import './charting/diagrams/CanvasView.js';   // registers the canvas view type
+import { ElementInstance } from './charting/diagrams/ElementInstance.js';
+import { ViewObjectInstance } from './charting/diagrams/ViewObjectInstance.js';
+import { RelationshipInstance } from './charting/diagrams/RelationshipInstance.js';
+import { ViewConnectionInstance } from './charting/diagrams/ViewConnectionInstance.js';
+
+/**
+ * ArchimateArchiFormat — pure import/export helpers for Archi’s native
+ * `.archimate` XML format (not the Open Group Model Exchange File Format).
+ *
+ * The module maps Archi model elements, relationships, and view/visual
+ * children to renderengine’s `archimateDiagram` inputs, and back again.
+ */
+
+export const ARCHI_VISUAL_OBJECTS = Object.freeze([
+    'diagram-model-note',
+    'diagram-model-group',
+    'diagram-model-connection',
+    'diagram-model-image',
+    'diagram-model-reference',
+    'sketch-model-sticky',
+    'sketch-model-actor',
+    'canvas-model-block',
+    'canvas-model-sticky',
+    'canvas-model-image',
+]);
+
+export const ARCHI_VIEW_TYPES = Object.freeze([
+    'archimate-diagram-model',
+    'sketch-model',
+    'canvas-model',
+]);
+
+const ARCHI_NAMESPACE = 'http://www.archimatetool.com/archimate';
+/** Archi's canvas classes live in their own namespace. */
+const ARCHI_CANVAS_NAMESPACE = 'http://www.archimatetool.com/archimate/canvas';
+
+/** Lightweight XML element descriptor used by both the DOMParser wrapper and
+ *  the Node fallback parser. Mirrors the small subset of DOM we need. */
+export class ArchiXMLElement {
+    constructor(tagName, attributes = {}) {
+        this.tagName = tagName;
+        this.attributes = attributes;
+        this.children = [];
+        this.textContent = '';
+    }
+
+    getAttribute(name) {
+        return this.attributes[name] ?? null;
+    }
+
+    querySelectorAll(tagName) {
+        const out = [];
+        for (const child of this.children) {
+            if (child.tagName === tagName) out.push(child);
+            out.push(...child.querySelectorAll(tagName));
+        }
+        return out;
+    }
+
+    querySelector(tagName) {
+        for (const child of this.children) {
+            if (child.tagName === tagName) return child;
+            const deep = child.querySelector(tagName);
+            if (deep) return deep;
+        }
+        return null;
+    }
+}
+
+/** Parse an XML string into an `ArchiXMLElement` tree. Uses DOMParser when
+ *  available (browser), otherwise a minimal dependency-free fallback. */
+export function parseXML(xml) {
+    if (typeof DOMParser !== 'undefined') {
+        const doc = new DOMParser().parseFromString(xml, 'application/xml');
+        const parserError = doc.querySelector('parsererror');
+        if (parserError) throw new Error('XML parse error');
+        return _fromDOMNode(doc.documentElement);
+    }
+    return _parseXMLFallback(xml);
+}
+
+function _fromDOMNode(node) {
+    const attrs = {};
+    for (const attr of node.attributes || []) {
+        attrs[attr.name] = attr.value;
+    }
+    const el = new ArchiXMLElement(node.tagName, attrs);
+    for (const child of node.childNodes || []) {
+        if (child.nodeType === 1) { // ELEMENT_NODE
+            el.children.push(_fromDOMNode(child));
+        } else if (child.nodeType === 3) { // TEXT_NODE
+            el.textContent += child.textContent;
+        }
+    }
+    if (!el.textContent.trim()) el.textContent = '';   // indentation between elements, not text
+    return el;
+}
+
+function _parseXMLFallback(xml) {
+    // XML 1.0 (2.11): a parser sees every line break as a newline; a CR written as 
 survives (decoded later).
+    const trimmed = xml.replace(/\r\n?/g, '\n').trim();
+    const root = _parseNode(trimmed, { pos: 0 });
+    if (!root) throw new Error('XML parse error: no root element');
+    return root;
+}
+
+function _parseNode(xml, state) {
+    _skipWhitespace(xml, state);
+    if (state.pos >= xml.length || xml[state.pos] !== '<') return null;
+
+    // Skip XML declarations, processing instructions and comments.
+    if (xml.slice(state.pos, state.pos + 2) === '<?') {
+        const end = xml.indexOf('?>', state.pos);
+        state.pos = end === -1 ? xml.length : end + 2;
+        return _parseNode(xml, state);
+    }
+    if (xml.startsWith('<!--', state.pos)) {
+        const end = xml.indexOf('-->', state.pos);
+        state.pos = end === -1 ? xml.length : end + 3;
+        return _parseNode(xml, state);
+    }
+
+    // A quoted attribute value may hold '>' or the other quote character.
+    const tagMatch = xml.slice(state.pos).match(/^<([^>\s/]+)((?:[^>"']|"[^"]*"|'[^']*')*)>/);
+    if (!tagMatch) throw new Error('XML parse error: malformed tag');
+    const tagName = tagMatch[1];
+    const attrText = tagMatch[2];
+    state.pos += tagMatch[0].length;
+
+    const isSelfClosing = attrText.trimEnd().endsWith('/');
+    const attributes = _parseAttributes(attrText);
+    const node = new ArchiXMLElement(tagName, attributes);
+
+    if (isSelfClosing) {
+        return node;
+    }
+
+    // Whitespace is text: a content's leading spaces are its own (Archi uses them to clear a picture);
+    // indentation between elements is dropped below, once the element is read.
+    while (state.pos < xml.length) {
+        if (xml.slice(state.pos, state.pos + 2) === '</') {
+            const closeMatch = xml.slice(state.pos).match(/^<\/([^>]+)>/);
+            if (!closeMatch || closeMatch[1] !== tagName) {
+                throw new Error(`XML parse error: mismatched closing tag for ${tagName}`);
+            }
+            state.pos += closeMatch[0].length;
+            if (!node.textContent.trim()) node.textContent = '';   // indentation between elements, not text
+            return node;
+        }
+        if (xml.startsWith('<![CDATA[', state.pos)) {
+            const end = xml.indexOf(']]>', state.pos);
+            node.textContent += xml.slice(state.pos + 9, end === -1 ? xml.length : end);
+            state.pos = end === -1 ? xml.length : end + 3;
+        } else if (xml.startsWith('<!--', state.pos)) {
+            const end = xml.indexOf('-->', state.pos);
+            state.pos = end === -1 ? xml.length : end + 3;
+        } else if (xml[state.pos] === '<') {
+            const child = _parseNode(xml, state);
+            if (child) node.children.push(child);
+        } else {
+            const textEnd = xml.indexOf('<', state.pos);
+            node.textContent += _unescapeXml(xml.slice(state.pos, textEnd === -1 ? xml.length : textEnd));
+            state.pos = textEnd === -1 ? xml.length : textEnd;
+        }
+    }
+    if (!node.textContent.trim()) node.textContent = '';   // indentation between elements, not text
+    return node;
+}
+
+function _skipWhitespace(xml, state) {
+    while (state.pos < xml.length && /\s/.test(xml[state.pos])) state.pos++;
+}
+
+function _parseAttributes(text) {
+    const attrs = {};
+    const regex = /([^\s=/]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+    let m;
+    while ((m = regex.exec(text)) !== null) {
+        attrs[m[1]] = _unescapeXml(m[2] ?? m[3]);
+    }
+    return attrs;
+}
+
+/** Decode the predefined entities and character references (the fallback parser's half of _escapeXml). */
+function _unescapeXml(str) {
+    return str.replace(/&(#x[0-9a-f]+|#\d+|lt|gt|quot|apos|amp);/gi, (whole, ref) => {
+        const r = ref.toLowerCase();
+        if (r[0] === '#') {
+            const code = r[1] === 'x' ? parseInt(r.slice(2), 16) : parseInt(r.slice(1), 10);
+            return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+        }
+        return { lt: '<', gt: '>', quot: '"', apos: "'", amp: '&' }[r];
+    });
+}
+
+/** Parse an Archi native XML model into plain JavaScript structures. */
+export function parseArchiModel(xml) {
+    const root = typeof xml === 'string' ? parseXML(xml) : xml;
+    const model = {
+        id: root.getAttribute('id'),
+        name: root.getAttribute('name'),
+        version: root.getAttribute('version'),
+        elements: [],
+        relationships: [],
+        views: [],
+        // The model's own documentation (Archi's "purpose") and properties, in order (keys may repeat).
+        documentation: _childText(root, 'purpose'),
+        properties: _propertyPairs(root),
+        archi: _extrasOrNull(_archiExtras(root, ARCHI_MODEL_HANDLED)),
+    };
+
+    for (const folder of root.children.filter(c => c.tagName === 'folder')) {
+        const folderType = folder.getAttribute('type');
+        if (folderType === 'diagrams') {
+            _walkViewFolder(folder, model);
+            continue;
+        }
+
+        // Recursively walk folder structure (handles nested sub-folders)
+        _walkFolder(folder, folderType, model);
+    }
+
+    return model;
+}
+
+/** A sub-folder as one step of a folder path: its id, name, documentation and properties. @private */
+function _folderStep(folder) {
+    const documentation = _childText(folder, 'documentation');
+    const properties = _propertyPairs(folder);
+    return {
+        id: folder.getAttribute('id'),
+        name: folder.getAttribute('name') ?? '',
+        ...(documentation && { documentation }),
+        ...(properties.length && { properties }),
+    };
+}
+
+/** Every view in the Views folder, sub-folders included, in file order; each
+ *  remembers its sub-folder path (`archiFolder`). @private */
+function _walkViewFolder(folder, model, path = []) {
+    for (const child of folder.children) {
+        if (child.tagName === 'element') {
+            const view = _parseView(child);
+            if (path.length) view.archiFolder = path;
+            model.views.push(view);
+        } else if (child.tagName === 'folder') {
+            _walkViewFolder(child, model, [...path, _folderStep(child)]);
+        }
+    }
+}
+
+/** Every element (or relationship) in a top-level folder, sub-folders included;
+ *  each remembers its sub-folder path (`archiFolder`). @private */
+function _walkFolder(folder, folderType, model, path = []) {
+    for (const child of folder.children) {
+        if (child.tagName === 'element') {
+            const parsed = _parseModelElement(child);
+            if (path.length) parsed.archiFolder = path;
+            if (folderType === 'relations') {
+                model.relationships.push(parsed);
+            } else {
+                model.elements.push(parsed);
+            }
+        } else if (child.tagName === 'folder') {
+            _walkFolder(child, folderType, model, [...path, _folderStep(child)]);
+        }
+    }
+}
+
+function _parseModelElement(el) {
+    const xsiType = el.getAttribute('xsi:type') || '';
+    const type = xsiType.replace(/^archimate:/, '');
+    const element = {
+        id: el.getAttribute('id'),
+        name: el.getAttribute('name'),
+        type,
+        documentation: _childText(el, 'documentation'),
+        properties: _parseProperties(el),
+    };
+    const source = el.getAttribute('source');
+    const target = el.getAttribute('target');
+    if (source) element.source = source;
+    if (target) element.target = target;
+    if (el.getAttribute('directed') === 'true') element.directed = true;
+    const archi = _extrasOrNull(_archiExtras(el, ARCHI_CONCEPT_HANDLED));
+    if (archi) element.archi = archi;
+    return element;
+}
+
+function _parseView(el) {
+    const xsiType = el.getAttribute('xsi:type') || '';
+    const view = {
+        id: el.getAttribute('id'),
+        name: el.getAttribute('name'),
+        type: _viewTypeFromXSI(xsiType),
+        documentation: _childText(el, 'documentation'),
+        properties: _propertyPairs(el),
+        archi: _extrasOrNull(_archiExtras(el, ARCHI_VIEW_HANDLED)),
+        children: [],
+    };
+    for (const child of el.children.filter(c => c.tagName === 'child')) {
+        view.children.push(_parseVisual(child));
+    }
+    _relativizeLocatedBendpoints(view);
+    return view;
+}
+
+/** Archi's bendpoint: offsets from the source's and the target's centre. */
+const BENDPOINT_KEYS = Object.freeze(['startX', 'startY', 'endX', 'endY']);
+
+/** Archi's size for a visual saved at its default size (width/height -1). @private */
+const ARCHI_DEFAULT_SIZE = Object.freeze({
+    'diagram-model-group': { width: 400, height: 140 },
+    'diagram-model-note': { width: 185, height: 80 },
+});
+const ARCHI_ELEMENT_SIZE = Object.freeze({ width: 120, height: 55 });
+
+/** Every visual's absolute bounds in a view (or visual tree), by visual id. @private */
+function _visualBoxes(root) {
+    const boxes = new Map();
+    const walk = (visual, origin) => {
+        const bounds = _absoluteBounds(visual, origin);
+        if (bounds && visual.id) boxes.set(visual.id, bounds);
+        for (const child of visual.children || []) walk(child, bounds ?? origin);
+    };
+    walk(root, VIEW_ORIGIN);
+    return boxes;
+}
+
+/** A box's anchor point as Archi (GEF's Rectangle#getCenter) takes it: integer halves. @private */
+const _centre = (b) => b && { x: b.x + Math.floor(b.width / 2), y: b.y + Math.floor(b.height / 2) };
+
+/**
+ * Where a connection's bendpoints are on the view. Archi places bendpoint i of n
+ * between its two offsets, weighted by w = (i + 1) / (n + 1) from source to target:
+ * (1 - w)(sourceCentre + start) + w(targetCentre + end). A connection to another
+ * connection has no box at that end; the other end's offset is used alone.
+ * @private
+ */
+function _bendpointLocations(sc, boxes) {
+    const src = _centre(boxes.get(sc.source));
+    const tgt = _centre(boxes.get(sc.target));
+    const n = sc.bendpoints.length;
+    return sc.bendpoints.flatMap((bp, i) => {
+        const fromSource = src && { x: src.x + bp.startX, y: src.y + bp.startY };
+        const fromTarget = tgt && { x: tgt.x + bp.endX, y: tgt.y + bp.endY };
+        if (!fromSource || !fromTarget) return fromSource || fromTarget ? [fromSource || fromTarget] : [];
+        const w = (i + 1) / (n + 1);
+        return [{ x: (1 - w) * fromSource.x + w * fromTarget.x, y: (1 - w) * fromSource.y + w * fromTarget.y }];
+    });
+}
+
+/** Archi bendpoints for points on the view, between two boxes (whole pixels, as Archi keeps them). @private */
+function _relativeBendpoints(points, sourceBox, targetBox) {
+    const src = _centre(sourceBox) ?? VIEW_ORIGIN;
+    const tgt = _centre(targetBox) ?? VIEW_ORIGIN;
+    return points.map(p => ({
+        startX: Math.round(p.x - src.x), startY: Math.round(p.y - src.y),
+        endX: Math.round(p.x - tgt.x), endY: Math.round(p.y - tgt.y),
+    }));
+}
+
+/** Convert a parsed view's x/y bendpoints (an older export) to Archi's form. @private */
+function _relativizeLocatedBendpoints(view) {
+    const boxes = _visualBoxes(view);
+    const walk = (visual) => {
+        for (const sc of visual.sourceConnections || []) {
+            if (sc.bendpoints?.some(bp => 'x' in bp)) {
+                sc.bendpoints = _relativeBendpoints(sc.bendpoints, boxes.get(sc.source), boxes.get(sc.target));
+            }
+        }
+        for (const child of visual.children || []) walk(child);
+    };
+    walk(view);
+}
+
+function _viewTypeFromXSI(xsiType) {
+    const map = {
+        'archimate:ArchimateDiagramModel': 'archimate-diagram-model',
+        'archimate:SketchModel': 'sketch-model',
+        'archimate:CanvasModel': 'canvas-model',
+        'canvas:CanvasModel': 'canvas-model',   // Archi writes canvases in their own namespace
+    };
+    return map[xsiType] || xsiType.replace(/^archimate:/, '');
+}
+
+/**
+ * Archi's XML names for the visual classes it renames (EMF extended metadata in
+ * Archi's model): xsi:type -> our visual type. Every other class is written
+ * under its own name (DiagramModelImage, DiagramModelReference, ...).
+ */
+const ARCHI_VISUAL_XML_NAMES = Object.freeze({
+    Group: 'diagram-model-group',
+    Note: 'diagram-model-note',
+    DiagramObject: 'diagram-object',
+    Connection: 'diagram-model-archimate-connection',
+});
+
+function _parseVisual(el) {
+    const xsiType = el.getAttribute('xsi:type') || '';
+    const className = xsiType.replace(/^[a-z]+:/, '');   // archimate:, canvas:, ...
+    const type = ARCHI_VISUAL_XML_NAMES[className] ?? className.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+    const visual = {
+        id: el.getAttribute('id'),
+        type,
+        archimateElement: el.getAttribute('archimateElement') || null,
+        referencedModel: el.getAttribute('referencedModel') || null,
+        imagePath: el.getAttribute('imagePath') || null,
+        name: el.getAttribute('name') || null,
+        text: _childText(el, 'content') || el.getAttribute('text') || null,
+        notes: _childText(el, 'notes') || null,
+        bounds: _parseBounds(el),
+        style: _parseStyle(el),
+        archi: _archiExtras(el),
+        features: _parseFeatures(el),
+        properties: _parseProperties(el),
+        sourceConnections: [],
+        children: [],
+    };
+
+    for (const sc of el.children.filter(c => c.tagName === 'sourceConnection')) {
+        const bendpoints = [];
+        for (const bp of sc.children.filter(c => c.tagName === 'bendpoint')) {
+            bendpoints.push(bp.getAttribute('x') !== null && bp.getAttribute('startX') === null
+                ? { x: Number(bp.getAttribute('x')), y: Number(bp.getAttribute('y')) }
+                : Object.fromEntries(BENDPOINT_KEYS.map(k => [k, Number(bp.getAttribute(k) ?? 0)])));
+        }
+        visual.sourceConnections.push({
+            id: sc.getAttribute('id'),
+            source: sc.getAttribute('source'),
+            target: sc.getAttribute('target'),
+            // Archi writes archimateRelationship; 'relationship' is what older exports of ours wrote.
+            relationship: sc.getAttribute('archimateRelationship') || sc.getAttribute('relationship') || null,
+            type: (sc.getAttribute('xsi:type') || '').replace(/^archimate:/, ''),
+            // A plain line's class (no xsi:type is Archi's default, DiagramModelConnection) and its look (type bits).
+            archiType: _kebab((sc.getAttribute('xsi:type') || 'DiagramModelConnection').replace(/^[a-z]+:/, '')),
+            connectionType: Number(sc.getAttribute('type')) || 0,
+            archi: _archiExtras(sc, ARCHI_LINE_HANDLED),   // a line's lock passes through as written
+            name: sc.getAttribute('name') || '',
+            style: _parseStyle(sc),
+            features: _parseFeatures(sc),
+            ...(bendpoints.length && { bendpoints }),
+        });
+    }
+
+    for (const child of el.children.filter(c => c.tagName === 'child')) {
+        visual.children.push(_parseVisual(child));
+    }
+
+    return visual;
+}
+
+function _parseBounds(el) {
+    const bounds = el.querySelector('bounds');
+    if (!bounds) return null;
+    return {
+        x: Number(bounds.getAttribute('x')),
+        y: Number(bounds.getAttribute('y')),
+        width: Number(bounds.getAttribute('width')),
+        height: Number(bounds.getAttribute('height')),
+    };
+}
+
+const _kebab = (className) => className.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+
+/** Attributes the model reads or writes itself; anything else on a visual or line is passed through. */
+const ARCHI_HANDLED_ATTRIBUTES = new Set([
+    'xsi:type', 'id', 'archimateElement', 'archimateRelationship', 'source', 'target', 'targetConnections',
+    'name', 'imagePath', 'type', 'text', 'locked',
+]);
+
+/** The feature that names the logical group (ItemGroup) a box is in: Archi has none of its own. */
+export const ARCHI_GROUP_FEATURE = 'renderengine.group';
+/** The feature that names the kind of that group when it is not a plain one ('background': a template's, pinned behind). */
+export const ARCHI_GROUP_KIND_FEATURE = 'renderengine.groupKind';
+/** The feature that fixes a box in place where Archi has no lock of its own (anything but a canvas box). */
+export const ARCHI_LOCK_FEATURE = 'renderengine.locked';
+/** The feature that marks a view as a template (kept to copy from): Archi has no such flag. */
+export const ARCHI_TEMPLATE_FEATURE = 'renderengine.template';
+
+/** The visuals Archi itself can lock (ILockable: its canvas classes). */
+const ARCHI_LOCKABLE = new Set(['canvas-model-block', 'canvas-model-sticky', 'canvas-model-image', 'canvas-model-connection']);
+/** A line's lock is not the arrangement's (which holds boxes): it passes through. */
+const ARCHI_LINE_HANDLED = {
+    attributes: new Set(['xsi:type', 'id', 'archimateElement', 'archimateRelationship', 'source', 'target', 'targetConnections', 'name', 'imagePath', 'type', 'text']),
+    elements: null,   // set below, once ARCHI_HANDLED_ELEMENTS exists
+    style: true,
+};
+/** Child elements the model reads itself. */
+const ARCHI_HANDLED_ELEMENTS = new Set(['child', 'sourceConnection', 'bounds', 'content', 'feature', 'property', 'bendpoint', 'documentation']);
+ARCHI_LINE_HANDLED.elements = ARCHI_HANDLED_ELEMENTS;
+
+/**
+ * What a visual or line carries that the model does not use, kept to write back:
+ * other attributes (locked, hintTitle, imagePosition, alpha, ...), other child
+ * elements (hintContent, notes, ...) and the raw style attributes.
+ * @private
+ */
+function _archiExtras(el, handled = { attributes: ARCHI_HANDLED_ATTRIBUTES, elements: ARCHI_HANDLED_ELEMENTS, style: true }) {
+    const attributes = {};
+    const locked = handled.attributes === ARCHI_HANDLED_ATTRIBUTES && el.getAttribute('locked') === 'true';
+    for (const [name, value] of Object.entries(el.attributes ?? {})) {
+        if (handled.attributes.has(name) || name.startsWith('xmlns')) continue;
+        if (handled.style && ARCHI_STYLE_ATTRIBUTES.includes(name)) continue;
+        attributes[name] = value;
+    }
+    const elements = el.children
+        .filter(c => !handled.elements.has(c.tagName))
+        .map(c => ({ tag: c.tagName, text: c.textContent, attributes: { ...(c.attributes ?? {}) } }));
+    return { attributes, elements, ...(handled.style && { style: _parseStyle(el) }), ...(locked && { locked: true }) };
+}
+
+/** What a concept (element or relationship) carries that the model does not read: accessType,
+ *  strength, profiles, ...; null when nothing. Written back on export. @private */
+const ARCHI_CONCEPT_HANDLED = {
+    attributes: new Set(['xsi:type', 'id', 'name', 'source', 'target', 'directed']),
+    elements: new Set(['documentation', 'property']),
+};
+/** The same for a view (hintTitle, viewpoint, connectionRouterType, hintContent, ...). */
+const ARCHI_VIEW_HANDLED = {
+    attributes: new Set(['xsi:type', 'id', 'name']),
+    elements: new Set(['documentation', 'property', 'child']),
+};
+/** The same for the model (its profiles, metadata, ...). */
+const ARCHI_MODEL_HANDLED = {
+    attributes: new Set(['id', 'name', 'version']),
+    elements: new Set(['folder', 'purpose', 'property']),
+};
+
+/** Extras with nothing in them are null. @private */
+function _extrasOrNull(extras) {
+    return Object.keys(extras.attributes).length || extras.elements.length ? extras : null;
+}
+
+/** Child elements kept as {tag, text, attributes}, as lines. @private */
+function _extraElementLines(elements = [], indent) {
+    return elements.map(({ tag, text = '', attributes = {} }) => {
+        const attrText = Object.entries(attributes).map(([k, v]) => ` ${k}="${_escapeAttr(v)}"`).join('');
+        return text ? `${indent}<${tag}${attrText}>${_escapeXml(text)}</${tag}>` : `${indent}<${tag}${attrText}/>`;
+    });
+}
+
+/** An instance's `archi` record from its parsed visual and its appearance as imported
+ *  (null when there is nothing to keep). @private */
+function _archiRecord(visual, appearance) {
+    const record = {
+        ...(visual.id && { id: visual.id }),   // Archi's id for the visual, kept on export
+        ...(visual.archiImagePath && { imagePath: visual.archiImagePath }),   // its picture's path in the archive
+        ...visual.archi,
+        ...(visual.name && { name: visual.name }),
+        ...(Object.keys(visual.features ?? {}).length && { features: { ...visual.features } }),
+    };
+    return { ...record, appearance: { ...appearance } };
+}
+
+/** Archi keeps a box's line transparency as a feature, not an attribute. */
+const ARCHI_LINE_ALPHA_FEATURE = 'lineAlpha';
+
+/** Which appearance fields each Archi style attribute sets. */
+const STYLE_FIELDS = Object.freeze({
+    fillColor: ['fillColor'], lineColor: ['strokeColor'], borderColor: ['strokeColor'], fontColor: ['textColor'],
+    font: ['fontFamily', 'fontSize', 'fontWeight', 'fontStyle'], lineWidth: ['strokeWidth'],
+    textAlignment: ['textAlign'], textPosition: ['textPosition'],
+    // Transparency: no fill is alpha 0, no line is the lineAlpha feature at 0.
+    alpha: ['fillColor'], [ARCHI_LINE_ALPHA_FEATURE]: ['strokeColor'],
+});
+
+/**
+ * Archi's style attributes for an appearance: the original value of each one
+ * whose meaning is unchanged since import (so values the model does not model,
+ * and a font's full SWT string, survive), and the appearance's own value for
+ * any changed. Without a record, what the appearance says.
+ * @private
+ */
+function _exportStyle(appearance = {}, record = null, { border = false, box = true } = {}) {
+    const original = record?.style ?? {};
+    const before = record?.appearance ?? _appearanceFromStyle(original, { box });
+    const mapped = _styleFromAppearance(appearance, { border, box });
+    const style = {};
+    for (const [attribute, fields] of Object.entries(STYLE_FIELDS)) {
+        const unchanged = fields.every(f => before[f] === appearance[f]);
+        if (unchanged && original[attribute] !== undefined) style[attribute] = original[attribute];
+        else if (!unchanged && mapped[attribute] !== undefined) style[attribute] = mapped[attribute];
+    }
+    return style;
+}
+
+/** Archi's style attributes on a box or line, as written (colours are "#rrggbb"). */
+const ARCHI_STYLE_ATTRIBUTES = Object.freeze([
+    'fillColor', 'lineColor', 'borderColor', 'fontColor', 'font', 'lineWidth', 'textAlignment', 'textPosition', 'alpha',
+]);
+
+/** The style attributes an element carries. @private */
+function _parseStyle(el) {
+    const style = {};
+    for (const name of ARCHI_STYLE_ATTRIBUTES) {
+        const value = el.getAttribute(name);
+        if (value !== null && value !== undefined && value !== '') style[name] = value;
+    }
+    const lineAlpha = el.children?.find(c => c.tagName === 'feature' && c.getAttribute('name') === ARCHI_LINE_ALPHA_FEATURE);
+    if (lineAlpha) style[ARCHI_LINE_ALPHA_FEATURE] = lineAlpha.getAttribute('value');
+    return style;
+}
+
+/** Archi's text alignment (draw2d PositionConstants) and our names for it. */
+const TEXT_ALIGN = Object.freeze({ 1: 'left', 2: 'center', 4: 'right' });
+/** Archi's text position (top, centre, bottom of the box). */
+const TEXT_POSITION = Object.freeze({ 0: 'top', 1: 'middle', 2: 'bottom' });
+
+/**
+ * An instance's appearance (ElementInstance#appearance) from Archi's style:
+ * fill, line (Archi's lineColor, or borderColor on groups and notes), text
+ * colour, line width, font, and text alignment and position.
+ * @private
+ */
+function _appearanceFromStyle(style = {}, { box = true } = {}) {
+    const a = {};
+    if (style.fillColor) a.fillColor = style.fillColor;
+    const line = style.lineColor ?? style.borderColor;
+    if (line) a.strokeColor = line;
+    if (style.fontColor) a.textColor = style.fontColor;
+    if (style.lineWidth) a.strokeWidth = Number(style.lineWidth);
+    if (box && style.alpha === '0') a.fillColor = 'none';
+    if (box && style[ARCHI_LINE_ALPHA_FEATURE] === '0') a.strokeColor = 'none';
+    Object.assign(a, _parseFontFeature(style.font));
+    // Archi centres a box's text unless the box says otherwise.
+    if (TEXT_ALIGN[style.textAlignment] || box) a.textAlign = TEXT_ALIGN[style.textAlignment] ?? 'center';
+    if (TEXT_POSITION[style.textPosition]) a.textPosition = TEXT_POSITION[style.textPosition];
+    return a;
+}
+
+/** Archi's style attributes back from an appearance (the inverse of _appearanceFromStyle). @private */
+function _styleFromAppearance(a = {}, { border = false, box = true } = {}) {
+    const style = {};
+    if (a.fillColor === 'none') style.alpha = '0';
+    else if (a.fillColor) style.fillColor = a.fillColor;
+    if (box && a.strokeColor === 'none') style[ARCHI_LINE_ALPHA_FEATURE] = '0';
+    if (a.strokeColor && a.strokeColor !== 'none') style[border ? 'borderColor' : 'lineColor'] = a.strokeColor;
+    if (a.textColor) style.fontColor = a.textColor;
+    if (a.strokeWidth !== undefined) style.lineWidth = String(a.strokeWidth);
+    if (a.fontFamily || a.fontSize || a.fontWeight || a.fontStyle) style.font = _fontString(a);
+    const align = Object.entries(TEXT_ALIGN).find(([, name]) => name === a.textAlign)?.[0];
+    if (align) style.textAlignment = align;
+    const position = Object.entries(TEXT_POSITION).find(([, name]) => name === a.textPosition)?.[0];
+    if (position) style.textPosition = position;
+    return style;
+}
+
+function _parseFeatures(el) {
+    const features = {};
+    for (const f of el.children.filter(c => c.tagName === 'feature')) {
+        if (f.getAttribute('name') === ARCHI_LINE_ALPHA_FEATURE) continue;   // style (see _parseStyle)
+        features[f.getAttribute('name')] = f.getAttribute('value');
+    }
+    return features;
+}
+
+/** An element's own properties as [{key, value}], in file order (Archi allows a key more than once). @private */
+function _propertyPairs(el) {
+    return el.children.filter(c => c.tagName === 'property').map(p => ({ key: p.getAttribute('key') ?? '', value: p.getAttribute('value') ?? '' }));
+}
+
+function _parseProperties(el) {
+    const props = {};
+    for (const p of el.children.filter(c => c.tagName === 'property')) {
+        props[p.getAttribute('key')] = p.getAttribute('value');
+    }
+    return props;
+}
+
+/** Archi native format stores flat string properties. RenderEngine stores a
+ *  typed array `{name, type, value}`. Import converts everything to 'string'
+ *  by default; callers can retype in the UI. */
+function _propertiesToTypedArray(props) {
+    if (!props || Object.keys(props).length === 0) return undefined;
+    return Object.entries(props).map(([name, value]) => ({ name, type: 'string', value }));
+}
+
+/** Export: stringify typed values back to Archi's flat key/value strings. */
+function _typedArrayToProperties(arr) {
+    const out = {};
+    for (const { name, value } of arr || []) {
+        if (!name) continue;
+        out[name] = value == null ? '' : String(value);
+    }
+    return out;
+}
+
+/** The text of an element's own child `tagName` (not a nested element's: a canvas block holds stickies with their own content). @private */
+function _childText(el, tagName) {
+    const child = el.children.find(c => c.tagName === tagName);
+    return child ? child.textContent : null;
+}
+
+/** Convert a parsed Archi model into an ArchimateModel (with views).
+ *  @param {Object} archiModel - parsed Archi XML model
+ *  @returns {ArchimateModel} with one view per original view (elementIds track which elements appear in each view)
+ *  Now applies visual bounds/waypoints per view. */
+export function toArchimateModel(archiModel) {
+    const elements = [];
+    const relationships = [];
+    const folders = [];
+    const elementFolders = [];
+    const views = [];
+    const elementById = new Map();
+    const relationshipById = new Map();
+
+    // Map all elements first
+    for (const el of archiModel.elements || []) {
+        const mapped = _mapElement(el);
+        elementById.set(el.id, mapped);
+        elements.push(mapped);
+    }
+
+    // Map all relationships
+    for (const rel of archiModel.relationships || []) {
+        const mapped = _mapRelationship(rel);
+        relationshipById.set(rel.id, mapped);
+        relationships.push(mapped);
+    }
+
+    // Each view: one instance per box Archi draws, and one per line.
+    for (const archiView of archiModel.views || []) {
+        const v = _viewInstances(archiView, { elementById, relationshipById });
+        // Our template flag is a feature on the view; the rest of its extras pass through.
+        const isTemplateFeature = (e) => e.tag === 'feature' && e.attributes?.name === ARCHI_TEMPLATE_FEATURE;
+        const template = !!archiView.archi?.elements?.some(e => isTemplateFeature(e) && e.attributes?.value === 'true');
+        if (archiView.archi?.elements) archiView.archi.elements = archiView.archi.elements.filter(e => !isTemplateFeature(e));
+        views.push({
+            id: archiView.id,
+            name: archiView.name,
+            ...(archiView.documentation && { documentation: archiView.documentation }),
+            elementIds: v.elementIds,
+            elementInstances: v.elementInstances,
+            relationshipInstances: v.relationshipInstances,
+            viewConnections: v.viewConnections,
+            arrangement: v.arrangement,
+            archiViewType: archiView.type,
+            ...(template && { template }),
+            ...(archiView.properties?.length && { properties: archiView.properties }),
+            ...(archiView.archiFolder && { archiFolder: archiView.archiFolder }),
+            ...(archiView.archi && { archi: archiView.archi }),
+            ...(v.folders.length && { folders: v.folders, folderLayout: v.folderLayout }),
+        });
+        folders.push(...v.folders);
+        elementFolders.push(...v.elementFolders);
+    }
+
+    return new ArchimateModel({
+        id: archiModel.id ?? undefined,
+        name: archiModel.name ?? '', elements, relationships, folders, elementFolders, views,
+        documentation: archiModel.documentation || undefined, properties: archiModel.properties ?? [],
+        // The specializations written for element types Archi lacks are not the model's own.
+        archi: archiModel.archi ? {
+            ...archiModel.archi,
+            elements: (archiModel.archi.elements ?? []).filter(e => !(e.tag === 'profile' && String(e.attributes?.id ?? '').startsWith(ARCHI_TYPE_PROFILE_PREFIX))),
+        } : null,
+    });
+}
+
+/** Where a visual sits on the view. Archi stores a nested visual's bounds
+ *  relative to its parent (a group, or an element drawn inside another), so
+ *  they are offset by the parent's absolute position. Null without bounds. @private */
+function _absoluteBounds(visual, origin) {
+    if (!visual.bounds) return null;
+    const { x, y, width, height } = visual.bounds;
+    const size = ARCHI_DEFAULT_SIZE[visual.type] ?? ARCHI_ELEMENT_SIZE;
+    return {
+        x: origin.x + x, y: origin.y + y,
+        width: width > 0 ? width : size.width,
+        height: height > 0 ? height : size.height,
+    };
+}
+
+const VIEW_ORIGIN = Object.freeze({ x: 0, y: 0 });
+
+/**
+ * Boxes on canvas and sketch views: no model element behind them, drawn as a
+ * shape with text (and, for a canvas sticky, maybe a picture). Archi type ->
+ * the renderer's shape.
+ */
+const VIEW_BOX_SHAPES = Object.freeze({
+    'canvas-model-block': 'rect',
+    'canvas-model-sticky': 'rect',
+    'sketch-model-sticky': 'rect',
+    'sketch-model-actor': 'stick-figure',
+});
+
+/** What a view-only box draws (a ViewObjectInstance's content), from its Archi visual. @private */
+function _viewObjectContent(visual) {
+    return _viewObjectDrawing(visual);
+}
+
+/** @private */
+function _viewObjectDrawing(visual) {
+    const text = visual.text || visual.name || '';
+    if (visual.type === 'diagram-model-note') {
+        // A note's text is its own content; an empty one shows its name, if any (Archi's legend note).
+        return { id: visual.id, name: visual.text || visual.name || '', label: visual.text || '', shape: 'note' };
+    }
+    if (visual.type === 'diagram-model-image' || visual.type === 'canvas-model-image') {
+        return {
+            id: visual.id, name: visual.name || 'Image', shape: 'image', iconUrl: visual.imagePath,
+            ...(visual.properties?.href && { href: visual.properties.href }),
+            ...(visual.type === 'canvas-model-image' && { archiVisualType: visual.type }),
+        };
+    }
+    const shape = VIEW_BOX_SHAPES[visual.type];
+    if (!shape) return null;
+    return {
+        id: visual.id, name: text, label: text, shape,   // an empty box shows no text
+        archiVisualType: visual.type,
+        ...(visual.imagePath && { iconUrl: visual.imagePath }),
+        ...(visual.notes && { documentation: visual.notes }),
+    };
+}
+
+/** Where a box is drawn: its centre, as the renderer places nodes (Archi keeps the top-left corner). @private */
+const _centreOf = (bounds) => ({ x: bounds.x + bounds.width / 2, y: bounds.y + bounds.height / 2 });
+
+/**
+ * One Archi view as instances: an ElementInstance per box that shows a model
+ * element (so the same element twice is two instances), a ViewObjectInstance
+ * per note or image, each centred on its box with that box's size and style;
+ * a RelationshipInstance per line, joining the two instances it joins, with its
+ * bend points (none is a straight line); groups as folders with their bounds.
+ * @private
+ */
+function _viewInstances(archiView, { elementById, relationshipById }) {
+    const boxes = _visualBoxes(archiView);
+    const elementInstances = new Map();
+    const instanceOfVisual = new Map();   // Archi visual id -> instance id
+    const elementIds = new Set();
+    const folders = [];
+    const folderLayout = {};
+    const elementFolders = [];
+    const lines = [];
+
+    let order = 0;   // document order is Archi's drawing order
+    const locked = [];
+    const groupMembers = new Map();   // group id -> instance ids
+    const groupKinds = new Map();     // group id -> its kind, when not a plain group
+    const place = (inst, bounds, style, type, visual) => {
+        inst.size = { width: bounds.width, height: bounds.height };
+        inst.zIndex = order++;
+        inst.appearance = _appearanceFromStyle(style);
+        // Archi centres a canvas sticky's text vertically unless it says otherwise.
+        if (type === 'canvas-model-sticky' && !TEXT_POSITION[style?.textPosition]) inst.appearance.textPosition = 'middle';
+        // Archi draws a canvas box without a border colour with no border.
+        if (type?.startsWith('canvas-model-') && !style?.borderColor && !style?.lineColor) inst.appearance.strokeColor = 'none';
+        inst.archi = _archiRecord(visual, inst.appearance);
+        // Archi's lock, and our logical group (kept as a feature), go to the view's arrangement.
+        const features = inst.archi?.features ?? {};
+        if (visual.archi?.locked || features[ARCHI_LOCK_FEATURE] === 'true') locked.push(inst.id);
+        const groupId = features[ARCHI_GROUP_FEATURE];
+        if (groupId) (groupMembers.get(groupId) ?? groupMembers.set(groupId, []).get(groupId)).push(inst.id);
+        if (groupId && features[ARCHI_GROUP_KIND_FEATURE]) groupKinds.set(groupId, features[ARCHI_GROUP_KIND_FEATURE]);
+        if (inst.archi?.features) {
+            delete inst.archi.features[ARCHI_GROUP_FEATURE];
+            delete inst.archi.features[ARCHI_GROUP_KIND_FEATURE];
+            delete inst.archi.features[ARCHI_LOCK_FEATURE];
+            if (!Object.keys(inst.archi.features).length) delete inst.archi.features;
+        }
+        elementInstances.set(inst.id, inst);
+        return inst;
+    };
+    const walk = (visual, parentFolderId, origin, parentBoxId = null) => {
+        const bounds = _absoluteBounds(visual, origin);
+        const instanceCount = elementInstances.size;
+        if (bounds) {
+            const { x, y } = _centreOf(bounds);
+            if (visual.archimateElement && elementById.has(visual.archimateElement)) {
+                const inst = place(new ElementInstance(visual.archimateElement, x, y), bounds, visual.style, visual.type, visual);
+                instanceOfVisual.set(visual.id, inst.id);
+                elementIds.add(visual.archimateElement);
+                if (parentFolderId) elementFolders.push([visual.archimateElement, parentFolderId]);
+            } else {
+                // Notes, images, and canvas and sketch boxes: drawn on this view only.
+                const content = _viewObjectContent(visual);
+                if (content) {
+                    const inst = place(new ViewObjectInstance({ ...content, width: bounds.width, height: bounds.height }, x, y), bounds, visual.style, visual.type, visual);
+                    instanceOfVisual.set(visual.id, inst.id);
+                }
+            }
+        }
+        if (visual.type === 'diagram-model-group') {
+            folders.push({
+                id: visual.id,
+                name: visual.name || 'Group',
+                documentation: visual.documentation || undefined,
+                parentId: parentFolderId || undefined,
+                children: [],
+            });
+            if (parentFolderId) folders.find(f => f.id === parentFolderId)?.children.push(visual.id);
+            if (bounds) {
+                // Its paint as an instance keeps it (the canvas editor draws and edits it), and the record to write back.
+                const appearance = _appearanceFromStyle(visual.style);
+                folderLayout[visual.id] = {
+                    x: bounds.x, y: bounds.y, width: bounds.width, height: bounds.height, collapsed: false, zIndex: order++,
+                    appearance, archi: _archiRecord(visual, appearance),
+                };
+            }
+            instanceOfVisual.set(visual.id, visual.id);   // a plain line may end at a group
+        }
+        // A box drawn inside another box, or a note or picture inside a group (an element's group
+        // is its folder): kept so the canvas moves it with its parent and export nests it there again.
+        const isBox = elementInstances.size > instanceCount;
+        const parent = parentBoxId ?? (visual.archimateElement ? null : parentFolderId);
+        if (isBox && parent) {
+            const inst = [...elementInstances.values()].at(-1);
+            inst.archi = { ...(inst.archi ?? {}), parent };
+        }
+        lines.push(...(visual.sourceConnections || []));
+        const folderId = visual.type === 'diagram-model-group' ? visual.id : parentFolderId;
+        const boxId = isBox ? visual.id : (visual.type === 'diagram-model-group' ? null : parentBoxId);
+        for (const child of visual.children || []) walk(child, folderId, bounds ?? origin, boxId);
+    };
+    for (const child of archiView.children || []) walk(child, null, VIEW_ORIGIN);
+
+    const relationshipInstances = new Map();
+    const viewConnections = [];
+    for (const sc of lines) {
+        const source = instanceOfVisual.get(sc.source);
+        const target = instanceOfVisual.get(sc.target);
+        if (!source || !target) continue;
+        if (!sc.relationship) {
+            // A plain line: Archi's connection between any two boxes, or a canvas connection.
+            const connection = new ViewConnectionInstance({
+                id: sc.id, sourceInstanceId: source, targetInstanceId: target,
+                waypoints: sc.bendpoints?.length ? _bendpointLocations(sc, boxes) : [],
+                type: sc.connectionType, label: sc.name, appearance: _appearanceFromStyle(sc.style, { box: false }), archiType: sc.archiType,
+            });
+            connection.archi = _archiRecord(sc, connection.appearance);
+            viewConnections.push(connection);
+            continue;
+        }
+        if (!relationshipById.has(sc.relationship)) continue;
+        const inst = new RelationshipInstance(sc.relationship, sc.bendpoints?.length ? _bendpointLocations(sc, boxes) : [], source, target);
+        inst.appearance = _appearanceFromStyle(sc.style, { box: false });
+        inst.archi = _archiRecord(sc, inst.appearance);
+        relationshipInstances.set(inst.id, inst);
+    }
+    const arrangement = {
+        // A plain group needs two members; a kind of group (a background) may have one.
+        groups: [...groupMembers].filter(([id, ids]) => ids.length > 1 || groupKinds.has(id))
+            .map(([id, memberIds]) => ({ id, memberIds, ...(groupKinds.has(id) && { kind: groupKinds.get(id) }) })),
+        locked,
+    };
+    return { elementIds: [...elementIds], elementInstances, relationshipInstances, viewConnections, folders, folderLayout, elementFolders, arrangement };
+}
+
+/** Convert a parsed Archi model into renderengine inputs.
+ *  Returns `{ elements, relationships, options }` ready for `archimateDiagram()`.
+ *  If `viewId` is omitted, the first view is used.
+ *  Kept as original for backward compatibility: applies visual bounds/features and handles all view visuals. */
+export function toRenderEngineModel(archiModel, viewId) {
+    const view = viewId
+        ? archiModel.views.find(v => v.id === viewId)
+        : archiModel.views[0];
+
+    const elements = [];
+    const relationships = [];
+    const annotations = [];
+    const elementById = new Map();
+    const relationshipById = new Map();
+
+    for (const el of archiModel.elements || []) {
+        const mapped = _mapElement(el);
+        elementById.set(el.id, mapped);
+        elements.push(mapped);
+    }
+
+    for (const rel of archiModel.relationships || []) {
+        const mapped = _mapRelationship(rel);
+        relationshipById.set(rel.id, mapped);
+        relationships.push(mapped);
+    }
+
+    const folders = [];
+    const folderLayout = {};
+    const elementFolders = []; // Array of [elementId, folderId] pairs
+
+    if (view) {
+        const boxes = _visualBoxes(view);
+        for (const visual of view.children || []) {
+            _mapVisual(visual, { elementById, relationshipById, elements, relationships, annotations, folders, folderLayout, elementFolders, boxes });
+        }
+    }
+
+    const options = {
+        annotations,
+        archimateVersion: '4',
+    };
+
+    return { elements, relationships, folders, folderLayout, elementFolders, options };
+}
+
+function _mapElement(el) {
+    const archiType = _toKebabType(el.type);
+    const layer = ArchimateNotation.elementLayer({ type: archiType });
+    // A type Archi has no class for was written as the nearest one, with its own kept as a feature.
+    const ownType = el.archi?.elements?.find(e => e.tag === 'feature' && e.attributes?.name === ARCHI_TYPE_FEATURE)?.attributes?.value;
+    const mapped = {
+        id: el.id,
+        name: el.name,
+        type: ownType || archiType,
+        layer: layer !== 'other' ? layer : undefined,
+        documentation: el.documentation || undefined,
+    };
+    const props = _propertiesToTypedArray(el.properties);
+    if (props) mapped.properties = props;
+    if (el.archiFolder) mapped.archiFolder = el.archiFolder;
+    if (el.archi) mapped.archi = ownType ? _withoutTypeMarks(el.archi) : el.archi;
+    return mapped;
+}
+
+/** An element's archi record without the feature and specialization written for its own type. @private */
+function _withoutTypeMarks(archi) {
+    const attributes = { ...(archi.attributes ?? {}) };
+    if (String(attributes.profiles ?? '').startsWith(ARCHI_TYPE_PROFILE_PREFIX)) delete attributes.profiles;
+    return {
+        ...archi,
+        attributes,
+        elements: (archi.elements ?? []).filter(e => !(e.tag === 'feature' && e.attributes?.name === ARCHI_TYPE_FEATURE)),
+    };
+}
+
+function _mapRelationship(rel) {
+    const base = _toKebabType(rel.type).replace(/-relationship$/, '');
+    const kind = base === 'association' && rel.directed ? 'association-directed' : base;
+    const mapped = {
+        id: rel.id,
+        source: rel.source,
+        target: rel.target,
+        kind,
+        label: rel.name || undefined,
+        documentation: rel.documentation || undefined,
+    };
+    const props = _propertiesToTypedArray(rel.properties);
+    if (props) mapped.properties = props;
+    if (rel.archiFolder) mapped.archiFolder = rel.archiFolder;
+    if (rel.archi) mapped.archi = rel.archi;
+    return mapped;
+}
+
+function _mapVisual(visual, ctx, parentBounds = null, parentFolderId = null, origin = VIEW_ORIGIN) {
+    const own = _absoluteBounds(visual, origin);
+    const bounds = own || parentBounds || { x: 0, y: 0, width: 120, height: 55 };
+    // Children are placed relative to this visual if it has bounds, else as it is placed.
+    const childOrigin = own ?? origin;
+    // Placed by its centre, as the renderer draws nodes; styled under the renderer's names.
+    const { x, y } = _centreOf(bounds);
+    const { fillColor, ...appearance } = _appearanceFromStyle(visual.style);
+    const visualProps = {
+        x, y,
+        width: bounds.width,
+        height: bounds.height,
+        ...appearance,
+        ...(fillColor && { color: fillColor }),
+    };
+
+    if (visual.archimateElement) {
+        const element = ctx.elementById.get(visual.archimateElement);
+        if (element) {
+            Object.assign(element, visualProps);
+            // A DiagramObject may carry a per-view text override.
+            if (visual.text) element.label = visual.text;
+        }
+        // Track which folder contains this element (if any)
+        if (parentFolderId && ctx.elementFolders) {
+            ctx.elementFolders.push([visual.archimateElement, parentFolderId]);
+        }
+        // On to its connections and to the elements drawn inside it (below).
+    }
+
+    const base = { id: visual.id, ...visualProps };
+
+    if (visual.type === 'diagram-model-note') {
+        ctx.annotations.push({
+            ...base,
+            label: visual.text || 'Note',
+            shape: 'note',
+        });
+        return;
+    }
+
+    if (visual.type === 'diagram-model-group') {
+        const folder = {
+            id: visual.id,
+            name: visual.name || 'Group',
+            documentation: visual.documentation || undefined,
+            parentId: parentFolderId || undefined,
+            children: [],
+        };
+        ctx.folders.push(folder);
+        ctx.folderLayout[visual.id] = {
+            x: bounds.x,
+            y: bounds.y,
+            width: visualProps.width,
+            height: visualProps.height,
+            collapsed: false,
+        };
+        // Recurse into children with this folder as parent
+        for (const child of visual.children || []) {
+            _mapVisual(child, ctx, bounds, visual.id, childOrigin);
+        }
+        return;
+    }
+
+    if (visual.type === 'diagram-model-image') {
+        ctx.annotations.push({
+            ...base,
+            label: visual.name || '',
+            iconUrl: visual.imagePath,
+            shape: 'image',
+            href: visual.properties?.href,
+        });
+        return;
+    }
+
+    if (visual.type === 'diagram-model-reference') {
+        ctx.annotations.push({
+            ...base,
+            label: visual.name || 'Reference',
+            reference: visual.referencedModel,
+            shape: 'note',
+        });
+        return;
+    }
+
+    if ([
+        'sketch-model-sticky', 'sketch-model-actor',
+        'canvas-model-block', 'canvas-model-sticky', 'canvas-model-image',
+    ].includes(visual.type)) {
+        ctx.annotations.push({
+            ...base,
+            label: visual.text || visual.name || visual.type,
+            archiVisualType: visual.type,
+            shape: visual.type.endsWith('-image') ? 'rect' : 'note',
+        });
+        return;
+    }
+
+    // An element's connections, then the visuals nested in it.
+    for (const sc of visual.sourceConnections || []) {
+        if (sc.relationship && sc.bendpoints?.length) {
+            // Apply bendpoints from the visual connection to the relationship model
+            const rel = ctx.relationshipById?.get(sc.relationship);
+            if (rel) {
+                rel.waypoints = _bendpointLocations(sc, ctx.boxes);
+            }
+        }
+    }
+
+    for (const child of visual.children || []) {
+        _mapVisual(child, ctx, bounds, parentFolderId, childOrigin);
+    }
+}
+
+function _toKebabType(name) {
+    if (!name) return '';
+    return name
+        .replace(/^archimate:/, '')
+        .replace(/([a-z])([A-Z])/g, '$1-$2')
+        .toLowerCase();
+}
+
+/**
+ * Archi's font: SWT FontData, "version|name|height in points|style|platform|...",
+ * style bit 1 bold, bit 2 italic. The size is kept in points ("9pt"), which SVG
+ * draws as Archi does.
+ * @private
+ */
+function _parseFontFeature(fontString) {
+    if (!fontString) return {};
+    const [, family, height, style] = fontString.split('|');
+    const result = {};
+    if (family) result.fontFamily = family;
+    if (height && Number(height) > 0) result.fontSize = `${Number(height)}pt`;
+    const bits = Number(style) || 0;
+    if (bits & 1) result.fontWeight = 'bold';
+    if (bits & 2) result.fontStyle = 'italic';
+    return result;
+}
+
+/** A font as SWT FontData's leading fields, which Archi reads (inverse of _parseFontFeature). @private */
+function _fontString({ fontFamily = 'Segoe UI', fontSize = '9pt', fontWeight, fontStyle } = {}) {
+    const points = String(fontSize).endsWith('px') ? parseFloat(fontSize) * 0.75 : parseFloat(fontSize);
+    const bits = (fontWeight === 'bold' ? 1 : 0) | (fontStyle === 'italic' ? 2 : 0);
+    return `1|${fontFamily}|${points}|${bits}`;
+}
+
+/** Convert an ArchimateView to Archi's visual-tree shape, ready for toArchiXML.
+ *  Returns array of visual child objects with bounds, sourceConnections (including bendpoints), and nested children.
+ *  This is the export-side bridge: ArchimateView → Archi visual tree → XML. */
+export function fromArchimateView(view) {
+    const visuals = [];
+    const relationshipsBySource = new Map();
+    const folderById = new Map();
+
+    // Index relationships by source visual ID for quick lookup
+    for (const rel of view.relationships || []) {
+        if (rel.viewConnection) continue;   // plain lines are written from view.viewConnections (below)
+        if (!relationshipsBySource.has(rel.source)) {
+            relationshipsBySource.set(rel.source, []);
+        }
+        relationshipsBySource.get(rel.source).push(rel);
+    }
+
+    // Groups: an ArchimateView's placedFolders (each after its parent, parentId the
+    // nearest group on the view); a plain view object's `folders` are all top level.
+    const groups = view.placedFolders ?? (view.folders || []).map(f => ({ ...f, parentId: undefined }));
+    const absolute = new Map();   // visual -> its bounds on the view
+    const stacking = new Map();   // visual -> its zIndex (Infinity: on top, in the order placed)
+    /** Put a visual on the view, or inside the group `groupId` with bounds relative to it. */
+    const placedById = new Map();   // visual id -> visual, for nesting a box in its box
+    const place = (visual, groupId, zIndex = Infinity, parentBoxId = null) => {
+        absolute.set(visual, visual.bounds);
+        stacking.set(visual, zIndex);
+        placedById.set(visual.id, visual);
+        const group = (parentBoxId && placedById.get(parentBoxId)) || (groupId && folderById.get(groupId));
+        if (!group) { visuals.push(visual); return; }
+        const origin = absolute.get(group);
+        visual.bounds = { ...visual.bounds, x: visual.bounds.x - origin.x, y: visual.bounds.y - origin.y };
+        (group.children ??= []).push(visual);   // a box gets its first child here
+    };
+    for (const folder of groups) {
+        const { x = 0, y = 0, width = 200, height = 150 } = view.folderLayout?.[folder.id] ?? folder;
+        const folderVisual = {
+            id: folder.id,
+            type: 'diagram-model-group',
+            name: folder.name,
+            bounds: { x, y, width, height },
+            children: [],
+            sourceConnections: [],
+        };
+        // Its paint as the view has it now: the original attributes where unchanged (as for a box).
+        _applyArchiRecord(folderVisual, folder.archi, folder.appearance ? _exportStyle(folder.appearance, folder.archi, { border: true }) : (folder.archi?.style ?? {}));
+        const folderZ = view.folderLayout?.[folder.id]?.zIndex ?? folder.zIndex;
+        if (folder.documentation) {
+            folderVisual.documentation = folder.documentation;
+        }
+        folderById.set(folder.id, folderVisual);
+        place(folderVisual, folder.parentId, folderZ ?? Infinity);
+    }
+
+    /** The visual id for a drawn item: Archi's own when it was imported, else one made from the instance id. */
+    const visualIdOf = (instanceId) => view.getElementInstance?.(instanceId)?.visualId ?? `diag-${instanceId}`;
+
+    // One visual per drawn item. A view's items carry their instance id as `id`
+    // and the model element's as `elementId` (a plain {id} item is both).
+    // Each item is placed by its centre, as the renderer draws it; Archi keeps the
+    // top-left corner, in whole pixels. A box nested in another is placed after it
+    // (whichever was added first), so it goes inside it.
+    const byVisualId = new Map((view.elements || []).map(el => [visualIdOf(el.id), el]));
+    const depthOf = (el, seen = new Set()) => {
+        const parent = byVisualId.get(view.getElementInstance?.(el.id)?.nestedIn);
+        return parent && !seen.has(parent) ? 1 + depthOf(parent, seen.add(el)) : 0;
+    };
+    const inPlacingOrder = (view.elements || []).map((el, i) => [el, depthOf(el), i]).sort((a, b) => a[1] - b[1] || a[2] - b[2]).map(([el]) => el);
+    for (const el of inPlacingOrder) {
+        const width = el.width || ARCHI_ELEMENT_SIZE.width;
+        const height = el.height || ARCHI_ELEMENT_SIZE.height;
+        const bounds = { x: Math.round((el.x || 0) - width / 2), y: Math.round((el.y || 0) - height / 2), width, height };
+        const visual = el.viewObject
+            ? { ..._viewObjectVisual(el, bounds), id: visualIdOf(el.id) }
+            : {
+                id: visualIdOf(el.id),
+                type: 'diagram-model-object',
+                archimateElement: el.elementId ?? el.id,
+                bounds,
+                sourceConnections: [],
+            };
+        // This view's style for the box (an ArchimateView keeps it on the instance), and what the file said besides.
+        const instance = view.getElementInstance?.(el.id);
+        _applyArchiRecord(visual, instance?.archi, _exportStyle(instance?.appearance, instance?.archi, { border: !!el.viewObject }));
+        // Fixed in place (on its own or in a locked group): Archi's lock where Archi has one (canvas
+        // boxes), else a feature Archi keeps. Its logical group: a feature.
+        if (view.arrangement?.isLocked(el.id)) {
+            if (ARCHI_LOCKABLE.has(visual.type)) visual.locked = true;
+            else visual.features = { ...(visual.features ?? {}), [ARCHI_LOCK_FEATURE]: 'true' };
+        }
+        const itemGroup = view.arrangement?.groupOf(el.id);
+        if (itemGroup) {
+            const kind = itemGroup.constructor.kind;
+            visual.features = { ...(visual.features ?? {}), [ARCHI_GROUP_FEATURE]: itemGroup.id, ...(kind !== 'group' && { [ARCHI_GROUP_KIND_FEATURE]: kind }) };
+        }
+
+        // Add connections from this element to others
+        const rels = relationshipsBySource.get(el.id) || [];
+        for (const rel of rels) {
+            const sc = {
+                id: view.relationshipInstances?.get?.(rel.id)?.archi?.id ?? `conn-${rel.id}`,
+                source: visual.id,
+                target: visualIdOf(rel.target),
+                relationship: rel.relationshipId ?? rel.id,
+                type: 'archimate:Connection',
+            };
+            const line = view.relationshipInstances?.get?.(rel.id);
+            _applyArchiRecord(sc, line?.archi, _exportStyle(line?.appearance, line?.archi, { box: false }));
+            if (rel.waypoints?.length) {
+                // Points on the view for now; made relative once every box is known (below).
+                sc.bendpoints = rel.waypoints.map(wp => ({ x: wp.x, y: wp.y }));
+            }
+            visual.sourceConnections.push(sc);
+        }
+
+        if (instance?.archi?.imagePath) visual.archiImagePath = instance.archi.imagePath;
+        place(visual, el.viewObject ? undefined : view.placedFolderOf?.(el.elementId ?? el.id), el.zIndex ?? Infinity, instance?.archi?.parent);
+    }
+
+    // Plain lines (no relationship): on their source box, with their own class and type bits.
+    const visualOf = new Map();
+    const index = (v) => { visualOf.set(v.id, v); (v.children || []).forEach(index); };
+    visuals.forEach(index);
+    for (const connection of view.viewConnections?.values?.() ?? []) {
+        // An end is a box (exported as "diag-<instance id>") or a group (under its own id).
+        const visualFor = (end) => visualOf.get(visualIdOf(end)) ?? visualOf.get(end);
+        const source = visualFor(connection.sourceInstanceId);
+        const target = visualFor(connection.targetInstanceId);
+        if (!source || !target) continue;
+        const sc = {
+            id: connection.id,
+            source: source.id,
+            target: target.id,
+            archiType: connection.archiType,
+            connectionType: connection.type,
+            name: connection.label || '',
+            ...(connection.waypoints.length && { bendpoints: connection.waypoints.map(wp => ({ x: wp.x, y: wp.y })) }),
+        };
+        _applyArchiRecord(sc, connection.archi, _exportStyle(connection.appearance, connection.archi, { box: false }));
+        source.sourceConnections.push(sc);
+    }
+
+    // Each level in stacking order (Archi draws in document order); ties keep their order.
+    const byStacking = (list) => {
+        list.sort((a, b) => stacking.get(a) - stacking.get(b));
+        list.forEach(v => byStacking(v.children ?? []));
+    };
+    byStacking(visuals);
+
+    _relativizeLocatedBendpoints({ children: visuals });
+    return visuals;
+}
+
+/**
+ * A model and its views as the writers take them (toArchiXML, toArchiFile,
+ * toExchangeXML): the model's data, and each view as an Archi view tree.
+ * @param {ArchimateModel} model
+ * @returns {[Object, Array<Object>]} `[modelData, views]`, to spread into a writer
+ */
+export function toArchiExport(model) {
+    const views = model.views().map(view => ({
+        id: view.id,
+        name: view.name,
+        type: view.archiViewType,
+        template: view.template,
+        documentation: view.documentation,
+        properties: view.properties,
+        archiFolder: view.archiFolder,
+        archi: view.archi,
+        children: fromArchimateView(view),
+    }));
+    return [{
+        id: model.id || 'model-1',
+        name: model.name || 'ArchiMate Model',
+        version: '5.0.0',
+        documentation: model.documentation,
+        properties: model.properties,
+        archi: model.archi,
+        elements: model.elements(),
+        relationships: model.relationships(),
+    }, views];
+}
+
+/**
+ * Put what the file said about a box or line back on its export visual: the
+ * style to write, its name and features (when it has none of its own), and the
+ * attributes and child elements the model does not use.
+ * @private
+ */
+function _applyArchiRecord(target, record, style) {
+    target.style = style;
+    if (!record) return;
+    if (record.name && !target.name) target.name = record.name;
+    if (record.features) target.features = { ...record.features, ...(target.features ?? {}) };
+    if (Object.keys(record.attributes ?? {}).length) target.extraAttributes = { ...record.attributes };
+    if (record.elements?.length) target.extraElements = record.elements.map(e => ({ ...e }));
+}
+
+/** <property> lines for [{key, value}] pairs (a model's or a view's). @private */
+function _propertyLines(pairs, indent) {
+    return (Array.isArray(pairs) ? pairs : []).map(({ key, value }) => `${indent}<property key="${_escapeAttr(key)}" value="${_escapeAttr(value)}"/>`);
+}
+
+/**
+ * Items written inside a top-level folder, each in the sub-folders its
+ * `archiFolder` path names (rebuilt as Archi had them: ids, names,
+ * documentation, properties); items without a path directly in the folder.
+ * `write(item, indent)` gives an item's lines.
+ * @private
+ */
+function _inSubFolders(items, write, indent = '    ') {
+    const lines = [];
+    const direct = items.filter(item => !item.archiFolder?.length);
+    // Sub-folders in the order they are first named, each holding the items one level deeper.
+    const groups = new Map();
+    for (const item of items.filter(item => item.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}<folder name="${_escapeAttr(step.name)}" id="${_escapeAttr(step.id)}">`);
+        if (step.documentation) lines.push(`${indent}  <documentation>${_escapeXml(step.documentation)}</documentation>`);
+        lines.push(..._inSubFolders(inner, write, indent + '  '));
+        lines.push(..._propertyLines(step.properties, indent + '  '));
+        lines.push(`${indent}</folder>`);
+    }
+    for (const item of direct) lines.push(...write(item, indent));
+    return lines;
+}
+
+/** One element or relationship: its attributes, documentation and properties. @private */
+function _serializeConcept(xsiType, attrs, concept, indent, extraLines = []) {
+    const all = { ...attrs, ...(concept.archi?.attributes ?? {}) };
+    const attrText = Object.entries(all).map(([k, v]) => ` ${k}="${_escapeAttr(v)}"`).join('');
+    const body = [];
+    if (concept.documentation) body.push(`${indent}  <documentation>${_escapeXml(concept.documentation)}</documentation>`);
+    body.push(..._extraElementLines(concept.archi?.elements, `${indent}  `));
+    body.push(...extraLines);
+    for (const [k, v] of Object.entries(_typedArrayToProperties(concept.properties))) {
+        body.push(`${indent}  <property key="${_escapeAttr(k)}" value="${_escapeAttr(v)}"/>`);
+    }
+    if (!body.length) return [`${indent}<element xsi:type="${xsiType}"${attrText}/>`];
+    return [`${indent}<element xsi:type="${xsiType}"${attrText}>`, ...body, `${indent}</element>`];
+}
+
+/** A view-only note or image as its Archi visual. @private */
+function _viewObjectVisual(el, bounds) {
+    const base = { id: `diag-${el.id}`, bounds, sourceConnections: [] };
+    if (el.archiVisualType) {
+        // A canvas or sketch box: its own class, text and picture.
+        return { ...base, type: el.archiVisualType, text: el.label ?? '', ...(el.iconUrl && { imagePath: el.iconUrl }) };
+    }
+    if (el.shape === 'image') {
+        return { ...base, type: el.archiVisualType === 'canvas-model-image' ? 'canvas-model-image' : 'diagram-model-image', name: el.name || '', imagePath: el.iconUrl, ...(el.href && { properties: [{ name: 'href', type: 'string', value: el.href }] }) };
+    }
+    return { ...base, type: 'diagram-model-note', text: el.label ?? '' };
+}
+
+/** Reverse mapping: produce an Archi native XML string from renderengine data. */
+export function toArchiXML(model, views) {
+    const { elements = [], relationships = [] } = model;
+    const viewArray = views || [];
+
+    const lines = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        `<archimate:model xmlns:archimate="${ARCHI_NAMESPACE}" xmlns:canvas="${ARCHI_CANVAS_NAMESPACE}" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" name="${_escapeAttr(model.name || 'Untitled')}" id="${_escapeAttr(model.id || _newId('id'))}" version="${_escapeAttr(model.version || '5.0')}"${Object.entries(model.archi?.attributes ?? {}).map(([k, v]) => ` ${k}="${_escapeAttr(v)}"`).join('')}>`,
+    ];
+
+    // Archi always has its nine top-level folders, and fails to open a model
+    // that lacks some of them while it has a view: write them all, in its order.
+    const byFolder = new Map(ARCHI_FOLDERS.map(folder => [folder.type, []]));
+    // Specializations written for element types Archi lacks, by id.
+    const typeProfiles = new Map();
+    for (const el of elements) {
+        // Archi knows ArchiMate 3.2 only: a version 4 type goes back to its 3.2 one, and a type
+        // Archi has no class for (an IT type, a custom type) to the nearest one.
+        const { folder, type, original } = archiFolderOf(el);
+        let profile = null;
+        // An element Archi already gave a specialization keeps that one.
+        if (original && !el.archi?.attributes?.profiles) {
+            profile = typeProfileId(original);
+            typeProfiles.set(profile, { name: typeDisplayName(original), conceptType: _toPascalType(type) });
+        }
+        byFolder.get(folder.type).push({ el, type, original, profile });
+    }
+    for (const folder of ARCHI_FOLDERS) {
+        const items = byFolder.get(folder.type);
+        const body = [];
+        if (folder.type === 'relations') {
+            body.push(..._inSubFolders(relationships, (rel, indent) => {
+                const name = rel.label ?? rel.name;
+                const directed = rel.kind === 'association-directed';
+                const kind = directed ? 'association' : (rel.kind || 'association');
+                return _serializeConcept(`archimate:${_toPascalType(kind)}Relationship`,
+                    { id: rel.id, ...(name && { name }), source: rel.source, target: rel.target, ...(directed && { directed: 'true' }) }, rel, indent);
+            }));
+        } else if (folder.type === 'diagrams') {
+            body.push(..._inSubFolders(viewArray, (view, indent) => _serializeView(view).map(line => indent.slice(4) + line)));
+        } else {
+            body.push(..._inSubFolders(items.map(item => ({ ...item, archiFolder: item.el.archiFolder })),
+                ({ el, type, original, profile }, indent) => _serializeConcept(`archimate:${_toPascalType(type)}`,
+                    { id: el.id, name: el.name || '', ...(profile && { profiles: profile }) }, el, indent,
+                    original ? [`${indent}  <feature name="${ARCHI_TYPE_FEATURE}" value="${_escapeAttr(original)}"/>`] : [])));
+        }
+        const open = `  <folder name="${_escapeAttr(folder.name)}" id="${folder.type}-folder" type="${folder.type}"`;
+        if (body.length) lines.push(`${open}>`, ...body.map(line => `  ${line}`), '  </folder>');
+        else lines.push(`${open}/>`);
+    }
+
+    // What else the model carried (profiles, ...), its own properties, then its documentation (Archi's "purpose").
+    lines.push(..._extraElementLines(model.archi?.elements, '  '));
+    for (const [id, { name, conceptType }] of typeProfiles) {
+        lines.push(`  <profile name="${_escapeAttr(name)}" id="${id}" conceptType="${conceptType}"/>`);
+    }
+    lines.push(..._propertyLines(model.properties, '  '));
+    if (model.documentation) lines.push(`  <purpose>${_escapeXml(model.documentation)}</purpose>`);
+    lines.push('</archimate:model>');
+    return lines.join('\n');
+}
+
+function _serializeView(view) {
+    const xsiType = {
+        'archimate-diagram-model': 'archimate:ArchimateDiagramModel',
+        'sketch-model': 'archimate:SketchModel',
+        'canvas-model': 'canvas:CanvasModel',
+    }[view.type] || 'archimate:ArchimateDiagramModel';
+
+    const extra = Object.entries(view.archi?.attributes ?? {}).map(([k, v]) => ` ${k}="${_escapeAttr(v)}"`).join('');
+    const lines = [`    <element xsi:type="${xsiType}" name="${_escapeAttr(view.name || 'View')}" id="${view.id}"${extra}>`];
+    // Archi lists each visual's incoming connections on it (targetConnections); without
+    // them it draws a line only when its target happens to be created before its source.
+    const incoming = new Map();
+    const collect = (visual) => {
+        for (const sc of visual.sourceConnections || []) {
+            if (!incoming.has(sc.target)) incoming.set(sc.target, []);
+            incoming.get(sc.target).push(sc.id);
+        }
+        (visual.children || []).forEach(collect);
+    };
+    (view.children || []).forEach(collect);
+    for (const visual of view.children || []) {
+        lines.push(..._serializeVisual(visual, '      ', incoming));
+    }
+    // After the boxes, as Archi writes a view: its documentation, other elements, properties.
+    if (view.documentation) lines.push(`      <documentation>${_escapeXml(view.documentation)}</documentation>`);
+    lines.push(..._extraElementLines(view.archi?.elements, '      '));
+    if (view.template) lines.push(`      <feature name="${ARCHI_TEMPLATE_FEATURE}" value="true"/>`);
+    lines.push(..._propertyLines(view.properties, '      '));
+    lines.push('    </element>');
+    return lines;
+}
+
+function _serializeVisual(visual, indent, incoming = new Map()) {
+    const xsiType = _visualTypeToXSI(visual.type);
+    const attrs = [`xsi:type="${xsiType}"`, `id="${visual.id}"`];
+    if (incoming.get(visual.id)?.length) attrs.push(`targetConnections="${incoming.get(visual.id).join(' ')}"`);
+    if (visual.archimateElement) attrs.push(`archimateElement="${visual.archimateElement}"`);
+    if (visual.referencedModel) attrs.push(`referencedModel="${visual.referencedModel}"`);
+    if (visual.imagePath) attrs.push(`imagePath="${_escapeAttr(visual.imagePath)}"`);
+    if (visual.name) attrs.push(`name="${_escapeAttr(visual.name)}"`);
+    if (visual.locked) attrs.push('locked="true"');
+    const { [ARCHI_LINE_ALPHA_FEATURE]: lineAlpha, ...attributeStyle } = visual.style || {};
+    for (const [name, value] of Object.entries(attributeStyle)) attrs.push(`${name}="${_escapeAttr(value)}"`);
+    for (const [name, value] of Object.entries(visual.extraAttributes || {})) attrs.push(`${name}="${_escapeAttr(value)}"`);
+
+    const lines = [`${indent}<child ${attrs.join(' ')}>`];
+    if (visual.bounds) {
+        const b = visual.bounds;
+        lines.push(`${indent}  <bounds x="${b.x}" y="${b.y}" width="${b.width}" height="${b.height}"/>`);
+    }
+    // A note's text: Archi keeps it in a <content> element.
+    if (visual.text) lines.push(`${indent}  <content>${_escapeXml(visual.text)}</content>`);
+    for (const [name, value] of Object.entries(visual.features || {})) {
+        lines.push(`${indent}  <feature name="${_escapeAttr(name)}" value="${_escapeAttr(String(value))}"/>`);
+    }
+    if (lineAlpha !== undefined) lines.push(`${indent}  <feature name="${ARCHI_LINE_ALPHA_FEATURE}" value="${_escapeAttr(String(lineAlpha))}"/>`);
+    for (const [key, value] of Object.entries(_typedArrayToProperties(visual.properties))) {
+        lines.push(`${indent}  <property key="${_escapeAttr(key)}" value="${_escapeAttr(value)}"/>`);
+    }
+    lines.push(..._extraElementLines(visual.extraElements, `${indent}  `));
+    for (const sc of visual.sourceConnections || []) {
+        // A relationship's line is archimate:Connection; a plain line keeps its own class.
+        const xsiType = sc.relationship ? 'archimate:Connection' : _visualTypeToXSI(sc.archiType ?? 'diagram-model-connection');
+        const scAttrs = [
+            // Archi's default class for a line needs no type, and Archi writes none.
+            ...(xsiType === 'archimate:DiagramModelConnection' ? [] : [`xsi:type="${xsiType}"`]),
+            `id="${sc.id}"`,
+            `source="${sc.source}"`,
+            `target="${sc.target}"`,
+        ];
+        if (sc.relationship) scAttrs.push(`archimateRelationship="${sc.relationship}"`);
+        if (!sc.relationship && sc.name) scAttrs.push(`name="${_escapeAttr(sc.name)}"`);
+        if (!sc.relationship && sc.connectionType) scAttrs.push(`type="${sc.connectionType}"`);
+        for (const [name, value] of Object.entries(sc.style || {})) scAttrs.push(`${name}="${_escapeAttr(value)}"`);
+        for (const [name, value] of Object.entries(sc.extraAttributes || {})) scAttrs.push(`${name}="${_escapeAttr(value)}"`);
+
+        if (sc.bendpoints?.length) {
+            lines.push(`${indent}  <sourceConnection ${scAttrs.join(' ')}>`);
+            for (const bp of sc.bendpoints) {
+                lines.push(`${indent}    <bendpoint ${BENDPOINT_KEYS.map(k => `${k}="${bp[k]}"`).join(' ')}/>`);
+            }
+            lines.push(`${indent}  </sourceConnection>`);
+        } else {
+            lines.push(`${indent}  <sourceConnection ${scAttrs.join(' ')}/>`);
+        }
+    }
+    for (const child of visual.children || []) {
+        lines.push(..._serializeVisual(child, `${indent}  `, incoming));
+    }
+    lines.push(`${indent}</child>`);
+    return lines;
+}
+
+/** Archi's top-level folders, in its order, with the layers whose elements each holds. */
+export const ARCHI_FOLDERS = Object.freeze([
+    { type: 'strategy', name: 'Strategy', layers: ['strategy'] },
+    { type: 'business', name: 'Business', layers: ['business'] },
+    { type: 'application', name: 'Application', layers: ['application'] },
+    { type: 'technology', name: 'Technology & Physical', layers: ['technology', 'physical'] },
+    { type: 'motivation', name: 'Motivation', layers: ['motivation'] },
+    { type: 'implementation_migration', name: 'Implementation & Migration', layers: ['implementation'] },
+    { type: 'other', name: 'Other', layers: ['composite', 'other'] },
+    { type: 'relations', name: 'Relations' },
+    { type: 'diagrams', name: 'Views' },
+]);
+
+/**
+ * Where Archi keeps an element: the top-level folder of its ArchiMate 3.2
+ * layer, with the 3.2 type it is written as and, for a type Archi lacks, its
+ * own (archiElementType).
+ * @param {Object} el - A model element
+ * @returns {{folder: Object, type: string, original: string|undefined}}
+ */
+export function archiFolderOf(el) {
+    const { type, original } = archiElementType(el);
+    const layer = ArchimateNotation.elementLayer({ type }, '3.2');
+    const folder = ARCHI_FOLDERS.find(x => x.layers?.includes(layer !== 'other' ? layer : el.layer)) ?? ARCHI_FOLDERS.find(x => x.type === 'other');
+    return { folder, type, original };
+}
+
+function _visualTypeToXSI(type) {
+    const map = {
+        'diagram-model-note': 'archimate:Note',
+        'diagram-model-group': 'archimate:Group',
+        'diagram-model-connection': 'archimate:DiagramModelConnection',
+        'canvas-model-connection': 'canvas:CanvasModelConnection',
+        'diagram-model-image': 'archimate:DiagramModelImage',
+        'diagram-model-reference': 'archimate:DiagramModelReference',
+        'sketch-model-sticky': 'archimate:SketchModelSticky',
+        'sketch-model-actor': 'archimate:SketchModelActor',
+        'canvas-model-block': 'canvas:CanvasModelBlock',
+        'canvas-model-sticky': 'canvas:CanvasModelSticky',
+        'canvas-model-image': 'canvas:CanvasModelImage',
+    };
+    return map[type] || 'archimate:DiagramObject';
+}
+
+function _toPascalType(kebab) {
+    if (!kebab) return '';
+    return kebab.split('-').map(p => p.charAt(0).toUpperCase() + p.slice(1)).join('');
+}
+
+function _newId(prefix = 'id') {
+    return `${prefix}_${Math.random().toString(36).slice(2, 9)}`;
+}
+
+/** Text for element content. A CR is written as a reference: a parser turns a literal one into a newline. */
+function _escapeXml(str) {
+    return String(str)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/\r/g, '&#xD;');
+}
+
+/** Text for an attribute value: a parser also turns a literal newline or tab there into a space. */
+function _escapeAttr(str) {
+    return _escapeXml(str).replace(/\n/g, '&#xA;').replace(/\t/g, '&#x9;');
+}
+
+/*
+ * Shared with the Open Group Exchange Format (archimateExchangeFormat.js), which
+ * reads and writes the same parsed model and view trees as this module.
+ */
+export {
+    _visualBoxes as archiVisualBoxes,
+    _bendpointLocations as archiBendpointLocations,
+    _relativizeLocatedBendpoints as relativizeArchiBendpoints,
+    _parseFontFeature as parseArchiFont,
+    _fontString as archiFontString,
+    _typedArrayToProperties as typedArrayToProperties,
+    _toPascalType as toPascalType,
+    _escapeXml as escapeXml,
+    _escapeAttr as escapeAttr,
+};