@dxos/diagram 0.11.1 → 0.14.0

package/src/ports.ts

@@ -0,0 +1,186 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Port ordering: the classic heuristic that the order of connectors along a box side should match
+// the order in which they head off, so they fan out instead of swapping over next to the box. Each
+// terminal is keyed by where its route turns after leaving the side, and the side's free terminals
+// take lattice slots in key order around the ones that stay put.
+//
+
+import type * as Scene from './scene.ts';
+import { type Rect } from './uml-grid.ts';
+
+type Point = Scene.Point;
+
+export type Side = 'top' | 'bottom' | 'left' | 'right';
+
+/** A routed connector with the boxes its ends sit on. */
+export type PortPath = {
+  points: readonly Point[];
+  source: Rect;
+  target: Rect;
+  /** Ends whose coordinate must not move (a straightened edge, or a face the router picked itself). */
+  fixed?: { start?: boolean; end?: boolean };
+};
+
+/** New coordinates along the side for the ends that moved; an absent end keeps its place. */
+export type Assigned = { start?: number; end?: number };
+
+export type AssignOptions = {
+  /** Slot spacing and minimum distance from a box corner. */
+  step: number;
+};
+
+const EPSILON = 0.5;
+
+/** Longer than any first segment, so a route that never turns sorts between the two turning fans. */
+const STRAIGHT = 1e6;
+
+/** The side of `rect` that `point` sits on, if any. */
+export const sideOf = (point: Point, rect: Rect): Side | undefined => {
+  const withinX = point.x >= rect.x - EPSILON && point.x <= rect.x + rect.w + EPSILON;
+  const withinY = point.y >= rect.y - EPSILON && point.y <= rect.y + rect.h + EPSILON;
+  if (withinX && Math.abs(point.y - rect.y) < EPSILON) {
+    return 'top';
+  }
+  if (withinX && Math.abs(point.y - (rect.y + rect.h)) < EPSILON) {
+    return 'bottom';
+  }
+  if (withinY && Math.abs(point.x - rect.x) < EPSILON) {
+    return 'left';
+  }
+  if (withinY && Math.abs(point.x - (rect.x + rect.w)) < EPSILON) {
+    return 'right';
+  }
+  return undefined;
+};
+
+const axisOf = (side: Side): 'x' | 'y' => (side === 'top' || side === 'bottom' ? 'x' : 'y');
+const normalOf = (side: Side): 'x' | 'y' => (axisOf(side) === 'x' ? 'y' : 'x');
+
+/**
+ * Sort key of a terminal along its side, from its route read outward: a route turning toward the
+ * side's high end belongs at the high end, and of two turning the same way the one that runs out
+ * farther before turning sits nearer the low end, so neither turn-off cuts the other's stub.
+ */
+export const keyOf = (outward: readonly Point[], side: Side): number => {
+  const axis = axisOf(side);
+  const normal = normalOf(side);
+  if (outward.length < 3) {
+    return 0;
+  }
+  const [terminal, bend, next] = outward;
+  const run = Math.abs(bend[normal] - terminal[normal]);
+  const turn = Math.sign(next[axis] - bend[axis]);
+  return turn === 0 ? 0 : turn * (STRAIGHT - run);
+};
+
+type Terminal = { path: number; end: 'start' | 'end'; coord: number; key: number; fixed: boolean };
+
+/**
+ * Lattice slots for `free` (already in key order) strictly between `low` and `high`, each as near
+ * its current coordinate as order and spacing allow; undefined when they do not fit.
+ */
+const fit = (free: readonly Terminal[], low: number, high: number, step: number): number[] | undefined => {
+  const snap = (value: number) => Math.round(value / step) * step;
+  const first = Math.ceil((low + step - EPSILON) / step) * step;
+  const last = Math.floor((high - step + EPSILON) / step) * step;
+  if (free.length === 0) {
+    return [];
+  }
+  if ((last - first) / step + 1 < free.length) {
+    return undefined;
+  }
+  const slots: number[] = [];
+  for (const [index, terminal] of free.entries()) {
+    const floor = index === 0 ? first : slots[index - 1] + step;
+    slots.push(Math.max(floor, snap(terminal.coord)));
+  }
+  for (let index = free.length - 1; index >= 0; index--) {
+    const ceiling = index === free.length - 1 ? last : slots[index + 1] - step;
+    slots[index] = Math.min(slots[index], ceiling);
+  }
+  return slots;
+};
+
+/**
+ * Reorders the ports on every box side so they follow their routes' key order, moving only the
+ * sides whose current order disagrees with it. Fixed terminals stay where they are and the free
+ * ones take slots on the `step` lattice in the gaps between them, at least `step` from a corner.
+ */
+export const assign = (paths: readonly PortPath[], { step }: AssignOptions): Assigned[] => {
+  const sides = new Map<string, { rect: Rect; side: Side; terminals: Terminal[] }>();
+  const rectIds = new Map<Rect, number>();
+  const idOf = (rect: Rect) => rectIds.get(rect) ?? rectIds.set(rect, rectIds.size).get(rect) ?? 0;
+  paths.forEach((path, index) => {
+    const ends = [
+      { end: 'start' as const, rect: path.source, outward: path.points },
+      { end: 'end' as const, rect: path.target, outward: [...path.points].reverse() },
+    ];
+    for (const { end, rect, outward } of ends) {
+      const side = outward.length >= 2 ? sideOf(outward[0], rect) : undefined;
+      if (!side) {
+        continue;
+      }
+      const leaves = Math.abs(outward[1][axisOf(side)] - outward[0][axisOf(side)]) < EPSILON;
+      const id = `${idOf(rect)}:${side}`;
+      const entry = sides.get(id) ?? { rect, side, terminals: [] };
+      entry.terminals.push({
+        path: index,
+        end,
+        coord: outward[0][axisOf(side)],
+        key: keyOf(outward, side),
+        // A route that runs along its side before leaving it gives no direction to order by.
+        fixed: Boolean(path.fixed?.[end]) || !leaves,
+      });
+      sides.set(id, entry);
+    }
+  });
+
+  const result: Assigned[] = paths.map(() => ({}));
+  for (const { rect, side, terminals } of sides.values()) {
+    if (terminals.length < 2 || terminals.every((terminal) => terminal.fixed)) {
+      continue;
+    }
+    const sorted = [...terminals].sort(
+      (left, right) => left.key - right.key || left.coord - right.coord || left.path - right.path,
+    );
+    // Equal coordinates are a shared trunk, which the nudge splits; only distinct ones out of order cross.
+    const inverted = sorted.some((terminal, index) => index > 0 && terminal.coord < sorted[index - 1].coord - EPSILON);
+    if (!inverted) {
+      continue;
+    }
+    const axis = axisOf(side);
+    const [lowEdge, highEdge] = axis === 'x' ? [rect.x, rect.x + rect.w] : [rect.y, rect.y + rect.h];
+    const fixed = sorted.filter((terminal) => terminal.fixed);
+    // Fixed terminals must already be in key order for the free ones to fit around them.
+    if (fixed.some((terminal, index) => index > 0 && terminal.coord < fixed[index - 1].coord - EPSILON)) {
+      continue;
+    }
+    const bounds = [lowEdge, ...fixed.map((terminal) => terminal.coord), highEdge];
+    const groups: Terminal[][] = bounds.slice(1).map(() => []);
+    let gap = 0;
+    for (const terminal of sorted) {
+      if (terminal.fixed) {
+        gap++;
+      } else {
+        groups[gap].push(terminal);
+      }
+    }
+    const placed = groups.map((group, index) => fit(group, bounds[index], bounds[index + 1], step));
+    if (placed.some((slots) => !slots)) {
+      continue;
+    }
+    groups.forEach((group, index) =>
+      group.forEach((terminal, position) => {
+        const coord = placed[index]?.[position];
+        if (coord !== undefined) {
+          result[terminal.path][terminal.end] = coord;
+        }
+      }),
+    );
+  }
+  return result;
+};

