@peter.prib/renderengine 0.2.10 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peter.prib/renderengine",
-  "version": "0.2.10",
+  "version": "0.4.0",
   "description": "ArchiMate modeller, diagram editor and chart library for the browser, with no runtime dependencies.",
   "type": "module",
   "main": "src/index.js",

package/src/charting/ModelCheckDialog.js

@@ -5,7 +5,9 @@ import { FormDialog } from './FormDialog.js';
  * ModelCheckDialog — a model check's findings (ModelChecker#run), listed:
  * each a button (⚠ a warning, ℹ for a look) that shows what it names
  * (`onReveal`), with what can be done about it beside (`actionsFor`), or
- * "nothing found". Any editor or part that checks a model shows it this way.
+ * "nothing found". Any editor or part that checks a model shows it this way;
+ * anything else listed to be opened (search results) too, with its own
+ * `title` and `empty` text.
  */
 export class ModelCheckDialog {
     /**
@@ -14,9 +16,13 @@ export class ModelCheckDialog {
      * @param {(finding: Object) => void} [options.onReveal] - Show what a finding names
      * @param {(finding: Object) => Array<{label: string, action: Function}>} [options.actionsFor]
      * @param {Document} [options.document]
+     * @param {string} [options.title] - In place of "Model check: n findings"
+     * @param {string} [options.empty] - What an empty list says
      */
-    constructor({ findings, onReveal = () => {}, actionsFor = () => [], document: doc = globalThis.document }) {
+    constructor({ findings, onReveal = () => {}, actionsFor = () => [], document: doc = globalThis.document, title = null, empty = 'Nothing found: the model passes every check.' }) {
         this.findings = findings;
+        this._title = title;
+        this.empty = empty;
         this.onReveal = onReveal;
         this.actionsFor = actionsFor;
         this.document = doc;
@@ -24,6 +30,7 @@ export class ModelCheckDialog {
 
     /** The dialog's title: how many findings. */
     get title() {
+        if (this._title) return this._title;
         const n = this.findings.length;
         return `Model check: ${n} finding${n === 1 ? '' : 's'}`;
     }
@@ -49,7 +56,7 @@ export class ModelCheckDialog {
                         on: { click: () => { dialog?.close(); act.action(); } },
                     })),
                 ],
-            })) : [{ text: 'Nothing found: the model passes every check.' }],
+            })) : [{ text: this.empty }],
         }, this.document);
         dialog = new FormDialog({
             title: this.title,

package/src/charting/ModelComparisonDialog.js

@@ -26,16 +26,23 @@ export class ModelCompareDialog {
      * @param {string} options.mineName - What the model compared is called
      * @param {string} options.theirsName - What the other is called
      * @param {() => void} [options.onMerge] - Merge from the other (offered when there is something to merge)
+     * @param {string} [options.note] - Said above the differences: why the other is offered (a proposal's rationale)
      * @param {Document} [options.document]
      */
-    constructor({ comparison, mineName, theirsName, onMerge = null, document: doc = globalThis.document }) {
+    constructor({ comparison, mineName, theirsName, onMerge = null, note = '', document: doc = globalThis.document }) {
         this.comparison = comparison;
         this.mineName = mineName;
         this.theirsName = theirsName;
         this.onMerge = onMerge;
+        this.note = note;
         this.document = doc;
     }
 
+    /** The dialog's description: the note, then `text`. */
+    described(text) {
+        return this.note ? `${this.note}\n\n${text}` : text;
+    }
+
     get title() {
         return `Compare "${this.mineName}" with "${this.theirsName}"`;
     }
@@ -74,7 +81,7 @@ export class ModelCompareDialog {
         const canMerge = !!this.onMerge && this.comparison.mergeable().length > 0;
         return new FormDialog({
             title: this.title,
-            description: this.summaryText(),
+            description: this.described(this.summaryText()),
             fields: this.fields(),
             submitLabel: canMerge ? 'Merge…' : 'Close',
             cancelLabel: 'Close',
@@ -107,7 +114,7 @@ export class ModelMergeDialog extends ModelCompareDialog {
         const nothing = !this.comparison.mergeable().length;
         return new FormDialog({
             title: this.title,
-            description: nothing ? `"${this.mineName}" has everything "${this.theirsName}" has.` : `${this.summaryText()}\n\nWhat the chosen need (a view's elements, a relationship's ends) comes too.`,
+            description: this.described(nothing ? `"${this.mineName}" has everything "${this.theirsName}" has.` : `${this.summaryText()}\n\nWhat the chosen need (a view's elements, a relationship's ends) comes too.`),
             fields: this.fields(),
             submitLabel: nothing ? 'Close' : 'Merge',
             idPrefix: 'model-merge-',

package/src/charting/ModelFileFormat.js

@@ -28,6 +28,9 @@ export class ModelFileFormat {
     /** Whether files in this format can be imported (opened) as well as exported. A subclass that only exports says no. */
     get imports() { return true; }
 
+    /** Whether a model can be exported in this format. A subclass that only reads (another tool's export) says no. */
+    get exports() { return true; }
+
     /** True when import takes the file's bytes (a zip archive), else its text. */
     get readsBytes() { return false; }
 
@@ -87,7 +90,7 @@ export function modelFileMenuItems(formats, {
     const choose = chooseFile ?? ((accept) => pickFile(accept, doc()));
     const tell = report ?? ((message) => (doc().defaultView ?? globalThis).alert(message));
     const groups = formats.map(format => [
-        only !== 'import' && enabled(format, 'export') && { label: only ? format.label : `Export ${format.label}`, action: () => save(format.export(model()), format.fileName) },
+        only !== 'import' && format.exports !== false && enabled(format, 'export') && { label: only ? format.label : `Export ${format.label}`, action: () => save(format.export(model()), format.fileName) },
         only !== 'export' && format.imports && enabled(format, 'import') && {
             label: only ? `${format.label}…` : `Import ${format.label}…`,
             action: () => importFile(format, { choose, onImport, report: tell }),

package/src/charting/archimate/ArchimateCanvasEditor.js

@@ -77,8 +77,12 @@ export class ArchimateCanvasEditor extends DiagramEditor {
      *   elements (null cancels). Without it the first of KIND_PREFERENCE that is allowed is used.
      * @param {(nodeOptions: Object) => void} [options.onNodeOptionsChange] - The ⚙ Settings menu changed
      *   the version or distinct shapes (the host may need to redraw more than the canvas, e.g. a palette)
+     * @param {(element: Object) => ({text: string, color?: string}|null)} [options.elementStatus] - A host's
+     *   live status for an element (a component's lifecycle state), drawn on its boxes
+     * @param {(element: Object) => Array<Object>} [options.elementMenuExtras] - A host's menu items for an
+     *   element (its transitions), at the end of a box's right-click menu
      */
-    constructor({ view, model, nodeOptions = {}, chooseKind = null, onNodeOptionsChange = null, templateMenu = null, customViewpoints = [], settingsManager = null, ...options }) {
+    constructor({ view, model, nodeOptions = {}, chooseKind = null, onNodeOptionsChange = null, templateMenu = null, customViewpoints = [], settingsManager = null, elementStatus = null, elementMenuExtras = null, ...options }) {
         super({ ...options, templates: new Map(), edges: new Map(), history: view.history, arrangement: view.arrangement });
         this.view = view;
         this.model = model;
@@ -91,6 +95,9 @@ export class ArchimateCanvasEditor extends DiagramEditor {
         this.settingsManager = settingsManager;
         /** Canvas templates (a CanvasTemplateMenu): placed on the canvas, saved from its shapes. */
         this.templateMenu = templateMenu;
+        /** A host's live status per element, drawn on its boxes, and its menu items per element. */
+        this.elementStatus = elementStatus;
+        this.elementMenuExtras = elementMenuExtras;
         this.addDropHandler({
             accepts: (dt) => Array.from(dt.types).includes(ARCHIMATE_TYPE_MIME),
             drop: (dt, point) => this.addElement(dt.getData(ARCHIMATE_TYPE_MIME), point),
@@ -128,6 +135,7 @@ export class ArchimateCanvasEditor extends DiagramEditor {
             ...(missing.length ? [{ label: `Add Missing Relationships (${missing.length})`, action: () => this.addMissingRelationships(elementId) }] : []),
             ...hintMenuItems(this.view, elementId, { onChange: () => this.render() }),
             ...(items.length ? [{ label: 'Save as template', items }] : []),
+            ...(element && this.elementMenuExtras ? this.elementMenuExtras(element) ?? [] : []),
         ];
     }
 
@@ -352,7 +360,11 @@ export class ArchimateCanvasEditor extends DiagramEditor {
             templates.set(inst.id, existing?.instance === inst ? existing
                 : new ArchimateElementTemplate(inst, model, { nodeOptions: this.nodeOptions }));
         }
-        for (const t of templates.values()) t.nodeOptions = this.nodeOptions;
+        for (const t of templates.values()) {
+            t.nodeOptions = this.nodeOptions;
+            // Asked afresh at every sync: a host's status is live, not part of the model.
+            t.status = this.elementStatus ? this.elementStatus(t.instance.resolve(model)) ?? null : null;
+        }
         // The view's groups (Archi groups: model folders with bounds on this view).
         for (const folder of view.placedFolders) {
             const existing = this.templates.get(folder.id);

package/src/charting/archimate/ArchimateElementTemplate.js

@@ -41,6 +41,8 @@ export class ArchimateElementTemplate extends GlyphTemplate {
         this.instance = instance;
         this.model = model;
         this.nodeOptions = nodeOptions;
+        /** A host's live status, `{text, color}` (the editor's elementStatus), or null: drawn as a pill. */
+        this.status = null;
     }
 
     /** State lives on the instance and the model element, not here. @protected */
@@ -156,6 +158,27 @@ export class ArchimateElementTemplate extends GlyphTemplate {
      * gets no glyph badge (buildNode leaves iconShape unset) but keeps an icon the element sets.
      */
     decorations(ctx) {
+        return [...this._badge(ctx), ...this.statusPill(ctx)];
+    }
+
+    /**
+     * The host's status (`status`), as a small pill inside the box's bottom
+     * right corner: its text, on its colour. Nothing without one.
+     */
+    statusPill({ w, h }) {
+        const text = this.status?.text;
+        if (!text) return [];
+        const label = String(text);
+        const ph = 12, pw = Math.min(w - 6, label.length * 5.5 + 10);
+        const x = w / 2 - pw - 3, y = h / 2 - ph - 3;
+        return [Glyph.group([
+            Glyph.rect(x, y, pw, ph, this.status.color || '#455a64', null, { rx: 6, ry: 6 }),
+            Glyph.text(label, x + pw / 2, y + ph / 2, { fill: '#ffffff', textAnchor: 'middle', verticalAlign: 'middle', fontSize: '8px' }),
+        ], { 'pointer-events': 'none', class: 'element-status' })];
+    }
+
+    /** The type badge (decorations). @private */
+    _badge(ctx) {
         const node = this.node;
         const { w, h } = ctx;
         const fixed = ArchimateElementTemplate.badgeSize(w, h);

package/src/charting/arrangement/layouts.js

@@ -153,14 +153,19 @@ function tree(boxes, { edges, gap }, direction) {
 
 /**
  * Fruchterman–Reingold: lines pull their ends together, every pair of boxes
- * pushes apart, cooling over the iterations. Deterministic: it starts from
- * where the boxes are (boxes on one spot are spread round it first).
+ * pushes apart, cooling over the iterations, all within a frame — a square
+ * round where the boxes were, room for them a grid's worth — so a box with no
+ * lines is not pushed away for ever. Deterministic: it starts from where the
+ * boxes are (boxes on one spot are spread round it first).
  */
 function forceDirected(boxes, edges, gap) {
     const size = Math.max(...boxes.map(b => Math.max(b.width, b.height))) + gap;
     const k = size * 1.2;
     const pos = boxes.map((b, i) => ({ x: b.left + b.width / 2 + (i % 3) * 0.5, y: b.top + b.height / 2 + Math.floor(i / 3) * 0.5 }));
     const index = new Map(boxes.map((b, i) => [b.id, i]));
+    const centre = { x: pos.reduce((t, p) => t + p.x, 0) / pos.length, y: pos.reduce((t, p) => t + p.y, 0) / pos.length };
+    const half = (k * (Math.ceil(Math.sqrt(boxes.length)) + 1)) / 2;
+    const inFrame = (v, c) => Math.min(c + half, Math.max(c - half, v));
     let temperature = size * 2;
     for (let iteration = 0; iteration < 120; iteration++) {
         const shift = pos.map(() => ({ x: 0, y: 0 }));
@@ -185,8 +190,8 @@ function forceDirected(boxes, edges, gap) {
         for (let i = 0; i < pos.length; i++) {
             const d = Math.max(1e-9, Math.hypot(shift[i].x, shift[i].y));
             const step = Math.min(d, temperature);
-            pos[i].x += (shift[i].x / d) * step;
-            pos[i].y += (shift[i].y / d) * step;
+            pos[i].x = inFrame(pos[i].x + (shift[i].x / d) * step, centre.x);
+            pos[i].y = inFrame(pos[i].y + (shift[i].y / d) * step, centre.y);
         }
         temperature *= 0.95;
     }

package/src/charting/datamodel/DataModel.js

@@ -6,11 +6,10 @@ import './StructuredType.js';
 import { LevelSchema } from './LevelSchema.js';
 import { LevelMapping } from './LevelMapping.js';
 import { NodeGeometry } from '../diagrams/NodeGeometry.js';
-import { ModelComparison } from '../diagramModel/ModelComparison.js';
 import { DataModelChecker } from './DataModelChecker.js';
-import { CommandHistory } from '../CommandHistory.js';
 import { MergeModelCommand } from '../diagramModel/MergeModelCommand.js';
-import { DataModelEditCommand } from './DataModelEditCommand.js';
+import { EditableModel } from '../model/EditableModel.js';
+import { Benchmark } from '../model/Benchmark.js';
 import { DataModelNotation } from '../../datamodel.js';
 import { NamingStandard } from './naming/NamingStandard.js';
 import { ClassificationScheme } from './ClassificationScheme.js';
@@ -38,11 +37,13 @@ const LEVELS = Object.freeze(['conceptual', 'logical', 'physical']);
  * (`{ entities, relationships }`, as dataModelDiagram takes them), is read as
  * three levels mapped one to one.
  *
- * It knows whether it changed since it was saved (`edited()`, `markSaved()`,
- * `isDirty()`, `onEdit(fn)`), as a ViewSetModel does, so a part can show it,
- * keep it and ask before it is lost.
+ * What any model a part edits has — whether it changed since saved, its undo
+ * history, compare and merge — is EditableModel's.
  */
-export class DataModel {
+export class DataModel extends EditableModel {
+    /** What a snapshot puts back (EditableModel#restore). */
+    static STATE = Object.freeze(['name', 'levels', 'mappings', 'mappingLayout', 'noteLayout', 'perspectives', 'contexts', 'dataTypes', 'namingStandard', 'classificationScheme', 'scorecard']);
+
     /** The levels, outermost first. */
     static LEVELS = LEVELS;
 
@@ -126,11 +127,7 @@ export class DataModel {
      * @param {string} [spec.name] - What the model is called
      */
     constructor(spec = {}) {
-        /** What the model is called. */
-        this.name = spec.name ?? '';
-        this._version = 0;
-        this._saved = 0;
-        this._editListeners = [];
+        super(spec);
         const { levels, mappings = [], mappingLayout = {}, noteLayout = {} } = spec.levels ? spec : DataModel.levelsFromCombined(spec);
         this.levels = Object.fromEntries(LEVELS.map(level => [level, new LevelSchema(level, levels?.[level] ?? {})]));
         this.mappings = LEVELS.slice(1).map((to, i) => {
@@ -157,6 +154,14 @@ export class DataModel {
         return new ModelScorecard(this);
     }
 
+    /** What it is measured by (Benchmark): its check's findings, and its Scorecard total. */
+    benchmark() {
+        return [
+            ...Benchmark.findings(this),
+            { key: 'scorecard', label: 'Scorecard', value: this.scored().total().score, better: 'higher', format: 'score' },
+        ];
+    }
+
     /** Keep a reviewer's scores and the weights (ModelScorecard.specFrom's), as one undo step. */
     scorecardCommand(spec) {
         return this.editCommand('Score the model', (model) => {
@@ -204,46 +209,6 @@ export class DataModel {
         ];
     }
 
-    /** How this model differs from another (ModelComparison), which can merge the other's into it. */
-    compareWith(other) {
-        return new ModelComparison(this, other);
-    }
-
-    /** Its undo history: a merge is one step on it. */
-    get history() {
-        return (this._history ??= new CommandHistory());
-    }
-
-    // ===== Changed since saved =====
-
-    /** Something changed (a perspective or context, a box or note moved): listeners hear of it. */
-    edited() {
-        this._version++;
-        this._emitEdit();
-    }
-
-    /** This state is the saved one (a file opened or saved). */
-    markSaved() {
-        this._saved = this._version;
-        this._emitEdit();
-    }
-
-    /** Whether it changed since markSaved. */
-    isDirty() {
-        return this._version !== this._saved;
-    }
-
-    /** Call `fn(model)` after every change (and markSaved). Returns an unsubscribe function. */
-    onEdit(fn) {
-        this._editListeners.push(fn);
-        return () => { this._editListeners = this._editListeners.filter(l => l !== fn); };
-    }
-
-    /** @private */
-    _emitEdit() {
-        for (const fn of this._editListeners) fn(this);
-    }
-
     /** A level's schema (LevelSchema). */
     level(name) {
         const schema = this.levels[name];
@@ -459,13 +424,7 @@ export class DataModel {
 
     // ===== Perspectives and contexts of one's own =====
 
-    // ===== Editing what a level holds (each a DataModelEditCommand: one undo step) =====
-
-    /** Put the model back as a snapshot says (DataModelEditCommand): its levels, mappings, layout, perspectives, contexts, data types. */
-    restore(json) {
-        const back = new DataModel(JSON.parse(JSON.stringify(json)));
-        for (const key of ['name', 'levels', 'mappings', 'mappingLayout', 'noteLayout', 'perspectives', 'contexts', 'dataTypes', 'namingStandard', 'classificationScheme', 'scorecard']) this[key] = back[key];
-    }
+    // ===== Editing what a level holds (each an editCommand: one undo step) =====
 
     /** Set how its data is classified (a ClassificationScheme spec), as one undo step. */
     classificationSchemeCommand(spec) {
@@ -481,11 +440,6 @@ export class DataModel {
         });
     }
 
-    /** A change made as one undo step. */
-    editCommand(label, change) {
-        return new DataModelEditCommand(this, label, change);
-    }
-
     /**
      * Add an entity at a level (`id` null: one made from its name) or change
      * one (what the spec leaves out, where it is drawn among it, kept).
@@ -837,13 +791,6 @@ export class DataModel {
     }
 
     /** An id from a name, not yet among `taken`. @private */
-    _freshId(name, taken) {
-        const base = String(name ?? 'item').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'item';
-        let id = base;
-        for (let n = 2; taken.some(t => t.id === id); n++) id = `${base}-${n}`;
-        return id;
-    }
-
     toJSON() {
         return {
             name: this.name,

package/src/charting/datamodel/DataModelChecker.js

@@ -53,17 +53,13 @@ export class DataModelChecker extends ModelChecker {
     foreignKeys() {
         return ATTRIBUTED.flatMap(level => {
             const schema = this.model.level(level);
-            const find = (ref) => {
-                const [name] = String(ref).split('.');
-                return schema.entity(name) ?? schema.entities.find(e => e.name.toLowerCase() === name.trim().toLowerCase()) ?? null;
-            };
             const related = (a, b) => schema.relationships.some(r => (r.source === a && r.target === b) || (r.source === b && r.target === a));
             return schema.entities.flatMap(e => (e.attributes ?? []).filter(a => a.isFK).flatMap(a => {
                 if (!a.references) {
                     return schema.relationships.some(r => r.source === e.id || r.target === e.id) ? []
                         : [this._entity(level, e, 'foreign-key-unrelated', 'info', `"${e.name}.${a.name}" is a foreign key, but "${e.name}" has no relationship`)];
                 }
-                const target = find(a.references);
+                const target = schema.resolveReference(a.references)?.entity;
                 if (!target) return [this._entity(level, e, 'reference-missing', 'warning', `"${e.name}.${a.name}" references "${a.references}", which is not at the ${level} level`)];
                 return related(e.id, target.id) ? []
                     : [this._entity(level, e, 'foreign-key-without-relationship', 'warning', `"${e.name}.${a.name}" references "${target.name}", but they have no relationship`)];

package/src/charting/datamodel/DataModelCompared.js

@@ -1,4 +1,5 @@
 import { ComparedKind } from '../diagramModel/ComparedKind.js';
+import { ListCompared } from '../diagramModel/ListCompared.js';
 
 /** A plain copy of JSON-shaped data. */
 const copy = (value) => (value === undefined ? undefined : JSON.parse(JSON.stringify(value)));
@@ -11,37 +12,6 @@ const copy = (value) => (value === undefined ? undefined : JSON.parse(JSON.strin
  * two models alike but for where their boxes are, are alike.
  */
 
-/** A list of a model's held in an array (`list(model)`), each by an id; bring puts a copy in place or adds it. */
-class ListCompared extends ComparedKind {
-    constructor() {
-        super();
-        if (new.target === ListCompared) throw new TypeError('ListCompared is abstract — subclass it');
-    }
-
-    /** The array the model holds them in. @abstract */
-    list(model) { throw new Error(`${this.constructor.name} must implement list()`); }
-
-    items(model) { return this.list(model); }
-    get(model, id) { return this.items(model).find(item => this.idOf(item) === id) ?? null; }
-
-    /** Put a copy of `item` at its place (in place of the one with its id, else last); undone, as it was. */
-    bring(model, item) {
-        const list = this.list(model);
-        const twin = this.copyOf(item);
-        const at = list.findIndex(x => this.idOf(x) === this.idOf(item));
-        if (at < 0) {
-            list.push(twin);
-            return () => { const i = list.indexOf(twin); if (i >= 0) list.splice(i, 1); };
-        }
-        const old = list[at];
-        list[at] = twin;
-        return () => { const i = list.indexOf(twin); if (i >= 0) list[i] = old; };
-    }
-
-    /** A copy to put in the other model. */
-    copyOf(item) { return copy(item); }
-}
-
 /** One level's entities: compared on all but where they are drawn. */
 export class LevelEntitiesCompared extends ListCompared {
     constructor(level) {

package/src/charting/datamodel/LevelSchema.js

@@ -27,6 +27,29 @@ export class LevelSchema {
         return this.entities.find(e => e.id === id) ?? null;
     }
 
+    /** An entity by id, else by name (any case), or null. */
+    named(text) {
+        const s = String(text ?? '').trim();
+        return this.entity(s) ?? this.entities.find(e => String(e.name ?? '').toLowerCase() === s.toLowerCase()) ?? null;
+    }
+
+    /**
+     * What a foreign key's `references` names: `{ entity, column }` (column
+     * null when it names the table alone), or null. `table` or `table.column`,
+     * the table by id or name; a table's own name may hold dots (a
+     * schema-qualified `sales.customer`), so the whole text is tried as a
+     * table first, then what is before its last dot, the rest its column.
+     */
+    resolveReference(ref) {
+        const text = String(ref ?? '').trim();
+        if (!text) return null;
+        const whole = this.named(text);
+        if (whole) return { entity: whole, column: null };
+        const dot = text.lastIndexOf('.');
+        const entity = dot > 0 ? this.named(text.slice(0, dot)) : null;
+        return entity ? { entity, column: text.slice(dot + 1).trim() || null } : null;
+    }
+
     /** Add an entity (its id unique at this level). */
     addEntity(entity) {
         if (!entity?.id) throw new TypeError('An entity needs an id');

package/src/charting/datamodel/SqlDdl.js

@@ -27,6 +27,15 @@ export class SqlDdl {
         return /^[a-z_][a-z0-9_]*$/.test(s) && !RESERVED.has(s) ? s : `"${s.replace(/"/g, '""')}"`;
     }
 
+    /**
+     * A table's name as SQL takes it: a schema-qualified one (`sales.customer`)
+     * each part as name() has it, so it names the table in its schema rather
+     * than one table called "sales.customer".
+     */
+    static tableName(text) {
+        return String(text).split('.').map(SqlDdl.name).join('.');
+    }
+
     /** A text as an SQL string literal. */
     static literal(text) {
         return `'${String(text).replace(/'/g, "''")}'`;
@@ -36,11 +45,7 @@ export class SqlDdl {
     write(model) {
         const schema = model.level('physical');
         const tables = schema.entities;
-        const find = (ref) => {
-            const [table, column] = String(ref).split('.').map(s => s.trim());
-            const target = schema.entity(table) ?? tables.find(t => t.name.toLowerCase() === table.toLowerCase());
-            return target ? { target, column } : null;
-        };
+        const table = SqlDdl.tableName;
         const out = [`-- ${model.name || 'Data model'}: the physical level, ${tables.length} table${tables.length === 1 ? '' : 's'}`, ''];
         for (const t of tables) {
             const columns = t.attributes ?? [];
@@ -50,28 +55,28 @@ export class SqlDdl {
                 ...(keys.length ? [`    PRIMARY KEY (${keys.join(', ')})`] : []),
                 ...columns.filter(c => c.isUnique && !c.isPK).map(c => `    UNIQUE (${SqlDdl.name(c.name)})`),
             ];
-            out.push(`CREATE TABLE ${SqlDdl.name(t.name)} (`, lines.join(',\n'), ');', '');
+            out.push(`CREATE TABLE ${table(t.name)} (`, lines.join(',\n'), ');', '');
         }
         for (const t of tables) {
             for (const c of (t.attributes ?? []).filter(a => a.isFK && a.references)) {
-                const ref = find(c.references);
+                const ref = schema.resolveReference(c.references);
                 if (!ref) {
                     out.push(`-- ${t.name}.${c.name} references ${c.references}, which is not a table here`);
                     continue;
                 }
-                const theirs = ref.column ? [ref.column] : (ref.target.attributes ?? []).filter(a => a.isPK).map(a => a.name);
+                const theirs = ref.column ? [ref.column] : (ref.entity.attributes ?? []).filter(a => a.isPK).map(a => a.name);
                 if (!theirs.length) {
-                    out.push(`-- ${t.name}.${c.name} references ${ref.target.name}, which has no primary key`);
+                    out.push(`-- ${t.name}.${c.name} references ${ref.entity.name}, which has no primary key`);
                     continue;
                 }
-                out.push(`ALTER TABLE ${SqlDdl.name(t.name)} ADD CONSTRAINT ${SqlDdl.name(`fk_${t.name}_${c.name}`.toLowerCase().replace(/[^a-z0-9_]+/g, '_'))}`
-                    + ` FOREIGN KEY (${SqlDdl.name(c.name)}) REFERENCES ${SqlDdl.name(ref.target.name)} (${theirs.map(SqlDdl.name).join(', ')});`);
+                out.push(`ALTER TABLE ${table(t.name)} ADD CONSTRAINT ${SqlDdl.name(`fk_${t.name}_${c.name}`.toLowerCase().replace(/[^a-z0-9_]+/g, '_'))}`
+                    + ` FOREIGN KEY (${SqlDdl.name(c.name)}) REFERENCES ${table(ref.entity.name)} (${theirs.map(SqlDdl.name).join(', ')});`);
             }
         }
         if (this.comments) {
             const notes = tables.flatMap(t => [
-                ...(t.description ? [`COMMENT ON TABLE ${SqlDdl.name(t.name)} IS ${SqlDdl.literal(t.description)};`] : []),
-                ...(t.attributes ?? []).filter(c => c.description).map(c => `COMMENT ON COLUMN ${SqlDdl.name(t.name)}.${SqlDdl.name(c.name)} IS ${SqlDdl.literal(c.description)};`),
+                ...(t.description ? [`COMMENT ON TABLE ${table(t.name)} IS ${SqlDdl.literal(t.description)};`] : []),
+                ...(t.attributes ?? []).filter(c => c.description).map(c => `COMMENT ON COLUMN ${table(t.name)}.${SqlDdl.name(c.name)} IS ${SqlDdl.literal(c.description)};`),
             ]);
             if (notes.length) out.push('', ...notes);
         }

package/src/charting/diagramModel/ListCompared.js

@@ -0,0 +1,35 @@
+import { ComparedKind } from './ComparedKind.js';
+
+/** A plain copy of JSON-shaped data. */
+const copy = (value) => (value === undefined ? undefined : JSON.parse(JSON.stringify(value)));
+
+/** A list of a model's held in an array (`list(model)`), each by an id; bring puts a copy in place or adds it. */
+export class ListCompared extends ComparedKind {
+    constructor() {
+        super();
+        if (new.target === ListCompared) throw new TypeError('ListCompared is abstract — subclass it');
+    }
+
+    /** The array the model holds them in. @abstract */
+    list(model) { throw new Error(`${this.constructor.name} must implement list()`); }
+
+    items(model) { return this.list(model); }
+    get(model, id) { return this.items(model).find(item => this.idOf(item) === id) ?? null; }
+
+    /** Put a copy of `item` at its place (in place of the one with its id, else last); undone, as it was. */
+    bring(model, item) {
+        const list = this.list(model);
+        const twin = this.copyOf(item);
+        const at = list.findIndex(x => this.idOf(x) === this.idOf(item));
+        if (at < 0) {
+            list.push(twin);
+            return () => { const i = list.indexOf(twin); if (i >= 0) list.splice(i, 1); };
+        }
+        const old = list[at];
+        list[at] = twin;
+        return () => { const i = list.indexOf(twin); if (i >= 0) list[i] = old; };
+    }
+
+    /** A copy to put in the other model. */
+    copyOf(item) { return copy(item); }
+}

package/src/charting/model/Benchmark.js

@@ -0,0 +1,59 @@
+/**
+ * Benchmark — what a model is measured by, so a change to it (a proposal, a
+ * merge) says whether it made the model better. Each measure:
+ * `{ key, label, value, better: 'lower'|'higher', format?: 'count'|'share'|'score' }`
+ * (a share is 0..1; a value of null is not measured yet).
+ *
+ * Every model with a checker is measured by its findings — warnings counted
+ * apart (`Benchmark.findings`); a model with more to say gives its own
+ * `benchmark()` (a data model its Scorecard, a requirements model how many
+ * stories say when they are done and trace to something), starting from those.
+ */
+export class Benchmark {
+    /** A model's measures: its own benchmark(), else its checker's findings, else none. */
+    static of(model) {
+        if (typeof model?.benchmark === 'function') return model.benchmark();
+        return Benchmark.findings(model);
+    }
+
+    /** The check's warnings and all its findings, each fewer the better. */
+    static findings(model) {
+        if (typeof model?.checker !== 'function') return [];
+        const found = model.checker().run();
+        return [
+            { key: 'warnings', label: 'Check warnings', value: found.filter(f => f.severity === 'warning').length, better: 'lower', format: 'count' },
+            { key: 'findings', label: 'Check findings', value: found.length, better: 'lower', format: 'count' },
+        ];
+    }
+
+    /**
+     * Two models' measures side by side, matched by key: `{key, label, format,
+     * before, after, change}` — change 'better', 'worse', 'same', or null when
+     * either is not measured.
+     */
+    static compare(before, after) {
+        const then = new Map(before.map(m => [m.key, m]));
+        return after.filter(m => then.has(m.key)).map(m => {
+            const was = then.get(m.key).value, now = m.value;
+            const change = was == null || now == null ? null
+                : was === now ? 'same'
+                    : (now < was) === (m.better === 'lower') ? 'better' : 'worse';
+            return { key: m.key, label: m.label, format: m.format ?? 'count', before: was, after: now, change };
+        });
+    }
+
+    /** A measure's value as it reads ('3', '50%', '72 of 100', '—'). */
+    static format(value, format = 'count') {
+        if (value == null) return '—';
+        if (format === 'share') return `${Math.round(value * 100)}%`;
+        if (format === 'score') return `${value} of 100`;
+        return String(value);
+    }
+
+    /** A comparison in a line: "Check findings 7 → 3 (better); …" — what did not change left out unless nothing did. */
+    static text(rows) {
+        const moved = rows.filter(r => r.change !== 'same');
+        const shown = moved.length ? moved : rows;
+        return shown.map(r => `${r.label} ${Benchmark.format(r.before, r.format)} → ${Benchmark.format(r.after, r.format)}${r.change && r.change !== 'same' ? ` (${r.change})` : ''}`).join('; ');
+    }
+}