@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/archimate.js

@@ -0,0 +1,723 @@
+// Copyright 2026 Jaroslav Peter Prib, Purveyor of Excellence
+/**
+ * ArchiMate notation — layers, the official element type catalog (each type
+ * a real object carrying its own layer, aspect, and icon — not a name in one
+ * lookup table and its layer in a second, separate one that could silently
+ * drift out of sync), and the 11 relationship types' line/arrowhead
+ * notation. Covers BOTH ArchiMate 3.2 and ArchiMate 4 — see "Two versions"
+ * below — every ArchimateNotation lookup takes an optional `version`
+ * (`'3.2'|'4'`, default `'4'`, `ArchimateNotation.versions()`).
+ *
+ * Kept in its own module, deliberately OO (ArchimateLayer/ArchimateElementType/
+ * ArchimateRelationshipType instances, queried through the ArchimateNotation
+ * registry below) rather than graphDiagram()'s usual flat string-keyed maps —
+ * this is domain data self-contained enough to own its own shape, and a
+ * type's layer being a genuine object reference (`type.layer`, not
+ * `TYPE_LAYERS[type.name]`) is what makes a dependent UI control trivial:
+ * `ArchimateNotation.typesInLayer(layer)` and `type.layer` are the same
+ * relationship read from either direction, so a "layer" dropdown and a
+ * "type" dropdown that must narrow to match it can never disagree.
+ *
+ * Colours, corner shapes, and relationship notations come from the spec's
+ * own "Appendix A: Summary of Language Notation" artwork, read out of the
+ * embedded LOSSLESS PNG figures (so the fills below are literal pixel
+ * values, not a sample off a rescaled page render); element/layer names
+ * cross-checked against a local jArchi scripting library's own element
+ * list. `notationShape` names each type's real outline from that same
+ * figure (see ArchimateElementType) — the emoji `icon` below is only the
+ * fallback badge for a type with no such shape.
+ *
+ * **Two versions.** ArchiMate 4 retires 19 of 3.2's element types: fifteen
+ * layer-specific behavior types (business-process/application-process/
+ * technology-process, and the same business-/application-/technology- split
+ * for function/service/interaction/event) collapse into five layer-
+ * INDEPENDENT "Common Domain" types (process/function/service/interaction/
+ * event — which layer one of these actually belongs to is no longer implied
+ * by its type name at all, so its `ArchimateElementType#layer` is `null`;
+ * the real layer must come from the element's own `layer` field); four more
+ * (contract, representation, constraint, gap) are retired outright, each
+ * replaced by an existing type (business-object, business-object,
+ * requirement, work-package respectively). `migrateElementToV4(element)`
+ * converts one 3.2-style element to its v4 equivalent — exactly the
+ * mapping (and property-tagging: `ArchiMate4_Domain`/`MigratedFrom` for a
+ * behavior consolidation, `LegacyType`/`Type` + `MigratedFrom` for a retired
+ * type) a jArchi "Migrate Model Elements from ArchiMate 3.2 to ArchiMate 4"
+ * script performs — `RenderEngine.archimateDiagram`'s own `archimateVersion`
+ * option (default `'4'`) runs every element through it automatically. Every
+ * other official 3.2 type (business-actor, application-component, goal,
+ * node, ...) — and all 11 relationship notations — are unchanged in v4.
+ */
+
+/** One ArchiMate layer — a fill colour and a generic fallback icon (used
+ *  only when neither an element nor its ArchimateElementType carries a more
+ *  specific one). */
+export class ArchimateLayer {
+    constructor(name, color, defaultIcon) {
+        this.name = name;
+        this.color = color;
+        this.defaultIcon = defaultIcon;
+    }
+}
+
+/** A handful of generic, aspect-wide alternative icons — shared across every
+ *  type of that aspect, so ArchimateElementType#iconChoices has real
+ *  alternatives to offer without hand-picking 3-4 unique glyphs for each of
+ *  the ~55 official types individually. Rounds out a type's own specific
+ *  icon (always choice 0 — the "ArchiMate standard" default) and its
+ *  layer's own generic one. */
+const ASPECT_ICONS = {
+    'active-structure': ['🧍', '📦', '🔌'],
+    behavior: ['▶️', '🔄', '⚡'],
+    'passive-structure': ['📄', '🗃️', '📁'],
+    motivation: ['🎯', '💭', '❗'],
+    other: ['🔀', '📍', '🗂️'],
+};
+
+/** One official ArchiMate element type — its own layer (a real
+ *  ArchimateLayer reference, or `null` for an ArchiMate 4 "Common Domain"
+ *  type — see the module's own doc comment — whose real layer isn't implied
+ *  by its type name at all and must come from the element itself), `aspect`
+ *  ('active-structure'|'behavior'|'passive-structure'|'motivation'|'other',
+ *  driving box corner style — see `cornerStyle`), and a representative icon. */
+export class ArchimateElementType {
+    constructor(name, layer, aspect, icon, notationShape, ownColor, description) {
+        this.name = name;
+        this.layer = layer;
+        this.aspect = aspect;
+        this.icon = icon;
+        // A fill of this type's OWN, overriding its layer's — the spec's own
+        // figure gives a few elements a colour their layer doesn't share
+        // (Plateau/Gap are green among the otherwise-pink Implementation &
+        // Migration elements; Grouping is unfilled; Junction is a plain
+        // black dot). `undefined` for everything else, which just takes the
+        // layer's colour — see the `color` getter.
+        this.ownColor = ownColor;
+        // The real ArchiMate notation's own distinct outline (graphDiagram
+        // `shape` value — see RenderEngine._nodeShapeEl) for this type, when
+        // one exists in the spec's own "Appendix A: Summary of Language
+        // Notation" (e.g. Process -> a plain arrow, Interface -> a lollipop,
+        // Node -> a 3D cube) — `undefined` for types the spec itself only
+        // ever shows as a plain box carrying a small mark — those get a
+        // box-with-mark shape of their own (object-box/contract-box/
+        // product-box/wavy-box/...), so EVERY official type now has a real
+        // vector glyph and archimateDiagram never falls back to an emoji for
+        // one. Used only when a diagram/element opts into
+        // `useDistinctShape` — see archimateDiagram's own option; the
+        // default everywhere else is still the plain box + corner icon.
+        this.notationShape = notationShape;
+        // Short human-readable explanation of what this element type means,
+        // suitable for a help tooltip in an authoring UI.
+        this.description = description;
+    }
+
+    /** This type's fill colour — its own (`ownColor`, for the handful the
+     *  spec colours differently from their layer) if it has one, else its
+     *  layer's, same as everywhere else (an element wanting a different
+     *  colour still sets `color` on itself, which beats both); `undefined`
+     *  for a layer-independent "Common Domain" type (`layer` is `null`) with
+     *  no own colour — the element's own resolved layer supplies one
+     *  instead, see RenderEngine._archimateLayerColor. */
+    get color() { return this.ownColor ?? this.layer?.color; }
+
+    /** A short list of reasonable icon alternatives for this type — choice
+     *  0 is always `this.icon` (the ArchiMate-standard default a plain
+     *  element/`archimateDiagram` still falls back to on its own); the rest
+     *  are generic icons shared by every type of the same aspect, then the
+     *  layer's own generic default (skipped for a layer-independent "Common
+     *  Domain" type, `layer` is `null`) — for a UI letting someone pick a
+     *  different one than the standard (e.g. the Properties dialog's icon
+     *  field in test/charts.html), never for automatic resolution, which
+     *  always means choice 0 unless a diagram sets `options.iconChoiceIndex`
+     *  (RenderEngine.archimateDiagram) to pick a different one for every
+     *  element at once. */
+    get iconChoices() {
+        return [...new Set([this.icon, ...(ASPECT_ICONS[this.aspect] ?? []), this.layer?.defaultIcon].filter(Boolean))];
+    }
+
+    /** 'chamfered' for every Motivation-layer type regardless of aspect
+     *  (every official Motivation element uses that shape); 'rounded' for
+     *  `aspect: 'behavior'`; 'sharp' otherwise — matches
+     *  RenderEngine._archimateCornerStyle's own rule, restated here as a
+     *  property of the type itself now that aspect is known up front
+     *  instead of an open per-element hint. A layer-independent "Common
+     *  Domain" type (`layer` is `null`) can never be Motivation, so this
+     *  still resolves correctly from `aspect` alone. */
+    get cornerStyle() {
+        if (this.layer?.name === 'motivation') return 'chamfered';
+        return this.aspect === 'behavior' ? 'rounded' : 'sharp';
+    }
+}
+
+/** Generic icon alternatives offered for an element with no recognised
+ *  official `type` at all (so ArchimateElementType#iconChoices doesn't
+ *  apply) — one from each aspect family plus a couple of layer defaults,
+ *  just enough variety for a picker to be worth showing. */
+export const GENERIC_ICON_CHOICES = [...new Set([
+    ...ASPECT_ICONS['active-structure'], ...ASPECT_ICONS.behavior, ...ASPECT_ICONS['passive-structure'],
+    ...ASPECT_ICONS.motivation, ...ASPECT_ICONS.other,
+])];
+
+/** One ArchiMate relationship type's notation — `lineStyle`
+ *  ('solid'|'dashed'|'dotted'), `arrowhead` (the target-end glyph), and
+ *  `arrowheadStart` (an independent source-end glyph, e.g. composition's
+ *  filled diamond at the "whole" end) — the same vocabulary graphDiagram's
+ *  own `edge.lineStyle`/`arrowhead`/`arrowheadStart` options use. */
+export class ArchimateRelationshipType {
+    constructor(name, lineStyle, arrowhead, arrowheadStart, description) {
+        this.name = name;
+        this.lineStyle = lineStyle;
+        this.arrowhead = arrowhead;
+        this.arrowheadStart = arrowheadStart;
+        // Short human-readable explanation of what this relationship means,
+        // suitable for a help tooltip in an authoring UI.
+        this.description = description;
+    }
+
+    /**
+     * This notation as line style values (EDGE_STYLE_PROPERTIES keys), its
+     * arrowheads as edge marker keys ('triangle-hollow' → 'trianglehollow',
+     * the same folding getEdgeMarker applies).
+     * @returns {{lineStyle: string, startMarker: string, endMarker: string}}
+     */
+    edgeStyle() {
+        const markerKey = (name) => (name ? String(name).toLowerCase().replace(/[^a-z]/g, '') : 'none');
+        return {
+            lineStyle: this.lineStyle,
+            startMarker: markerKey(this.arrowheadStart),
+            endMarker: markerKey(this.arrowhead),
+        };
+    }
+}
+
+// Exact fills, read out of the spec's own Appendix A artwork — the figures
+// are embedded LOSSLESS PNGs, so these are the literal pixel values of the
+// notation, not a sample off a rescaled/antialiased page render (which is
+// what an earlier pass here did, against a different document, and got
+// application/technology/composite visibly wrong).
+const LAYERS = {
+    strategy: new ArchimateLayer('strategy', '#F5DEAA', '♟️'),
+    business: new ArchimateLayer('business', '#FFFFAF', '👤'),
+    application: new ArchimateLayer('application', '#AFFFFF', '⚙️'),
+    // Technology and Physical share one green in the spec's own figure.
+    technology: new ArchimateLayer('technology', '#AFFFAF', '🖥️'),
+    physical: new ArchimateLayer('physical', '#AFFFAF', '📦'),
+    motivation: new ArchimateLayer('motivation', '#CCCCFF', '🧭'),
+    implementation: new ArchimateLayer('implementation', '#FFE0E0', '🚀'),
+    // Composite has no single colour of its own — Location (its one filled
+    // element) is orange, while Grouping/Junction carry their own overrides
+    // below (an unfilled dashed box and a plain black dot respectively).
+    composite: new ArchimateLayer('composite', '#FFBF80', '▫️'),
+    other: new ArchimateLayer('other', '#E8E8E8', '▫️'),
+};
+// Accepted alias spellings — both point at the SAME layer object, not a copy.
+LAYERS.infrastructure = LAYERS.technology;
+LAYERS.migration = LAYERS.implementation;
+
+const ELEMENT_TYPES_V3_2 = new Map();
+/** name, layer key, aspect, icon, notationShape? — one row per official
+ *  ArchiMate 3.2 element (see the class doc comment for where these were
+ *  checked; `notationShape` cross-checked against the spec's own Appendix A,
+ *  "Summary of Language Notation" — a `graphDiagram` shape name, or omitted
+ *  for a type the spec only ever shows as a plain box, or whose real glyph
+ *  is too compound to render cleanly as a whole-node shape here; a 6th,
+ *  `ownColor`, overrides the layer's fill for the few the spec colours
+ *  differently). */
+const ELEMENT_TYPE_ROWS = [
+    // Strategy — Resource is the layer's one active-structure element
+    // (sharp corners); the other three are behavior (rounded).
+    ['resource', 'strategy', 'active-structure', '🔋', 'battery', undefined, 'An asset owned or controlled by an organization that helps achieve strategic goals.'],
+    ['capability', 'strategy', 'behavior', '🧱', 'steps', undefined, 'A stable ability an organization possesses to perform a particular activity.'],
+    ['course-of-action', 'strategy', 'behavior', '🏹', 'target', undefined, 'A strategic approach or plan chosen to achieve a goal.'],
+    ['value-stream', 'strategy', 'behavior', '➡️', 'flag', undefined, 'A sequence of activities that creates an overall result for a customer or stakeholder.'],
+    // Business
+    ['business-actor', 'business', 'active-structure', '🧍', 'stick-figure', undefined, 'An organizational entity, person, department, or role that performs behavior.'],
+    ['business-role', 'business', 'active-structure', '🎭', 'cylinder', undefined, 'A named responsibility assigned to an actor; the skills and permissions needed to perform behavior.'],
+    ['business-collaboration', 'business', 'active-structure', '🤝', 'double-circle', undefined, 'A temporary or permanent aggregation of two or more business roles that work together.'],
+    ['business-interface', 'business', 'active-structure', '🔌', 'lollipop', undefined, 'The point of access where business services are made available to the environment.'],
+    ['business-process', 'business', 'behavior', '▶️', 'arrow', undefined, 'A sequence of business behaviors that achieves a specific outcome such as a product or service.'],
+    ['business-function', 'business', 'behavior', '🔧', 'chevron', undefined, 'A collection of business behavior based on a chosen set of criteria such as resources or competencies.'],
+    ['business-interaction', 'business', 'behavior', '🔄', 'half-circle', undefined, 'A unit of collective business behavior performed by two or more business roles.'],
+    ['business-event', 'business', 'behavior', '⚡', 'flag', undefined, 'Something that happens and may trigger business behavior.'],
+    ['business-service', 'business', 'behavior', '🛎️', 'pill', undefined, 'A service that fulfills a business need for a customer or other internal/external user.'],
+    ['business-object', 'business', 'passive-structure', '📁', 'object-box', undefined, 'A passive element representing a concept used within a particular business domain.'],
+    ['contract', 'business', 'passive-structure', '📜', 'contract-box', undefined, 'A formal or informal specification of an agreement between a provider and a consumer.'],
+    ['representation', 'business', 'passive-structure', '🖼️', 'wavy-box', undefined, 'A perceptible form of the information carried by a business object.'],
+    ['product', 'business', 'passive-structure', '🏷️', 'product-box', undefined, 'A coherent collection of services and/or passive structure, accompanied by a contract.'],
+    // Application
+    ['application-component', 'application', 'active-structure', '🧩', 'component', undefined, 'A modular, deployable, and replaceable part of a software system that encapsulates its behavior and data.'],
+    ['application-collaboration', 'application', 'active-structure', '🔗', 'double-circle', undefined, 'An aggregate of two or more application components that work together.'],
+    ['application-interface', 'application', 'active-structure', '🔌', 'lollipop', undefined, 'The point of access where application services are made available to users or other applications.'],
+    ['application-function', 'application', 'behavior', '🔧', 'chevron', undefined, 'A cohesive group of application behavior that an automated component can perform.'],
+    ['application-process', 'application', 'behavior', '▶️', 'arrow', undefined, 'A sequence of application behaviors that achieves a specific outcome.'],
+    ['application-interaction', 'application', 'behavior', '🔄', 'half-circle', undefined, 'A unit of collective application behavior performed by components working together.'],
+    ['application-event', 'application', 'behavior', '⚡', 'flag', undefined, 'Something that happens in the application domain and may trigger application behavior.'],
+    ['application-service', 'application', 'behavior', '🛎️', 'pill', undefined, 'An externally visible unit of application functionality exposed to users or other applications.'],
+    ['data-object', 'application', 'passive-structure', '🗃️', 'object-box', undefined, 'A passive element suitable for automated processing, representing structured data.'],
+    // Technology
+    ['node', 'technology', 'active-structure', '📦', 'cube', undefined, 'A computational or physical resource that hosts, manipulates, or interacts with other technology elements.'],
+    ['device', 'technology', 'active-structure', '💻', 'device', undefined, 'A physical hardware resource upon which system software or artifacts may be stored or deployed.'],
+    ['system-software', 'technology', 'active-structure', '💿', 'system-software-box', undefined, 'Software that provides or contributes to an environment for storing, executing, and using software or data.'],
+    ['technology-collaboration', 'technology', 'active-structure', '🤝', 'double-circle', undefined, 'An aggregate of two or more technology active-structure elements that work together.'],
+    ['technology-interface', 'technology', 'active-structure', '🔌', 'lollipop', undefined, 'The point of access where technology services are made available.'],
+    ['path', 'technology', 'active-structure', '↔️', 'double-arrow-dashed', undefined, 'A link between two or more technology nodes along which data or material can flow.'],
+    ['communication-network', 'technology', 'active-structure', '📡', 'double-arrow', undefined, 'A set of structures and channels that connects technology nodes and enables communication.'],
+    ['technology-function', 'technology', 'behavior', '🔧', 'chevron', undefined, 'A collection of technology behavior that can be performed by a technology node.'],
+    ['technology-process', 'technology', 'behavior', '▶️', 'arrow', undefined, 'A sequence of technology behaviors that achieves a specific outcome.'],
+    ['technology-interaction', 'technology', 'behavior', '🔄', 'half-circle', undefined, 'A unit of collective technology behavior performed by nodes or components working together.'],
+    ['technology-event', 'technology', 'behavior', '⚡', 'flag', undefined, 'Something that happens in the technology domain and may trigger technology behavior.'],
+    ['technology-service', 'technology', 'behavior', '🛎️', 'pill', undefined, 'An externally visible unit of technology functionality exposed to users or other technology elements.'],
+    ['artifact', 'technology', 'passive-structure', '📄', 'document', undefined, 'A physical or digital piece of data that is used or produced in a software development or deployment process.'],
+    // Physical — no behavior elements at this layer, all structure.
+    ['equipment', 'physical', 'active-structure', '⚙️', 'gear', undefined, 'One or more physical machines, tools, or instruments that can create, use, store, move, or transform materials.'],
+    ['facility', 'physical', 'active-structure', '🏭', 'factory', undefined, 'A physical structure or environment used to house people, machines, or other physical resources.'],
+    ['distribution-network', 'physical', 'active-structure', '🚚', 'double-arrow', undefined, 'A network used to transport materials or physical goods between locations.'],
+    ['material', 'physical', 'passive-structure', '🪨', 'hexagon', undefined, 'Tangible physical matter used or consumed in the production of products or delivery of services.'],
+    // Motivation — aspect is nominal here; every Motivation type is
+    // chamfered regardless (see ArchimateElementType#cornerStyle).
+    ['stakeholder', 'motivation', 'motivation', '🧑', 'cylinder', undefined, 'An individual, team, organization, or class thereof with an interest in the outcome of the architecture.'],
+    ['driver', 'motivation', 'motivation', '🧭', 'wheel', undefined, 'Something that creates, motivates, and fuels change in an organization.'],
+    ['assessment', 'motivation', 'motivation', '🔍', 'magnifier', undefined, 'An analysis of the state of affairs of the enterprise with respect to a driver.'],
+    ['goal', 'motivation', 'motivation', '🎯', 'target', undefined, 'A high-level statement of intent or direction that an organization wants to reach.'],
+    ['outcome', 'motivation', 'motivation', '🏆', 'target', undefined, 'An end result that has been achieved or is intended to be achieved.'],
+    ['principle', 'motivation', 'motivation', '❗', 'principle', undefined, 'A normative property of all elements within a given context that directs design decisions.'],
+    ['requirement', 'motivation', 'motivation', '📋', 'parallelogram', undefined, 'A statement of need that must be realized by systems or elements.'],
+    ['constraint', 'motivation', 'motivation', '🚧', 'constraint', undefined, 'A restriction on the way in which a system is realized.'],
+    ['meaning', 'motivation', 'motivation', '💭', 'cloud', undefined, 'The knowledge or expertise present in, or the interpretation given to, a concept in a particular context.'],
+    ['value', 'motivation', 'motivation', '💎', 'ellipse', undefined, 'The relative worth, utility, or importance of a particular element or outcome.'],
+    // Implementation & Migration
+    ['work-package', 'implementation', 'behavior', '📋', 'rounded-box', undefined, 'A series of actions designed to accomplish a defined set of objectives or deliverables.'],
+    ['deliverable', 'implementation', 'passive-structure', '🎁', 'wavy-box', undefined, 'A precisely-defined result of a work package that is delivered to stakeholders.'],
+    ['implementation-event', 'implementation', 'behavior', '⚡', 'flag', undefined, 'A behavior element denoting a state change related to the implementation or migration process.'],
+    // Plateau/Gap are green in the spec's own figure, not their layer's pink.
+    ['plateau', 'implementation', 'other', '🏔️', 'stack', '#E0FFE0', 'A relatively stable state of the architecture that exists during a limited period of time.'],
+    ['gap', 'implementation', 'other', '⚠️', 'gap-circle', '#E0FFE0', 'A statement of difference between two plateaus, typically between baseline and target architecture.'],
+    // Composite / Other
+    ['location', 'composite', 'other', '📍', 'pin', undefined, 'A conceptual or physical place where elements are situated or where behavior takes place.'],
+    ['grouping', 'composite', 'other', '🗂️', 'grouping-box', '#FFFFFF', 'A generic way to group any set of elements that belong together for analysis or presentation.'],
+    ['junction', 'composite', 'other', '🔀', 'junction', undefined, 'A point at which relationships can be split or joined; used to connect multiple elements in a single flow.'],
+];
+for (const [name, layerKey, aspect, icon, notationShape, ownColor, description] of ELEMENT_TYPE_ROWS) {
+    ELEMENT_TYPES_V3_2.set(name, new ArchimateElementType(name, LAYERS[layerKey], aspect, icon, notationShape, ownColor, description));
+}
+
+/** The 15 layer-specific ArchiMate 3.2 behavior types that ArchiMate 4
+ *  consolidates into 5 layer-independent "Common Domain" ones — exactly the
+ *  jArchi migration script's own `behaviorMapping` table (same keys/shape:
+ *  `newType` + `originalLayer`, the value `migrateElementToV4` tags a
+ *  migrated element's `ArchiMate4_Domain` property with). */
+const V4_BEHAVIOR_MIGRATION = {
+    'business-process': { newType: 'process', originalLayer: 'Business' },
+    'application-process': { newType: 'process', originalLayer: 'Application' },
+    'technology-process': { newType: 'process', originalLayer: 'Technology' },
+    'business-function': { newType: 'function', originalLayer: 'Business' },
+    'application-function': { newType: 'function', originalLayer: 'Application' },
+    'technology-function': { newType: 'function', originalLayer: 'Technology' },
+    'business-service': { newType: 'service', originalLayer: 'Business' },
+    'application-service': { newType: 'service', originalLayer: 'Application' },
+    'technology-service': { newType: 'service', originalLayer: 'Technology' },
+    'business-interaction': { newType: 'interaction', originalLayer: 'Business' },
+    'application-interaction': { newType: 'interaction', originalLayer: 'Application' },
+    'technology-interaction': { newType: 'interaction', originalLayer: 'Technology' },
+    'business-event': { newType: 'event', originalLayer: 'Business' },
+    'application-event': { newType: 'event', originalLayer: 'Application' },
+    'technology-event': { newType: 'event', originalLayer: 'Technology' },
+};
+
+/** The 4 ArchiMate 3.2 types ArchiMate 4 retires outright, each replaced by
+ *  an existing type — exactly the jArchi migration script's own
+ *  `legacyMapping` table (same keys/shape: `newType` + the `tag`/`value`
+ *  property pair `migrateElementToV4` tags a migrated element with, e.g.
+ *  `LegacyType: 'Contract'`). */
+const V4_LEGACY_MIGRATION = {
+    contract: { newType: 'business-object', tag: 'LegacyType', value: 'Contract' },
+    representation: { newType: 'business-object', tag: 'LegacyType', value: 'Representation' },
+    constraint: { newType: 'requirement', tag: 'Type', value: 'Constraint' },
+    gap: { newType: 'work-package', tag: 'LegacyType', value: 'Gap' },
+};
+
+/** name, aspect, icon, notationShape — the 5 ArchiMate 4 "Common Domain"
+ *  behavior types V4_BEHAVIOR_MIGRATION's 15 v3.2 types consolidate into.
+ *  `layer` is `null` for all five (see ArchimateElementType's own doc
+ *  comment) — icon/notationShape echo their v3.2 counterparts' own (the
+ *  spec's notation for process/function/service/interaction/event is
+ *  unchanged in v4, only which layers can use them changed). */
+const V4_COMMON_DOMAIN_ROWS = [
+    ['process', 'behavior', '▶️', 'arrow'],
+    ['function', 'behavior', '🔧', 'chevron'],
+    ['service', 'behavior', '🛎️', 'pill'],
+    ['interaction', 'behavior', '🔄', 'half-circle'],
+    ['event', 'behavior', '⚡', 'flag'],
+];
+
+/** The ArchiMate 4 element catalog — every ELEMENT_TYPES_V3_2 entry NOT
+ *  retired/consolidated away (same ArchimateElementType objects — a type
+ *  unaffected by the migration, e.g. business-actor, is identical in both
+ *  versions, not a copy that could drift), plus the 5 Common Domain types
+ *  above. Retired names (contract, business-process, ...) are deliberately
+ *  ABSENT here, not aliased to their replacement — a v4 catalog lookup for
+ *  one really shouldn't resolve to anything; migrateElementToV4 is the
+ *  place that actually converts an element's `type` away from one, always
+ *  run (for `archimateVersion: '4'`, the default) before any catalog
+ *  lookup happens. */
+const ELEMENT_TYPES_V4 = new Map();
+for (const [name, type] of ELEMENT_TYPES_V3_2) {
+    if (V4_BEHAVIOR_MIGRATION[name] || V4_LEGACY_MIGRATION[name]) continue;
+    ELEMENT_TYPES_V4.set(name, type);
+}
+for (const [name, aspect, icon, notationShape] of V4_COMMON_DOMAIN_ROWS) {
+    ELEMENT_TYPES_V4.set(name, new ArchimateElementType(name, null, aspect, icon, notationShape));
+}
+
+const ELEMENT_TYPES_BY_VERSION = { '3.2': ELEMENT_TYPES_V3_2, '4': ELEMENT_TYPES_V4 };
+function elementTypesFor(version) { return ELEMENT_TYPES_BY_VERSION[version] || ELEMENT_TYPES_V4; }
+
+const RELATIONSHIP_TYPES = new Map();
+/** name, lineStyle, arrowhead, arrowheadStart — the 11 official ArchiMate
+ *  relationship notations (see the class doc comment for where these were
+ *  checked). */
+const RELATIONSHIP_TYPE_ROWS = [
+    ['composition', 'solid', 'none', 'diamond', 'A whole consists of parts; a part belongs to only one whole and shares its lifecycle.'],
+    ['aggregation', 'solid', 'none', 'diamond-hollow', 'A whole consists of parts; parts may belong to multiple wholes and have independent lifecycles.'],
+    ['assignment', 'solid', 'arrow', 'circle', 'Behavior or structure is assigned to an active-structure element (e.g., a role or component).'],
+    ['realization', 'dotted', 'triangle-hollow', undefined, 'A logical element is realized by a more concrete element.'],
+    ['specialization', 'solid', 'triangle-hollow', undefined, 'A specialized element is a specific kind of a more general element.'],
+    ['serving', 'solid', 'open-arrow', undefined, 'An element provides its behavior, value, or functionality to another element.'],
+    ['access', 'dotted', 'open-arrow', undefined, 'A behavior element reads or writes a passive-structure element.'],
+    ['influence', 'dashed', 'open-arrow', undefined, 'One element affects another, often used for drivers, goals, and outcomes.'],
+    ['triggering', 'solid', 'arrow', undefined, 'One element causes another element to start or happen.'],
+    ['flow', 'dashed', 'arrow', undefined, 'Something (information, value, or material) passes from one element to another.'],
+    ['association', 'solid', 'none', undefined, 'A generic, undirected link with no specific ArchiMate semantics.'],
+    // The spec's relationships figure shows association twice — plain
+    // (undirected, above) and with a single-barb arrow for the directed form.
+    ['association-directed', 'solid', 'open-arrow-half', undefined, 'A generic directed link with no specific ArchiMate semantics.'],
+];
+for (const [name, lineStyle, arrowhead, arrowheadStart, description] of RELATIONSHIP_TYPE_ROWS) {
+    RELATIONSHIP_TYPES.set(name, new ArchimateRelationshipType(name, lineStyle, arrowhead, arrowheadStart, description));
+}
+
+/**
+ * Converts one ArchiMate 3.2-style `element` to its ArchiMate 4 equivalent —
+ * exactly the two mapping tables (V4_BEHAVIOR_MIGRATION/V4_LEGACY_MIGRATION)
+ * above, themselves a direct copy of a jArchi "Migrate Model Elements from
+ * ArchiMate 3.2 to ArchiMate 4" script's own `behaviorMapping`/
+ * `legacyMapping` objects. A layer-specific behavior type (business-process,
+ * application-function, ...) becomes its Common Domain equivalent (process,
+ * function, ...), tagged `ArchiMate4_Domain` with the original layer name
+ * (`'Business'`/`'Application'`/`'Technology'`) and `MigratedFrom` with the
+ * original type — plus, unlike the jArchi script (which relies on Archi's
+ * own model tree to still know an element's real layer after its type
+ * changes), an explicit `layer` field IS set here too, UNLESS the element
+ * already had its own (respecting that override) — needed because
+ * RenderEngine has no such tree; a Common Domain type's `ArchimateElementType
+ * #layer` is `null` (see the module's own doc comment), so without this the
+ * migrated element's layer/colour would silently fall through to 'other'. A
+ * retired type (contract, representation, constraint, gap) becomes its
+ * replacement type instead, tagged with what it used to be (`LegacyType`/
+ * `Type` + `MigratedFrom`, matching the jArchi script's own tag choice per
+ * type). Returns `element` UNCHANGED (same reference, no clone at all) for
+ * any other type — most v3.2 types (business-actor, application-component,
+ * goal, node, ...) are identical in v4 and need no migration.
+ * @param {object} element
+ * @returns {object}
+ */
+export function migrateElementToV4(element) {
+    const type = element?.type;
+    if (typeof type !== 'string') return element;
+
+    const behaviorRule = V4_BEHAVIOR_MIGRATION[type];
+    if (behaviorRule) {
+        return {
+            ...element,
+            type: behaviorRule.newType,
+            layer: element.layer || behaviorRule.originalLayer.toLowerCase(),
+            ArchiMate4_Domain: behaviorRule.originalLayer,
+            MigratedFrom: type,
+        };
+    }
+    const legacyRule = V4_LEGACY_MIGRATION[type];
+    if (legacyRule) {
+        return { ...element, type: legacyRule.newType, [legacyRule.tag]: legacyRule.value, MigratedFrom: type };
+    }
+    return element;
+}
+
+/** V4_BEHAVIOR_MIGRATION backwards: 'process:business' -> 'business-process'. */
+const V32_BEHAVIOR_TYPE = Object.fromEntries(Object.entries(V4_BEHAVIOR_MIGRATION)
+    .map(([oldType, { newType, originalLayer }]) => [`${newType}:${originalLayer.toLowerCase()}`, oldType]));
+
+/**
+ * The ArchiMate 3.2 type an element is, for tools that know only 3.2 (Archi).
+ * A 3.2 type is itself; an element migrated by migrateElementToV4 goes back to
+ * what it was (`MigratedFrom`); an ArchiMate 4 Common Domain type takes its
+ * layer's 3.2 type (a business `process` is a `business-process`, an
+ * implementation `event` an `implementation-event`), business when it has no
+ * layer. Any other type (a custom one) is returned as it is.
+ * @param {object} element
+ * @returns {string}
+ */
+export function archimate32Type(element) {
+    const type = element?.type;
+    if (typeof type !== 'string') return type;
+    if (ELEMENT_TYPES_V3_2.has(element.MigratedFrom)) return element.MigratedFrom;
+    if (ELEMENT_TYPES_V3_2.has(type)) return type;
+    const layer = String(element.layer || element.ArchiMate4_Domain || 'business').toLowerCase();
+    if (type === 'event' && layer === 'implementation') return 'implementation-event';
+    return V32_BEHAVIOR_TYPE[`${type}:${layer}`] ?? V32_BEHAVIOR_TYPE[`${type}:business`] ?? type;
+}
+
+/** The registry: every lookup archimateDiagram (and a caller building its
+ *  own ArchiMate authoring UI — see the Properties dialog / Add Element
+ *  dialog in test/charts.html) needs, all reading from the same underlying
+ *  ArchimateLayer/ArchimateElementType/ArchimateRelationshipType objects
+ *  above rather than parallel maps. Every element-type lookup below takes an
+ *  optional `version` (`'3.2'|'4'`, default `'4'`, see `versions()`) — an
+ *  unrecognised version falls back to `'4'` the same forgiving way an
+ *  unrecognised relationship kind falls back to plain 'association'.
+ *  Relationship notation and layers themselves are unchanged between
+ *  versions, so those lookups take no `version` at all. */
+export const ArchimateNotation = {
+    /** The two ArchiMate versions this registry knows — `'3.2'` and `4` (the
+     *  DEFAULT everywhere a `version` parameter is optional). */
+    versions() { return ['3.2', '4']; },
+
+    /** Every distinct ArchimateLayer (alias spellings collapsed — 'infrastructure'
+     *  and 'technology' are the same object, so this lists it once). */
+    layers() { return [...new Set(Object.values(LAYERS))]; },
+    /** An ArchimateLayer by name (including alias spellings), or undefined. */
+    layer(name) { return LAYERS[name]; },
+
+    /** Every ArchimateElementType for `version` (default `4`), in catalog order. */
+    elementTypes(version = '4') { return [...elementTypesFor(version).values()]; },
+    /** Just the names, e.g. for a <datalist>. */
+    elementTypeNames(version = '4') { return [...elementTypesFor(version).keys()]; },
+    /** An ArchimateElementType by its official name for `version`, or
+     *  undefined for a custom/unofficial type string, or a type retired in
+     *  that version (e.g. `elementType('contract', 4)` — see
+     *  migrateElementToV4, the place a retired name actually gets converted
+     *  away, before any catalog lookup). */
+    elementType(name, version = '4') { return elementTypesFor(version).get(name); },
+    /** Icon alternatives for `typeName` at `version` — a recognised official
+     *  type's own ArchimateElementType#iconChoices (choice 0 the
+     *  ArchiMate-standard default), or GENERIC_ICON_CHOICES for anything
+     *  else (a custom type, or none at all) — what a UI's icon picker offers
+     *  (e.g. the Properties dialog in test/charts.html), not automatic
+     *  resolution (RenderEngine._archimateDefaultIcon), which always means
+     *  choice 0 unless a diagram's own `options.iconChoiceIndex` says
+     *  otherwise. */
+    iconChoices(typeName, version = '4') {
+        const type = elementTypesFor(version).get(typeName);
+        return type ? type.iconChoices : GENERIC_ICON_CHOICES;
+    },
+    /** Every ArchimateElementType belonging to `layerName` at `version` — the
+     *  query a "type" dropdown that must narrow to match a chosen "layer"
+     *  needs; reads the SAME `type.layer` relationship elementLayer() below
+     *  derives from, so the two can never disagree. A Common Domain type
+     *  (ArchiMate 4's process/function/service/interaction/event — `layer`
+     *  is `null`) never matches any layer here, since it doesn't belong to
+     *  one at the TYPE level at all — only a specific element instance does
+     *  (via its own `layer` field). */
+    typesInLayer(layerName, version = '4') {
+        const layer = LAYERS[layerName];
+        return layer ? [...elementTypesFor(version).values()].filter(t => t.layer === layer) : [];
+    },
+
+    /** Every ArchimateRelationshipType. */
+    relationshipTypes() { return [...RELATIONSHIP_TYPES.values()]; },
+    /** Just the names. */
+    relationshipTypeNames() { return [...RELATIONSHIP_TYPES.keys()]; },
+    /** A relationship type by name — an unrecognised/missing `name` returns
+     *  the plain 'association' notation rather than undefined, since every
+     *  call site wants SOME notation to fall back to, not a null check. */
+    relationshipType(name) { return RELATIONSHIP_TYPES.get(name) || RELATIONSHIP_TYPES.get('association'); },
+
+    /** Human-readable description for an element `typeName` at `version`, or
+     *  undefined for an unrecognised/retired type. */
+    describe(typeName, version = '4') {
+        const type = elementTypesFor(version).get(typeName);
+        return type?.description;
+    },
+    /** Human-readable description for a relationship `name`, or undefined for
+     *  an unrecognised kind. */
+    describeRelationship(name) {
+        const rel = RELATIONSHIP_TYPES.get(name);
+        return rel?.description;
+    },
+
+    /** Which layer `element` belongs to at `version`, as a plain layer-name
+     *  string (element.layer/type may reference a layer this registry has
+     *  never heard of — a caller's own custom layer name is still valid
+     *  input everywhere else in archimateDiagram, so this returns a string,
+     *  not an ArchimateLayer, and never throws for an unknown one).
+     *  Precedence: an explicit `element.layer` always wins (the ONLY source
+     *  of truth for a Common Domain type, whose own layer is `null` — see
+     *  the module's own doc comment); then `element.type` matched against
+     *  `version`'s own catalog (ElementType#layer — most official names,
+     *  e.g. 'goal'/'node'/'resource', do NOT start with their own layer's
+     *  name, so the next rule alone would get them wrong); then the prefix
+     *  of `type` before its first '-' (so a custom `type:'business-my-
+     *  widget'` still implies 'business' with zero extra config, and a v4
+     *  Common Domain element with neither `layer` nor a recognised type
+     *  falls through here too, e.g. `type:'process'` has no '-' at all ->
+     *  'other'); neither present -> 'other'. */
+    elementLayer(element, version = '4') {
+        if (element?.layer) return element.layer;
+        const type = element?.type;
+        if (typeof type !== 'string') return 'other';
+        const known = elementTypesFor(version).get(type);
+        if (known?.layer) return known.layer.name;
+        const dash = type.indexOf('-');
+        return dash > 0 ? type.slice(0, dash) : 'other';
+    },
+
+
+    migrateElementToV4,
+    archimate32Type,
+};
+
+
+/**
+ * ArchiMate viewpoints — a catalog of standard viewpoints, and a user's own
+ * after them (`custom`, kept by CustomViewpoints). Each lists the element type
+ * names it allows, or a layer/aspect filter.
+ */
+export const ARCHIMATE_STANDARD_VIEWPOINTS = [
+    {
+        name: 'All',
+        description: 'No restriction; every element type is allowed.',
+        allowedTypes: null,
+    },
+    {
+        name: 'Organization',
+        description: 'Structure of the enterprise: actors, roles, collaborations, interfaces and locations.',
+        allowedTypes: ['business-actor', 'business-role', 'business-collaboration', 'business-interface', 'location'],
+    },
+    {
+        name: 'Business Process Cooperation',
+        description: 'Business processes, functions, services and events, plus the actors/roles/objects they relate to.',
+        allowedTypes: ['business-actor', 'business-role', 'business-collaboration', 'business-interface',
+            'business-process', 'business-function', 'business-interaction', 'business-event', 'business-service',
+            'business-object', 'contract', 'representation', 'product', 'location'],
+    },
+    {
+        name: 'Product',
+        description: 'Products, services, contracts and the business objects they operate on.',
+        allowedTypes: ['business-service', 'business-process', 'business-function', 'business-event',
+            'business-object', 'contract', 'representation', 'product', 'application-service', 'application-component'],
+    },
+    {
+        name: 'Application Cooperation',
+        description: 'Application components, collaborations, interfaces, functions, processes and services.',
+        allowedTypes: ['application-component', 'application-collaboration', 'application-interface',
+            'application-function', 'application-process', 'application-interaction', 'application-event',
+            'application-service', 'data-object'],
+    },
+    {
+        name: 'Application Usage',
+        description: 'How applications support business behavior.',
+        allowedTypes: ['business-process', 'business-function', 'business-interaction', 'business-event',
+            'business-service', 'business-object', 'application-component', 'application-collaboration',
+            'application-interface', 'application-function', 'application-process', 'application-interaction',
+            'application-event', 'application-service', 'data-object'],
+    },
+    {
+        name: 'Technology',
+        description: 'Technology and infrastructure elements, including physical equipment.',
+        allowedTypes: ['node', 'device', 'system-software', 'technology-collaboration', 'technology-interface',
+            'communication-network', 'path', 'technology-function', 'technology-process', 'technology-interaction',
+            'technology-event', 'technology-service', 'technology-object', 'artifact', 'equipment', 'facility',
+            'distribution-network', 'material'],
+    },
+    {
+        name: 'Motivation',
+        description: 'Stakeholders, drivers, assessments, goals, outcomes, principles, requirements and constraints.',
+        allowedTypes: ['stakeholder', 'driver', 'assessment', 'goal', 'outcome', 'principle', 'requirement',
+            'constraint', 'meaning', 'value', 'risk'],
+    },
+    {
+        name: 'Strategy',
+        description: 'Capabilities, resources, value streams and courses of action.',
+        allowedTypes: ['resource', 'capability', 'course-of-action', 'value-stream'],
+    },
+    {
+        name: 'Implementation & Migration',
+        description: 'Work packages, deliverables, plateaus and gaps.',
+        allowedTypes: ['work-package', 'deliverable', 'plateau', 'gap'],
+    },
+];
+
+export class ArchimateViewpoints {
+    static get standard() { return ARCHIMATE_STANDARD_VIEWPOINTS; }
+
+    static all(custom = []) {
+        return [...ARCHIMATE_STANDARD_VIEWPOINTS, ...custom];
+    }
+
+    static names(custom = []) {
+        return this.all(custom).map(v => v.name);
+    }
+
+    static byName(name, custom = []) {
+        return this.all(custom).find(v => v.name === name) || ARCHIMATE_STANDARD_VIEWPOINTS[0];
+    }
+
+    /**
+     * Element type names allowed by `viewpoint` at `version`.
+     * @param {object|string} viewpoint — viewpoint object or name
+     * @param {string} version — '3.2' or '4'
+     * @param {object[]} custom — additional custom viewpoints
+     * @returns {string[]}
+     */
+    static allowedElementTypes(viewpoint, version = '4', custom = []) {
+        const vp = typeof viewpoint === 'string' ? this.byName(viewpoint, custom) : viewpoint;
+        if (!vp || vp.name === 'All') return ArchimateNotation.elementTypeNames(version);
+        if (vp.allowedTypes) {
+            // Only return types that actually exist in this version's catalog.
+            const valid = new Set(ArchimateNotation.elementTypeNames(version));
+            return vp.allowedTypes.filter(t => valid.has(t));
+        }
+        return ArchimateNotation.elementTypes(version)
+            .filter(t => this._typeMatchesViewpoint(t, vp))
+            .map(t => t.name);
+    }
+
+    static _typeMatchesViewpoint(type, viewpoint) {
+        if (viewpoint.aspects && !viewpoint.aspects.includes(type.aspect)) return false;
+        if (viewpoint.layers) {
+            return viewpoint.layers.includes(type.layer?.name);
+        }
+        if (viewpoint.layer) {
+            return type.layer?.name === viewpoint.layer;
+        }
+        return true;
+    }
+
+
+    /**
+     * Returns true if `typeName` is allowed by `viewpoint` at `version`.
+     */
+    static isAllowed(typeName, viewpoint, version = '4', custom = []) {
+        const allowed = this.allowedElementTypes(viewpoint, version, custom);
+        return allowed.includes(typeName);
+    }
+
+    /**
+     * Validate a single element against a viewpoint. Returns a warning string
+     * if the element is not allowed, or undefined.
+     */
+    static validateElement(element, viewpoint, version = '4', custom = []) {
+        const vp = typeof viewpoint === 'string' ? this.byName(viewpoint, custom) : viewpoint;
+        if (!vp || vp.name === 'All') return undefined;
+        const typeName = element?.type;
+        if (typeof typeName !== 'string') return undefined;
+        const allowed = this.allowedElementTypes(vp, version, custom);
+        if (allowed.includes(typeName)) return undefined;
+        return `Type "${typeName}" is not allowed in the "${vp.name}" viewpoint.`;
+    }
+
+    /**
+     * Build a custom viewpoint object from a layer/aspect filter.
+     */
+    static custom({ name = 'Custom', description = '', layer = null, aspects = null, layers = null, allowedTypes = null } = {}) {
+        return { name, description, layer, aspects, layers, allowedTypes };
+    }
+}