package/src/relations.test.ts

@@ -0,0 +1,98 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { parse as parseDsl, printCommands, read } from './dsl/index.ts';
+import { markers, parse as parseMermaid } from './mermaid.ts';
+import * as Scene from './scene.ts';
+import { relationStyle } from './uml.ts';
+
+describe('relations', () => {
+  test('each relation derives its markers, and head/tail still override', ({ expect }) => {
+    expect(Scene.markersOf({ relation: 'inheritance' })).toEqual({ end: 'triangle', dashed: false });
+    expect(Scene.markersOf({ relation: 'implementation' })).toEqual({ end: 'triangle', dashed: true });
+    expect(Scene.markersOf({ relation: 'composition' })).toEqual({ start: 'diamond-filled', dashed: false });
+    expect(Scene.markersOf({ relation: 'aggregation' })).toEqual({ start: 'diamond', dashed: false });
+    expect(Scene.markersOf({ relation: 'one-to-many' })).toEqual({ start: 'one', end: 'crowsfoot', dashed: false });
+    expect(Scene.markersOf({ relation: 'many-to-many' })).toEqual({
+      start: 'crowsfoot',
+      end: 'crowsfoot',
+      dashed: false,
+    });
+    expect(Scene.markersOf({ relation: 'dependency' })).toEqual({ end: 'open', dashed: true });
+    // Documents from before relations keep drawing as they did.
+    expect(Scene.markersOf({})).toEqual({ end: 'arrow', dashed: false });
+    expect(Scene.markersOf({ head: 'triangle', tail: 'circle' })).toEqual({
+      start: 'circle',
+      end: 'triangle',
+      dashed: false,
+    });
+    expect(Scene.markersOf({ relation: 'inheritance', head: 'none' })).toEqual({ dashed: false });
+  });
+
+  test('the DSL relationship words', ({ expect }) => {
+    const { diagram, problems } = read(`
+      node Animal  node Dog  node Shape  node Square  node Order  node Line  node Team  node Member
+      node Customer  node Student  node Course  node App  node Log
+      edge Dog extends Animal
+      edge Square implements Shape
+      edge Order composes Line
+      edge Team owns Member
+      edge Customer one-to-many Order
+      edge Student many-to-many Course
+      edge App depends-on Log
+      edge App -> Log
+    `);
+    expect(problems).toEqual([]);
+    expect(diagram?.edges.map((edge) => `${edge.from.node}:${edge.relation ?? '-'}:${edge.to.node}`)).toEqual([
+      'Dog:inheritance:Animal',
+      'Square:implementation:Shape',
+      'Order:composition:Line',
+      'Team:aggregation:Member',
+      'Customer:one-to-many:Order',
+      'Student:many-to-many:Course',
+      'App:dependency:Log',
+      'App:-:Log',
+    ]);
+  });
+
+  test('an unknown relationship word is an error on the word', ({ expect }) => {
+    const text = 'node A\nnode B\nedge A loves B';
+    const [problem] = parseDsl(text).problems;
+    expect(text.slice(problem.from, problem.to)).toBe('loves');
+  });
+
+  test('laid-out edges carry their relation, and the scene round-trips through print and parse', ({ expect }) => {
+    const { commands } = parseDsl(
+      'node Animal\nnode Dog below Animal\nedge Dog extends Animal\nnode Leg below Dog\nedge Dog composes Leg',
+    );
+    const edges = commands.flatMap((command) =>
+      command.op === 'upsert-object' && command.object.id === 'edges' ? command.object.elements : [],
+    );
+    const relations = edges.flatMap((element) => (element.kind === 'arrow' ? [element.relation] : []));
+    expect(relations).toEqual(['inheritance', 'composition']);
+    const printed = printCommands(commands);
+    expect(printed).toContain('relation=inheritance');
+    expect(printCommands(parseDsl(printed).commands)).toBe(printed);
+  });
+
+  test('mermaid tokens, UML class relations and DSL words agree', ({ expect }) => {
+    const graph = parseMermaid(
+      ['flowchart TB', '  B --|> A', '  C ..|> A', '  E o--> F', '  G --{ H', '  I -.-> J'].join('\n'),
+    );
+    expect(graph.edges.map(({ kind }) => markers(kind).relation)).toEqual([
+      'inheritance',
+      'implementation',
+      'aggregation',
+      'one-to-many',
+      'dependency',
+    ]);
+    expect(
+      (['inheritance', 'realization', 'composition', 'aggregation', 'dependency', 'association'] as const).map(
+        (kind) => relationStyle(kind).relation,
+      ),
+    ).toEqual(['inheritance', 'implementation', 'composition', 'aggregation', 'dependency', undefined]);
+  });
+});

