@formicoidea/labre-core 0.31.0 → 0.33.0

package/dist/_pkgs/affine-block-surface/extensions/validation.js

@@ -0,0 +1,4620 @@
+import { createIdentifier } from '../../global/di/index.js';
+import { Bound, lineIntersects } from '../../global/gfx/index.js';
+import { GfxGroupLikeElementModel, GfxPrimitiveElementModel, InteractivityExtension, roleIsA, } from '../../std/gfx/index.js';
+import { effect, signal } from '@preact/signals-core';
+import { backgroundPlot } from '../framework-background/def.js';
+import { backgroundAxisFact, backgroundTransitionBands, backgroundTransitionVisibleProps, } from '../framework-background/facts.js';
+import { backgroundInVariant } from '../framework-background/labels.js';
+import { Overlay, OverlayIdentifier } from '../renderer/overlay.js';
+import { QualityNudgeIdentifier } from './map-quality.js';
+import { ViolationTimeline } from './violation-timeline.js';
+/**
+ * Severity `profile` gives `rule` — the rule's own when the profile is silent
+ * about it, or when there is no profile at all.
+ */
+export function profileSeverity(rule, profile) {
+    // Own keys only: `rules` is an object literal shipped by a framework, so
+    // `rules['constructor']` must not resolve to something off the prototype.
+    return profile !== undefined && Object.hasOwn(profile.rules, rule.id)
+        ? profile.rules[rule.id]
+        : rule.severity;
+}
+/**
+ * The profile a background of `framework` is checked against when it names
+ * none: the one flagged {@link ValidationProfile.isDefault}, or — failing that
+ * — the first one registered, so a framework that forgot the flag still has a
+ * resolvable answer instead of silently losing its profiles.
+ */
+export function defaultProfileOf(profiles, framework) {
+    let first;
+    for (const profile of profiles) {
+        if (profile.framework !== framework)
+            continue;
+        if (profile.isDefault)
+            return profile;
+        first ??= profile;
+    }
+    return first;
+}
+function indexProfiles(profiles) {
+    const byId = new Map();
+    const defaults = new Map();
+    for (const profile of profiles) {
+        byId.set(profile.id, profile);
+        if (defaults.has(profile.framework))
+            continue;
+        const fallback = defaultProfileOf(profiles, profile.framework);
+        if (fallback)
+            defaults.set(profile.framework, fallback);
+    }
+    return { byId, defaults };
+}
+/**
+ * The profile a finding of `rule` is judged by: the one its background NAMES,
+ * or the framework's default.
+ *
+ * A profile id belonging to another framework is ignored rather than honoured:
+ * a background carrying `bpmn.executable` says nothing about a Wardley rule,
+ * and a stale id left behind by a paste must never silence one.
+ */
+function resolveProfile(rule, chosenId, index) {
+    const named = chosenId === undefined ? undefined : index.byId.get(chosenId);
+    if (named !== undefined && named.framework === rule.framework)
+        return named;
+    return index.defaults.get(rule.framework);
+}
+/**
+ * The profile id each role-carrying element names, in one pass — then the same
+ * for the ones that name none but SIT INSIDE one that does.
+ *
+ * Role-carrying only: a profile is a decision about a framework's background,
+ * and a neutral element cannot be one. That keeps the pass on exactly the same
+ * cheap guard the rule families already use.
+ */
+function readChosenProfiles(elements) {
+    const chosen = new Map();
+    const roleCarrying = [];
+    for (const el of elements) {
+        if (el.role === undefined)
+            continue;
+        roleCarrying.push(el);
+        const id = el.validationProfile;
+        // Whatever a peer wrote: a client that got it wrong must not break
+        // evaluation on this one.
+        if (typeof id === 'string')
+            chosen.set(el.id, id);
+    }
+    // Nobody chose anything => no inheritance to compute, and not one bound read
+    // on the whole surface. The overwhelmingly common case: choosing the default
+    // profile back WRITES NOTHING (`setProfile` clears the field), so `chosen` is
+    // empty on every document whose author never left the default.
+    if (chosen.size > 0)
+        inheritChosenProfiles(roleCarrying, chosen);
+    return chosen;
+}
+/**
+ * A frame that named no profile inherits the one chosen on the frame it is
+ * DRAWN INSIDE — the innermost of them.
+ *
+ * ## The question this answers
+ *
+ * A profile is chosen per root instance (PF9.1), and a finding is judged by the
+ * profile of the instance it is ATTRIBUTED to ({@link applyProfiles}). Those two
+ * sentences only describe the same element while every attribution target is
+ * something the author can reach a picker on. They stop describing the same
+ * element the moment a framework frames a question against an INNER frame — a
+ * C4 boundary, a BPMN lane — and the picker is offered on the outer one alone,
+ * which is the arbitration C4's recette settled (PO, 28/08/2026: the board
+ * arbitrates the checklist, the boundary does not). Without this, raising a
+ * board to its review level would harden the eleven rules framed against the
+ * board and silently leave the two framed against a boundary at the default
+ * for ever.
+ *
+ * Inheritance is the general form of that fix and carries no framework name: an
+ * instance with no choice of its own is governed by the choice made on the
+ * frame it sits in, which is what a reader looking at the two nested rectangles
+ * already assumes. An instance that DOES name a profile keeps it — a nested
+ * frame can still be arbitrated separately the day a framework offers a picker
+ * on one.
+ *
+ * ## The arithmetic
+ *
+ * Centre-in-frame, innermost first, ties to the smaller id — the same reading
+ * {@link plotContaining}, the audit and the C4 export use to answer "which frame
+ * is this drawn on", so a board can never read two different answers to that
+ * question. The element BOX rather than the plot: a plot needs the frame's
+ * geometry declaration, which is a per-RULE datum, and this map is built once
+ * for every rule at once. The margin only matters to an artefact lying on a
+ * title band, and inheriting a level of requirement there is harmless where
+ * counting it as a member would not be.
+ *
+ * Cross-framework nesting resolves itself downstream and needs no test here:
+ * {@link resolveProfile} ignores a profile id belonging to another framework, so
+ * a frame that inherits a foreign one falls back to its own framework's default
+ * — exactly what it got before inheriting anything.
+ */
+function inheritChosenProfiles(elements, chosen) {
+    const frames = elements
+        .filter(el => chosen.has(el.id))
+        .map(el => ({ id: el.id, bound: el.elementBound }));
+    // Read off the map BEFORE writing to it: an inherited id must never be
+    // inherited on again, or a chain of frames would depend on the walk order.
+    const inherited = [];
+    for (const el of elements) {
+        if (chosen.has(el.id))
+            continue;
+        const centre = el.elementBound.center;
+        let inner = null;
+        for (const frame of frames) {
+            if (!frame.bound.containsPoint(centre))
+                continue;
+            if (inner === null ||
+                isInside(frame.bound, inner.bound, frame.id, inner.id)) {
+                inner = frame;
+            }
+        }
+        if (inner !== null)
+            inherited.push([el.id, chosen.get(inner.id)]);
+    }
+    for (const [id, profileId] of inherited)
+        chosen.set(id, profileId);
+}
+/** Whether `a` is the tighter frame of the two — smaller area, then smaller id. */
+function isInside(a, b, aId, bId) {
+    const areaA = a.w * a.h;
+    const areaB = b.w * b.h;
+    return areaA === areaB ? aId < bId : areaA < areaB;
+}
+/**
+ * Whether `rule` is `'off'` under EVERY profile in play on this surface — in
+ * which case it is not evaluated at all, which is what `'off'` is for.
+ *
+ * The default counts as in play unconditionally: a background naming nothing
+ * falls back to it, and the surface can gain one at any moment. So the
+ * short-circuit only fires when the answer cannot change, and errs towards
+ * evaluating — a missed skip costs a linear pass, a wrong skip costs a silent
+ * rule.
+ */
+function isRuleSilent(rule, chosen, index) {
+    if (profileSeverity(rule, index.defaults.get(rule.framework)) !== 'off') {
+        return false;
+    }
+    for (const id of chosen.values()) {
+        const profile = index.byId.get(id);
+        // Unknown id, or another framework's: falls back to the default, already
+        // known to be off.
+        if (profile === undefined || profile.framework !== rule.framework)
+            continue;
+        if (profileSeverity(rule, profile) !== 'off')
+            return false;
+    }
+    return true;
+}
+/**
+ * Re-judge what a rule raised, background by background: rewrite each finding's
+ * severity to what its own profile says, and drop the ones the profile turned
+ * off.
+ *
+ * After the family, never before: only the family knows which background a
+ * finding was measured against ({@link Violation.backgroundId}), and that is
+ * precisely what names the profile. A family measuring against no background
+ * has no instance to read a choice from and falls back to the default.
+ */
+function applyProfiles(rule, raised, chosen, index) {
+    const kept = [];
+    for (const violation of raised) {
+        const chosenId = violation.backgroundId === undefined
+            ? undefined
+            : chosen.get(violation.backgroundId);
+        const severity = profileSeverity(rule, resolveProfile(rule, chosenId, index));
+        if (severity === 'off')
+            continue;
+        violation.severity = severity;
+        kept.push(violation);
+    }
+    return kept;
+}
+/**
+ * Complain once per distinct problem. A family runs on every evaluation, so a
+ * bare `console.warn` about a malformed rule would fill the console at 8 Hz
+ * while somebody drags.
+ */
+const warned = new Set();
+function warnOnce(reason) {
+    if (warned.has(reason))
+        return;
+    warned.add(reason);
+    console.warn(`[validation] ${reason}`);
+}
+/**
+ * Every background instance on the surface carrying the rule's frame role.
+ *
+ * Empty when the rule declares no frame role, and empty on a board whose maps
+ * were all authored before that role existed — which is what makes an old
+ * document stay a sketch instead of lighting up.
+ */
+function backgroundsOf(rule, elements) {
+    const backgroundRole = rule.backgroundRole;
+    if (backgroundRole === undefined)
+        return [];
+    const backgrounds = [];
+    for (const el of elements) {
+        if (el.role === undefined)
+            continue;
+        if (roleIsA(el.role, backgroundRole, rule.roles)) {
+            backgrounds.push({
+                id: el.id,
+                bound: el.elementBound,
+                props: el,
+            });
+        }
+    }
+    return backgrounds;
+}
+/**
+ * Every element on the surface acting as a framework background for a REAL-TIME
+ * rule.
+ *
+ * Recorded by the manager after each evaluation, and read on the next one — the
+ * one fact about a deleted background that nothing else can reconstruct. See
+ * {@link ValidationManager._backgrounds}.
+ *
+ * ## Why the moment is filtered here too
+ *
+ * This runs on the gesture path, once per evaluation, and it is a FULL surface
+ * walk per rule. `evaluateRules` already refuses to walk an on-demand rule, so
+ * leaving it in here would have handed the drawing budget back exactly what the
+ * second moment took away from it — measured at +58 % on the manager's tick with
+ * the two Wardley check-up rules registered, and invisible to a bench that times
+ * `evaluateRules` alone.
+ *
+ * It is also the right answer and not merely the cheap one: `_backgrounds`
+ * exists to decide whether an incremental REAL-TIME pass must fall back to a
+ * full sweep. An on-demand rule never takes part in that pass, so the frames it
+ * measures against have nothing to invalidate — and a framework whose only rules
+ * are on-demand has no incremental pass to protect in the first place.
+ */
+export function backgroundElementIds(rules, elements) {
+    const ids = new Set();
+    for (const rule of rules) {
+        if (!isRealtime(rule))
+            continue;
+        for (const background of backgroundsOf(rule, elements))
+            ids.add(background.id);
+    }
+    return ids;
+}
+/**
+ * The instance a finding is attributed to: the one that CONTAINS the subject,
+ * failing that the nearest by edge-to-edge gap.
+ *
+ * Same question `evaluateElementInBackground` answers inline, asked by the
+ * families whose subjects normally ARE on the map — an inertia bar, an arrow, a
+ * pair of overlapping labels. Ties go to the smaller id so a persisted
+ * arbitration never depends on the order a `Y.Map` was rebuilt in — on BOTH
+ * halves of the question: a small chart dropped on a big one contains the same
+ * artefact twice, and returning whichever of the two the walk met first would
+ * have made the promise above true only of the near miss. Same walk and same
+ * tie-break as {@link containingBackground}, which asks the containment half
+ * alone.
+ */
+function attributeBackground(bound, backgrounds) {
+    let containing = null;
+    let nearest = null;
+    let nearestDistance = Infinity;
+    for (const background of backgrounds) {
+        if (background.bound.contains(bound)) {
+            if (containing === null || background.id < containing.id) {
+                containing = background;
+            }
+            continue;
+        }
+        const distance = gapSquared(background.bound, bound);
+        if (distance < nearestDistance ||
+            (distance === nearestDistance &&
+                nearest !== null &&
+                background.id < nearest.id)) {
+            nearestDistance = distance;
+            nearest = background;
+        }
+    }
+    return containing ?? nearest;
+}
+/**
+ * The PLOT of one instance, in model coordinates — the element box minus the
+ * declared margin, i.e. the region the frame actually draws its content in.
+ *
+ * A rule that carries no {@link ValidationRule.background} declaration has no
+ * margin to subtract and the whole element box is its plot. That is the honest
+ * answer rather than a refusal: `backgroundRole` alone is a complete declaration
+ * for a family that only needs to know WHICH frame something is on, and
+ * demanding a geometry declaration to count elements inside a box would be
+ * asking a framework to declare axes its rule never reads (the same argument
+ * `relation-endpoints` makes about its own optional frame).
+ *
+ * ## The degenerate plot
+ *
+ * `backgroundPlot` subtracts the declared margins with no guard, so a frame
+ * dragged narrower than `margin.left + margin.right` yields a NEGATIVE extent —
+ * and a `Bound` of negative width contains no point at all, anywhere. Left
+ * alone, a membership family would then tally zero for a frame the user can see
+ * holding something, and a `min` rule would answer "this frame holds none" while
+ * pointing at one that visibly does. A false accusation whose only remedy —
+ * widen the frame — is nowhere in the sentence.
+ *
+ * So a plot that has collapsed falls back to the element box: the same answer
+ * this function already gives a rule that declares no geometry at all, and the
+ * one reading under which the artefact the user is looking at still counts.
+ * Silence would be defensible too; being wrong in the accusing direction is not.
+ */
+function plotOf(def, frame) {
+    const bound = frame.bound;
+    if (def === undefined)
+        return bound;
+    const plot = backgroundPlot(def, bound.w, bound.h);
+    if (!(plot.width > 0) || !(plot.height > 0))
+        return bound;
+    return new Bound(bound.x + plot.x0, bound.y + plot.y0, plot.width, plot.height);
+}
+/**
+ * The instance an element BELONGS TO: the one whose plot contains its centre,
+ * and nothing else.
+ *
+ * ## The deliberate divergence from {@link attributeBackground}
+ *
+ * `attributeBackground` answers "which map is this finding about", and falls
+ * back to the NEAREST frame when none contains the subject — which is right for
+ * a finding that has already been raised and needs somewhere to be waived.
+ *
+ * This answers a different question: "is this artefact IN that frame". A
+ * nearest-fallback here would be a bug with a plausible face — a start event
+ * floating just outside a pool would satisfy "this pool has a start event", and
+ * a sequence flow from inside the pool to that floating task would read as
+ * staying inside it. Membership has to mean membership, or the two families
+ * built on it certify drawings that show the opposite of what they claim.
+ *
+ * The CENTRE, and the plot rather than the element box: the centre is where the
+ * eye puts an artefact (the reading {@link ElementInZoneDef.measure} already
+ * defaults to) and the plot is the region the frame draws in, so an artefact
+ * lying on the pool's own title band is not counted as being in the pool. Same
+ * resolution the audit uses to place an element, so a board never reads two
+ * different answers to "which frame is this on".
+ *
+ * Ties go to the smaller id, never to the order a `Y.Map` was rebuilt in — the
+ * invariant every attribution in this file holds, and it matters here for the
+ * same reason: the answer decides which frame a persisted arbitration is
+ * written on.
+ */
+function plotContaining(centre, frames) {
+    let found = null;
+    for (const frame of frames) {
+        if (!frame.plot.containsPoint(centre))
+            continue;
+        if (found === null || frame.instance.id < found.id)
+            found = frame.instance;
+    }
+    return found;
+}
+/**
+ * Every instance of the rule's frame, each with its plot resolved once.
+ *
+ * A board carries units of frames and hundreds of subjects, so the margin
+ * arithmetic is done per FRAME and never per subject.
+ */
+function framePlots(rule, elements) {
+    return backgroundsOf(rule, elements).map(instance => ({
+        instance,
+        plot: plotOf(rule.background, instance),
+    }));
+}
+/**
+ * Whether a rule whose whole question is asked ABOUT a frame forgot to name one
+ * — and, if so, says so once.
+ *
+ * `backgroundsOf` answers `[]` both for "this rule names no frame role" and for
+ * "this board carries no such frame", and the second is a legitimate silence
+ * every family in this file honours: a sketch drawn before the frame is a
+ * sketch. The first is a typo in the data, and left undistinguished it produces
+ * a rule that never fires and never says why — the failure the missing-bound
+ * warnings a few lines below exist to prevent, under a comment saying it is the
+ * worst thing declarative data can do.
+ *
+ * The two are distinguishable statically, so they are distinguished here, before
+ * a single element is walked.
+ */
+function missingFrameRole(rule, family) {
+    if (rule.backgroundRole !== undefined)
+        return false;
+    warnOnce(`${family} rule "${rule.id}" names no frame role, and its whole question ` +
+        `is asked about a frame — the rule is not evaluated.`);
+    return true;
+}
+/**
+ * Build the finding of `rule` against `elementIds`. One place, so every family
+ * carries the rule's keys, its fallbacks and its background attribution the
+ * same way.
+ *
+ * `words` is how a family with several ways of failing says WHICH one did: the
+ * finding is still the rule's — same id, same severity, same arbitration — but
+ * the sentence the user reads is the one that fits their mistake.
+ */
+function raise(rule, elementIds, backgroundId, words = rule) {
+    return {
+        ruleId: rule.id,
+        elementIds,
+        severity: rule.severity,
+        messageKey: words.messageKey,
+        ...(words.messageFallback !== undefined
+            ? { messageFallback: words.messageFallback }
+            : {}),
+        ...(words.suggestionKey ? { suggestion: words.suggestionKey } : {}),
+        ...(words.suggestionFallback !== undefined
+            ? { suggestionFallback: words.suggestionFallback }
+            : {}),
+        ...(backgroundId !== undefined ? { backgroundId } : {}),
+    };
+}
+/**
+ * "Is this element on the framework's background?"
+ *
+ * An element carrying `rule.appliesTo` (or a specialisation of it) whose bounds
+ * are not fully contained by any element carrying `rule.backgroundRole` is in
+ * violation. BOTH sides are roles — the engine never reads a shape type.
+ *
+ * When the surface carries NO background with that role there is no map to be
+ * outside of, so the rule yields nothing: a Wardley node dropped on a blank
+ * canvas is a sketch, not an error — and so is a map authored before the role
+ * existed.
+ *
+ * Cost: two linear passes, one `elementBound` per candidate. Backgrounds are
+ * counted in units, so the per-element cost is constant in practice.
+ */
+function evaluateElementInBackground(rule, elements) {
+    const subjectRole = rule.appliesTo;
+    if (subjectRole === undefined)
+        return [];
+    const backgrounds = backgroundsOf(rule, elements);
+    if (backgrounds.length === 0)
+        return [];
+    const violations = [];
+    for (const el of elements) {
+        // Cheapest possible exit for a neutral element: no role, no evaluation.
+        if (el.role === undefined)
+            continue;
+        if (!roleIsA(el.role, subjectRole, rule.roles))
+            continue;
+        const bound = el.elementBound;
+        // One pass, and it answers two questions at once: is this element on ANY
+        // map (in which case there is nothing to report), and if not, which map is
+        // it nearest to. The second answer is the finding's `backgroundId`, and it
+        // has to be taken here — a board carries several maps, and by the time the
+        // violation reaches the UI there is no way left to tell which one the user
+        // was working on.
+        let nearest = null;
+        let nearestDistance = Infinity;
+        let framed = false;
+        for (const background of backgrounds) {
+            if (background.bound.contains(bound)) {
+                framed = true;
+                break;
+            }
+            const distance = gapSquared(background.bound, bound);
+            // Strictly nearer wins; an exact tie is broken by the smaller id, never
+            // by which background the surface happened to be walked in first.
+            // `backgroundId` decides where a PERSISTED decision gets written and read
+            // back, so it cannot depend on the iteration order of a Map rebuilt from
+            // a Y.Map on every load and every merge.
+            if (distance < nearestDistance ||
+                (distance === nearestDistance &&
+                    nearest !== null &&
+                    background.id < nearest.id)) {
+                nearestDistance = distance;
+                nearest = background;
+            }
+        }
+        if (framed)
+            continue;
+        violations.push(raise(rule, [el.id], nearest?.id));
+    }
+    return violations;
+}
+/**
+ * Squared width of the GAP between two bounds — zero when they touch or
+ * overlap, otherwise the distance from edge to edge. Squared because it is only
+ * ever compared against another one, so the square root would buy nothing and
+ * cost a call per background per violating element.
+ *
+ * Edges, not centres. "Nearest centre" reads plausibly and is wrong as soon as
+ * the maps differ in size: a component 20 units off the right edge of a large
+ * map is 900 units from its centre, so a small map 60 units further away wins —
+ * and the element gets attributed to a map it is nowhere near. Comparing gaps
+ * gives the answer the eye gives, whatever the two maps measure.
+ *
+ * A background that CONTAINS the element never reaches this: containment exits
+ * the loop first, and a framed element raises nothing at all.
+ */
+function gapSquared(background, bound) {
+    const dx = Math.max(background.x - bound.maxX, bound.x - background.maxX, 0);
+    const dy = Math.max(background.y - bound.maxY, bound.y - background.maxY, 0);
+    return dx * dx + dy * dy;
+}
+/**
+ * How many points a CURVED segment is sampled into. A Wardley map is ~1600
+ * units wide and the tightest tolerance any rule declares is 24, so 32 chords
+ * put the sampling error two orders of magnitude below the thing being
+ * measured. Paid only by an element that actually carries tangents.
+ */
+const CURVE_SAMPLES = 32;
+/** A point on the cubic Bézier `p0 → p1` with control points `c0`, `c1`. */
+function cubicAt(p0, c0, c1, p1, t) {
+    const u = 1 - t;
+    const a = u * u * u;
+    const b = 3 * u * u * t;
+    const c = 3 * u * t * t;
+    const d = t * t * t;
+    return [
+        a * p0[0] + b * c0[0] + c * c1[0] + d * p1[0],
+        a * p0[1] + b * c0[1] + c * c1[1] + d * p1[1],
+    ];
+}
+/** Anything but a rounding difference away from `p`. */
+function departsFrom(candidate, p) {
+    return (isPoint(candidate) &&
+        (Math.abs(candidate[0] - p[0]) > 1e-6 ||
+            Math.abs(candidate[1] - p[1]) > 1e-6));
+}
+/**
+ * The POLYLINE a directional element exposes, in absolute model coordinates —
+ * `null` for anything that is not one.
+ *
+ * Duck-typed on purpose. The engine must not import a connector model: it knows
+ * roles and geometry, and "an element that runs from here to there" is
+ * geometry. Two sources, in order:
+ *
+ * 1. `absolutePath` — the ROUTED path, which is what the user sees and what a
+ *    right-angled connector actually traces;
+ * 2. the free endpoints of an unattached edge, for an element the layout has
+ *    not routed yet (a freshly pasted connector, a fixture in a unit test).
+ *
+ * An edge attached at both ends and never laid out has neither, and gets no
+ * verdict at all — silence, not a guess.
+ *
+ * ## Curved edges
+ *
+ * A routed path is not always a polyline. A curved connector stores its whole
+ * shape in TWO points carrying tangents (`absOut` on the first, `absIn` on the
+ * second) — so reading the bare coordinates gives the CHORD, and a bar sitting
+ * exactly on the drawn curve reads as 150 units off it. Wardley draws straight
+ * connectors, but the connector toolbar lets the mode be changed, and a rule
+ * that is confidently wrong about what the user can plainly see is worse than
+ * one that says nothing.
+ *
+ * Detected by geometry, not by mode: a point whose tangent departs from itself
+ * is a curve, whatever the element type calls it. The segment is then sampled
+ * ({@link CURVE_SAMPLES}) so every downstream test — distance, intersection —
+ * measures the drawn shape.
+ */
+function elementPath(el) {
+    const edge = el;
+    const raw = edge.absolutePath;
+    if (Array.isArray(raw) && raw.length >= 2) {
+        const anchors = [];
+        for (const point of raw) {
+            const x = point?.[0];
+            const y = point?.[1];
+            if (typeof x !== 'number' || typeof y !== 'number')
+                return null;
+            anchors.push([x, y]);
+        }
+        const points = [anchors[0]];
+        for (let i = 1; i < anchors.length; i++) {
+            const from = anchors[i - 1];
+            const to = anchors[i];
+            const out = raw[i - 1]?.absOut;
+            const into = raw[i]?.absIn;
+            // Straight unless a tangent says otherwise — the common case, and the
+            // one that must not pay for the other.
+            if (!departsFrom(out, from) && !departsFrom(into, to)) {
+                points.push(to);
+                continue;
+            }
+            const c0 = isPoint(out) ? out : from;
+            const c1 = isPoint(into) ? into : to;
+            for (let s = 1; s <= CURVE_SAMPLES; s++) {
+                points.push(cubicAt(from, c0, c1, to, s / CURVE_SAMPLES));
+            }
+        }
+        return points;
+    }
+    const from = edge.source?.position;
+    const to = edge.target?.position;
+    if (isPoint(from) && isPoint(to))
+        return [from, to];
+    return null;
+}
+function isPoint(value) {
+    return (Array.isArray(value) &&
+        value.length >= 2 &&
+        typeof value[0] === 'number' &&
+        typeof value[1] === 'number');
+}
+/**
+ * Which way a directional element RUNS: the unit vector from where it starts to
+ * where it ends.
+ *
+ * End to end, not segment by segment: an elbowed arrow wanders, but what it
+ * says is where it came from and where it points. `null` for an element with no
+ * path, or one whose ends coincide — a zero-length arrow means nothing and is
+ * not a mistake worth a message.
+ */
+function elementDirection(el) {
+    const path = elementPath(el);
+    if (path === null)
+        return null;
+    const [sx, sy] = path[0];
+    const [ex, ey] = path[path.length - 1];
+    const dx = ex - sx;
+    const dy = ey - sy;
+    const length = Math.hypot(dx, dy);
+    if (length === 0)
+        return null;
+    return [dx / length, dy / length];
+}
+/** Squared distance from `p` to the segment `a…b`. */
+function pointSegmentDistanceSquared(p, a, b) {
+    const vx = b[0] - a[0];
+    const vy = b[1] - a[1];
+    const lengthSquared = vx * vx + vy * vy;
+    let t = 0;
+    if (lengthSquared > 0) {
+        t = ((p[0] - a[0]) * vx + (p[1] - a[1]) * vy) / lengthSquared;
+        t = t < 0 ? 0 : t > 1 ? 1 : t;
+    }
+    const dx = p[0] - (a[0] + t * vx);
+    const dy = p[1] - (a[1] + t * vy);
+    return dx * dx + dy * dy;
+}
+/** Squared distance from `p` to the nearest point of the polyline `path`. */
+function pointPathDistanceSquared(p, path) {
+    let best = Infinity;
+    for (let i = 1; i < path.length; i++) {
+        const d = pointSegmentDistanceSquared(p, path[i - 1], path[i]);
+        if (d < best)
+            best = d;
+    }
+    return best;
+}
+/** The centre of a bound, as a point. */
+function centreOf(bound) {
+    return [bound.x + bound.w / 2, bound.y + bound.h / 2];
+}
+/**
+ * "Does this arrow run against the axis?"
+ *
+ * The subject's direction is confronted with the declared FORWARD sense of one
+ * axis of the frame it sits on (PF5.15). The verdict is an angle and nothing
+ * else: no shape type, no colour, no element type — an arrow is a subject
+ * because it carries the role, and it is wrong because of where it points.
+ *
+ * A subject with no direction ({@link elementDirection}) and a frame that
+ * declares no such axis both yield silence rather than a guess.
+ *
+ * Cost: one `elementBound` and one path read per subject, plus the frame
+ * attribution. Constant per element — the frames are counted in units.
+ */
+function evaluateOrientationAgainstAxis(rule, elements) {
+    const subjectRole = rule.appliesTo;
+    const against = rule.against;
+    const def = rule.background;
+    if (subjectRole === undefined || against === undefined || def === undefined) {
+        return [];
+    }
+    const axis = backgroundAxisFact(def, against.axis);
+    if (axis === undefined)
+        return [];
+    const backgrounds = backgroundsOf(rule, elements);
+    // No frame on the board, no sense to run against: a lone arrow is a sketch.
+    if (backgrounds.length === 0)
+        return [];
+    // Beyond this angle from the axis' forward sense, the subject runs against
+    // it. Perpendicular (90°) plus the declared dead zone.
+    const limit = Math.cos(((90 + against.toleranceDeg) * Math.PI) / 180);
+    const violations = [];
+    for (const el of elements) {
+        if (el.role === undefined)
+            continue;
+        if (!roleIsA(el.role, subjectRole, rule.roles))
+            continue;
+        const direction = elementDirection(el);
+        if (direction === null)
+            continue;
+        const alignment = direction[0] * axis.forward[0] + direction[1] * axis.forward[1];
+        if (alignment >= limit)
+            continue;
+        violations.push(raise(rule, [el.id], attributeBackground(el.elementBound, backgrounds)?.id));
+    }
+    return violations;
+}
+/**
+ * "Is this straddling what it is supposed to be straddling — and, if the rule
+ * asks, posed on what it is supposed to be posed on?"
+ *
+ * The subject must STRADDLE one of the frame's declared transitions: its own
+ * extent along `boundaryAxis` has to intersect the transition band
+ * ({@link backgroundTransitionBands}), which is what "superimposed on the
+ * dashed line" is as geometry (see {@link AttachmentDef.boundaryAxis}).
+ *
+ * A rule may ALSO name a carrier (PF5.16), and then the subject must sit within
+ * `tolerance` of an element carrying that role — an edge, measured along its
+ * path. That half is optional, and Wardley's W2 stopped declaring it on the PO
+ * recette of 02/08/2026: a bar on a divider with no dependency under it is a
+ * legitimate map, not a mistake.
+ *
+ * One finding, and it says which half failed. Two requirements are still a
+ * single badge on a single symbol — two would be pedantry on a bar eight units
+ * wide — but they are two different mistakes with two different gestures to fix
+ * them, so the finding carries the words of the one that actually failed. When
+ * BOTH fail it reports the carrier: a symbol attached to nothing has to find
+ * something to be about before where it sits can mean anything.
+ *
+ * A rule that names a carrier stays silent while the board carries none: a map
+ * with no dependency yet is a map being drawn, not a map with a misplaced
+ * symbol.
+ *
+ * ## The boundary half asks nothing while the boundary is hidden
+ *
+ * The frontiers are read off the INSTANCE, not off the declaration alone
+ * ({@link backgroundTransitionBands}): a framework that lets the user switch its
+ * graduations off names the prop that shows them, and a frame with them off
+ * yields no band, so every subject on it passes.
+ *
+ * Proportionality, and the PO's own wording (25/08/2026): a user who has hidden
+ * the dashed columns is looking at a plain card, and telling them a bar is not
+ * astride a line they cannot see is a finding they cannot act on — the gesture
+ * it asks for would aim at nothing. Judge the drawing that is on the canvas,
+ * not the one the declaration could have painted. The rule is not weakened, it
+ * is scoped: turn the columns back on and every verdict comes back, on the same
+ * bars, in the same places.
+ */
+function evaluateAttachment(rule, elements) {
+    const subjectRole = rule.appliesTo;
+    const attachment = rule.attachment;
+    if (subjectRole === undefined || attachment === undefined)
+        return [];
+    const carrierRole = attachment.carrierRole;
+    // A carrier is something with a PATH. Declaring anything else here produces a
+    // rule that can never fire; say so once instead of shrugging.
+    const carrierKind = carrierRole === undefined ? undefined : rule.roles[carrierRole]?.kind;
+    if (carrierKind !== undefined && carrierKind !== 'edge') {
+        warnOnce(`attachment rule "${rule.id}" names a "${carrierKind}" role ` +
+            `("${carrierRole}") as its carrier — only an "edge" role ` +
+            `has a path, and "posed on" is a distance to one, so this rule can ` +
+            `never fire.`);
+        return [];
+    }
+    const carriers = [];
+    const subjects = [];
+    for (const el of elements) {
+        if (el.role === undefined)
+            continue;
+        if (carrierRole !== undefined &&
+            roleIsA(el.role, carrierRole, rule.roles)) {
+            const path = elementPath(el);
+            if (path !== null)
+                carriers.push(path);
+        }
+        else if (roleIsA(el.role, subjectRole, rule.roles)) {
+            subjects.push(el);
+        }
+    }
+    if (subjects.length === 0)
+        return [];
+    if (carrierRole !== undefined && carriers.length === 0)
+        return [];
+    const backgrounds = backgroundsOf(rule, elements);
+    const tolerance = attachment.tolerance ?? 0;
+    const toleranceSquared = tolerance * tolerance;
+    // The transition test needs a frame to read the bands off, so a rule asking
+    // for one on a board with no frame simply does not ask.
+    const def = rule.background;
+    let axis = attachment.boundaryAxis !== undefined && def !== undefined
+        ? backgroundAxisFact(def, attachment.boundaryAxis)
+        : undefined;
+    if (axis !== undefined && def?.transitionBandWidth === undefined) {
+        // A width the frame never declared is not a width the engine may invent:
+        // guessing one would indict every subject on the board over a number
+        // nobody wrote down.
+        warnOnce(`attachment rule "${rule.id}" asks for the "${attachment.boundaryAxis}" ` +
+            `transitions, but its background declares no "transitionBandWidth" — ` +
+            `the boundary half of this rule is not evaluated.`);
+        axis = undefined;
+    }
+    // Bands are a function of the frame's bounds, and a board carries units of
+    // frames against hundreds of subjects: read once per frame, not per bar.
+    const bandsOf = new Map();
+    const violations = [];
+    for (const el of subjects) {
+        const bound = el.elementBound;
+        const centre = centreOf(bound);
+        let carried = carrierRole === undefined;
+        for (const path of carriers) {
+            if (pointPathDistanceSquared(centre, path) <= toleranceSquared) {
+                carried = true;
+                break;
+            }
+        }
+        const frame = attributeBackground(bound, backgrounds);
+        let inBand = true;
+        // The frontier the subject missed: the nearest one, which is the one the
+        // user was aiming at and the only one a suggestion can point back to.
+        let missed;
+        if (carried && axis !== undefined && frame !== null && def) {
+            let bands = bandsOf.get(frame.id);
+            if (bands === undefined) {
+                // `frame.props` is what makes the bands the ones the user can SEE: a
+                // frame whose graduations are switched off yields none, and the
+                // "no transition at all" branch below turns that into silence.
+                const all = backgroundTransitionBands(def, frame.bound, frame.props);
+                // A transition ACROSS a horizontal axis is a vertical band, i.e. an `x`.
+                bands = axis.orientation === 'horizontal' ? all.x : all.y;
+                bandsOf.set(frame.id, bands);
+            }
+            // The subject's own EXTENT across the axis, not a point inside it: the
+            // question is whether the frontier passes THROUGH the subject, and a
+            // centre cannot answer it for anything wider than a hair.
+            const horizontal = axis.orientation === 'horizontal';
+            const from = horizontal ? bound.x : bound.y;
+            const to = horizontal ? bound.maxX : bound.maxY;
+            const value = horizontal ? centre[0] : centre[1];
+            inBand = false;
+            let nearest = Infinity;
+            for (const band of bands) {
+                // Two intervals overlapping: the subject covers the frontier, or the
+                // frame's declared band covers the subject.
+                if (from <= band.max && to >= band.min) {
+                    inBand = true;
+                    break;
+                }
+                const away = Math.abs(value - band.at);
+                if (away < nearest) {
+                    nearest = away;
+                    missed = band;
+                }
+            }
+            // A frame with no transition at all asks nothing of the subject — and
+            // since the bands are read through the instance, "none" covers both a
+            // frame that declares no frontier and one whose frontiers the user has
+            // hidden.
+            if (bands.length === 0)
+                inBand = true;
+        }
+        if (carried && inBand)
+            continue;
+        // The words of the half that failed. Carrier first when a rule declares
+        // one: it is the more actionable of the two, and the only one that makes
+        // the other mean anything. A boundary-only rule has `carried` true and no
+        // `offBoundary`, so it says its own sentence — the only one it has.
+        const violation = raise(rule, [el.id], frame?.id, carried ? attachment.offBoundary : rule);
+        if (carried && missed !== undefined)
+            violation.boundaryId = missed.id;
+        violations.push(violation);
+    }
+    return violations;
+}
+/**
+ * How much shared extent counts as an overlap rather than a shared edge.
+ *
+ * Two boxes that TOUCH — a label ending exactly where a node begins — share no
+ * area and are perfectly readable, which is precisely what alignment and snap
+ * produce all day. The house `Bound.isOverlapWithBound` answers `true` for them
+ * (it compares against `+EPSILON`, so equality passes), so this asks for real
+ * shared extent instead. Small enough that a pixel of genuine overlap still
+ * counts, large enough that float noise on a snapped edge does not.
+ */
+const OVERLAP_EPSILON = 1e-6;
+/** Do these two bounds share AREA, as opposed to an edge? */
+function boundsOverlap(a, b) {
+    return (b.maxX - a.minX > OVERLAP_EPSILON &&
+        a.maxX - b.minX > OVERLAP_EPSILON &&
+        b.maxY - a.minY > OVERLAP_EPSILON &&
+        a.maxY - b.minY > OVERLAP_EPSILON);
+}
+/**
+ * Do these two subjects actually collide, given each one's geometry?
+ *
+ * ## Known limit: a ROTATED node is measured by its bounding box
+ *
+ * `elementBound` is the axis-aligned box of a rotated element, so a 120×26
+ * label at 45° presents as roughly 103×103 — the same inflation this family
+ * refuses to accept for an edge, where the fix was to measure along the path.
+ * A rotated NODE has no equivalent cheap answer: it needs an oriented box and a
+ * separating-axis test on both sides of every pair, in the inner loop of the
+ * only super-linear family here.
+ *
+ * Deliberately not built, and deliberately written down. Rotating a Wardley
+ * node is not a gesture the framework has; the day a framework rotates its
+ * artefacts is the day this is worth the inner loop, and {@link OverlapSubject}
+ * is where the oriented box would go. Until then the failure mode is a
+ * false POSITIVE on a rotated pair — a warning too many, never a miss — which
+ * is the right way round for a readability rule that is only ever a warning.
+ * A test pins the behaviour so a change to it cannot be silent.
+ *
+ * A rotated `text` role holds the same line, and has to be MADE to: narrowing
+ * a rotated box to the band an unrotated renderer would draw in is how a miss
+ * gets built (at 180° the words are at the other end of it). So
+ * {@link textInkBound} hands a rotated element its whole box back.
+ */
+function subjectsCollide(a, b, minPenetration) {
+    // Bounding boxes first: on a dense map almost every pair dies here, and this
+    // is the test the O(n²) sweep is really made of.
+    if (!boundsOverlap(a.bound, b.bound))
+        return false;
+    if (a.path === null && b.path === null) {
+        return (minPenetration <= 0 ||
+            boundsPenetration(a.bound, b.bound) > minPenetration);
+    }
+    // Two paths: zero-width lines, so there is no depth to measure and a declared
+    // crossing is reported as it always was.
+    if (a.path !== null && b.path !== null)
+        return pathsCross(a.path, b.path);
+    const path = (a.path ?? b.path);
+    const bound = a.path === null ? a.bound : b.bound;
+    if (!pathHitsBound(path, bound))
+        return false;
+    return minPenetration <= 0 || pathPenetration(path, bound) > minPenetration;
+}
+/**
+ * How far two overlapping boxes reach INTO each other: the smaller of the two
+ * axis overlaps, which is the distance one of them would have to move to come
+ * free. Corner-grazing gives a small number on both axes; a name written across
+ * a node gives the height of the letters.
+ */
+function boundsPenetration(a, b) {
+    return Math.min(Math.min(a.maxX - b.minX, b.maxX - a.minX), Math.min(a.maxY - b.minY, b.maxY - a.minY));
+}
+/**
+ * The deepest any point of `path` gets under an edge of `bound` — 0 when the
+ * path only touches it, negative when it misses entirely.
+ *
+ * "Depth" is the distance to the NEAREST edge, so a link crossing a label
+ * lengthwise through the middle scores half the line height, and one clipping a
+ * corner scores almost nothing. Exact, not sampled: that distance is the
+ * minimum of four linear functions of the position along the segment, hence
+ * concave, so its maximum is attained either at an end of the segment or where
+ * two of the four swap places — at most eight candidates, all of them tested.
+ *
+ * Only ever reached by a pair that already collides, i.e. off the hot path of
+ * the sweep.
+ */
+function pathPenetration(path, bound) {
+    const edges = (p) => [
+        p[0] - bound.minX,
+        bound.maxX - p[0],
+        p[1] - bound.minY,
+        bound.maxY - p[1],
+    ];
+    const depthAt = (from, to, t) => {
+        let depth = Infinity;
+        for (let k = 0; k < 4; k++) {
+            depth = Math.min(depth, from[k] + t * (to[k] - from[k]));
+        }
+        return depth;
+    };
+    let deepest = -Infinity;
+    for (let i = 1; i < path.length; i++) {
+        const from = edges(path[i - 1]);
+        const to = edges(path[i]);
+        deepest = Math.max(deepest, depthAt(from, to, 0), depthAt(from, to, 1));
+        for (let m = 0; m < 4; m++) {
+            for (let n = m + 1; n < 4; n++) {
+                const slope = to[m] - from[m] - (to[n] - from[n]);
+                if (slope === 0)
+                    continue;
+                const t = (from[n] - from[m]) / slope;
+                if (t <= 0 || t >= 1)
+                    continue;
+                deepest = Math.max(deepest, depthAt(from, to, t));
+            }
+        }
+    }
+    return deepest;
+}
+/**
+ * Advance width of one character, as a fraction of the font size, by CLASS.
+ *
+ * The engine measures no text: a canvas in the evaluation path would cost a
+ * `measureText` per label per pass, and would make the verdict depend on which
+ * fonts a host happens to have loaded — the same map would validate differently
+ * in a headless report and in a browser. So the width is DECLARED, and read off
+ * this table.
+ *
+ * ## Why a table and not one mean advance
+ *
+ * A single ratio was the first answer and it was wrong in the direction that
+ * matters. Letters differ by a factor of FOUR — `i` is 0.24 em and `W` is 0.9 —
+ * so an average tuned on `Customer` reads `utility` half as wide again as it is
+ * drawn, and a link 15 units past the last letter of a lowercase name lands
+ * inside the ghost. That is the very false positive this geometry exists to
+ * remove, and it survived the first version for every narrow-lettered name.
+ *
+ * Five classes, still constant per character, still no canvas, still the same
+ * answer on every host:
+ *
+ * | class | em | characters |
+ * | --- | --- | --- |
+ * | thin | 0.26 | `i l I j` and the punctuation, brackets and the SPACE |
+ * | narrow | 0.35 | `f t r " *` |
+ * | wide | 0.85 | `m w M W @ %` |
+ * | capital | 0.62 | `A`–`Z`, the rest of them |
+ * | full-width | 1.00 | anything from U+2E80 up: CJK, kana, hangul |
+ * | nothing | 0.00 | combining marks, zero-width joiners, variation selectors |
+ * | default | 0.53 | everything else, lowercase and digits |
+ *
+ * ## The precision, measured rather than claimed
+ *
+ * Against the real renderer at Inter 18, over the 28-name bench in
+ * `integration-test/.../wardley-validation.spec.ts` — which prints every line
+ * and fails outside ±15 % on ANY of them:
+ *
+ * | name | drawn | declared |
+ * | --- | --- | --- |
+ * | `utility` | 46.4 | 45.7 (−1 %) |
+ * | `little` | 36.6 | 36.2 (−1 %) |
+ * | `ERP` | 33.7 | 33.5 (−1 %) |
+ * | `Customer` | 83.2 | 77.2 (−7 %) |
+ * | `Payment gateway` | 152.0 | 144.9 (−5 %) |
+ * | `Cloud` | 49.7 | 44.5 (**−11 %**, the worst of the 28) |
+ * | `WWWWWWWWWW` | 170.8 | 153.0 (−10 %) |
+ * | `付款` | 36.0 | 36.0 (0 %) |
+ *
+ * **Never wide, on any of the 28** — which is the property that matters: an
+ * over-estimate is a ghost past the last letter, and a link crossing it is
+ * precisely the false positive this geometry exists to remove. What is left is
+ * a few units of silence at the end of a name, on the scale
+ * {@link ValidationRule.minPenetration} is calibrated on.
+ *
+ * (The drawn figure itself moves by a few percent with the web font's loading
+ * state — the other half of why the engine does not try to measure exactly.)
+ */
+const TEXT_ADVANCE = /* @__PURE__ */ (() => {
+    const table = Object.create(null);
+    for (const char of " .,:;!|'`()[]{}/\\-ilIj")
+        table[char] = 0.26;
+    for (const char of 'ftr"*')
+        table[char] = 0.35;
+    for (const char of 'mwMW@%')
+        table[char] = 0.85;
+    return table;
+})();
+/** Width of one character, in em. See {@link TEXT_ADVANCE}. */
+function charAdvance(char) {
+    const declared = TEXT_ADVANCE[char];
+    if (declared !== undefined)
+        return declared;
+    const code = char.codePointAt(0) ?? 0;
+    // Code points that draw nothing OF THEIR OWN, and so advance nothing: a
+    // combining mark sits on the letter before it, a zero-width space or joiner
+    // is not there at all, and a variation selector only says how to draw its
+    // neighbour. Billed at full price they turn "élément" pasted from a Mac
+    // (decomposed: nine code points, seven glyphs) into a fifth of a name's worth
+    // of white paper — a false positive, which is the one thing this must not
+    // manufacture. Before the full-width test, since U+FE0F is above it.
+    if ((code >= 0x0300 && code <= 0x036f) ||
+        (code >= 0x200b && code <= 0x200d) ||
+        code === 0xfe0f) {
+        return 0;
+    }
+    // Full-width scripts, where one character IS one em.
+    if (code >= 0x2e80)
+        return 1;
+    // The rest of the capitals: wider than lowercase, narrower than `M`.
+    if (code >= 65 && code <= 90)
+        return 0.62;
+    return 0.53;
+}
+/** Width of one line of text, in model units. */
+function lineWidth(line, fontSize) {
+    let em = 0;
+    for (const char of line)
+        em += charAdvance(char);
+    return em * fontSize;
+}
+/**
+ * The box the TEXT of an element actually occupies, inside the box the element
+ * was created with.
+ *
+ * A text element is created at a width that says nothing about its content — a
+ * Wardley label is 120 to 200 units wide whether it reads "ERP" or "Customer
+ * relationship management" — so its box carries empty margin on the side its
+ * `textAlign` runs away from. Measuring that box makes the rule report things
+ * the user cannot see, which is exactly the report they stop believing.
+ *
+ * Narrowed on the horizontal only, and never widened: the height stored on the
+ * element IS the rendered block (the editor writes `lineHeight × lines` back on
+ * every edit), and the renderer lays the lines out from the TOP of the box.
+ * An element exposing no text is left exactly as it was, so a fixture or a
+ * host element that carries none is measured by its box as before; one whose
+ * text reads EMPTY gets a width of zero, and {@link evaluateNoOverlap} drops it
+ * from the pass entirely — it draws nothing, so it collides with nothing.
+ *
+ * ## A ROTATED text is measured by its whole box
+ *
+ * `elementBound` is the axis-aligned box of a rotated element, and this cuts a
+ * band out of it where an UNROTATED renderer would put the ink. At 180° the
+ * words are at the other end of the box, so the band would be white paper and
+ * the letters outside it: a MISS, not a warning too many. A rotated text
+ * therefore keeps its whole box — over-reporting, which is the failure mode the
+ * family already accepts for a rotated node, and the one a readability warning
+ * can afford.
+ */
+function textInkBound(el, bound) {
+    const text = el;
+    if (typeof text.fontSize !== 'number' || text.text == null)
+        return bound;
+    if (typeof text.rotate === 'number' && text.rotate !== 0)
+        return bound;
+    let longest = 0;
+    // NFC first: the same name typed here and pasted from a Mac can arrive as the
+    // same glyphs in a different number of code points, and a width that depends
+    // on which one would be a rule that answers differently on identical text.
+    for (const line of String(text.text).normalize('NFC').split('\n')) {
+        longest = Math.max(longest, lineWidth(line, text.fontSize));
+    }
+    const w = Math.min(bound.w, longest);
+    const x = text.textAlign === 'center'
+        ? bound.x + (bound.w - w) / 2
+        : text.textAlign === 'right'
+            ? bound.maxX - w
+            : bound.x;
+    return new Bound(x, bound.y, w, bound.h);
+}
+function pathHitsBound(path, bound) {
+    for (let i = 1; i < path.length; i++) {
+        if (bound.containsPoint(path[i - 1]) || bound.containsPoint(path[i])) {
+            return true;
+        }
+        if (bound.intersectLine(path[i - 1], path[i]) !== null)
+            return true;
+    }
+    return false;
+}
+function pathsCross(a, b) {
+    for (let i = 1; i < a.length; i++) {
+        for (let j = 1; j < b.length; j++) {
+            if (lineIntersects(a[i - 1], a[i], b[j - 1], b[j]))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * "Do these two things sit on top of each other?" (PF5.13)
+ *
+ * The first family that is not element-local: it evaluates PAIRS, so a finding
+ * names two elements and neither of them alone is at fault. Which pairs is
+ * declared data — `[label, node]`, `[label, link]` — and the geometry each side
+ * is measured with follows the role's own `kind`, so an edge is measured along
+ * its path and never by the bounding box of its diagonal.
+ *
+ * ## Cost, and the dirty set
+ *
+ * Naive it is O(p²) over the PARTICIPANTS — the elements carrying one of the
+ * declared roles, never the whole surface — with every bound read exactly once
+ * and a rectangle test as the inner loop. That is what the bench measures on
+ * the reference map, and it fits.
+ *
+ * With an {@link IncrementalContext} it is O(|dirty| × p): findings that name
+ * only untouched elements are carried over from the previous evaluation, and
+ * only the couples involving something that MOVED are re-tested. A drag on a
+ * dense map is one element against the participants, not the whole grid against
+ * itself.
+ */
+function evaluateNoOverlap(rule, elements, incremental) {
+    const pairs = rule.overlap;
+    if (pairs === undefined || pairs.length === 0)
+        return [];
+    // The distinct roles the pairs mention, and the pairs re-expressed as index
+    // couples into that list — so the inner loop compares booleans, not strings.
+    const slots = [];
+    const couples = [];
+    for (const [a, b] of pairs) {
+        const ia = slots.indexOf(a) >= 0 ? slots.indexOf(a) : slots.push(a) - 1;
+        const ib = slots.indexOf(b) >= 0 ? slots.indexOf(b) : slots.push(b) - 1;
+        couples.push([ia, ib]);
+    }
+    const subjects = [];
+    for (const el of elements) {
+        // Neutral element: never a participant, whatever it sits on.
+        if (el.role === undefined)
+            continue;
+        let matched = false;
+        const filled = slots.map(slot => {
+            const isA = roleIsA(el.role, slot, rule.roles);
+            matched ||= isA;
+            return isA;
+        });
+        if (!matched)
+            continue;
+        const kind = rule.roles[el.role]?.kind;
+        // A `text` role is measured by the ink of its text, not by the box it was
+        // created at; everything else by its bounds.
+        const bound = kind === 'text' ? textInkBound(el, el.elementBound) : el.elementBound;
+        // A text emptied of its words draws NOTHING, and a zero-width box is still
+        // a vertical line that a wider box can be said to contain. Out of the pass:
+        // it cannot make anything unreadable. Only a TEXT — a perfectly vertical
+        // connector has a flat box too, and is measured along its path.
+        if (kind === 'text' && bound.w === 0)
+            continue;
+        subjects.push({
+            id: el.id,
+            bound,
+            // An `edge` role is measured along its path.
+            path: kind === 'edge' ? elementPath(el) : null,
+            slots: filled,
+        });
+    }
+    if (subjects.length < 2)
+        return [];
+    const backgrounds = backgroundsOf(rule, elements);
+    const declared = (a, b) => couples.some(([i, j]) => (a.slots[i] && b.slots[j]) || (a.slots[j] && b.slots[i]));
+    const minPenetration = rule.minPenetration ?? 0;
+    const found = [];
+    const test = (a, b) => {
+        if (!declared(a, b) || !subjectsCollide(a, b, minPenetration))
+            return;
+        // Sorted, so the same collision reads the same way every time — and the
+        // frame is read off the SAME half whichever end the pair was reached from,
+        // or a full pass and an incremental one could attribute one collision to
+        // two different maps.
+        const [first, second] = a.id < b.id ? [a, b] : [b, a];
+        found.push(raise(rule, [first.id, second.id], attributeBackground(first.bound, backgrounds)?.id));
+    };
+    const sweep = () => {
+        for (let i = 0; i < subjects.length; i++) {
+            for (let j = i + 1; j < subjects.length; j++)
+                test(subjects[i], subjects[j]);
+        }
+        return found;
+    };
+    if (incremental === undefined)
+        return sweep();
+    const { dirty } = incremental;
+    /**
+     * Anything that IS or WAS a frame sends the whole surface back through the
+     * sweep.
+     *
+     * A frame is not a participant, so no pair-wise re-test ever reaches the
+     * findings attributed to it — and moving, resizing or DELETING one changes
+     * every one of those attributions, which is what decides the map-wide
+     * arbitration and the profile in force. Deletion is the case that made this
+     * necessary and the one a "is a current background dirty" test cannot see:
+     * once the map is gone `backgrounds` is empty, nothing looks dirty, and the
+     * findings measured against it would vanish from a live board.
+     */
+    const frameTouched = backgrounds.some(background => dirty.has(background.id)) ||
+        incremental.previous.some(violation => violation.backgroundId !== undefined &&
+            dirty.has(violation.backgroundId));
+    if (frameTouched)
+        return sweep();
+    /**
+     * ...and so does a change big enough that the shortcut is no longer one.
+     *
+     * The dirty path costs `dirtyParticipants × p`; the sweep costs `p²/2`. Past
+     * the crossover the "optimisation" is several times the price of the thing it
+     * replaces — measured at 8× and OUT of the 16 ms budget for a lasso drag over
+     * a third of a 500-element map, against 2.2 ms for the sweep it was avoiding.
+     * One comparison buys back the worst case entirely.
+     */
+    let dirtyParticipants = 0;
+    const isDirty = subjects.map(subject => {
+        const changed = dirty.has(subject.id);
+        if (changed)
+            dirtyParticipants++;
+        return changed;
+    });
+    if (dirtyParticipants * 2 >= subjects.length)
+        return sweep();
+    // Only the couples involving something that changed. Everything else keeps
+    // the verdict it already had.
+    for (let i = 0; i < subjects.length; i++) {
+        if (!isDirty[i])
+            continue;
+        for (let j = 0; j < subjects.length; j++) {
+            if (j === i)
+                continue;
+            // A dirty–dirty couple is reachable from both ends and must be tested
+            // once. The earlier index already tested it against everything, so only
+            // look forward — no per-couple key, and nothing allocated in the loop
+            // that is the whole cost of this path.
+            if (j < i && isDirty[j])
+                continue;
+            test(subjects[i], subjects[j]);
+        }
+    }
+    const alive = new Set(subjects.map(subject => subject.id));
+    // The `backgroundId` is deliberately NOT filtered on here: a pair-wise
+    // finding depends on its frame only for ATTRIBUTION, and any change to that
+    // frame already took the whole surface through the sweep above. Dropping
+    // findings on it as well is how a live overlap disappeared when its map was
+    // deleted.
+    const carried = incremental.previous.filter(violation => violation.ruleId === rule.id &&
+        violation.elementIds.every(id => !dirty.has(id) && alive.has(id)));
+    return [...carried, ...found];
+}
+/**
+ * Hue windows, in degrees, in ascending order. The last one wraps back onto
+ * red, which is why the table is read as "first upper bound above the hue".
+ */
+const TONE_HUES = [
+    [15, 'red'],
+    [45, 'orange'],
+    [70, 'yellow'],
+    [160, 'green'],
+    [200, 'teal'],
+    [260, 'blue'],
+    [300, 'purple'],
+    [345, 'magenta'],
+    [360, 'red'],
+];
+/**
+ * Tone words, longest first so a substring can never win over the name that
+ * contains it. This is how a THEME TOKEN is classified — `--affine-palette-shape-red`
+ * carries its own answer in its name, and reading it is the only way to classify
+ * a variable the engine has no stylesheet to resolve.
+ */
+const TONE_WORDS = [
+    ['magenta', 'magenta'],
+    ['purple', 'purple'],
+    ['orange', 'orange'],
+    ['yellow', 'yellow'],
+    ['green', 'green'],
+    ['white', 'grey'],
+    ['black', 'grey'],
+    ['blue', 'blue'],
+    ['teal', 'teal'],
+    ['grey', 'grey'],
+    ['gray', 'grey'],
+    ['red', 'red'],
+];
+/** Below this saturation a colour reads as a grey whatever its hue says. */
+const GREY_SATURATION = 0.15;
+/** Below this alpha nothing is on screen, so there is nothing to judge. */
+const INVISIBLE_ALPHA = 0.08;
+/** `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa` → `[r, g, b, a]` in 0..1. */
+function parseHex(value) {
+    const hex = value.slice(1);
+    const short = hex.length === 3 || hex.length === 4;
+    if (!short && hex.length !== 6 && hex.length !== 8)
+        return null;
+    const size = short ? 1 : 2;
+    const channels = [];
+    for (let i = 0; i < hex.length; i += size) {
+        const chunk = hex.slice(i, i + size);
+        const parsed = Number.parseInt(short ? chunk + chunk : chunk, 16);
+        if (Number.isNaN(parsed))
+            return null;
+        channels.push(parsed / 255);
+    }
+    return [channels[0], channels[1], channels[2], channels[3] ?? 1];
+}
+/**
+ * Which tone family a colour belongs to, or `undefined` when the engine cannot
+ * honestly say.
+ *
+ * Two readings, in order: the NUMBER when the colour is a hex the process can
+ * actually see, and the NAME when it is a theme token it cannot. Anything else —
+ * `transparent`, a gradient, an `rgb()` triple, a variable with no tone in its
+ * name — is unclassifiable, and unclassifiable means silence: a convention rule
+ * that guessed would indict a user over a colour nobody here can see.
+ */
+export function toneOf(value) {
+    if (!value)
+        return undefined;
+    const raw = value.trim().toLowerCase();
+    if (raw === '' || raw === 'transparent')
+        return undefined;
+    if (raw.startsWith('#')) {
+        const rgba = parseHex(raw);
+        if (rgba === null)
+            return undefined;
+        const [r, g, b, a] = rgba;
+        if (a < INVISIBLE_ALPHA)
+            return undefined;
+        const max = Math.max(r, g, b);
+        const min = Math.min(r, g, b);
+        const lightness = (max + min) / 2;
+        const span = max - min;
+        // Saturation of the HSL model, and the two ends of the lightness scale
+        // where hue stops meaning anything at all.
+        const saturation = span === 0 ? 0 : span / (1 - Math.abs(2 * lightness - 1));
+        if (saturation < GREY_SATURATION || lightness < 0.06 || lightness > 0.96) {
+            return 'grey';
+        }
+        let hue;
+        if (max === r)
+            hue = ((g - b) / span) % 6;
+        else if (max === g)
+            hue = (b - r) / span + 2;
+        else
+            hue = (r - g) / span + 4;
+        hue = (hue * 60 + 360) % 360;
+        for (const [limit, tone] of TONE_HUES)
+            if (hue < limit)
+                return tone;
+        return 'red';
+    }
+    for (const [word, tone] of TONE_WORDS)
+        if (raw.includes(word))
+            return tone;
+    return undefined;
+}
+/**
+ * The colour-bearing props the engine reads, duck-typed.
+ *
+ * Duck-typed for the same reason {@link elementPath} is: the engine must not
+ * import a shape model, a text model or a connector model to answer a question
+ * that is about pixels. An element that carries none of these has no colour to
+ * be judged on and is skipped on the cheapest possible test.
+ */
+const COLOUR_PROPS = ['fillColor', 'strokeColor', 'color'];
+/**
+ * Every string a `Color` value can present. A theme PAIR (`{ light, dark }`)
+ * yields both members: they are one decision seen under two themes, and the
+ * caller treats them as alternatives rather than as two separate colours.
+ */
+function colourStrings(value) {
+    if (typeof value === 'string')
+        return [value];
+    if (value === null || typeof value !== 'object')
+        return [];
+    const out = [];
+    for (const key of ['normal', 'light', 'dark']) {
+        const member = value[key];
+        if (typeof member === 'string')
+            out.push(member);
+    }
+    return out;
+}
+/**
+ * Whether this element is drawn in a tone the convention does not sanction.
+ *
+ * Per PROP, not per string: a `{ light, dark }` pair is ONE colour, so it
+ * offends only when neither of its two members lands on a sanctioned tone. A
+ * prop whose colour cannot be classified is skipped, and an element whose props
+ * are all unclassifiable is never indicted.
+ *
+ * An unfilled shape's `fillColor` is deliberately ignored: it is stored, it is
+ * not painted, and a rule about what the map LOOKS like has no business reading
+ * a colour that is not on screen.
+ */
+function departsFromTones(el, allowed) {
+    const record = el;
+    const filled = record['filled'];
+    for (const prop of COLOUR_PROPS) {
+        if (prop === 'fillColor' && filled === false)
+            continue;
+        let classified = false;
+        let sanctioned = false;
+        for (const raw of colourStrings(record[prop])) {
+            const tone = toneOf(raw);
+            if (tone === undefined)
+                continue;
+            classified = true;
+            if (allowed.has(tone)) {
+                sanctioned = true;
+                break;
+            }
+        }
+        if (classified && !sanctioned)
+            return true;
+    }
+    return false;
+}
+/**
+ * "Is this drawn in one of the tones the frame sanctions for it?" (PF13.8 / Q5)
+ *
+ * The sanctioned tones come from the FRAME's own palette, resolved through the
+ * `@name` indirection every background label already uses — so the rule restates
+ * no colour the background owns, and a host restyling the frame restyles the
+ * convention with it. See {@link ToneConventionDef}.
+ *
+ * A rule whose named entries resolve to nothing classifiable warns once and
+ * evaluates nothing: a convention with no reference colour is not a convention,
+ * and indicting the whole board over a broken declaration is the one outcome
+ * worse than silence.
+ */
+function evaluateToneConvention(rule, elements) {
+    const subjectRole = rule.appliesTo;
+    const tone = rule.tone;
+    const def = rule.background;
+    if (subjectRole === undefined || tone === undefined || def === undefined) {
+        return [];
+    }
+    const palette = def.chrome?.palette;
+    const allowed = new Set();
+    for (const name of tone.palette) {
+        // Straight at the entry rather than through `backgroundColor('@name')`,
+        // which answers a broken magenta for a name the palette does not carry —
+        // and a magenta the rule never asked for would silently become a sanctioned
+        // tone.
+        const entry = palette?.[name];
+        const classified = entry === undefined ? undefined : toneOf(entry);
+        if (classified !== undefined)
+            allowed.add(classified);
+    }
+    if (allowed.size === 0) {
+        warnOnce(`tone-convention rule "${rule.id}" names no palette entry that resolves ` +
+            `to a classifiable tone — it is not evaluated.`);
+        return [];
+    }
+    const backgrounds = backgroundsOf(rule, elements);
+    const violations = [];
+    for (const el of elements) {
+        if (el.role === undefined)
+            continue;
+        if (!roleIsA(el.role, subjectRole, rule.roles))
+            continue;
+        if (!departsFromTones(el, allowed))
+            continue;
+        violations.push(raise(rule, [el.id], attributeBackground(el.elementBound, backgrounds)?.id));
+    }
+    return violations;
+}
+/**
+ * "Is most of what is on this map of one declared nature?" (PF13.8 / Q6)
+ *
+ * A remark about the MAP, so the finding names the BACKGROUND and nothing else:
+ * no single element is at fault, and drawing a badge on one of two hundred
+ * components would be an accusation aimed at a bystander.
+ *
+ * Counted PER MAP. A board carrying a map of activities beside a map of
+ * practices holds two different answers, and a tally over the whole surface
+ * would give both of them the wrong one.
+ *
+ * ## The gate
+ *
+ * A surface where NOT ONE subject carries the fact yields nothing, silently —
+ * see {@link MajorityDef}. That is the state the Wardley `nature` is in today,
+ * and the rule ships inert rather than waiting in a branch somewhere for
+ * somebody to remember it.
+ */
+function evaluateMajorityFact(rule, elements) {
+    const subjectRole = rule.appliesTo;
+    const majority = rule.majority;
+    if (subjectRole === undefined || majority === undefined)
+        return [];
+    const backgrounds = backgroundsOf(rule, elements);
+    // No frame on the board: no map for the remark to be about.
+    if (backgrounds.length === 0)
+        return [];
+    const tally = new Map();
+    for (const el of elements) {
+        if (el.role === undefined)
+            continue;
+        if (!roleIsA(el.role, subjectRole, rule.roles))
+            continue;
+        const frame = attributeBackground(el.elementBound, backgrounds);
+        if (frame === null)
+            continue;
+        let counts = tally.get(frame.id);
+        if (counts === undefined) {
+            counts = { subjects: 0, known: 0, matching: 0 };
+            tally.set(frame.id, counts);
+        }
+        counts.subjects += 1;
+        const fact = el[majority.fact];
+        // Whatever a peer wrote, and whatever a framework has not written yet.
+        if (typeof fact !== 'string' || fact === '')
+            continue;
+        counts.known += 1;
+        if (fact === majority.value)
+            counts.matching += 1;
+    }
+    const violations = [];
+    // Sorted, so a board with two qualifying maps always reports them the same
+    // way whichever order the surface happened to be walked in.
+    for (const id of [...tally.keys()].sort()) {
+        const counts = tally.get(id);
+        // THE GATE: nothing here carries the fact, so there is no majority to be in.
+        if (counts.known === 0)
+            continue;
+        // A strict majority of the SUBJECTS, not of the ones that happen to be
+        // classified: half a map left unclassified is not a mandate.
+        if (counts.matching * 2 <= counts.subjects)
+            continue;
+        violations.push(raise(rule, [id], id));
+    }
+    return violations;
+}
+/**
+ * The two ids a typed edge points at, or `null` — the EXTRACTION alone, with no
+ * opinion on what the pair means.
+ *
+ * Duck-typed exactly like {@link elementPath}, and for the same reason: the
+ * engine knows roles and geometry, and must not import a connector model. An
+ * end holding a bare `position` and no `id` is bound to nothing.
+ *
+ * `null` is the ADR's own guard, and it is not marginal — releasing the link
+ * tool over empty canvas produces such an edge at any time, and a palette
+ * sample of a stroke style is one by construction. An edge that relates nothing
+ * is never evaluated.
+ *
+ * Whether a SELF-LOOP is one of the answers is a policy, and each family states
+ * its own on top of this: see {@link boundEnds} and {@link endpointIds}.
+ */
+function rawEndpointIds(el) {
+    const edge = el;
+    const source = edge.source?.id;
+    const target = edge.target?.id;
+    if (typeof source !== 'string' || typeof target !== 'string')
+        return null;
+    return [source, target];
+}
+/**
+ * The two ids a typed edge BINDS, self-loops excluded.
+ *
+ * A self-loop states nothing about an ORDER: it is one element, compared with
+ * itself, and no move can ever resolve the finding — so the families that read
+ * a layout treat it exactly like an edge that relates nothing.
+ */
+function boundEnds(el) {
+    const ends = rawEndpointIds(el);
+    if (ends === null || ends[0] === ends[1])
+        return null;
+    return ends;
+}
+/**
+ * "Are these two in the order their relation states?" — W4 (`docs/adr/0010`).
+ *
+ * The first family whose subject is a RELATION. For every element carrying the
+ * declared edge role, the two elements it binds are projected onto one axis of
+ * the frame and compared in the order the edge states: for
+ * `wardley:dependency`, the source is the consumer and must sit higher on the
+ * visibility axis than what it needs.
+ *
+ * The order comes from the persisted `source → target` pair, never from the
+ * geometry — that is the whole point, and the reason this rule can fire at all.
+ * Every other input is declaration: which axis, which way it runs, how much
+ * slack, all read off the frame the framework already declares.
+ *
+ * ## What it stays silent about, and why each one matters
+ *
+ * - **no frame on the board** — nothing declares an axis, so there is no order
+ *   to be in. A chain drawn on blank canvas is a sketch;
+ * - **an edge with a free end** — it relates nothing (see {@link boundEnds});
+ * - **an end whose element is gone** — a dangling id says nothing about a
+ *   layout;
+ * - **a pair straddling TWO frames** — "higher than" is a question inside one
+ *   frame of reference, and two maps have two;
+ * - **an edge carrying no role, or another role** — proportionality (PRD
+ *   principle 8). A change arrow is oriented too and is not a dependency.
+ *
+ * ## Cost
+ *
+ * Linear in the EDGES: one pass to index the elements by id, one pass over the
+ * edges, and two constant-time frame attributions per edge. There is no graph
+ * closure and no pair-wise sweep — the rule is about a relation somebody drew,
+ * never about every couple of nodes that could have had one. A cycle A→B→A is
+ * two edges and is judged as two edges: at least one of them is against the
+ * order, and that one is reported.
+ */
+function evaluateRelativeOrder(rule, elements) {
+    const order = rule.relativeOrder;
+    const def = rule.background;
+    if (order === undefined || def === undefined)
+        return [];
+    const axis = backgroundAxisFact(def, order.axis);
+    if (axis === undefined) {
+        warnOnce(`relative-order rule "${rule.id}" measures along "${order.axis}", which ` +
+            `its background does not declare — the rule is not evaluated.`);
+        return [];
+    }
+    const backgrounds = backgroundsOf(rule, elements);
+    // No frame, no frame of reference: a chain on blank canvas is a sketch.
+    if (backgrounds.length === 0)
+        return [];
+    const byId = new Map();
+    const edges = [];
+    for (const el of elements) {
+        byId.set(el.id, el);
+        // Cheapest possible exit for a neutral element: no role, no evaluation.
+        if (el.role === undefined)
+            continue;
+        if (roleIsA(el.role, order.edgeRole, rule.roles))
+            edges.push(el);
+    }
+    if (edges.length === 0)
+        return [];
+    const horizontal = axis.orientation === 'horizontal';
+    // How far along the axis' FORWARD sense a bound sits. One number, so the
+    // comparison below reads the same whichever way the axis runs.
+    const along = (bound) => {
+        const centre = centreOf(bound);
+        return centre[0] * axis.forward[0] + centre[1] * axis.forward[1];
+    };
+    const violations = [];
+    for (const edge of edges) {
+        const ends = boundEnds(edge);
+        if (ends === null)
+            continue;
+        const [sourceId, targetId] = ends;
+        const source = byId.get(sourceId);
+        const target = byId.get(targetId);
+        if (source === undefined || target === undefined)
+            continue;
+        const sourceBound = source.elementBound;
+        const targetBound = target.elementBound;
+        const frame = attributeBackground(sourceBound, backgrounds);
+        // Two maps, two frames of reference: the question does not arise.
+        if (frame === null)
+            continue;
+        if (attributeBackground(targetBound, backgrounds)?.id !== frame.id)
+            continue;
+        const ahead = along(sourceBound) - along(targetBound);
+        const expected = order.expect === 'source-ahead' ? ahead : -ahead;
+        const span = horizontal ? frame.bound.w : frame.bound.h;
+        const tolerance = (order.toleranceRatio ?? 0) * span;
+        if (expected >= -tolerance)
+            continue;
+        violations.push(raise(rule, [edge.id, sourceId, targetId].sort(), frame.id));
+    }
+    return violations;
+}
+/**
+ * The two ids a typed edge points at, SELF-LOOP INCLUDED — the one difference
+ * with {@link boundEnds}, and the reason this family reads the raw pair.
+ *
+ * `boundEnds` answers `null` for an edge whose two ends are the same element,
+ * because an order rule genuinely has nothing to say about one: it would be
+ * comparing an element with itself and no move could ever resolve the finding.
+ * A GRAMMAR rule is the opposite case — a loop is a sentence about the same
+ * artefact twice, which is exactly what {@link RelationEndpointsDef.forbidSelfLoop}
+ * exists to arbitrate. Folding the loop into the null here would make that flag
+ * unreachable, silently.
+ */
+const endpointIds = rawEndpointIds;
+/**
+ * The roles the sanctioned sentences speak of — the ALPHABET of the rule. See
+ * {@link RelationEndpointsDef.allowed} for why an end outside it is silence.
+ */
+function endpointAlphabet(allowed) {
+    const roles = [];
+    for (const triplet of allowed) {
+        for (const role of [triplet.source, triplet.target]) {
+            if (!roles.includes(role))
+                roles.push(role);
+        }
+    }
+    return roles;
+}
+/**
+ * Whether `role` is one the rule's own framework DECLARES.
+ *
+ * The FALLBACK half of {@link RelationEndpointsDef.flagNeutral}'s vocabulary
+ * test — used on its own only by a rule that declares no matrix, and composed
+ * with the grammar's own alphabet when there is one (see the call site).
+ *
+ * A membership test on the vocabulary the rule already carries, and deliberately
+ * not a prefix match on the `framework:` half of the id: the namespace is a
+ * naming convention (`role.ts` types a role id as a bare string and says as
+ * much), while the vocabulary is data the framework hands the engine. Reading
+ * the data cannot be wrong about a framework that spells its own prefix
+ * differently — `ddd-context-map` roles are `context-map:` — and it keeps this
+ * file free of string surgery on ids it does not own.
+ *
+ * `roleIsA` against every declared role would give the same answer at a higher
+ * price: a role outside the vocabulary has no parent chain to walk here, since
+ * the walk reads `rule.roles`, so it can only ever match itself.
+ *
+ * `Object.hasOwn`, and never a bare index: `role` comes off a `Y.Map`, so it is
+ * whatever a peer or an importer wrote, and an element persisted with
+ * `role: 'toString'` would answer "declared" against a bag containing no such
+ * entry. The same threat model {@link elementExceptions} guards with its
+ * `Array.isArray`. Every other read of a role bag in this file goes through
+ * `roleIsA`, which writes `defs[current]?.parent` and terminates harmlessly on
+ * a prototype hit; this is the only place that tests for the PRESENCE of a key.
+ */
+function declaresRole(rule, role) {
+    return role !== undefined && Object.hasOwn(rule.roles, role);
+}
+/** The elements a finding names, deduplicated and sorted. */
+function namedElements(ids) {
+    return Array.from(new Set(ids)).sort();
+}
+/**
+ * "Does this relation say something the framework's grammar allows?"
+ *
+ * The second family whose subject is a RELATION, and the first that reads
+ * nothing but MEANING: no axis, no coordinate, no distance. For every element
+ * carrying the declared edge role it reads the persisted `source → target` pair
+ * and the roles at the two ends, and confronts the sentence with the ones the
+ * framework sanctions — an actor issues a command, a command lands on an
+ * aggregate. A relation drawn upside-down on a Wardley map is a layout mistake;
+ * a relation drawn between the wrong two artefacts is a modelling one, and no
+ * amount of dragging fixes it.
+ *
+ * ## What it stays silent about, and why each one matters
+ *
+ * - **an edge carrying no role, or another role** — proportionality (PRD
+ *   principle 8): a free connector is not a claim. Unless the rule declares
+ *   {@link RelationEndpointsDef.flagNeutral}, which asks for exactly one kind of
+ *   role-less link back: one drawn between two artefacts of this framework's own
+ *   vocabulary, i.e. a relation the user drew and the model does not contain;
+ * - **an edge with a free end** — it relates nothing;
+ * - **an end whose element is gone** — a dangling id says nothing about a model;
+ * - **an end OUTSIDE the alphabet of {@link RelationEndpointsDef.allowed}** —
+ *   the hard requirement of this family. A flow onto a hotspot, onto a neutral
+ *   shape, onto an artefact of another framework: the user is sketching, and a
+ *   grammar that indicted the sketch would be switched off within a day (see
+ *   {@link RelationEndpointsDef.allowed});
+ * - **a self-loop, unless the framework asked** — see
+ *   {@link RelationEndpointsDef.forbidSelfLoop}. Silence here is TOTAL: a loop
+ *   the framework tolerates is not then judged against the matrix, where it
+ *   would fail for a reason nobody meant.
+ *
+ * ## One finding per edge, at most
+ *
+ * An edge already indicted for the sentence it says is not indicted again for
+ * saying it twice: the duplicate and exclusivity passes only see relations that
+ * got through the matrix. Two badges on one link, for one gesture to fix, is
+ * pedantry the canvas cannot afford.
+ *
+ * ## The frame
+ *
+ * {@link ValidationRule.backgroundRole} is optional here and buys ATTRIBUTION
+ * only — the map a finding is written against, so the map-wide arbitration has
+ * somewhere to live (the `no-overlap` pattern). No background DECLARATION is
+ * required: this family reads no fact off the frame, and demanding one would be
+ * asking a framework to declare geometry its grammar never consults.
+ *
+ * ## Cost
+ *
+ * Linear in the elements plus linear in the EDGES: one indexing pass, one pass
+ * over the edges, then one pass over the node pairs that actually carry more
+ * than one relation — which on any real board is a handful. There is no
+ * pair-wise sweep over the nodes: the rule is about relations somebody drew,
+ * never about every couple that could have had one.
+ *
+ * An {@link IncrementalContext} is deliberately NOT honoured, exactly like
+ * `relative-order-along-axis`: a dirty set names the elements that moved, and
+ * this family's verdict does not depend on where anything is. Re-reading every
+ * edge is the cost of the linear pass it already was.
+ */
+function evaluateRelationEndpoints(rule, elements) {
+    const endpoints = rule.endpoints;
+    if (endpoints === undefined)
+        return [];
+    const byId = new Map();
+    const edges = [];
+    // Role-less connectors, kept only when the rule asked to hear about them —
+    // and only the ones that are connectors at all, which the persisted pair is
+    // the duck-typed proof of. A board is mostly neutral elements, and a rule
+    // declaring no `flagNeutral` must not allocate one entry per rectangle.
+    const neutral = [];
+    for (const el of elements) {
+        byId.set(el.id, el);
+        // Cheapest possible exit for a neutral element: no role, no evaluation…
+        if (el.role === undefined) {
+            // …unless the rule is precisely about the links that carry none.
+            if (endpoints.flagNeutral !== undefined && rawEndpointIds(el) !== null) {
+                neutral.push(el);
+            }
+            continue;
+        }
+        if (roleIsA(el.role, endpoints.edgeRole, rule.roles)) {
+            edges.push({ el, role: el.role });
+        }
+    }
+    if (edges.length === 0 && neutral.length === 0)
+        return [];
+    const backgrounds = backgroundsOf(rule, elements);
+    // An EMPTY matrix is a matrix that says nothing, which is the same claim as
+    // declaring none — the reading `allowed`'s own header gives it — so it is
+    // normalised to `undefined` here rather than left to mean an empty alphabet.
+    // Left as one it would silence the rule WHOLE, self-loops and duplicates
+    // included, since every end is outside an alphabet of no roles: exactly the
+    // opposite of what a framework that lists no sentence and forbids loops
+    // asked for. A matrix says nothing about the other three verdicts; it never
+    // switches them off.
+    const allowed = endpoints.allowed === undefined || endpoints.allowed.length === 0
+        ? undefined
+        : endpoints.allowed;
+    const alphabet = allowed === undefined ? null : endpointAlphabet(allowed);
+    // `roleIsA` walks a parent chain, and the two questions below ask it about
+    // the same handful of roles once per edge on the board — a Context Mapping
+    // board draws one vocabulary a hundred times over. Memoised for the duration
+    // of THIS pass and no longer: the precedent is `evaluateNoOverlap`, which
+    // precomputes each subject's slot memberships once instead of re-asking per
+    // couple.
+    const spoken = new Map();
+    const speaks = (role) => {
+        if (alphabet === null)
+            return true;
+        if (role === undefined)
+            return false;
+        const memo = spoken.get(role);
+        if (memo !== undefined)
+            return memo;
+        const answer = alphabet.some(known => roleIsA(role, known, rule.roles));
+        spoken.set(role, answer);
+        return answer;
+    };
+    // Keyed by the whole triplet of roles, joined by NUL — which no vocabulary
+    // contains — so no two sentences can ever fold into one answer.
+    const sanctioned = new Map();
+    const inMatrix = (edgeRole, sourceRole, targetRole) => {
+        const key = `${edgeRole}\u0000${sourceRole}\u0000${targetRole}`;
+        const memo = sanctioned.get(key);
+        if (memo !== undefined)
+            return memo;
+        const answer = allowed.some(triplet => roleIsA(edgeRole, triplet.edge, rule.roles) &&
+            roleIsA(sourceRole, triplet.source, rule.roles) &&
+            roleIsA(targetRole, triplet.target, rule.roles));
+        sanctioned.set(key, answer);
+        return answer;
+    };
+    const exclusivePairs = endpoints.exclusivePairs ?? [];
+    // Hoisted above the walk: the pair bookkeeping is a `DrawnRelation`, a sorted
+    // id list and a map entry PER EDGE, and a rule that judges sentences only
+    // would have allocated all three just to drop them. This runs on the gesture
+    // path, inside the 16 ms the drawing has.
+    const needsPairs = endpoints.forbidDuplicate === true || exclusivePairs.length > 0;
+    const violations = [];
+    // Every relation drawn between one UNORDERED pair of elements, which is the
+    // grain both the duplicate and the exclusivity questions are asked at. Filled
+    // in the same pass that judges the sentences, walked once afterwards.
+    const between = new Map();
+    for (const { el: edge, role } of edges) {
+        const ends = endpointIds(edge);
+        if (ends === null)
+            continue;
+        const [sourceId, targetId] = ends;
+        const source = byId.get(sourceId);
+        const target = byId.get(targetId);
+        if (source === undefined || target === undefined)
+            continue;
+        // Outside the grammar entirely: the user is sketching.
+        if (!speaks(source.role) || !speaks(target.role))
+            continue;
+        // A node, not the edge's own box: the box of a diagonal link spans both
+        // ends and would attribute a relation to whichever map its corner grazes.
+        const frameId = attributeBackground(source.elementBound, backgrounds)?.id;
+        if (sourceId === targetId) {
+            if (endpoints.forbidSelfLoop) {
+                violations.push(raise(rule, namedElements([edge.id, sourceId, targetId]), frameId, endpoints.selfLoop ?? rule));
+            }
+            continue;
+        }
+        if (allowed !== undefined && !inMatrix(role, source.role, target.role)) {
+            violations.push(raise(rule, namedElements([edge.id, sourceId, targetId]), frameId, endpoints.offMatrix ?? rule));
+            continue;
+        }
+        if (!needsPairs)
+            continue;
+        const key = sourceId < targetId
+            ? `${sourceId} ${targetId}`
+            : `${targetId} ${sourceId}`;
+        const drawn = between.get(key);
+        const relation = {
+            id: edge.id,
+            role,
+            sourceId,
+            targetId,
+            ids: namedElements([edge.id, sourceId, targetId]),
+            ...(frameId !== undefined ? { frameId } : {}),
+        };
+        if (drawn === undefined)
+            between.set(key, [relation]);
+        else
+            drawn.push(relation);
+    }
+    // Which roles a role-less link may be flagged BETWEEN.
+    //
+    // The rule's own ALPHABET when it declares a matrix — the roles its grammar
+    // actually has endpoints for, which is the tightest honest reading and gets
+    // `roleIsA` inheritance and the memo above for free. It also excludes, by
+    // construction and with nothing for an author to remember, the roles a
+    // framework declares for things that are not endpoints of anything: a
+    // background role, a legend glyph, a lane. Presuming somebody meant to draw a
+    // typed relation onto a POOL is exactly the over-firing this test exists to
+    // prevent.
+    //
+    // `speaks` cannot do the job alone, and the reason is worth stating: with no
+    // matrix it answers `true` for everything, `undefined` included, because
+    // "outside the alphabet" has no meaning when there is no alphabet. A
+    // matrix-less rule therefore falls back to membership in the vocabulary
+    // ({@link declaresRole}), which stays purely the dictionary `roleIsA` walks —
+    // the bag is NOT overloaded into a filter, so an author never has to shrink
+    // their inheritance dictionary in order to change what gets flagged.
+    const inVocabulary = (role) => alphabet === null ? declaresRole(rule, role) : speaks(role);
+    // The NEUTRAL pass: a link carrying no role at all, drawn between two
+    // artefacts this rule's grammar could have related. See
+    // {@link RelationEndpointsDef.flagNeutral} — the gesture that produces one is
+    // quick-connect, which stamps nothing, so the user has drawn a relation the
+    // model does not contain.
+    //
+    // The edge is judged on WHAT it joins and never against the matrix: the matrix
+    // says which sentences are legal, and this edge says no sentence at all. A
+    // self-loop is skipped for the same reason `boundEnds` skips one everywhere
+    // else — a link from an artefact to itself is not evidence that a typed
+    // relation was meant.
+    for (const el of neutral) {
+        const ends = boundEnds(el);
+        if (ends === null)
+            continue;
+        const [sourceId, targetId] = ends;
+        const source = byId.get(sourceId);
+        const target = byId.get(targetId);
+        if (source === undefined || target === undefined)
+            continue;
+        if (!inVocabulary(source.role) || !inVocabulary(target.role))
+            continue;
+        violations.push(raise(rule, namedElements([el.id, sourceId, targetId]), attributeBackground(source.elementBound, backgrounds)?.id, endpoints.flagNeutral));
+    }
+    if (!needsPairs)
+        return violations;
+    // Sorted, so a board holding several offending pairs always reports them the
+    // same way whichever order the surface happened to be walked in.
+    for (const key of [...between.keys()].sort()) {
+        const drawn = between.get(key);
+        if (drawn.length < 2)
+            continue;
+        // By edge id, so the relation that keeps its innocence is the same one on
+        // every peer and after every reload — never the one a Y.Map rebuild
+        // happened to yield first.
+        const relations = [...drawn].sort((a, b) => (a.id < b.id ? -1 : 1));
+        if (endpoints.forbidDuplicate) {
+            const seen = new Set();
+            for (const relation of relations) {
+                // Same role AND same ordered pair: A → B and B → A are two different
+                // sentences, and a framework that wants them exclusive says so in
+                // `exclusivePairs`.
+                const sentence = `${relation.role} ${relation.sourceId} ${relation.targetId}`;
+                // The FIRST one is not a duplicate of anything; every copy after it is.
+                if (seen.has(sentence)) {
+                    violations.push(raise(rule, relation.ids, relation.frameId, endpoints.duplicate ?? rule));
+                }
+                seen.add(sentence);
+            }
+        }
+        // Two declared pairs can both cover the same two relations (a pair written
+        // on a parent role and one on its specialisation): one situation, one
+        // finding.
+        const reported = new Set();
+        for (const [first, second] of exclusivePairs) {
+            for (let i = 0; i < relations.length; i++) {
+                for (let j = i + 1; j < relations.length; j++) {
+                    const a = relations[i];
+                    const b = relations[j];
+                    const matched = (roleIsA(a.role, first, rule.roles) &&
+                        roleIsA(b.role, second, rule.roles)) ||
+                        (roleIsA(a.role, second, rule.roles) &&
+                            roleIsA(b.role, first, rule.roles));
+                    if (!matched)
+                        continue;
+                    const couple = `${a.id} ${b.id}`;
+                    if (reported.has(couple))
+                        continue;
+                    reported.add(couple);
+                    // BOTH relations and both ends: either link is a legitimate
+                    // resolution, so neither may be left out of the finding, and the pair
+                    // of artefacts is what makes the two of them one situation.
+                    //
+                    // The frame is the SMALLER of the two the relations were attributed
+                    // to — the house tie-break, and it has to be one: each relation is
+                    // attributed by its OWN source node, so two links drawn from opposite
+                    // ends can name two frames, and taking the first one's would write a
+                    // map-wide arbitration wherever the surface happened to be walked.
+                    const frameId = b.frameId !== undefined &&
+                        (a.frameId === undefined || b.frameId < a.frameId)
+                        ? b.frameId
+                        : a.frameId;
+                    violations.push(raise(rule, namedElements([a.id, b.id, a.sourceId, a.targetId]), frameId, endpoints.exclusive ?? rule));
+                }
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * The cited zones of one instance, as model-space rectangles.
+ *
+ * Ratios are of the PLOT — the element box minus the declared margin — so this
+ * is the same resolution `backgroundBoundaryCoords` does for transitions, and
+ * the reason a rule never restates a coordinate the declaration already owns.
+ * In the rule's OWN citation order, so `boundaryId` names the first zone the
+ * rule itself mentions rather than the first one the declaration happens to
+ * list.
+ *
+ * ## Resolved against the INSTANCE, variants included
+ *
+ * A variant is a second reading of the same frame, and a zone that belongs to
+ * the other reading is not drawn on this instance at all: it is not a region of
+ * it either, and measuring against a quadrant nobody can see would indict an
+ * artefact for sitting where the chart shows nothing. Same gate the renderer and
+ * the label walk pass through, read off the same props.
+ *
+ * Silence, not {@link warnOnce}: a rule citing a zone the declaration does not
+ * declare is a broken RULE and says so, but a rule citing a zone this INSTANCE
+ * does not read is a perfectly good rule looking at a frame turned to its other
+ * page.
+ */
+function zoneRegions(def, zoneIds, frame) {
+    const bound = frame.bound;
+    const plot = backgroundPlot(def, bound.w, bound.h);
+    const regions = [];
+    for (const id of zoneIds) {
+        const zone = (def.zones ?? []).find(candidate => candidate.id === id);
+        if (zone === undefined)
+            continue;
+        if (!backgroundInVariant(def, zone.variants, frame.props))
+            continue;
+        regions.push({
+            id,
+            bound: new Bound(bound.x + plot.x0 + zone.rect.x * plot.width, bound.y + plot.y0 + zone.rect.y * plot.height, zone.rect.w * plot.width, zone.rect.h * plot.height),
+        });
+    }
+    return regions;
+}
+/**
+ * The instance a subject is judged against: the one that CONTAINS it.
+ *
+ * Not `attributeBackground`, and the difference is the point: "which zone is
+ * this in" only means something for an artefact that is ON the map. An element
+ * next to the card is outside every zone of it, which under `expect: 'inside'`
+ * would make it a finding of THIS rule — a second, worse-worded version of
+ * `element-in-background`, raised on artefacts the framework may perfectly well
+ * allow off the frame. Off every frame is silence here, and whether that is
+ * itself a mistake is a different rule's question.
+ *
+ * Ties go to the smaller id, never to the order a `Y.Map` was rebuilt in: the
+ * answer decides where a persisted arbitration is written.
+ */
+function containingBackground(bound, backgrounds) {
+    let found = null;
+    for (const background of backgrounds) {
+        if (!background.bound.contains(bound))
+            continue;
+        if (found === null || background.id < found.id)
+            found = background;
+    }
+    return found;
+}
+/**
+ * "Is this artefact in the region it belongs in?" — the zone half of
+ * `element-in-background`.
+ *
+ * The zones are the frame's own declared ones, named by id: a rule says
+ * `zoneIds: ['core'], expect: 'outside'` and the geometry comes from the
+ * declaration the renderer paints from. Nothing is restated, so a framework
+ * that redraws its quadrants moves its rules with them.
+ *
+ * ## Not gated on the tint
+ *
+ * A zone is SEMANTIC; its `fillVisibleProp` only decides whether it is
+ * coloured in. A user who switched the tints off to print a clean chart has not
+ * told the tool that the Core quadrant stopped being the Core quadrant — the
+ * labels, the axes and the whole point of the chart are still there.
+ *
+ * A deliberate contrast with `attachment`, which DOES read the instance's props
+ * before judging a transition, and the two are not in tension: a transition is a
+ * LINE, and a line the user has hidden is a line they cannot aim at, so the
+ * gesture the finding asks for would point at nothing. A quadrant is a REGION of
+ * a frame of reference that is still fully on screen. Judge the drawing that is
+ * on the canvas — and a hidden tint does not take a quadrant off it.
+ */
+function evaluateElementInZone(rule, elements) {
+    const subjectRole = rule.appliesTo;
+    const inZone = rule.inZone;
+    const def = rule.background;
+    if (subjectRole === undefined || inZone === undefined || def === undefined) {
+        return [];
+    }
+    if (inZone.zoneIds.length === 0)
+        return [];
+    const declared = new Set((def.zones ?? []).map(zone => zone.id));
+    const unknown = inZone.zoneIds.filter(id => !declared.has(id));
+    if (unknown.length > 0) {
+        // Measuring against the zones it happened to recognise would be a DIFFERENT
+        // rule — a narrower union, a shorter list of forbidden ground — and nothing
+        // on the canvas would show the difference.
+        warnOnce(`element-in-zone rule "${rule.id}" names zone(s) its background does ` +
+            `not declare (${unknown.join(', ')}) — the rule is not evaluated.`);
+        return [];
+    }
+    const backgrounds = backgroundsOf(rule, elements);
+    // No frame on the board, no zones to be in: an artefact on blank canvas is a
+    // sketch.
+    if (backgrounds.length === 0)
+        return [];
+    // Zones are a function of the frame's bounds AND of the reading it is turned
+    // to, and a board carries units of frames against hundreds of subjects:
+    // resolved once per frame, per variant. Both halves are in the key, so the
+    // entry can never outlive the reading it was built for — an id alone would be
+    // right only for as long as nobody moved this map out of one evaluation.
+    const regionsOf = new Map();
+    const extent = inZone.measure === 'extent';
+    const violations = [];
+    for (const el of elements) {
+        if (el.role === undefined)
+            continue;
+        if (!roleIsA(el.role, subjectRole, rule.roles))
+            continue;
+        const bound = el.elementBound;
+        const frame = containingBackground(bound, backgrounds);
+        if (frame === null)
+            continue;
+        // Keyed by the frame AND the reading it is turned to, joined by NUL — which
+        // no id and no variant name contains — so the two halves can never fold
+        // into one entry.
+        const variant = def.variantProp === undefined ? '' : String(frame.props[def.variantProp]);
+        const key = `${frame.id}\u0000${variant}`;
+        let regions = regionsOf.get(key);
+        if (regions === undefined) {
+            regions = zoneRegions(def, inZone.zoneIds, frame);
+            regionsOf.set(key, regions);
+        }
+        // Every cited zone belongs to the frame's OTHER reading: this instance has
+        // no such region, so there is nothing to be inside or outside of. Under
+        // `expect: 'inside'` the alternative would be indicting every subject on a
+        // frame that simply shows another page.
+        if (regions.length === 0)
+            continue;
+        const centre = centreOf(bound);
+        // `inside` asks for the subject to be WHOLLY in one zone; `outside` for it
+        // to share no area with any. The border belongs to the zone in both
+        // readings, so two neighbours never disagree about an artefact on their
+        // frontier.
+        const occupies = (region) => extent
+            ? region.bound.contains(bound)
+            : region.bound.containsPoint(centre);
+        const touches = (region) => extent
+            ? boundsOverlap(region.bound, bound)
+            : region.bound.containsPoint(centre);
+        if (inZone.expect === 'inside') {
+            if (regions.some(occupies))
+                continue;
+            // The zone the subject missed: the nearest one, which is the one the user
+            // was aiming at and the only one a suggestion can point back to.
+            let nearest;
+            let distance = Infinity;
+            for (const region of regions) {
+                const gap = gapSquared(region.bound, bound);
+                if (gap < distance) {
+                    distance = gap;
+                    nearest = region;
+                }
+            }
+            const violation = raise(rule, [el.id], frame.id);
+            if (nearest !== undefined)
+                violation.boundaryId = nearest.id;
+            violations.push(violation);
+            continue;
+        }
+        const trespassed = regions.find(touches);
+        if (trespassed === undefined)
+            continue;
+        const violation = raise(rule, [el.id], frame.id);
+        violation.boundaryId = trespassed.id;
+        violations.push(violation);
+    }
+    return violations;
+}
+/**
+ * "Does this artefact belong on THIS view?"
+ *
+ * The first family whose subject is the SHEET. Every other one starts from an
+ * artefact — a node, a relation, a pair — and asks something about where it is
+ * or what touches it. This one starts from a frame that has DECLARED what kind
+ * of view it is, and judges what has been drawn on it against that declaration.
+ *
+ * The level is read off the instance, from the prop the rule names
+ * ({@link ViewAdmissibilityDef.levelProp}) — the very idiom the background
+ * primitives already use for labels and variants — so the engine learns which
+ * views exist from the document rather than from a registry of its own.
+ *
+ * ## What it stays silent about, and why each one matters
+ *
+ * - **a frame that declares NO level** — the overwhelming majority, and every
+ *   frame in every document written before the prop existed. No fact, no rule
+ *   (PRD principle 8): a sheet whose author never said which view it is has
+ *   made no claim for anything to contradict, and a family that guessed would
+ *   light up every diagram already on disk.
+ * - **a level the rule's table does not name**, or names with an empty list —
+ *   the rule has nothing to say about that view. That is what lets a framework
+ *   ship the levels that forbid something and stay quiet on the one that
+ *   forbids nothing, instead of a rule that can never fire.
+ * - **an element carrying no role** — a rectangle somebody dropped on the sheet
+ *   to think with belongs to no notation, so no view can refuse it.
+ * - **an element off every declared view** — it is on the canvas beside the
+ *   sheet, not on it, and a view judges what is drawn ON it.
+ * - **the frame itself**, and any other frame of the same role: a view is not
+ *   an artefact drawn on itself.
+ *
+ * ## Which view judges an element
+ *
+ * The one whose plot contains its CENTRE ({@link plotContaining}) — membership,
+ * with the same tie-break every attribution in this file uses, and never the
+ * nearest-frame fallback: "this artefact is on that view" has to mean it, or a
+ * box floating beside a context diagram would be indicted by it.
+ *
+ * A subject on two nested views is judged by ONE of them, the smaller id, which
+ * is the same answer `role-count` and `edge-locality` give. Two views drawn on
+ * top of each other is not a case C4 has, and inventing a second verdict for it
+ * would mean inventing which of the two the author meant.
+ *
+ * ## Cost, and why it is realtime-safe
+ *
+ * One pass to collect the views (units per board), one plot resolved per view,
+ * then ONE pass over the elements with one containment walk and at most
+ * `forbidden.length` role tests each. Linear in the surface, no graph, no pair
+ * walk, nothing quadratic — the same budget `element-in-background` and
+ * `role-count` are measured on.
+ */
+function evaluateViewAdmissibility(rule, elements) {
+    const def = rule.admissibility;
+    if (def === undefined)
+        return [];
+    if (missingFrameRole(rule, 'view-admissibility'))
+        return [];
+    // The views that have both DECLARED a level and given this rule something to
+    // say about it. Resolved once, per frame — the plot arithmetic and the table
+    // lookup must not be paid per subject.
+    const views = [];
+    const forbiddenOf = new Map();
+    for (const frame of framePlots(rule, elements)) {
+        const stated = frame.instance.props[def.levelProp];
+        // A level is a non-empty string or it is nothing. The value comes off a
+        // Y.Map, so it is whatever a peer, an importer or an older client wrote.
+        if (typeof stated !== 'string' || stated === '')
+            continue;
+        // Own keys only: `forbidden` is an object literal shipped by a framework.
+        if (!Object.hasOwn(def.forbidden, stated))
+            continue;
+        const forbidden = def.forbidden[stated];
+        if (forbidden === undefined || forbidden.length === 0)
+            continue;
+        views.push(frame);
+        forbiddenOf.set(frame.instance.id, forbidden);
+    }
+    // No view on the board has stated a level this rule judges: not one element
+    // is walked.
+    if (views.length === 0)
+        return [];
+    const violations = [];
+    for (const el of elements) {
+        // Cheapest possible exit for a neutral element: no role, no evaluation.
+        const role = el.role;
+        if (role === undefined)
+            continue;
+        // A view is never an artefact drawn on ITSELF — its own centre is inside
+        // its own plot, so without this a rule forbidding the frame's own role
+        // would indict every frame that declared a level.
+        if (forbiddenOf.has(el.id))
+            continue;
+        const view = plotContaining(centreOf(el.elementBound), views);
+        if (view === null)
+            continue;
+        const forbidden = forbiddenOf.get(view.id);
+        if (forbidden === undefined)
+            continue;
+        // One finding per element, whichever forbidden role matched: the author has
+        // drawn one box on the wrong sheet, and telling them twice about it would
+        // be describing our table rather than their diagram.
+        if (forbidden.some(entry => roleIsA(role, entry, rule.roles))) {
+            violations.push(raise(rule, [el.id], view.id));
+        }
+    }
+    return violations;
+}
+/**
+ * "How many relations reach this node?" — the cardinality half of a grammar.
+ *
+ * One pass to count, one pass to judge. For every element carrying the declared
+ * edge role, the persisted `source → target` pair adds one OUT to its source and
+ * one IN to its target; then every subject node is confronted with the bounds
+ * its rule declares.
+ *
+ * ## What it stays silent about, and why each one matters
+ *
+ * - **an edge with a free end** — it relates nothing, so it is not evidence of a
+ *   node being connected. A link the user has grabbed and not yet dropped must
+ *   not make a start event legal for the length of the gesture;
+ * - **an end that is not a subject of this rule** — nothing to say about it;
+ * - **a rule declaring no bound at all** — it asks nothing. It warns once, since
+ *   data that can never fire and never says why is the worst thing declarative
+ *   data can do.
+ *
+ * ## An end whose element is GONE, and why this family keeps the other half
+ *
+ * A dangling id counts against nobody, but the edge is not dropped: the node at
+ * the surviving end really does have one relation leaving it, and no gesture the
+ * user makes on THAT node changes the fact. This family counts the ends, never
+ * the survivors.
+ *
+ * A deliberate divergence from the three families whose subject is the RELATION
+ * — `relative-order-along-axis`, `relation-endpoints`, `edge-locality` — which
+ * drop such an edge whole, because a sentence with a missing half is not a
+ * sentence anybody can be told about. A COUNT has no such problem, and neither
+ * does the traversal in {@link evaluateReachability}, which follows the arc to
+ * an element that is not there and simply never reaches anything by it. Two
+ * different questions, two different readings of the same broken pair.
+ *
+ * A SELF-LOOP counts on both sides: the node genuinely has one edge leaving and
+ * one arriving, and that is what the document says. Whether a loop is legitimate
+ * at all is `relation-endpoints`' question, asked with its own flag, and a
+ * count that quietly ignored loops would let one launder a node past a `maxOut`.
+ *
+ * ## One finding per node
+ *
+ * The bounds are tested in a fixed order — in, then out; fewest, then most; and
+ * {@link EdgeDegreeDef.eitherMin} LAST — and the first one that fails is the
+ * finding. Five badges on one symbol for one situation is pedantry the canvas
+ * cannot afford; the same argument `relation-endpoints` makes about not
+ * indicting an edge twice.
+ *
+ * The disjunction goes last on purpose. A per-direction bound names the side the
+ * user has to act on, and "nothing arrives here" is a more useful sentence than
+ * "neither side has enough"; the disjunction only speaks when the four
+ * conjunctive bounds have nothing to say. It is orthogonal to them, not a
+ * substitute: a rule may cap one side and still ask for two on either.
+ *
+ * ## Cost
+ *
+ * Linear in the elements plus linear in the EDGES, with one hash lookup per end.
+ * No pair-wise sweep and no closure: the rule is about the relations somebody
+ * drew, never about the ones they could have drawn.
+ */
+function evaluateEdgeDegree(rule, elements) {
+    const subjectRole = rule.appliesTo;
+    const degree = rule.degree;
+    if (subjectRole === undefined || degree === undefined)
+        return [];
+    const { minIn, maxIn, minOut, maxOut, eitherMin } = degree;
+    // A pattern satisfied by every node — one supplying no bound at all — would
+    // indict the whole board, which is the loudest possible way for a typo in the
+    // data to be wrong. Dropped rather than honoured, and said once.
+    const pattern = degree.forbidPattern;
+    const patternBounds = pattern === undefined
+        ? null
+        : [
+            ['in', '>=', pattern.minIn],
+            ['in', '<=', pattern.maxIn],
+            ['out', '>=', pattern.minOut],
+            ['out', '<=', pattern.maxOut],
+        ].filter(([, , value]) => value !== undefined);
+    if (patternBounds !== null && patternBounds.length === 0) {
+        warnOnce(`edge-degree rule "${rule.id}" declares a forbidden pattern with no ` +
+            `bound in it, which every node matches — the pattern is dropped.`);
+    }
+    const forbidden = patternBounds !== null && patternBounds.length > 0 ? patternBounds : null;
+    if (minIn === undefined &&
+        maxIn === undefined &&
+        minOut === undefined &&
+        maxOut === undefined &&
+        eitherMin === undefined &&
+        forbidden === null) {
+        warnOnce(`edge-degree rule "${rule.id}" declares no bound at all — the rule is ` +
+            `not evaluated.`);
+        return [];
+    }
+    // In the surface's own walk order, so a board reports its offending nodes the
+    // same way every other element-local family does.
+    const subjects = [];
+    const bySubjectId = new Map();
+    const edges = [];
+    for (const el of elements) {
+        // Cheapest possible exit for a neutral element: no role, no evaluation.
+        if (el.role === undefined)
+            continue;
+        if (roleIsA(el.role, subjectRole, rule.roles)) {
+            const subject = { el, in: 0, out: 0 };
+            subjects.push(subject);
+            bySubjectId.set(el.id, subject);
+        }
+        if (roleIsA(el.role, degree.edgeRole, rule.roles))
+            edges.push(el);
+    }
+    if (subjects.length === 0)
+        return [];
+    for (const edge of edges) {
+        const ends = rawEndpointIds(edge);
+        if (ends === null)
+            continue;
+        const source = bySubjectId.get(ends[0]);
+        if (source !== undefined)
+            source.out += 1;
+        const target = bySubjectId.get(ends[1]);
+        if (target !== undefined)
+            target.in += 1;
+    }
+    // Only resolved when something is actually wrong: a conformant board is the
+    // common case and must not pay for the frames it never names.
+    let backgrounds = null;
+    const violations = [];
+    for (const subject of subjects) {
+        const words = minIn !== undefined && subject.in < minIn
+            ? (degree.tooFewIn ?? rule)
+            : maxIn !== undefined && subject.in > maxIn
+                ? (degree.tooManyIn ?? rule)
+                : minOut !== undefined && subject.out < minOut
+                    ? (degree.tooFewOut ?? rule)
+                    : maxOut !== undefined && subject.out > maxOut
+                        ? (degree.tooManyOut ?? rule)
+                        : // LAST, and deliberately: a per-direction bound names the side
+                            // the user has to act on, which is a more useful sentence than
+                            // "neither side". The disjunction only speaks when the four
+                            // above have nothing to say.
+                            eitherMin !== undefined &&
+                                subject.in < eitherMin &&
+                                subject.out < eitherMin
+                                ? (degree.neither ?? rule)
+                                : // LAST of all, for the same reason: a bound that failed names
+                                    // what is missing, and a forbidden zone names a shape. When
+                                    // both have something to say, the missing thing is the more
+                                    // actionable half.
+                                    forbidden !== null &&
+                                        forbidden.every(([side, test, value]) => test === '>='
+                                            ? subject[side] >= value
+                                            : subject[side] <= value)
+                                        ? (pattern ?? rule)
+                                        : null;
+        if (words === null)
+            continue;
+        backgrounds ??= backgroundsOf(rule, elements);
+        const frameId = attributeBackground(subject.el.elementBound, backgrounds)?.id;
+        violations.push(raise(rule, [subject.el.id], frameId, words));
+    }
+    return violations;
+}
+/**
+ * "How many of these does one frame hold?" — existence and uniqueness.
+ *
+ * The tally is per INSTANCE and anchored ON it, exactly like
+ * {@link evaluateMajorityFact}: a board carrying three pools holds three
+ * independent answers, the bracket lands on the pool the answer is about, and
+ * the `map` exemption scope therefore covers that pool and no other.
+ *
+ * ## Containment, and only containment
+ *
+ * A subject belongs to the frame whose plot contains its CENTRE
+ * ({@link plotContaining}) — deliberately not `attributeBackground`'s
+ * nearest-fallback, which would let a start event floating beside a pool satisfy
+ * "this pool has a start event". A subject inside no frame at all is counted by
+ * nobody, and whether that is itself a mistake is `element-in-background`'s
+ * question.
+ *
+ * ## Silence
+ *
+ * - **no frame on the board** — nothing to count into. An artefact on blank
+ *   canvas is a sketch, and a process sketched before its pool was drawn must
+ *   not light up;
+ * - **a rule declaring neither bound** — it asks nothing, and warns once;
+ * - **a frame the GUARD has not armed** — see {@link RoleCountDef.ifPresent}.
+ *   Not judged, rather than judged and found compliant: a conditional
+ *   requirement says nothing at all about the case its condition excludes.
+ *
+ * An EMPTY frame is not silence: a pool holding no start event is precisely what
+ * `min` is for, so every instance gets an entry before the walk, not when a
+ * subject happens to land on it. The guard is what turns that back into silence
+ * for a notation where the artefact is optional on its own.
+ *
+ * ## Cost
+ *
+ * One pass over the elements, one plot per frame, one containment test per
+ * subject per frame — the frames are counted in units, so this is constant per
+ * element in practice, like every other attribution in this file.
+ */
+function evaluateRoleCount(rule, elements) {
+    const count = rule.roleCount;
+    if (count === undefined)
+        return [];
+    if (missingFrameRole(rule, 'role-count'))
+        return [];
+    const { min, max } = count;
+    if (min === undefined && max === undefined) {
+        warnOnce(`role-count rule "${rule.id}" declares neither a minimum nor a maximum ` +
+            `— the rule is not evaluated.`);
+        return [];
+    }
+    const frames = framePlots(rule, elements);
+    // No frame on the board: nothing for the count to be about.
+    if (frames.length === 0)
+        return [];
+    const tally = new Map();
+    for (const frame of frames)
+        tally.set(frame.instance.id, 0);
+    // The frames the GUARD has armed. Left null by a rule that declares none, so
+    // an unguarded rule allocates nothing and reads nothing extra per element.
+    const guard = count.ifPresent;
+    const armed = guard === undefined ? null : new Set();
+    for (const el of elements) {
+        // Cheapest possible exit for a neutral element: no role, no evaluation.
+        if (el.role === undefined)
+            continue;
+        const counts = count.exact === true
+            ? el.role === count.subject
+            : roleIsA(el.role, count.subject, rule.roles);
+        // Not `else if`: nothing forbids a vocabulary where the guard role and the
+        // counted role overlap, and an element that is both must arm the frame AND
+        // be counted in it. Two independent questions about one element.
+        const arms = guard !== undefined && roleIsA(el.role, guard, rule.roles);
+        if (!counts && !arms)
+            continue;
+        // Resolved once for both questions: the containment walk is the expensive
+        // half, and an element that is subject and guard at once must not pay twice.
+        const frame = plotContaining(centreOf(el.elementBound), frames);
+        // Off every frame: it neither counts towards a requirement nor arms one.
+        // An artefact floating beside a pool is a draft, on both readings.
+        if (frame === null)
+            continue;
+        if (counts)
+            tally.set(frame.id, (tally.get(frame.id) ?? 0) + 1);
+        if (arms)
+            armed.add(frame.id);
+    }
+    const violations = [];
+    // Sorted, so a board with several offending frames always reports them the
+    // same way whichever order the surface happened to be walked in.
+    for (const id of [...tally.keys()].sort()) {
+        // A frame the guard has not armed is not judged at all — not walked, not
+        // found compliant. That is the difference between "this notation requires
+        // one" and "this notation requires one WHEN the other is there".
+        if (armed !== null && !armed.has(id))
+            continue;
+        const held = tally.get(id);
+        const words = min !== undefined && held < min
+            ? (count.tooFew ?? rule)
+            : max !== undefined && held > max
+                ? (count.tooMany ?? rule)
+                : null;
+        if (words === null)
+            continue;
+        violations.push(raise(rule, [id], id, words));
+    }
+    return violations;
+}
+/**
+ * "Does this relation stay inside one frame, or cross between two?"
+ *
+ * The third family whose subject is a RELATION, and the only one that reads the
+ * frames rather than the roles: a sequence flow belongs to one pool, a message
+ * flow exists only between two. The two ends carry the same roles in the legal
+ * case and the illegal one, so nothing but the attribution can tell them apart.
+ *
+ * Each END is attributed on its own, by the centre of ITS element and never by
+ * the edge's box — the box of a link between two pools spans both of them and
+ * would answer whichever question was asked of it.
+ *
+ * ## What it stays silent about, and why each one matters
+ *
+ * - **no frame on the board** — a process sketched before anybody drew a pool is
+ *   a sketch, and this is the family a poolless board would otherwise light up
+ *   from end to end;
+ * - **an edge with a free end, or an end whose element is gone** — it relates
+ *   nothing;
+ * - **a self-loop** — one element compared with itself is always in its own
+ *   frame, so it says nothing about locality either way; whether a loop is legal
+ *   at all is `relation-endpoints`' question ({@link boundEnds});
+ * - **an end inside NO frame** — the decisive one, and it is the same
+ *   proportionality {@link RelationEndpointsDef.allowed}'s alphabet applies: a
+ *   task dropped beside the pool is a draft, and a tool that answered "that flow
+ *   leaves the pool" would be indicting the act of sketching.
+ *
+ * ## The finding names the edge AND its two ends
+ *
+ * The `relative-order-along-axis` and `relation-endpoints` precedent, for the
+ * same reason: the finding has two honest resolutions — move the artefact into
+ * the frame it belongs to, or re-point the link — and the second is only
+ * reachable from the edge. It is attributed to the SOURCE's frame, like every
+ * other relation finding in this file.
+ *
+ * ## Cost
+ *
+ * Linear in the elements plus linear in the edges, with the plots resolved once
+ * per frame.
+ */
+function evaluateEdgeLocality(rule, elements) {
+    const locality = rule.locality;
+    if (locality === undefined)
+        return [];
+    if (missingFrameRole(rule, 'edge-locality'))
+        return [];
+    const frames = framePlots(rule, elements);
+    // No frame on the board, no locality to be in or out of.
+    if (frames.length === 0)
+        return [];
+    const byId = new Map();
+    const edges = [];
+    for (const el of elements) {
+        byId.set(el.id, el);
+        // Cheapest possible exit for a neutral element: no role, no evaluation.
+        if (el.role === undefined)
+            continue;
+        if (roleIsA(el.role, locality.edgeRole, rule.roles))
+            edges.push(el);
+    }
+    if (edges.length === 0)
+        return [];
+    const same = locality.mode === 'same-background';
+    const violations = [];
+    for (const edge of edges) {
+        const ends = boundEnds(edge);
+        if (ends === null)
+            continue;
+        const [sourceId, targetId] = ends;
+        const source = byId.get(sourceId);
+        const target = byId.get(targetId);
+        if (source === undefined || target === undefined)
+            continue;
+        const sourceFrame = plotContaining(centreOf(source.elementBound), frames);
+        if (sourceFrame === null)
+            continue;
+        const targetFrame = plotContaining(centreOf(target.elementBound), frames);
+        if (targetFrame === null)
+            continue;
+        // Conformant when the two ends agree with the mode: one instance for
+        // `same-background`, two for `cross-background`.
+        const together = sourceFrame.id === targetFrame.id;
+        if (together === same)
+            continue;
+        violations.push(raise(rule, namedElements([edge.id, sourceId, targetId]), sourceFrame.id));
+    }
+    return violations;
+}
+/**
+ * "Can you get here from the start?" — the orphan question.
+ *
+ * The first family that builds a GRAPH. Every element carrying the declared edge
+ * role contributes one directed arc, `source → target`, read off the persisted
+ * pair and never off the geometry; a breadth-first walk leaves from every root
+ * at once; and every subject the walk never reached is a finding.
+ *
+ * ## Silence when there is no root
+ *
+ * TOTAL, and it is the load-bearing decision of this family. A process with no
+ * start event has every one of its tasks unreachable, so the rule would answer
+ * an empty board with one finding per artefact on it — a wall of brackets whose
+ * single real cause is a missing start event, which is `role-count`'s question
+ * and is already asked once, on the frame. One mistake, one sentence.
+ *
+ * A root is seeded into the visited set, which is also what makes "a root is
+ * never its own orphan" fall out rather than needing a second test.
+ *
+ * ## Two readings of "root"
+ *
+ * {@link ReachabilityDef.implicitRoots} adds the subjects nothing points at to
+ * the set the walk leaves from — the second, silent way a notation with an
+ * optional start marker says "the work begins here". Under it the gate above
+ * means "no root of EITHER kind", and what is left is every subject that has an
+ * incoming counted edge and that no root reaches: a ring entered from nowhere,
+ * and a subject fed only by an edge whose own source the walk never leaves from
+ * (a dangling id, or an element outside both roles). See that field for why the
+ * second one is reported here and fixed elsewhere.
+ *
+ * The two readings share every line but the seeding, deliberately: the answer to
+ * "can you get here" must not depend on which one a framework picked — including
+ * for that second shape, which behaves identically either way.
+ *
+ * ## Direction, and the arcs it does not add
+ *
+ * The walk follows arcs FORWARD only. "Reachable from the start" is a statement
+ * about the direction the process runs in; a task that only points BACK at the
+ * chain is exactly the mistake this exists to find, and an undirected walk would
+ * certify it. An edge with a free end, or an end whose element is gone, adds no
+ * arc — it connects nothing.
+ *
+ * ## Cost, and the incremental story
+ *
+ * O(V + E): one indexing pass, one adjacency build, one traversal that visits
+ * each node and each arc at most once.
+ *
+ * An {@link IncrementalContext} is deliberately NOT honoured, and could not
+ * usefully be: reachability is a GLOBAL property, so re-pointing a single edge
+ * can orphan or rescue an arbitrary number of nodes nowhere near it, and any
+ * dirty edge invalidates the whole answer. A framework that finds the traversal
+ * too expensive for the drawing path declares its rule `'on-demand'` — the
+ * moment is the rule's to choose ({@link ValidationMoment}), and this family
+ * stays agnostic about which one it is evaluated at.
+ */
+function evaluateReachability(rule, elements) {
+    const def = rule.reachability;
+    if (def === undefined)
+        return [];
+    const subjects = [];
+    const edges = [];
+    // Seeded with the roots, which is what makes a root that is also a subject
+    // reachable by definition rather than by a second test.
+    const visited = new Set();
+    const queue = [];
+    for (const el of elements) {
+        // Cheapest possible exit for a neutral element: no role, no evaluation.
+        if (el.role === undefined)
+            continue;
+        if (roleIsA(el.role, def.rootRole, rule.roles)) {
+            if (!visited.has(el.id)) {
+                visited.add(el.id);
+                queue.push(el.id);
+            }
+        }
+        if (roleIsA(el.role, def.subjectRole, rule.roles))
+            subjects.push(el);
+        if (roleIsA(el.role, def.edgeRole, rule.roles))
+            edges.push(el);
+    }
+    if (subjects.length === 0)
+        return [];
+    const implicit = def.implicitRoots === true;
+    // Under the declared-roots-only reading the gate is answerable before a
+    // single arc is built, which is the cheapest exit this family has. The
+    // implicit reading cannot take it: whether there is a root at all is a fact
+    // about the ARCS, so it has to wait for them.
+    if (!implicit && queue.length === 0)
+        return [];
+    const next = new Map();
+    // Every element some arc points AT — tracked only for the implicit reading,
+    // which is the only one that needs an in-degree. A board on the declared
+    // reading allocates nothing.
+    const pointedAt = implicit ? new Set() : null;
+    for (const edge of edges) {
+        const ends = rawEndpointIds(edge);
+        if (ends === null)
+            continue;
+        const outgoing = next.get(ends[0]);
+        if (outgoing === undefined)
+            next.set(ends[0], [ends[1]]);
+        else
+            outgoing.push(ends[1]);
+        pointedAt?.add(ends[1]);
+    }
+    if (pointedAt !== null) {
+        // A subject nothing points at IS a beginning — see
+        // {@link ReachabilityDef.implicitRoots}. In the surface's walk order, and
+        // through the same `visited` guard the declared roots use, so a subject
+        // that is also a declared root is seeded exactly once.
+        //
+        // A SELF-LOOP disqualifies its own node, and rightly: something does point
+        // at it. A ring of one is the smallest instance of the only defect this
+        // reading still reports.
+        for (const el of subjects) {
+            if (pointedAt.has(el.id) || visited.has(el.id))
+                continue;
+            visited.add(el.id);
+            queue.push(el.id);
+        }
+    }
+    // THE GATE: no root of EITHER kind on the board, so nothing is unreachable —
+    // see above. Under the implicit reading a board reaches this only when every
+    // one of its subjects is pointed at, i.e. when they all sit in rings entered
+    // from nowhere, and the question genuinely does not arise.
+    if (queue.length === 0)
+        return [];
+    // Breadth-first from every root at once. `head` walks the queue instead of
+    // `shift()`ing it: a shift is O(n) on a real array, which would turn an
+    // O(V + E) traversal quadratic on the one board big enough to notice.
+    for (let head = 0; head < queue.length; head++) {
+        const outgoing = next.get(queue[head]);
+        if (outgoing === undefined)
+            continue;
+        for (const id of outgoing) {
+            if (visited.has(id))
+                continue;
+            visited.add(id);
+            queue.push(id);
+        }
+    }
+    // Only resolved when something is actually wrong — the conformant board pays
+    // nothing for the frames it never names.
+    let backgrounds = null;
+    const violations = [];
+    for (const el of subjects) {
+        if (visited.has(el.id))
+            continue;
+        backgrounds ??= backgroundsOf(rule, elements);
+        const frameId = attributeBackground(el.elementBound, backgrounds)?.id;
+        violations.push(raise(rule, [el.id], frameId));
+    }
+    return violations;
+}
+/**
+ * Zero-width characters: present in the string, absent from the page.
+ *
+ * A name made of one of these is a name nobody can read, and a user who pasted
+ * one has an artefact that LOOKS unnamed and validates as named — the worst of
+ * both, and impossible to debug from the canvas. `trim()` does not remove them
+ * (they are not `WhiteSpace` in the spec), so they are stripped first.
+ *
+ * ESCAPED, never written as the characters themselves. A class holding the raw
+ * code points is invisible in every diff, review UI and editor — which makes it
+ * the one constant in this file that can be silently changed by a linter, a
+ * paste or a codemod that strips zero-width characters, with nothing on screen
+ * to show it happened. The escapes are: zero-width space, zero-width
+ * non-joiner, zero-width joiner, word joiner, and the byte-order mark.
+ */
+const INVISIBLE_CHARS = /[\u200B-\u200D\u2060\uFEFF]/g;
+/**
+ * Whether a non-string value knows how to render ITSELF as text, as opposed to
+ * inheriting `Object.prototype.toString` and answering `'[object Object]'`.
+ *
+ * The duck-typed test for "this is a text-bearing model": a `Y.Text` overrides
+ * `toString`, and so does every wrapper the canvas could plausibly store in that
+ * slot. A plain object does not, and neither does a number.
+ *
+ * An ARRAY is excluded even though it overrides `toString`, and that is the case
+ * worth spelling out: a raw delta list is the shape a text most plausibly
+ * degrades into, and `String([{ insert: 'x' }])` is `'[object Object]'` all over
+ * again. A list of runs is not a name; a model that can render one is.
+ */
+function rendersAsText(value) {
+    if (typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const own = value.toString;
+    return typeof own === 'function' && own !== Object.prototype.toString;
+}
+/**
+ * The words an element carries, or `''` — the EXTRACTION alone, with no opinion
+ * on whether having none is a mistake.
+ *
+ * Duck-typed on `text`, exactly like {@link elementPath} and
+ * {@link rawEndpointIds} are on their own properties, and for the same reason:
+ * the engine knows roles and geometry and must not import an element model. That
+ * one property is what a shape's `Y.Text`, a connector's label and a free text
+ * element all expose, and `String()` is what turns any of them into the content
+ * — the same conversion {@link textInkBound} has always relied on.
+ *
+ * NFC first, for the reason that function gives: the same name typed here and
+ * pasted from elsewhere can arrive as the same glyphs in a different number of
+ * code points. Then the invisibles, then the whitespace. What is left is what a
+ * reader would see.
+ *
+ * ## What is not a name
+ *
+ * A value that is neither a string nor something that knows how to render itself
+ * as one. `String({})` is `'[object Object]'` — eleven visible characters, which
+ * would make an artefact carrying a malformed `text` read as NAMED, and named
+ * with a word the user can neither see nor delete.
+ *
+ * `text` comes off a `Y.Map`, so it is whatever a peer or an importer wrote —
+ * the same threat model {@link elementExceptions} guards with its `Array.isArray`
+ * and {@link declaresRole} with its `Object.hasOwn`. The test is for an own
+ * `toString`, which a `Y.Text` has and a plain object does not: it accepts every
+ * shape the canvas actually stores without this file importing one of them.
+ */
+function elementLabel(el) {
+    const text = el.text;
+    if (text == null)
+        return '';
+    if (typeof text !== 'string' && !rendersAsText(text))
+        return '';
+    return String(text).normalize('NFC').replace(INVISIBLE_CHARS, '').trim();
+}
+/**
+ * "Does this artefact say what it is?"
+ *
+ * The first family that reads an element's WORDS. Every other one asks about
+ * geometry, roles or relations, all of which a reader can partly infer from the
+ * drawing; a box with nothing written in it is the one defect nothing recovers.
+ *
+ * ## What counts as absent
+ *
+ * No `text` at all, an empty one, one that is only whitespace, and one that is
+ * only invisible code points — see {@link elementLabel}. Anything a reader would
+ * see is a label, however short: judging the QUALITY of a name is not this
+ * family's business and probably nobody's.
+ *
+ * ## Silence
+ *
+ * The usual proportionality: an element with no role is not a subject, and a
+ * board carrying no subject raises nothing. There is no frame requirement —
+ * {@link ValidationRule.backgroundRole} buys attribution only, the `no-overlap`
+ * pattern, so a rule may name a frame to give its findings somewhere to be
+ * waived and need not.
+ *
+ * ## The moment, and why a framework should think about it
+ *
+ * Naming is the one property a user changes by TYPING, one character at a time.
+ * `text` is verdict-bearing only for a framework that registers a real-time rule
+ * of this family — {@link verdictPropsOf} adds it then and only then — so a rule
+ * declared `'on-demand'` costs the drawing path nothing at all, and a real-time
+ * one wakes the debounced evaluation on every keystroke in every shape on the
+ * board. Both are supported; the second is a choice a framework should make
+ * deliberately.
+ *
+ * ## Cost
+ *
+ * One pass, one `text` read per subject. Linear, and paid only by the elements
+ * carrying the subject role.
+ */
+function evaluateLabelPresence(rule, elements) {
+    const subjectRole = rule.appliesTo;
+    const label = rule.label;
+    if (subjectRole === undefined || label === undefined)
+        return [];
+    if (label.present !== true)
+        return [];
+    // Only resolved when something is actually wrong — a named board pays nothing
+    // for the frames it never has to name.
+    let backgrounds = null;
+    const violations = [];
+    for (const el of elements) {
+        // Cheapest possible exit for a neutral element: no role, no evaluation.
+        if (el.role === undefined)
+            continue;
+        if (!roleIsA(el.role, subjectRole, rule.roles))
+            continue;
+        if (elementLabel(el) !== '')
+            continue;
+        backgrounds ??= backgroundsOf(rule, elements);
+        const frameId = attributeBackground(el.elementBound, backgrounds)?.id;
+        violations.push(raise(rule, [el.id], frameId));
+    }
+    return violations;
+}
+const RULE_FAMILIES = {
+    'element-in-background': evaluateElementInBackground,
+    'orientation-against-axis': evaluateOrientationAgainstAxis,
+    attachment: evaluateAttachment,
+    'no-overlap': evaluateNoOverlap,
+    'tone-convention': evaluateToneConvention,
+    'majority-fact': evaluateMajorityFact,
+    'relative-order-along-axis': evaluateRelativeOrder,
+    'relation-endpoints': evaluateRelationEndpoints,
+    'element-in-zone': evaluateElementInZone,
+    'edge-degree': evaluateEdgeDegree,
+    'role-count': evaluateRoleCount,
+    'edge-locality': evaluateEdgeLocality,
+    reachability: evaluateReachability,
+    'label-presence': evaluateLabelPresence,
+    'view-admissibility': evaluateViewAdmissibility,
+};
+/** A rule the drawing path evaluates. `moment` absent means `'realtime'`. */
+function isRealtime(rule) {
+    return (rule.moment ?? 'realtime') === 'realtime';
+}
+/** The exceptions an element carries, always an array, never a copy to keep. */
+export function elementExceptions(element) {
+    const stored = element.validationExceptions;
+    // The value comes out of a Y.Map, so it is whatever a peer wrote: a client
+    // that got it wrong must not break evaluation on this one.
+    return Array.isArray(stored) ? stored : [];
+}
+/** Whether `element` is excused from `ruleId`. */
+export function hasException(element, ruleId) {
+    return elementExceptions(element).some(exception => exception?.ruleId === ruleId);
+}
+/**
+ * Stamp `exemption` on the findings a user exception already covers.
+ *
+ * Called only when a rule actually raised something, so a conformant board — the
+ * common case, and the one the 16 ms budget is measured on — pays nothing at
+ * all for the feature.
+ */
+function applyExceptions(rule, raised, elements) {
+    const byId = new Map();
+    for (const el of elements)
+        byId.set(el.id, el);
+    const excused = (id) => {
+        if (id === undefined)
+            return false;
+        const el = byId.get(id);
+        return el !== undefined && hasException(el, rule.id);
+    };
+    for (const violation of raised) {
+        // EVERY indicted element must be excused: a rule indicting two elements of
+        // which only one is excused is still a live finding.
+        const perElement = violation.elementIds.every(excused);
+        // Narrower scope first, so revoking walks from the local decision outward
+        // and each click visibly changes the state instead of doing nothing.
+        if (perElement)
+            violation.exemption = 'element';
+        // ...and the map scope reads THIS finding's own background, never "some
+        // background on the board carries the exception". An arbitration made on
+        // one map says nothing about the map next to it.
+        else if (excused(violation.backgroundId))
+            violation.exemption = 'map';
+        // Nothing covers it (any more). Stamped rather than left alone because an
+        // incremental pass CARRIES OVER finding objects from the last evaluation
+        // (see {@link IncrementalContext}), and one that kept a stale `exemption`
+        // would read as excused on a board where the exception has been revoked.
+        else
+            delete violation.exemption;
+    }
+}
+/**
+ * Run every rule over every element. Pure and synchronous — the unit of the
+ * 16 ms budget (PF5.12), and the only thing the bench measures.
+ *
+ * `profiles` is the level of requirement in force (PF9). Omitted, every rule is
+ * judged by its own declared severity, which is exactly what a framework
+ * shipping no profile gets.
+ *
+ * `incremental` is what the caller knows about what CHANGED. Omitted — the
+ * default, and what every test and the bench's full-evaluation case pass — the
+ * whole surface is re-judged from scratch. Handed in, the pair-wise family
+ * re-tests only the couples a change can have affected; the answer is the same,
+ * it is just reached without walking the grid against itself.
+ */
+export function evaluateRules(rules, elements, profiles = [], incremental) {
+    return runRules(rules, elements, profiles, 'realtime', incremental);
+}
+/**
+ * Run every rule of one MOMENT over every element. The body both
+ * {@link evaluateRules} and {@link evaluateCheckup} are made of — one pipeline,
+ * so a profile, an exception and a background attribution mean exactly the same
+ * thing whichever moment a rule is declared at.
+ *
+ * The moment is tested INSIDE the loop rather than by filtering the array: one
+ * property read per rule, no allocation, and the "an on-demand rule costs the
+ * drawing path nothing" claim is true of every evaluation and not just of the
+ * ones that bothered to filter.
+ */
+function runRules(rules, elements, profiles, moment, incremental) {
+    if (rules.length === 0)
+        return [];
+    // No profile registered => not a single extra read on the whole surface.
+    const index = profiles.length > 0 ? indexProfiles(profiles) : null;
+    const chosen = index ? readChosenProfiles(elements) : null;
+    const violations = [];
+    for (const rule of rules) {
+        // The other moment's rules are not this pass's business — checked FIRST,
+        // so an on-demand rule never reaches a profile lookup, let alone an
+        // element (PF5.14).
+        if ((isRealtime(rule) ? 'realtime' : 'on-demand') !== moment)
+            continue;
+        // `'off'` everywhere means never walked: the cheapest exit there is, taken
+        // before a single element is touched.
+        if (index && chosen && isRuleSilent(rule, chosen, index))
+            continue;
+        let raised = RULE_FAMILIES[rule.family](rule, elements, incremental);
+        if (index && chosen && raised.length > 0) {
+            raised = applyProfiles(rule, raised, chosen, index);
+        }
+        if (raised.length === 0)
+            continue;
+        // Exceptions are read LAST, and independently of the profile: an
+        // arbitration a user made is theirs, and changing the level of requirement
+        // never revokes one (PF9.3).
+        applyExceptions(rule, raised, elements);
+        violations.push(...raised);
+    }
+    return violations;
+}
+/** The registered rules a check-up runs — and nothing else ever evaluates. */
+export function onDemandRules(rules) {
+    return rules.filter(rule => !isRealtime(rule));
+}
+/**
+ * Run the ON-DEMAND rules over the surface (PF5.14). The exact mirror of
+ * {@link evaluateRules}, for the moment the drawing path never touches.
+ *
+ * Synchronous and total: this is what a test, a host and a report call. The
+ * manager drives the same pipeline one rule at a time so a long check-up can
+ * yield the thread — see {@link ValidationManager.runCheckup} — and both reach
+ * the same answer, because both are {@link runRules}.
+ *
+ * The findings are ordinary {@link Violation} objects and go through the same
+ * profile and exception passes as any other. What makes them REMARKS rather
+ * than verdicts is where they land: they never reach `violations$`, so they
+ * never reach the timeline, the bracket or the badge. A framework declares them
+ * `audit` on top of that, which is the severity for "collected, invisible to the
+ * drawing user" — belt and braces, and the braces are structural.
+ */
+export function evaluateCheckup(rules, elements, profiles = []) {
+    return runRules(rules, elements, profiles, 'on-demand');
+}
+/**
+ * How long a check-up may hold the thread before yielding it back.
+ *
+ * One frame, so a check-up that turns out to be expensive costs a dropped frame
+ * at worst instead of a locked tab. A rule is the unit of interruption — the
+ * smallest slice that has a meaning — so a single rule slower than this still
+ * runs to completion and the next one waits for the following task.
+ *
+ * The rules shipped today cost well under a millisecond between them, so the
+ * yield never fires in the delivered configuration — which would leave the
+ * generation counter and the supersession path as code nothing reaches. It is
+ * therefore a DEFAULT rather than a constant: {@link ValidationManager.checkupSliceMs}
+ * is settable, and lowering it makes every rule a slice, which is how a test
+ * exercises the yield and the race with the real rules instead of a stub.
+ */
+export const CHECKUP_SLICE_MS = 16;
+/**
+ * Grant `ruleId` an exception on `element`, unless it already has one.
+ *
+ * The write goes through the declared `@field()` accessor, so it lands in the
+ * Y.Map, syncs to every peer, joins the undo stack and survives a copy — see the
+ * note on `GfxPrimitiveElementModel.validationExceptions`.
+ */
+export function grantException(element, ruleId, author, now = Date.now()) {
+    if (hasException(element, ruleId))
+        return;
+    element.validationExceptions = [
+        ...elementExceptions(element),
+        // The timestamp is taken at the moment of the gesture, and an absent author
+        // stays ABSENT rather than becoming an empty string.
+        { ruleId, at: now, ...(author !== undefined ? { author } : {}) },
+    ];
+}
+/** Remove `ruleId`'s exception from `element`, if it has one. */
+export function revokeException(element, ruleId) {
+    const current = elementExceptions(element);
+    const next = current.filter(exception => exception?.ruleId !== ruleId);
+    if (next.length === current.length)
+        return;
+    if (next.length > 0) {
+        element.validationExceptions = next;
+        return;
+    }
+    // The last one goes, so the KEY goes. Assigning `undefined` through the
+    // accessor would leave the key in the Y.Map holding an undefined value —
+    // invisible through the getter, but synced to every peer and shipped in every
+    // snapshot. `clearField` removes it, so an element whose exceptions were all
+    // revoked really is indistinguishable from one that never had any, in the
+    // document and not just in this tab.
+    element.clearField('validationExceptions');
+}
+/**
+ * The exceptions `element` ANSWERS FOR, i.e. the ones a menu on it should be
+ * able to revoke.
+ *
+ * Same rule the canvas mark follows ({@link anchorOf}): an exception is
+ * answered for by the outermost canvas group containing the element that
+ * carries it, or by that element when it is not grouped. So the entry lives on
+ * the whole Wardley component rather than on the bare node inside it, moves
+ * down to the element the moment the group is dissolved, and appears on a
+ * framework background for the map-wide arbitration it carries.
+ *
+ * Reads STORED exceptions, not current violations: an exception outlives the
+ * violation that prompted it (move the component back onto the map and the
+ * finding goes, the arbitration stays), and it is the arbitration the user is
+ * asking to take back.
+ */
+export function exceptionsAnchoredOn(element, surface) {
+    const candidates = [element];
+    if (element instanceof GfxGroupLikeElementModel) {
+        for (const descendant of element.descendantElements) {
+            if (descendant instanceof GfxPrimitiveElementModel) {
+                candidates.push(descendant);
+            }
+        }
+    }
+    const anchored = [];
+    for (const candidate of candidates) {
+        const exceptions = elementExceptions(candidate);
+        if (exceptions.length === 0)
+            continue;
+        // Anything whose anchor is somebody else belongs to somebody else's menu —
+        // that is what keeps the entry on the outermost group and off its members.
+        if (anchorOf(candidate.id, surface)?.id !== element.id)
+            continue;
+        for (const exception of exceptions) {
+            if (exception?.ruleId) {
+                anchored.push({ element: candidate, ruleId: exception.ruleId });
+            }
+        }
+    }
+    return anchored;
+}
+/** A framework registers its rules here; nothing else registers rules. */
+export const ValidationRuleIdentifier = createIdentifier('ValidationRule');
+/**
+ * Register a framework's rules. Call it from the FLAG-GATED view extension —
+ * validation is tooling, so a disabled framework must contribute nothing.
+ *
+ * ```ts
+ * context.register(ValidationRuleExtension(WARDLEY_RULES));
+ * ```
+ */
+export function ValidationRuleExtension(rules) {
+    return {
+        setup: di => {
+            for (const rule of rules) {
+                di.addImpl(ValidationRuleIdentifier(rule.id), () => rule);
+            }
+        },
+    };
+}
+/** A framework registers its profiles here; nothing else registers profiles. */
+export const ValidationProfileIdentifier = createIdentifier('ValidationProfile');
+/**
+ * Register a framework's profiles. Call it from the FLAG-GATED view extension,
+ * beside {@link ValidationRuleExtension}: a level of requirement is tooling, so
+ * a disabled framework offers none — and the id already written on a background
+ * simply goes unread until the flag comes back.
+ *
+ * ```ts
+ * context.register(ValidationProfileExtension(WARDLEY_PROFILES));
+ * ```
+ */
+export function ValidationProfileExtension(profiles) {
+    return {
+        setup: di => {
+            for (const profile of profiles) {
+                di.addImpl(ValidationProfileIdentifier(profile.id), () => profile);
+            }
+        },
+    };
+}
+/** A framework declares its root instances here, when no rule already does. */
+export const ValidationFrameworkIdentifier = createIdentifier('ValidationFramework');
+/**
+ * Register a framework's root-instance declaration.
+ *
+ * ```ts
+ * context.register(
+ *   ValidationFrameworkExtension([
+ *     { framework: 'estuarine', backgroundRole: 'estuarine:map', roles: ESTUARINE_ROLES },
+ *   ])
+ * );
+ * ```
+ *
+ * Keyed by framework AND role, so a framework with two kinds of board declares
+ * both and neither silently replaces the other.
+ */
+export function ValidationFrameworkExtension(defs) {
+    return {
+        setup: di => {
+            for (const def of defs) {
+                di.addImpl(ValidationFrameworkIdentifier(`${def.framework}|${def.backgroundRole}`), () => def);
+            }
+        },
+    };
+}
+/** Shared answer for "this element is nobody's frame", allocated once. */
+const EMPTY_FRAMEWORKS = new Set();
+/**
+ * The frameworks `role` is a ROOT INSTANCE of — the one test that decides
+ * whether an element is somebody's frame, and the only one.
+ *
+ * TWO sources, and they answer the same question:
+ *
+ * - a registered RULE naming this role as the background it measures against.
+ *   A rule that frames against a role is a framework saying "this is my map",
+ *   with no second registry to keep in step;
+ * - a registered {@link ValidationFrameworkDef}, for the framework whose whole
+ *   contribution is nudges and which therefore has no rule to be derived from.
+ *
+ * Pure, and exported, because every per-instance surface downstream — the
+ * profile picker, the nudge checklist, the check-up — is built on this answer,
+ * and a function taking its inputs is testable without a DI container, a
+ * surface or an editor.
+ *
+ * Empty for a neutral element, and for a background authored before its role
+ * existed: no role, no framework, no tooling.
+ */
+export function frameworksOfRole(role, rules, frameworkDefs = []) {
+    if (role === undefined)
+        return EMPTY_FRAMEWORKS;
+    const frameworks = new Set();
+    for (const rule of rules) {
+        if (rule.backgroundRole === undefined)
+            continue;
+        if (roleIsA(role, rule.backgroundRole, rule.roles)) {
+            frameworks.add(rule.framework);
+        }
+    }
+    for (const def of frameworkDefs) {
+        if (roleIsA(role, def.backgroundRole, def.roles)) {
+            frameworks.add(def.framework);
+        }
+    }
+    // One shared answer for "this element is nobody's frame": the common case by
+    // far, on every element of every board that carries no framework.
+    return frameworks.size === 0 ? EMPTY_FRAMEWORKS : frameworks;
+}
+/** Recompute delay, so a drag re-evaluates once instead of once per frame. */
+const VALIDATION_DELAY_MS = 120;
+/**
+ * Element props that can change a verdict, WHATEVER the registered rules are.
+ * Everything else — `opacity` and the other `@local()` fields, colours,
+ * labels — is ignored, so brushing a canvas (`SpotlightManager` writes
+ * `opacity` on every element it dims) neither re-evaluates the surface nor
+ * pushes the pending evaluation further away.
+ *
+ * A framework can add to this list without the engine learning its name: see
+ * {@link verdictPropsOf}.
+ */
+export const VERDICT_PROPS = [
+    'xywh',
+    'rotate',
+    'role',
+    // The two ends of a typed edge ARE the relation's orientation since
+    // `docs/adr/0010`, so re-pointing one — or reversing the edge, which writes
+    // both — changes a verdict exactly as much as moving a node does. Without
+    // these, an inversion would leave the finding on screen until the next
+    // unrelated drag woke the engine.
+    'source',
+    'target',
+    // A user exception changes a verdict as much as a move does: without this,
+    // granting one on a peer's tab would leave the mark up until the next drag.
+    'validationExceptions',
+    // Changing the level of requirement re-judges everything measured against
+    // this background (PF9). Written on a background, read for every finding
+    // attributed to it — and, like an exception, it can be DELETED (choosing the
+    // default back removes the key), which is why `touchesVerdict` reads
+    // `oldValues` too.
+    'validationProfile',
+];
+/**
+ * {@link VERDICT_PROPS} plus what the REGISTERED rules make verdict-bearing.
+ *
+ * A framework background can carry visibility toggles, and one of them may be
+ * the toggle that shows the frontiers a rule measures against — hide the
+ * dashed columns of a Wardley map and the findings about them stop being
+ * findings ({@link backgroundTransitionBands}). Without this the toggle would be
+ * as inert as a colour: the marks would stay on screen until some unrelated
+ * drag happened to wake the engine, which is a board that lies about a document
+ * that has already changed.
+ *
+ * Derived from the DECLARATIONS the engine was handed, never from a name it
+ * knows: `backgroundTransitionVisibleProps` reads the prop each framework
+ * writes beside the line it gates. A framework whose background declares no
+ * toggle contributes nothing and the set is the constant.
+ *
+ * ## `text`, and why it is not in the constant
+ *
+ * `label-presence` is the one family whose verdict turns on an element's words,
+ * and words are what a user changes by TYPING. Watched unconditionally, every
+ * keystroke in every shape on the board would wake the debounced evaluation —
+ * a cost paid by every document, for a question most of them never ask.
+ *
+ * So it is added exactly when a REAL-TIME rule of that family is registered.
+ * The moment filter is deliberate and mirrors {@link backgroundElementIds}: an
+ * on-demand rule is never evaluated on the gesture path, so waking that path for
+ * it would hand back precisely what declaring the second moment bought — and a
+ * framework that wants its naming checked while the user types says so by
+ * declaring the rule real-time, which is the one place that decision belongs.
+ */
+export function verdictPropsOf(rules) {
+    const props = new Set(VERDICT_PROPS);
+    for (const rule of rules) {
+        if (rule.family === 'label-presence' && isRealtime(rule))
+            props.add('text');
+        // The level a VIEW declares decides which roles it admits, so changing it —
+        // or clearing it back to "free sketch", which DELETES the key, which is why
+        // `touchesVerdict` reads `oldValues` too — re-judges everything drawn on
+        // that frame. Derived from the rule's own declaration and never from a name
+        // the engine knows, exactly like the transition toggles below.
+        if (rule.admissibility !== undefined) {
+            props.add(rule.admissibility.levelProp);
+        }
+        if (rule.background === undefined)
+            continue;
+        for (const prop of backgroundTransitionVisibleProps(rule.background)) {
+            props.add(prop);
+        }
+    }
+    return props;
+}
+/**
+ * Whether an `elementUpdated` payload can have changed a verdict.
+ *
+ * It has to read `oldValues` as well as `props`, because a Y.Map **delete**
+ * fills only the former (`syncElementFromY` puts a key in `props` for `add` and
+ * `update` only). `validationExceptions` is the first {@link VERDICT_PROPS}
+ * entry whose normal life includes being removed — `xywh` and `rotate` are
+ * never deleted, `role` is only ever added — so this branch had never been
+ * exercised. Reading `props` alone means an UNDO of an exception, which deletes
+ * the key, wakes nothing: the board keeps showing a finding as excused when the
+ * document no longer says so, and its Revoke button becomes a no-op.
+ *
+ * A payload carrying neither is unreadable, so it counts as "might have": the
+ * cost of a spurious re-evaluation is a debounce tick, the cost of a missed one
+ * is a board that lies.
+ */
+export function touchesVerdict(payload, watched = VERDICT_PROPS) {
+    const { props, oldValues } = payload;
+    if (!props && !oldValues)
+        return true;
+    for (const prop of watched) {
+        if (props !== undefined && prop in props)
+            return true;
+        if (oldValues !== undefined && prop in oldValues)
+            return true;
+    }
+    return false;
+}
+/**
+ * Owns the evaluation and the reactive violation list. No-op until a framework
+ * registers a rule.
+ */
+export class ValidationManager extends InteractivityExtension {
+    constructor() {
+        super(...arguments);
+        /**
+         * Current violations. The reactive seam a host panel (wave 2) subscribes to;
+         * wave 1 ships only the canvas affordance.
+         */
+        this.violations$ = signal([]);
+        /**
+         * Level 3 — what an AI audit reported, and ONLY that (PF14.1).
+         *
+         * A second signal rather than a marked subset of {@link violations$}, and the
+         * reason is the invariant the whole audit seam exists to protect: **the
+         * deterministic engine never depends on the AI**. Nothing in `evaluate()`
+         * reads this signal, writes it or is slowed by it; nothing here is ever
+         * recomputed, carried over by an incremental pass, or judged by a profile.
+         * The 16 ms budget is measured on a function that cannot see this field.
+         *
+         * Merging the two lists and discriminating by severity would have been
+         * cheaper to type and much more expensive to reason about: every consumer of
+         * `violations$` — the overlay, the timeline, the bubble, the exception
+         * toolbar, `userFacingViolations`, the incremental carry-over — would have
+         * had to learn to skip entries it must never touch, and forgetting one of
+         * them in some future slice would put a model's opinion behind a canvas
+         * bracket. Two signals make that a type error instead of a review.
+         *
+         * The findings ARE violation objects (`AuditFinding` is assignable to
+         * {@link Violation}, pinned by a test), so a host panel renders them with the
+         * code it already has. They are session state, never persisted: an audit is
+         * an opinion at a moment, and the document says what it contains, not what a
+         * model thought of it on Tuesday.
+         */
+        this.auditFindings$ = signal([]);
+        /**
+         * Which violations are still FRESH, i.e. still owed the loud bracket.
+         *
+         * It lives here rather than inside the overlay because the affordance has two
+         * halves on two different technologies — a canvas bracket that fades, and a
+         * DOM badge that takes over — and they are mutually exclusive: the badge
+         * appears only once the bracket is fully gone. Two copies of "when did I
+         * first see this" would drift, and the handover would show both at once or
+         * neither.
+         *
+         * Session state, never persisted: a document says which rules it breaks, not
+         * when you happened to look at them.
+         */
+        this.timeline = new ViolationTimeline();
+        /**
+         * The last check-up (PF5.14), or `null` while none has been asked for.
+         *
+         * A SEPARATE signal from {@link violations$}, and that separation is the whole
+         * design: a remark never reaches the timeline, the bracket or the badge,
+         * because it never reaches the list those three read. "Outside the canvas
+         * affordance" is therefore a property of the wiring, not a filter somebody has
+         * to remember to apply.
+         *
+         * Reset to `null` on unmount and never persisted: a document says what it
+         * contains, not when somebody last checked it.
+         */
+        this.checkup$ = signal(null);
+        /**
+         * The element whose Map quality panel is OPEN, or `null` — the seam between
+         * the toolbar entry that asks for it (`validation-toolbar.ts`, PF7.11) and the
+         * widget that draws it.
+         *
+         * A signal rather than a DOM call because the two live in different trees: the
+         * entry is a lit template inside `editor-menu-button`'s shadow root, and the
+         * panel is a widget on the root block. Session state, like every other "what
+         * is open" in this file.
+         */
+        this.mapQualityFor$ = signal(null);
+        this._pending = null;
+        /**
+         * Bumped by every {@link runCheckup}, so a run that yielded the thread can
+         * tell it has been superseded and drop its partial results on the floor
+         * instead of overwriting a newer answer.
+         */
+        this._checkupGeneration = 0;
+        /**
+         * How long {@link runCheckup} may hold the thread between two rules.
+         *
+         * Settable rather than fixed so the interruption and the supersession are
+         * TESTABLE with the rules a framework actually ships: at the shipped default
+         * the Wardley check-up costs half a millisecond and never yields, which would
+         * leave the whole race path unreached by anything. Dropped to zero, every rule
+         * becomes a slice.
+         */
+        this.checkupSliceMs = CHECKUP_SLICE_MS;
+        /**
+         * Element ids added, removed or updated since the last verdict — the dirty
+         * set of PF5.13. Filled by the subscriptions, drained by every evaluation.
+         */
+        this._dirty = new Set();
+        /** Whether {@link violations$} holds a verdict a dirty set can build on. */
+        this._evaluated = false;
+        /**
+         * The ids that were framework BACKGROUNDS at the last evaluation.
+         *
+         * `no-overlap` already sends the surface back through a full sweep when a
+         * frame is touched, and it finds a DELETED one by looking for its id in the
+         * previous findings — the only trace a departed element leaves. That trace
+         * does not exist when the frame's profile put the rule on `'off'`: the
+         * findings measured against it were dropped by `applyProfiles`, so `previous`
+         * is empty, the deletion looks like an ordinary one, and the overlap that
+         * comes back to life under the default profile is never reported. No family
+         * can close that hole — an element that is gone from the surface AND absent
+         * from the findings is invisible to everything except a memory of it.
+         *
+         * So the manager keeps that memory. A dirty id that used to be a background
+         * forces the full pass, whatever the previous findings say or fail to say —
+         * which makes `incremental === full` true by construction rather than by the
+         * luck of no shipped profile using `'off'` yet.
+         */
+        this._backgrounds = new Set();
+        this._rules = null;
+        this._verdictProps = null;
+        this._nudges = null;
+        this._frameworks = null;
+        this._profiles = null;
+        this._subscriptions = [];
+        this._disposeSurfaceEffect = null;
+    }
+    static { this.key = 'validation-manager'; }
+    /**
+     * Publish an audit's results. The ONLY writer of {@link auditFindings$}, and
+     * deliberately dumb: it stores, it does not evaluate, re-judge or merge.
+     *
+     * Replaces rather than appends — a run's findings are a whole answer about
+     * the board as it was, so accumulating two runs would show a user a
+     * contradiction and call it a list.
+     */
+    setAuditFindings(findings) {
+        this.auditFindings$.value = findings;
+    }
+    /** Registered rules, resolved once. Empty when every framework is flagged off. */
+    get _activeRules() {
+        this._rules ??= Array.from(this.std.provider.getAll(ValidationRuleIdentifier).values());
+        return this._rules;
+    }
+    /**
+     * The props worth re-evaluating for, given what is registered. Resolved once,
+     * beside the rules it is derived from — see {@link verdictPropsOf}.
+     */
+    get _watchedProps() {
+        this._verdictProps ??= verdictPropsOf(this._activeRules);
+        return this._verdictProps;
+    }
+    /**
+     * Registered nudges, resolved once. Empty when no framework ships one, or
+     * when every framework is flagged off.
+     */
+    get _activeNudges() {
+        this._nudges ??= Array.from(this.std.provider.getAll(QualityNudgeIdentifier).values());
+        return this._nudges;
+    }
+    /**
+     * Registered root-instance declarations, resolved once. Empty when every
+     * framework derives its frames from its rules, which is all of them but the
+     * ones that ship no rule at all — see {@link ValidationFrameworkDef}.
+     */
+    get _activeFrameworks() {
+        this._frameworks ??= Array.from(this.std.provider.getAll(ValidationFrameworkIdentifier).values());
+        return this._frameworks;
+    }
+    /**
+     * Registered profiles, resolved once. Empty when no framework ships one, in
+     * which case every rule is judged by its own declared severity.
+     */
+    get _activeProfiles() {
+        this._profiles ??= Array.from(this.std.provider.getAll(ValidationProfileIdentifier).values());
+        return this._profiles;
+    }
+    get _overlay() {
+        return this.std.getOptional(OverlayIdentifier(ValidationOverlay.overlayName));
+    }
+    mounted() {
+        // No rule registered => never subscribe, never evaluate. The cost of
+        // validation on a board where nothing can be evaluated is this single
+        // length check, once.
+        //
+        // Deliberately about the RULES alone, and not about the root-instance
+        // declarations that also feed `frameworksOf`: what the subscriptions drive
+        // is the evaluation, and a framework that registers no rule has nothing to
+        // evaluate however many frames it declares. Its tooling reaches the user
+        // through getters nobody subscribes to — `nudgesFor` for the Map quality
+        // popup, `profilesFor` for the toolbar dropdown — which are called on the
+        // element in hand at the moment of the gesture, and answer the same thing
+        // whether or not this method ever ran.
+        if (this._activeRules.length === 0)
+            return;
+        // The surface is a SIGNAL, not a fact: it can legitimately be null at
+        // mount and arrive later, and it is replaced if the surface block is. A
+        // one-shot peek here would leave validation silently dead for the whole
+        // session — hence tracking it rather than reading it once.
+        this._disposeSurfaceEffect = effect(() => {
+            this._resubscribe(this.gfx.surface$.value);
+        });
+    }
+    unmounted() {
+        if (this._pending)
+            clearTimeout(this._pending);
+        this._pending = null;
+        this._disposeSurfaceEffect?.();
+        this._disposeSurfaceEffect = null;
+        this._unsubscribe();
+        this._dirty.clear();
+        this._evaluated = false;
+        this._backgrounds = new Set();
+        this.timeline.clear();
+        // Supersede any check-up still yielding between two rules, and forget the
+        // last one: both are session state, and a stale answer outliving the
+        // surface it was measured on is a panel that lies.
+        this._checkupGeneration += 1;
+        this.checkup$.value = null;
+        this.mapQualityFor$.value = null;
+        // Session state, and the session is over. An audit describes a board at a
+        // moment; carrying one across a remount would show it against a different
+        // surface (PF14.1).
+        this.auditFindings$.value = [];
+        super.unmounted();
+    }
+    _unsubscribe() {
+        for (const subscription of this._subscriptions)
+            subscription.unsubscribe();
+        this._subscriptions = [];
+    }
+    _resubscribe(surface) {
+        this._unsubscribe();
+        if (!surface)
+            return;
+        this._subscriptions.push(surface.elementAdded.subscribe(({ id }) => this._schedule(id)));
+        this._subscriptions.push(surface.elementRemoved.subscribe(({ id }) => {
+            // A check-up measured on a map that no longer exists is an answer about
+            // nothing. The panel is closed by then (the widget watches the same
+            // signal), but the result would otherwise sit in memory waiting to be
+            // shown against whatever the user opens next.
+            this._forgetCheckupOf(id);
+            this._schedule(id);
+        }));
+        this._subscriptions.push(surface.elementUpdated.subscribe(payload => {
+            // A prop that cannot change a verdict must not even rearm the timer.
+            if (!touchesVerdict(payload, this._watchedProps))
+                return;
+            this._schedule(payload.id);
+        }));
+        // A new surface knows nothing about the last one: judge it in full.
+        this.evaluate();
+    }
+    _schedule(id) {
+        this._dirty.add(id);
+        if (this._pending)
+            clearTimeout(this._pending);
+        this._pending = setTimeout(() => {
+            this._pending = null;
+            this.evaluate(true);
+        }, VALIDATION_DELAY_MS);
+    }
+    /**
+     * Evaluate now. Exposed so a host (and the bench) can drive it directly.
+     *
+     * `incremental` is the DEBOUNCED path's privilege and nobody else's: it is
+     * the only caller that knows exactly which elements moved since the last
+     * verdict. Everything else — a gesture that must land on the spot, a surface
+     * arriving, a host asking — pays for a full pass, because a full pass is
+     * always right and a wrong dirty set is a board that lies.
+     */
+    evaluate(incremental = false) {
+        const rules = this._activeRules;
+        const surface = this.gfx.surface;
+        // Whatever happens below, what accumulated is now accounted for: a dirty
+        // set left behind would be replayed against a later, unrelated snapshot.
+        const dirty = this._dirty;
+        this._dirty = new Set();
+        if (rules.length === 0 || !surface)
+            return;
+        const previous = this.violations$.peek();
+        // A frame that WAS there and is now dirty invalidates attributions no
+        // pair-wise re-test would reach — including, when its profile silenced the
+        // rule, findings that were never recorded for the family to find.
+        const frameTouched = [...dirty].some(id => this._backgrounds.has(id));
+        const violations = evaluateRules(rules, surface.elementModels, this._activeProfiles, incremental && this._evaluated && dirty.size > 0 && !frameTouched
+            ? { dirty, previous }
+            : undefined);
+        this._evaluated = true;
+        this._backgrounds = backgroundElementIds(rules, surface.elementModels);
+        // Stay silent when nothing changed: `violations$` is the seam a host panel
+        // subscribes to, and a clean board must not wake it on every debounce tick.
+        if (violations.length === 0 && this.violations$.peek().length === 0)
+            return;
+        // Age the marks BEFORE waking anybody, so the canvas half and the DOM half
+        // read the same clock within one evaluation and never disagree about which
+        // of the two markers is due.
+        //
+        // Exempted findings are dropped HERE and only here: `violations$` keeps
+        // them, so the bubble and a host panel see the full picture, while the
+        // flash and the bracket see only what is still asking for something.
+        const shown = liveViolations(userFacingViolations(violations));
+        this.timeline.sync(shown, performance.now());
+        this.violations$.value = violations;
+        this._overlay?.setViolations(shown, this.timeline);
+    }
+    /** The registered rule with this id, if its framework is enabled. */
+    ruleOf(ruleId) {
+        return this._activeRules.find(rule => rule.id === ruleId);
+    }
+    /**
+     * The profiles selectable on `element`, i.e. those of every framework it is a
+     * ROOT INSTANCE of ({@link frameworksOf}).
+     *
+     * Gated for free: flag off, nothing registered, no framework, no profile
+     * offered. A framework that ships profiles and is a root instance of nothing —
+     * neither a rule framing against the role nor a declaration naming it —
+     * offers nothing to choose between, correctly.
+     *
+     * Empty for a neutral element, and for a background authored before its role
+     * existed: no role, no framework, no profile.
+     */
+    profilesFor(element) {
+        const frameworks = this.frameworksOf(element);
+        if (frameworks.size === 0)
+            return [];
+        return this._activeProfiles.filter(profile => frameworks.has(profile.framework));
+    }
+    /**
+     * The frameworks `element` is a ROOT INSTANCE of — those with a registered
+     * rule measuring against a background carrying this element's role, and those
+     * that declared the role outright ({@link ValidationFrameworkDef}).
+     *
+     * The one test that decides whether an element is a framework's frame, and the
+     * only one: every per-instance surface (the profile picker, the nudge
+     * checklist, the check-up) agrees about what a root instance is without any of
+     * them saying so twice. Both sources are registered from the flag-gated view
+     * extension, so it stays gated for free — flag off, nothing registered, no
+     * framework.
+     *
+     * Empty for a neutral element, and for a background authored before its role
+     * existed.
+     */
+    frameworksOf(element) {
+        return frameworksOfRole(element.role, this._activeRules, this._activeFrameworks);
+    }
+    /**
+     * The nudges offered on `element` (PF7.10), in declared order.
+     *
+     * Same derivation as {@link profilesFor} and gated the same way: a framework
+     * that registers no nudge — or whose flag is off — offers none, and the ids
+     * already ticked on the element stay written, unread, until it comes back.
+     */
+    nudgesFor(element) {
+        const frameworks = this.frameworksOf(element);
+        if (frameworks.size === 0)
+            return [];
+        return this._activeNudges
+            .filter(nudge => frameworks.has(nudge.framework))
+            .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+    }
+    /** The on-demand rules a check-up on `element` would walk (PF5.14). */
+    checkupRulesFor(element) {
+        const frameworks = this.frameworksOf(element);
+        if (frameworks.size === 0)
+            return [];
+        return onDemandRules(this._activeRules).filter(rule => frameworks.has(rule.framework));
+    }
+    /**
+     * Whether `element` has a Map quality panel to open at all: a framework of
+     * its own declaring a NUDGE.
+     *
+     * The panel is the checklist and nothing else since the PO recette of
+     * 02/08/2026, so this asks for the checklist and nothing else — a framework
+     * that declared only on-demand rules would otherwise be offered a panel with
+     * nothing in it. {@link checkupRulesFor} and {@link runCheckup} are unchanged
+     * and unrelated: a host can still ask for a check-up, it simply is not what
+     * this panel is.
+     *
+     * Generic by construction (PF7.11) — nothing here names a framework. A second
+     * framework shipping nudges gets the entry and the panel with no code written
+     * anywhere.
+     */
+    hasMapQuality(element) {
+        return this.nudgesFor(element).length > 0;
+    }
+    /**
+     * Open the Map quality panel on `element`; the widget draws it.
+     *
+     * Opening on a DIFFERENT instance forgets the last check-up. The panel already
+     * refuses to render a run belonging to another map ({@link CheckupRun.backgroundId}),
+     * so this is not what makes the display correct — it is what stops a result
+     * measured on a map the user has moved on from (or deleted) sitting in memory
+     * waiting to be shown again. Reopening on the SAME map keeps its stamp, which
+     * is the one case where "last check-up: 01:51" is worth reading.
+     */
+    openMapQuality(element) {
+        this._forgetCheckupOf(element.id, true);
+        this.mapQualityFor$.value = element.id;
+    }
+    closeMapQuality() {
+        this.mapQualityFor$.value = null;
+    }
+    /**
+     * Drop the current check-up when it is about `backgroundId` — or, with
+     * `unless`, when it is about anything else.
+     *
+     * The two callers are the two ways a run stops being about something the user
+     * can look at: the instance it measured was deleted, and the panel moved to a
+     * different instance.
+     */
+    _forgetCheckupOf(backgroundId, unless = false) {
+        const run = this.checkup$.peek();
+        if (run === null)
+            return;
+        if ((run.backgroundId === backgroundId) !== unless) {
+            this.checkup$.value = null;
+        }
+    }
+    /**
+     * Run the check-up on `element` (PF5.14).
+     *
+     * ## It is about ONE instance
+     *
+     * The walk covers the whole surface — that is where the elements are — but the
+     * ANSWER is narrowed to the map that was asked about, on
+     * {@link Violation.backgroundId}, which every family measuring against a frame
+     * already records. A board carrying two Wardley maps holds two independent
+     * answers, and handing the panel a tally over both would be exactly the
+     * whole-surface count {@link evaluateMajorityFact} goes out of its way not to
+     * compute. Narrowed HERE and not at the rendering: a run that reaches a host,
+     * a report or the agent has to already be about one map.
+     *
+     * ## Why this is async, for two rules that take a microsecond
+     *
+     * Because the moment exists precisely so that a framework may ship a control
+     * that does NOT fit a frame. A check-up walks the surface with no dirty set
+     * and no budget over its head, and the honest way to offer that is to be
+     * interruptible: the driver evaluates ONE RULE at a time — the smallest slice
+     * that has a meaning — and yields the thread whenever the slice has held it
+     * for {@link checkupSliceMs}. The panel sees `done` climb towards `total`, so
+     * progress is the same value the results arrive in and there is no second
+     * signal to keep in step.
+     *
+     * A run started while another is still yielding SUPERSEDES it: the older one
+     * notices its generation is stale on its next slice and drops what it had.
+     * Clicking twice therefore gives the second answer, never a race between two.
+     *
+     * ## A rule that throws
+     *
+     * ...ends the run, visibly. The failure must not leave the panel believing a
+     * check-up is in flight — that reads as "Checking…" for ever and disables the
+     * one button that could try again, on every map, until the editor is
+     * remounted. So the run is finished with {@link CheckupRun.error} and whatever
+     * it had managed to collect.
+     *
+     * @returns the finished run, or `null` if it was superseded or there was
+     * nothing to run.
+     */
+    async runCheckup(element) {
+        const rules = this.checkupRulesFor(element);
+        const generation = ++this._checkupGeneration;
+        const backgroundId = element.id;
+        if (rules.length === 0) {
+            this.checkup$.value = null;
+            return null;
+        }
+        const at = Date.now();
+        const results = [];
+        const total = rules.length;
+        let sliceStart = performance.now();
+        this.checkup$.value = { backgroundId, at, results: [], done: 0, total };
+        for (let i = 0; i < total; i++) {
+            // The surface is re-read on every slice: the user can keep drawing while
+            // this runs, and a rule must be judged against the board as it is now,
+            // not against a snapshot taken before the last yield.
+            const surface = this.gfx.surface;
+            if (!surface || generation !== this._checkupGeneration)
+                return null;
+            try {
+                for (const remark of evaluateCheckup([rules[i]], surface.elementModels, this._activeProfiles)) {
+                    // This map's remarks, and only this map's. A family that measures
+                    // against no frame records no `backgroundId` and is dropped: it has
+                    // said nothing about the instance the user is looking at.
+                    if (remark.backgroundId === backgroundId)
+                        results.push(remark);
+                }
+            }
+            catch (error) {
+                console.error(`[validation] check-up rule "${rules[i].id}" threw`, error);
+                const failed = {
+                    backgroundId,
+                    at,
+                    results: [...results],
+                    // Finished, deliberately: see the note above. A locked button is a
+                    // worse failure than a reported one.
+                    done: total,
+                    total,
+                    error: true,
+                };
+                this.checkup$.value = failed;
+                return failed;
+            }
+            this.checkup$.value = {
+                backgroundId,
+                at,
+                results: [...results],
+                done: i + 1,
+                total,
+            };
+            if (i + 1 < total &&
+                performance.now() - sliceStart > this.checkupSliceMs) {
+                // Back of the queue, so paint and input go first. `setTimeout(0)` and
+                // not a microtask: a microtask would yield the call stack and nothing
+                // else, which is exactly the freeze this exists to avoid.
+                await new Promise(resolve => setTimeout(resolve, 0));
+                sliceStart = performance.now();
+            }
+        }
+        return generation === this._checkupGeneration ? this.checkup$.peek() : null;
+    }
+    /**
+     * The profile `element` is actually checked against — the one it names, or
+     * its framework's default. `undefined` when it is not a root instance of any
+     * enabled framework, or when its framework ships no profile.
+     */
+    profileOf(element) {
+        const available = this.profilesFor(element);
+        const named = available.find(profile => profile.id === element.validationProfile);
+        if (named)
+            return named;
+        const framework = available[0]?.framework;
+        return framework === undefined
+            ? undefined
+            : defaultProfileOf(available, framework);
+    }
+    /**
+     * Put `element` on `profileId`, and re-judge the board on the spot.
+     *
+     * Choosing the DEFAULT clears the key rather than writing it, so a background
+     * that never left the default stays byte-identical to one created before
+     * profiles existed — and a user who tries strict and comes back leaves no
+     * trace. Everything else is one flat string in the same `@field()` the role
+     * and the exceptions live in: it syncs, it undoes, it survives a copy and an
+     * export, with no block schema change.
+     *
+     * Exceptions are deliberately left alone. A level of requirement is not an
+     * amnesty: raising it must not resurrect decisions the user made, and
+     * lowering it must not quietly delete them (PF9.3).
+     *
+     * @returns whether the document actually changed.
+     */
+    setProfile(element, profileId) {
+        // The write below goes through a `@field()` accessor, i.e. `store.transact`,
+        // which has no readonly guard of its own. A readonly board arbitrates
+        // nothing — and `false` keeps the caller's telemetry silent too.
+        if (this.std.store.readonly)
+            return false;
+        const available = this.profilesFor(element);
+        const target = available.find(profile => profile.id === profileId);
+        // Never write a profile nobody registered, nor one belonging to a framework
+        // this element is not a background of.
+        if (!target)
+            return false;
+        const isDefault = defaultProfileOf(available, target.framework)?.id === target.id;
+        const next = isDefault ? undefined : target.id;
+        if ((element.validationProfile ?? undefined) === next)
+            return false;
+        if (next === undefined)
+            element.clearField('validationProfile');
+        else
+            element.validationProfile = next;
+        // The 120 ms debounce would get there on its own; the gesture has to land
+        // immediately, exactly like an exception does.
+        this.evaluate();
+        return true;
+    }
+    /**
+     * Which elements an exception of the given scope is written on.
+     *
+     * `element` — the elements the rule actually indicts, which is what makes the
+     * exception local (PF8.2): excusing one component says nothing about the next.
+     *
+     * `map` — the background element these findings were MEASURED AGAINST, and
+     * only that one. It comes from {@link Violation.backgroundId}, recorded by the
+     * rule family when it picked the frame, so a board carrying three maps holds
+     * three independent arbitrations and a gesture made on one writes on one.
+     * That choice is what lets a map-wide arbitration exist with NO block schema
+     * change and no hidden per-document store: it is one more value in the same
+     * `@field()`, on an element that is selected, copied, exported and deleted
+     * like any other. A family that measures against no background records no
+     * `backgroundId`, has no map to hang an exception on, and offers no map scope.
+     */
+    _targetsOf(violations, scope, surface) {
+        const ids = scope === 'map'
+            ? new Set(violations
+                .map(violation => violation.backgroundId)
+                .filter((id) => id !== undefined))
+            : new Set(violations.flatMap(violation => violation.elementIds));
+        return Array.from(ids)
+            .map(id => surface.getElementById(id))
+            .filter((el) => el !== null);
+    }
+    /**
+     * Grant or revoke `ruleId`'s exception at `scope`, over the elements the given
+     * violations indict.
+     *
+     * Takes the whole set rather than one violation on purpose: a Wardley
+     * component is a GROUP, so one bubble line can stand for several indicted
+     * members, and one click has to settle all of them.
+     *
+     * Re-evaluates on the spot instead of waiting for the 120 ms debounce the
+     * field write would trigger anyway — the gesture must apply immediately
+     * (PF8.1).
+     *
+     * @returns the elements actually written to, so the caller can tell a real
+     * arbitration from a no-op and only report the former.
+     */
+    setException(violations, scope, granted, author) {
+        // Same transact hole as `setProfile`; an empty return is what keeps the
+        // bubble from emitting Granted/Revoked telemetry for a write that never
+        // happened.
+        if (this.std.store.readonly)
+            return [];
+        const ruleId = violations[0]?.ruleId;
+        const surface = this.gfx.surface;
+        if (ruleId === undefined || !surface)
+            return [];
+        // Never write an exception for a rule nobody registered: with the framework
+        // flagged off there is no rule to arbitrate on.
+        if (!this.ruleOf(ruleId))
+            return [];
+        const targets = this._targetsOf(violations, scope, surface).filter(element => hasException(element, ruleId) !== granted);
+        if (targets.length === 0)
+            return [];
+        // One timestamp for the whole gesture: a single click is a single decision,
+        // whatever number of elements it happens to touch.
+        const at = Date.now();
+        for (const element of targets) {
+            if (granted)
+                grantException(element, ruleId, author, at);
+            else
+                revokeException(element, ruleId);
+        }
+        this.evaluate();
+        return targets;
+    }
+    /**
+     * The exceptions on `element` that can still be taken back — those it answers
+     * for ({@link exceptionsAnchoredOn}) whose rule is actually REGISTERED.
+     *
+     * The rule filter is what makes the menu entry disappear with the framework:
+     * flag off, no rule reaches the container, so there is nothing to arbitrate
+     * on and nothing to offer. The exceptions themselves are untouched — they are
+     * document data and outlive the tooling (PF8.6).
+     */
+    revocableExceptionsOn(element) {
+        const surface = this.gfx.surface;
+        if (!surface)
+            return [];
+        return exceptionsAnchoredOn(element, surface).filter(({ ruleId }) => this.ruleOf(ruleId) !== undefined);
+    }
+    /**
+     * Take back every exception `element` answers for, in one gesture.
+     *
+     * @returns one entry per (rule, scope) actually written, so the caller can
+     * report the arbitration and tell a real one from a no-op.
+     */
+    revokeExceptionsOn(element) {
+        // Same transact hole as `setProfile`, same telemetry contract: no entry
+        // returned, nothing reported.
+        if (this.std.store.readonly)
+            return [];
+        const anchored = this.revocableExceptionsOn(element);
+        if (anchored.length === 0)
+            return [];
+        const reported = new Map();
+        for (const { element: target, ruleId } of anchored) {
+            const rule = this.ruleOf(ruleId);
+            if (!rule)
+                continue;
+            revokeException(target, ruleId);
+            // An exception written on the framework's own background IS the map-wide
+            // one — the same test `applyExceptions` uses to read it back.
+            const scope = rule.backgroundRole !== undefined &&
+                target.role !== undefined &&
+                roleIsA(target.role, rule.backgroundRole, rule.roles)
+                ? 'map'
+                : 'element';
+            const key = `${ruleId}|${scope}`;
+            const entry = reported.get(key);
+            if (entry)
+                entry.elementCount += 1;
+            else {
+                reported.set(key, {
+                    ruleId,
+                    framework: rule.framework,
+                    scope,
+                    elementCount: 1,
+                });
+            }
+        }
+        this.evaluate();
+        return Array.from(reported.values());
+    }
+}
+/**
+ * Where a mark is DRAWN for one violating element: the outermost canvas group
+ * containing it, or the element itself when it is not grouped.
+ *
+ * A RENDERING decision, not a semantic one. The violation object keeps naming
+ * the elements actually at fault (`elementIds`); the group never appears in it,
+ * is never evaluated, and carries no role. This exists because a mark drawn on
+ * a lone member — a Wardley component is a group of {node, label} — collides
+ * with the group's own selection rect and becomes unreadable.
+ *
+ * Frames are deliberately skipped: they are group-compatible BLOCKS and appear
+ * in the group chain, but framing a whole frame would be a wild over-reach.
+ */
+function anchorOf(elementId, surface) {
+    const element = surface.getElementById(elementId);
+    if (!element)
+        return null;
+    // `getGroups` walks outward, so the last CANVAS group is the outermost one.
+    const canvasGroups = surface
+        .getGroups(elementId)
+        .filter(group => group instanceof GfxGroupLikeElementModel);
+    return canvasGroups[canvasGroups.length - 1] ?? element;
+}
+/**
+ * The MIDDLE of a drawn path, by arc length — not the middle point of the
+ * array, which on an elbowed connector is wherever the router happened to put a
+ * bend.
+ */
+function pathMidpoint(path) {
+    if (path.length === 0)
+        return null;
+    if (path.length === 1)
+        return [path[0][0], path[0][1]];
+    let total = 0;
+    for (let i = 1; i < path.length; i++) {
+        total += Math.hypot(path[i][0] - path[i - 1][0], path[i][1] - path[i - 1][1]);
+    }
+    // A degenerate path (every point on top of the last) has no middle to find;
+    // any of its points is the answer.
+    if (total === 0)
+        return [path[0][0], path[0][1]];
+    let walked = 0;
+    for (let i = 1; i < path.length; i++) {
+        const from = path[i - 1];
+        const to = path[i];
+        const length = Math.hypot(to[0] - from[0], to[1] - from[1]);
+        if (walked + length >= total / 2) {
+            const t = length === 0 ? 0 : (total / 2 - walked) / length;
+            return [from[0] + (to[0] - from[0]) * t, from[1] + (to[1] - from[1]) * t];
+        }
+        walked += length;
+    }
+    return [path[path.length - 1][0], path[path.length - 1][1]];
+}
+/**
+ * Whether the mark on this element belongs on the MIDDLE of a link rather than
+ * on a corner of a box.
+ *
+ * Two independent answers, either of which is enough, because they are the two
+ * ways an edge can be one:
+ *
+ * 1. its ROLE says so — a declared role of `kind: 'edge'`, which is the
+ *    semantic answer and the one a framework owns;
+ * 2. its GEOMETRY says so — the element exposes a path ({@link elementPath}),
+ *    which covers a generalist connector carrying no role at all, and an
+ *    element whose framework is not loaded.
+ *
+ * Vocabularies are optional: a caller that has none (the canvas overlay, which
+ * only ever reads `bound`) still gets the geometric answer.
+ */
+function anchorKindOf(element, vocabularies) {
+    // A GROUP is never an edge, whatever it contains: the mark frames the group's
+    // box, and the middle of that box is not on any of its members.
+    if (element instanceof GfxGroupLikeElementModel)
+        return 'node';
+    const role = element.role;
+    for (const defs of vocabularies) {
+        const def = role === undefined ? undefined : defs[role];
+        if (def?.kind === 'edge')
+            return 'edge';
+    }
+    return elementPath(element) !== null ? 'edge' : 'node';
+}
+/**
+ * Where the badge for `element` is pinned, in model space.
+ *
+ * Exported so a test can assert the coordinate rather than the rendering, and
+ * so the widget converts ONE point instead of reproducing the offsets.
+ */
+function markPointOf(element, kind, bound) {
+    if (kind === 'edge') {
+        const middle = pathMidpoint(elementPath(element) ?? []);
+        // The intersection of the rectangle's diagonals — its centre — for an edge
+        // the layout has not routed yet.
+        return middle ?? [bound.x + bound.w / 2, bound.y + bound.h / 2];
+    }
+    // Outside the corner by the mark's gap plus half a badge, so it does not land
+    // under the selected-rect north-east resize handle.
+    const offset = VIOLATION_MARK_PADDING + VIOLATION_BADGE_SIZE / 2;
+    return [bound.maxX + offset, bound.y - offset];
+}
+/**
+ * Group violations by the anchor their mark is drawn on — one entry per
+ * anchor, so several violating members of the same group share a single
+ * bracket, a single badge and a single bubble.
+ *
+ * Pure and stateless, and called at paint time by both halves of the
+ * affordance, so the mark follows a group that moves and falls back onto the
+ * element the moment the group is dissolved, with nothing to invalidate.
+ *
+ * @param vocabularies the registered role vocabularies, for the SEMANTIC half
+ * of "is this an edge" ({@link anchorKindOf}). Optional: a caller that only
+ * reads `bound` — the canvas overlay draws the same bracket either way — needs
+ * none, and still gets the geometric answer.
+ */
+export function resolveViolationAnchors(violations, surface, vocabularies = []) {
+    const anchors = new Map();
+    for (const violation of violations) {
+        for (const id of violation.elementIds) {
+            const anchor = anchorOf(id, surface);
+            if (!anchor)
+                continue;
+            let entry = anchors.get(anchor.id);
+            if (!entry) {
+                const bound = anchor.elementBound;
+                const kind = anchorKindOf(anchor, vocabularies);
+                entry = {
+                    id: anchor.id,
+                    bound,
+                    kind,
+                    markAt: markPointOf(anchor, kind, bound),
+                    violations: [],
+                };
+                anchors.set(anchor.id, entry);
+            }
+            // A single violation naming two members of one group resolves to that
+            // group twice and must be recorded once. Two SEPARATE violations of the
+            // same rule stay separate here — collapsing what is DISPLAYED is the
+            // bubble's call, not this function's.
+            if (!entry.violations.includes(violation)) {
+                entry.violations.push(violation);
+            }
+        }
+    }
+    return Array.from(anchors.values());
+}
+/**
+ * Violations the drawing user is meant to SEE. `audit` is collected for
+ * reporting and stays invisible on the canvas — that is what the severity
+ * means (see {@link ViolationSeverity}), and the UI is the only place that can
+ * honour it: the engine reports everything, unfiltered, to the host panel.
+ */
+export function userFacingViolations(violations) {
+    return violations.filter(violation => violation.severity !== 'audit');
+}
+/**
+ * Violations still asking for something, i.e. not covered by an exception.
+ *
+ * This is the whole of PF8's canvas behaviour: an exempted finding is dropped
+ * from the timeline, so it never flashes, and from the overlay, so it carries no
+ * bracket. It keeps its badge and its line in the bubble, where it reads as
+ * "exception" and can be revoked — the state changed, the finding did not
+ * disappear.
+ */
+export function liveViolations(violations) {
+    return violations.filter(violation => violation.exemption === undefined);
+}
+/**
+ * One violation per RULE, first occurrence wins.
+ *
+ * What a detail bubble renders is rule-level — a label, a severity, a hint —
+ * so two components of the same group both drawn off the map, which are two
+ * violations, would produce the same sentence twice. The engine is right to
+ * report both (it names the elements); a list that repeats itself is just
+ * noise. Which member moved is on the canvas, not in a list.
+ */
+export function distinctByRule(violations) {
+    const byRule = new Map();
+    for (const violation of violations) {
+        const kept = byRule.get(violation.ruleId);
+        // A LIVE finding always wins the slot: two members of one group, one
+        // excused and one not, must read as "this rule still applies here" rather
+        // than as an exception that quietly covers both.
+        if (kept === undefined || (kept.exemption && !violation.exemption)) {
+            byRule.set(violation.ruleId, violation);
+        }
+    }
+    return Array.from(byRule.values());
+}
+/**
+ * How loudly an ANCHOR is drawn: the loudest of the violations sharing it, so
+ * a fresh finding is not muted by an older one on the same group.
+ *
+ * The single arbiter between the two markers. `> 0` means the bracket still has
+ * the anchor; exactly `0` means it is done and the badge takes over. Both
+ * halves call this, on the same timeline, so they can never both claim it.
+ */
+export function anchorEmphasis(anchor, timeline, now) {
+    let emphasis = 0;
+    for (const violation of anchor.violations) {
+        emphasis = Math.max(emphasis, timeline.emphasis(violation, now));
+    }
+    return emphasis;
+}
+/**
+ * Mark geometry in MODEL units, deliberately — the affordance zooms with the
+ * board like any element on it.
+ *
+ * The house convention for annotation overlays is the opposite (divide by the
+ * zoom, keep a constant size on screen), and that is right for a snap guide,
+ * which is transient and never numerous. It is wrong here. The dimensioning
+ * case is a hundred-component map, zoomed out: screen-constant marks grow
+ * relative to the content they annotate until the brackets are all you can see
+ * and the map underneath is unreadable. Zoomed out far enough these become
+ * small along with everything else, and that is the point — a board you cannot
+ * read is a worse answer than a mark you have to zoom in to inspect.
+ *
+ * The one exception is the CLICK target, which lives in DOM and keeps a screen
+ * minimum so it stays reachable by thumb (see the widget). Invisible padding
+ * around a model-sized visual: the pattern `edgeless-auto-complete` already
+ * uses on this canvas.
+ */
+const MARK_CORNER = 10;
+const MARK_LINE_WIDTH = 2;
+/**
+ * Gap between the anchor's bounds and the mark, in MODEL units. Exported
+ * because the badge sits ON the bracket's top-right corner and has to use the
+ * same gap to land there.
+ */
+export const VIOLATION_MARK_PADDING = 6;
+/** Diameter of the persistent badge, in MODEL units. */
+export const VIOLATION_BADGE_SIZE = 16;
+/** The one amber the affordance is drawn in, canvas and DOM alike. */
+export const VIOLATION_MARK_COLOR = '#f5a623';
+/**
+ * The EPHEMERAL half of the PF7 affordance: amber corner brackets that flash on
+ * the anchor of a violation the moment it appears, hold for a few seconds, then
+ * fade out (see {@link ViolationTimeline}). What stays behind afterwards is the
+ * badge — `affine-violation-detail-widget`, a DOM sibling of this overlay.
+ *
+ * The handover is strict: an anchor whose emphasis has reached zero is skipped
+ * here and picked up by the badge, so the two markers are never on screen at
+ * the same time. {@link anchorEmphasis} is the single arbiter, read from the
+ * one timeline the manager owns.
+ *
+ * An overlay rather than a renderer change: it touches no element model, writes
+ * nothing to the document, creates no undo entry, and disappears with the rule
+ * that produced it. The fade is session state too — nothing about "when did I
+ * first see this" ever reaches the document.
+ *
+ * The mark is anchored on the outermost enclosing canvas group rather than on
+ * the bare element — see {@link resolveMarkAnchors}. Evaluation is untouched by
+ * this: it stays on the element carrying the role, because its position is what
+ * the rule is about.
+ */
+export class ValidationOverlay extends Overlay {
+    constructor() {
+        super(...arguments);
+        /**
+         * The violations themselves — NOT their bounds, and not their groups either.
+         * Both are resolved at paint time so the mark tracks what it accuses:
+         * evaluation is debounced, the renderer is not, so a frozen snapshot would
+         * leave the bracket behind at the drag's starting point until 120 ms after
+         * the user let go — and a dissolved group would keep framing nothing.
+         */
+        this._violations = [];
+        /**
+         * Handed in with the violations by {@link ValidationManager}, which owns it —
+         * the DOM badge reads the same instance, and the two markers must never
+         * disagree about whether the bracket is done.
+         */
+        this._timeline = null;
+        /** Armed only while something is still fading. */
+        this._frame = null;
+        /**
+         * Whether the renderer this overlay paints into is gone.
+         *
+         * It matters because the two ends of the affordance are on different
+         * lifecycles: the overlay dies with the surface COMPONENT (the renderer
+         * disposes it), while {@link ValidationManager} lives on the gfx scope and
+         * keeps its subscriptions on the surface MODEL, which outlives the component.
+         * So an evaluation can perfectly well land here after teardown — switch to
+         * page mode, edit the doc — and without this flag it would arm an animation
+         * loop repainting a dead renderer sixty times a second for three seconds.
+         *
+         * Not permanent: the overlay is a DI singleton and is handed a new renderer
+         * if the surface comes back.
+         */
+        this._detached = false;
+        this._onFrame = () => {
+            this._frame = null;
+            this._schedule();
+        };
+    }
+    static { this.overlayName = 'validation'; }
+    /**
+     * Repaint, and keep repainting for as long as a mark is inside its window.
+     *
+     * This is the only clock the affordance runs, and it stops on its own: a
+     * board with no violation, or whose violations have all settled, requests no
+     * animation frame at all.
+     */
+    _schedule() {
+        if (this._detached)
+            return;
+        this.refresh();
+        if (this._frame !== null)
+            return;
+        if (!this._timeline?.isAnimating(performance.now()))
+            return;
+        this._frame = requestAnimationFrame(this._onFrame);
+    }
+    _cancelFrame() {
+        if (this._frame === null)
+            return;
+        cancelAnimationFrame(this._frame);
+        this._frame = null;
+    }
+    _forget() {
+        this._cancelFrame();
+        this._violations = [];
+        // The timeline belongs to the manager and is shared with the badge: drop
+        // the reference, never the contents.
+        this._timeline = null;
+    }
+    /**
+     * @param violations already filtered to what the user is meant to see.
+     * @param timeline the manager's, already synced against these violations.
+     */
+    setViolations(violations, timeline) {
+        if (this._detached)
+            return;
+        this._violations = violations;
+        this._timeline = timeline;
+        this._schedule();
+    }
+    setRenderer(renderer) {
+        this._detached = renderer === null;
+        super.setRenderer(renderer);
+    }
+    clear() {
+        this._forget();
+        super.clear();
+    }
+    dispose() {
+        this._detached = true;
+        this._forget();
+        super.dispose();
+    }
+    render(ctx, _rc) {
+        const timeline = this._timeline;
+        if (!timeline || this._violations.length === 0)
+            return;
+        const now = performance.now();
+        // Everything has settled and the badges have it: the cheapest possible
+        // exit, before a single group chain is walked. The canvas repaints on
+        // every pan, zoom and edit — this overlay must cost nothing between the
+        // rare moments it has something to say.
+        if (!timeline.isAnimating(now))
+            return;
+        const surface = this.gfx.surface;
+        if (!surface)
+            return;
+        // Model units, NOT divided by the zoom: the mark scales with the board.
+        const corner = MARK_CORNER;
+        const padding = VIOLATION_MARK_PADDING;
+        ctx.save();
+        ctx.strokeStyle = VIOLATION_MARK_COLOR;
+        ctx.lineWidth = MARK_LINE_WIDTH;
+        for (const anchor of resolveViolationAnchors(this._violations, surface)) {
+            const emphasis = anchorEmphasis(anchor, timeline, now);
+            // Done fading: the badge has this anchor now, and the two never overlap.
+            if (emphasis <= 0)
+                continue;
+            const { bound } = anchor;
+            const x = bound.x - padding;
+            const y = bound.y - padding;
+            const maxX = bound.maxX + padding;
+            const maxY = bound.maxY + padding;
+            ctx.globalAlpha = emphasis;
+            ctx.beginPath();
+            // Four corner brackets: reads as an annotation, not as a selection box.
+            ctx.moveTo(x + corner, y);
+            ctx.lineTo(x, y);
+            ctx.lineTo(x, y + corner);
+            ctx.moveTo(maxX - corner, y);
+            ctx.lineTo(maxX, y);
+            ctx.lineTo(maxX, y + corner);
+            ctx.moveTo(x, maxY - corner);
+            ctx.lineTo(x, maxY);
+            ctx.lineTo(x + corner, maxY);
+            ctx.moveTo(maxX, maxY - corner);
+            ctx.lineTo(maxX, maxY);
+            ctx.lineTo(maxX - corner, maxY);
+            ctx.stroke();
+        }
+        ctx.restore();
+    }
+}