package/src/rules.ts

@@ -0,0 +1,117 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// The diagram rule library: what makes a drawing read well to a person, as `diagram-rule` blocks in
+// `rules/DIAGRAM.mdl` (a term of its own, so the code-review harness, which reads `rule` blocks, never
+// picks these up). Each rule names how it is judged: `code` rules are measured from the scene's
+// geometry by `Appeal`, `vision` rules are asked of a decision model shown the rendered image, and
+// `both` rules have a geometric measure that the image judge can be checked against.
+//
+
+import text from '../rules/DIAGRAM.mdl?raw';
+
+export type Evaluator = 'code' | 'vision' | 'both';
+
+export type Category = 'crossings' | 'flow' | 'alignment' | 'space' | 'groups' | 'labels' | 'edges' | 'hierarchy';
+
+export type DiagramRule = {
+  /** Kebab-case id; `Appeal`'s evaluators and the image judge's decision keys are derived from it. */
+  readonly id: string;
+  /** What a good diagram does, in one line. */
+  readonly title: string;
+  readonly category: Category;
+  readonly evaluator: Evaluator;
+  /** Relative importance in the overall appeal score; the research ranks crossings far above the rest. */
+  readonly weight: number;
+  /** The yes/no question a vision judge answers; `yes` means the drawing follows the rule. */
+  readonly question?: string;
+  readonly criteria?: { readonly true: string; readonly false: string };
+  /** Rationale, the evidence behind the rule, and what does not count against it. */
+  readonly prose: string;
+};
+
+const EVALUATORS: readonly Evaluator[] = ['code', 'vision', 'both'];
+const CATEGORIES: readonly Category[] = [
+  'crossings',
+  'flow',
+  'alignment',
+  'space',
+  'groups',
+  'labels',
+  'edges',
+  'hierarchy',
+];
+const FIELDS = new Set(['category', 'evaluator', 'weight', 'question', 'yes', 'no']);
+
+const isEvaluator = (value: string): value is Evaluator => (EVALUATORS as readonly string[]).includes(value);
+const isCategory = (value: string): value is Category => (CATEGORIES as readonly string[]).includes(value);
+
+/** The line arrays of every ```mdl fence in a document. */
+const fences = (document: string): string[][] => {
+  const blocks: string[][] = [];
+  let block: string[] | undefined;
+  for (const line of document.split(/\r?\n/)) {
+    if (!block) {
+      if (/^\s*```mdl\s*$/.test(line)) {
+        block = [];
+      }
+    } else if (/^\s*```\s*$/.test(line)) {
+      blocks.push(block);
+      block = undefined;
+    } else {
+      block.push(line);
+    }
+  }
+  return blocks;
+};
+
+/**
+ * Parses the `diagram-rule` blocks of an `.mdl` document, ignoring every other block. A malformed rule
+ * throws, naming it, since a rule that silently drops out would leave its evaluator unbound.
+ */
+export const parse = (document: string): DiagramRule[] =>
+  fences(document).flatMap((lines) => {
+    const start = lines.findIndex((line) => line.trim() !== '');
+    const header = start >= 0 ? /^diagram-rule\s+([a-z0-9-]+)\s*:\s*(.+)$/.exec(lines[start].trim()) : null;
+    if (!header) {
+      return [];
+    }
+    const [, id, title] = header;
+    const fields: Record<string, string> = {};
+    const prose: string[] = [];
+    for (const line of lines.slice(start + 1)) {
+      const field = /^\s*([a-z]+)\s*:\s*(.*)$/.exec(line);
+      if (field && FIELDS.has(field[1])) {
+        fields[field[1]] = field[2].trim();
+      } else {
+        prose.push(line.trim());
+      }
+    }
+    const { category = '', evaluator = '', weight = '1', question, yes, no } = fields;
+    if (!isCategory(category) || !isEvaluator(evaluator) || !Number.isFinite(Number(weight))) {
+      throw new Error(`diagram-rule ${id}: needs category (${CATEGORIES.join('|')}), evaluator and a numeric weight.`);
+    }
+    if (evaluator !== 'code' && !question) {
+      throw new Error(`diagram-rule ${id}: a ${evaluator} rule needs a question for the image judge.`);
+    }
+    return [
+      {
+        id,
+        title,
+        category,
+        evaluator,
+        weight: Number(weight),
+        ...(question ? { question } : {}),
+        ...(yes && no ? { criteria: { true: yes, false: no } } : {}),
+        prose: prose.join('\n').trim(),
+      },
+    ];
+  });
+
+/** Every rule in `rules/DIAGRAM.mdl`. */
+export const RULES: readonly DiagramRule[] = parse(text);
+
+/** The camelCase decision key a judge answers a rule under. */
+export const keyOf = (id: string): string => id.replace(/-([a-z0-9])/g, (_, letter: string) => letter.toUpperCase());

package/src/scene.ts

@@ -28,7 +28,8 @@ export const Color = Schema.Literals([
 ]);
 export type Color = Schema.Schema.Type<typeof Color>;
 
-export const Fill = Schema.Literals(['none', 'solid', 'pattern']);
+/** `tint` is a light wash of the element's color, for backdrops such as group frames that text sits on. */
+export const Fill = Schema.Literals(['none', 'solid', 'pattern', 'tint']);
 export type Fill = Schema.Schema.Type<typeof Fill>;
 
 export const Stroke = Schema.Literals(['sketchy', 'solid', 'dashed', 'dotted']);
@@ -55,9 +56,17 @@ const id = Schema.String.annotate({
   description: 'Stable element id, unique within the object (e.g. "left-eye"). Used to edit or delete the element.',
 });
 
+/** The closed-shape kinds {@link Box} covers. */
+export const BoxKind = Schema.Literals(['rect', 'ellipse', 'diamond', 'triangle']);
+export type BoxKind = Schema.Schema.Type<typeof BoxKind>;
+
+/** Which corners a rect rounds. */
+export const Corners = Schema.Literals(['top', 'bottom', 'none']);
+export type Corners = Schema.Schema.Type<typeof Corners>;
+
 /** Closed shape drawn inside a local bounding box. */
 export const Box = Schema.Struct({
-  kind: Schema.Literals(['rect', 'ellipse', 'diamond', 'triangle']),
+  kind: BoxKind,
   id,
   x: Schema.Number.annotate({ description: 'Left edge (object-local units).' }),
   y: Schema.Number.annotate({ description: 'Top edge (object-local units).' }),
@@ -65,7 +74,7 @@ export const Box = Schema.Struct({
   h: Schema.Number,
   rotation: Schema.optional(Schema.Number).annotate({ description: 'Clockwise rotation in degrees.' }),
   text: Schema.optional(Schema.String).annotate({ description: 'Centered label.' }),
-  corners: Schema.optional(Schema.Literals(['top', 'bottom', 'none'])).annotate({
+  corners: Schema.optional(Corners).annotate({
     description: 'Rects only: round just these corners (default all); backends without corner control ignore it.',
   }),
   ...styleFields,
@@ -135,9 +144,57 @@ export type Text = Schema.Schema.Type<typeof Text>;
 /** UML-style end markers: the head sits at the target, the tail at the source. */
 export const ArrowHead = Schema.Literals(['arrow', 'triangle', 'crowsfoot', 'none']);
 export type ArrowHead = Schema.Schema.Type<typeof ArrowHead>;
-export const ArrowTail = Schema.Literals(['none', 'circle']);
+export const ArrowTail = Schema.Literals(['none', 'circle', 'arrow']);
 export type ArrowTail = Schema.Schema.Type<typeof ArrowTail>;
 
+/**
+ * What a connector means, in UML and ER terms; renderers derive its end markers and dash from it.
+ * The source end is the subtype (inheritance, implementation), the whole (composition), the owner
+ * (aggregation), or the one side (one-to-many); the target end is the other.
+ */
+export const Relation = Schema.Literals([
+  'association',
+  'dependency',
+  'inheritance',
+  'implementation',
+  'composition',
+  'aggregation',
+  'one-to-many',
+  'many-to-many',
+]);
+export type Relation = Schema.Schema.Type<typeof Relation>;
+
+/** A marker a renderer draws at a connector end. */
+export type Marker = 'arrow' | 'open' | 'triangle' | 'crowsfoot' | 'one' | 'diamond' | 'diamond-filled' | 'circle';
+
+export type RelationMarkers = { start?: Marker; end?: Marker; dashed: boolean };
+
+const RELATION_MARKERS: Record<Relation, RelationMarkers> = {
+  'association': { end: 'arrow', dashed: false },
+  'dependency': { end: 'open', dashed: true },
+  'inheritance': { end: 'triangle', dashed: false },
+  'implementation': { end: 'triangle', dashed: true },
+  'composition': { start: 'diamond-filled', dashed: false },
+  'aggregation': { start: 'diamond', dashed: false },
+  'one-to-many': { start: 'one', end: 'crowsfoot', dashed: false },
+  'many-to-many': { start: 'crowsfoot', end: 'crowsfoot', dashed: false },
+};
+
+/**
+ * The markers an arrow draws: its relation's, unless `head` or `tail` says otherwise, which keeps
+ * documents written before relations existed drawing as they did.
+ */
+export const markersOf = (arrow: Pick<Arrow, 'relation' | 'head' | 'tail' | 'stroke'>): RelationMarkers => {
+  const derived = arrow.relation ? RELATION_MARKERS[arrow.relation] : { end: 'arrow' as const, dashed: false };
+  const end = arrow.head === undefined ? derived.end : arrow.head === 'none' ? undefined : arrow.head;
+  const start = arrow.tail === undefined ? derived.start : arrow.tail === 'none' ? undefined : arrow.tail;
+  return {
+    ...(start ? { start } : {}),
+    ...(end ? { end } : {}),
+    dashed: arrow.stroke === undefined ? derived.dashed : arrow.stroke === 'dashed',
+  };
+};
+
 /**
  * Connector. Endpoints are element refs — `"<elementId>"` within the same object or
  * `"<objectId>/<elementId>"` across objects, either with an optional `#<port>` naming an
@@ -156,7 +213,11 @@ export const Arrow = Schema.Struct({
     description: 'Marker at the target end (default arrow): triangle for inheritance, crowsfoot for has-many.',
   }),
   tail: Schema.optional(ArrowTail).annotate({
-    description: 'Marker at the source end (default none): circle for containment.',
+    description: 'Marker at the source end (default none): circle for containment, arrow for a two-way connector.',
+  }),
+  relation: Schema.optional(Relation).annotate({
+    description:
+      'What the connector means; sets its markers: inheritance and implementation (hollow triangle at the target), composition and aggregation (filled or hollow diamond at the source, the whole), one-to-many (bar at the source, crow’s foot at the target), many-to-many, dependency (dashed, open arrow), association.',
   }),
   ...styleFields,
 });

package/src/score.test.ts

@@ -0,0 +1,64 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import { describe, test } from 'vitest';
+
+import { analyze } from './diagnostics.ts';
+import { DEFAULT, type Layout } from './objective.ts';
+import type * as Scene from './scene.ts';
+import { HALF_COST, evaluate, fromCost, fromObjective, overall } from './score.ts';
+
+const box = (id: string, x: number, y: number): Scene.WorldObject => ({
+  id,
+  origin: { x, y },
+  elements: [{ kind: 'rect', id: 'frame', x: 0, y: 0, w: 64, h: 64 }],
+});
+
+const layoutOf = (objects: Scene.WorldObject[]): Layout => ({ objects, report: analyze(objects) });
+
+describe('score', () => {
+  test('cost maps to 1 at zero, 0.5 at half, towards 0 beyond', ({ expect }) => {
+    expect(fromCost(0)).toBe(1);
+    expect(fromCost(HALF_COST)).toBe(0.5);
+    expect(fromCost(HALF_COST * 99)).toBeCloseTo(0.01);
+    expect(fromCost(-1)).toBe(1);
+  });
+
+  test('objective scorers are constraints then costs, all in [0, 1]', ({ expect }) => {
+    const scores = Effect.runSync(evaluate(fromObjective(DEFAULT), layoutOf([box('a', 0, 0), box('b', 256, 0)])));
+    expect(scores.map(({ kind }) => kind)).toEqual([
+      ...DEFAULT.constraints.map(() => 'constraint'),
+      ...DEFAULT.costs.map(() => 'cost'),
+    ]);
+    for (const { score } of scores) {
+      expect(score).toBeGreaterThanOrEqual(0);
+      expect(score).toBeLessThanOrEqual(1);
+    }
+    expect(overall(scores)).toBeGreaterThan(0);
+  });
+
+  test('a broken constraint scores 0 and gates the overall score', ({ expect }) => {
+    const scores = Effect.runSync(evaluate(fromObjective(DEFAULT), layoutOf([box('a', 0, 0), box('b', 32, 32)])));
+    const hard = scores.find(({ id }) => id === 'no-hard-defects');
+    expect(hard?.score).toBe(0);
+    expect(hard?.detail).toMatch(/overlap/);
+    expect(overall(scores)).toBe(0);
+  });
+
+  test('nothing judged is no score, not a perfect one', ({ expect }) => {
+    expect(overall([])).toBeUndefined();
+    expect(overall([{ kind: 'architecture', score: 0, error: 'down' }])).toBeUndefined();
+  });
+
+  test('other kinds join the mean', ({ expect }) => {
+    expect(
+      overall([
+        { kind: 'constraint', score: 1 },
+        { kind: 'cost', score: 0.5 },
+        { kind: 'judge', score: 1 },
+      ]),
+    ).toBe(0.75);
+  });
+});