@formicoidea/labre-core 0.31.0 → 0.33.0

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

@@ -0,0 +1,767 @@
+import { getUniverseRegistry, hostLanguage, queryPivotProperties, } from '../../affine-shared/services/index.js';
+import { createIdentifier } from '../../global/di/index.js';
+import { LifeCycleWatcher, } from '../../std/index.js';
+import { GfxControllerIdentifier, GfxPrimitiveElementModel, isPivotBound, readElementTags, roleIsA, } from '../../std/gfx/index.js';
+import { effect, signal } from '@preact/signals-core';
+// Straight at the two leaf modules rather than at the barrel, for the reason
+// `validation.ts` states: `index.js` also re-exports the RENDERER, and a
+// reading is a one-way read of pure declaration data that must never pull a
+// canvas in.
+import { backgroundPlot, } from '../framework-background/def.js';
+import { backgroundTransitionBands } from '../framework-background/facts.js';
+/** Deepest role chain reported by {@link ReadingNodeType.specialises}. */
+const MAX_ROLE_DEPTH = 32;
+/** Numeric slack on the two geometry comparisons. Model units. */
+const GEOMETRY_EPSILON = 1e-6;
+/** Complain once per malformed declaration: a reading can be asked for often. */
+const warned = new Set();
+function warnOnce(reason) {
+    if (warned.has(reason))
+        return;
+    warned.add(reason);
+    console.warn(`[reading] ${reason}`);
+}
+/**
+ * Compiled convention patterns, keyed by source. A profile is a module-level
+ * constant, so this cache holds one entry per declared convention for the life
+ * of the process — and a broken pattern is compiled (and complained about)
+ * once rather than on every render of the panel.
+ */
+const patterns = new Map();
+function compile(pattern) {
+    const cached = patterns.get(pattern);
+    if (cached !== undefined)
+        return cached;
+    let compiled = null;
+    try {
+        // `s` so `.` crosses the newline of a wrapped canvas label: without it an
+        // anchored pattern (`^…$`) fails on every two-line name whatever it says,
+        // which reads to the user as "the convention dislikes long names".
+        compiled = new RegExp(pattern, 'ius');
+    }
+    catch (error) {
+        warnOnce(`naming convention /${pattern}/ does not compile (${String(error)}) — ` +
+            `the naming line is dropped rather than reported as a mismatch.`);
+    }
+    patterns.set(pattern, compiled);
+    return compiled;
+}
+/** The text an element carries itself, `''` when it carries none. */
+function ownText(element) {
+    const text = element.text;
+    if (typeof text === 'string')
+        return text.trim();
+    if (text && typeof text.toString === 'function') {
+        return String(text).trim();
+    }
+    return '';
+}
+/**
+ * The members of the group holding this element, or `null` when it is not
+ * grouped — or when asking cannot be done safely.
+ *
+ * `group` is a getter that walks the element's SURFACE, so on an element that
+ * is not attached to one it throws. A reading must never throw: a panel that
+ * crashes on an odd element is worse than one that has nothing to say about its
+ * name, and the caller's fallback (no name, therefore no naming line) is the
+ * same silence every other unreadable field produces.
+ */
+function groupMembers(element) {
+    let group;
+    try {
+        group = element.group;
+    }
+    catch {
+        return null;
+    }
+    const children = group?.childElements;
+    return Array.isArray(children)
+        ? children
+        : null;
+}
+/**
+ * The subject's NAME.
+ *
+ * Its own text first, then — because a framework artefact on this canvas is a
+ * composite — the text of the sibling carrying the profile's label role. That
+ * is the same fact `tags-toolbar.ts` works around from the other direction: one
+ * click selects the group, the role lives on the circle, and the name lives on
+ * a free text beside it.
+ */
+function readName(element, profile) {
+    const own = ownText(element);
+    if (own)
+        return own;
+    const labelRole = profile.labelRole;
+    if (!labelRole)
+        return '';
+    const children = groupMembers(element);
+    if (children === null)
+        return '';
+    for (const child of children) {
+        if (!(child instanceof GfxPrimitiveElementModel))
+            continue;
+        if (child.id === element.id)
+            continue;
+        if (!roleIsA(child.role, labelRole, profile.roles))
+            continue;
+        const text = ownText(child);
+        if (text)
+            return text;
+    }
+    return '';
+}
+/** The role chain above `roleId`, nearest first, bounded like `roleIsA` is. */
+function specialisationChain(roleId, roles) {
+    const chain = [];
+    let current = roles[roleId]?.parent;
+    for (let hops = 0; current !== undefined && hops < MAX_ROLE_DEPTH; hops++) {
+        chain.push(current);
+        current = roles[current]?.parent;
+    }
+    return chain;
+}
+/** Centre of a bound. Reading a position is reading where the thing IS. */
+const centreOf = (bound) => [
+    bound.x + bound.w / 2,
+    bound.y + bound.h / 2,
+];
+/**
+ * The frame the subject sits ON — containment of its CENTRE, and nothing else.
+ *
+ * Deliberately not the "nearest map" attribution the validation engine uses: a
+ * finding has to be filed against some map even when the subject is off in the
+ * margin, whereas a phase read off a map the component is not on would be an
+ * invented fact. A component beside the map has no phase, and the panel says
+ * nothing rather than something plausible.
+ *
+ * The centre, not the whole bound: a node overhanging the edge of the map is
+ * still on it to every reader.
+ *
+ * ## Two frames under one component
+ *
+ * The first match in DOCUMENT order wins — not the smallest, not the topmost.
+ * Deterministic, and deliberately not clever: z-order is a paint concern and
+ * "the smallest frame containing it" is a rule nobody declared. Two overlapping
+ * maps of different sizes are a board that has not decided what it is, and a
+ * reading that quietly picked one of them by area would be harder to argue with
+ * than one that picked the first. The day a framework needs nesting, this is the
+ * one function to change.
+ */
+function frameOf(element, elements, profile) {
+    const frame = profile.frame;
+    if (!frame)
+        return null;
+    const [cx, cy] = centreOf(element.elementBound);
+    for (const candidate of elements) {
+        if (candidate.id === element.id)
+            continue;
+        if (candidate.role === undefined)
+            continue;
+        if (!roleIsA(candidate.role, frame.backgroundRole, profile.roles))
+            continue;
+        const bound = candidate.elementBound;
+        if (cx >= bound.x &&
+            cx <= bound.x + bound.w &&
+            cy >= bound.y &&
+            cy <= bound.y + bound.h) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * The phase, read from the position and the frame's DECLARED zones.
+ *
+ * Two facts, both taken from the declaration and never from a number in this
+ * file: which zone the subject's centre falls in, and whether it is inside the
+ * band around a transition. The second is the "zone of punctuated equilibrium"
+ * — the frontier is a region, not a coordinate — and a component sitting in one
+ * is a different statement from a component sitting in a phase.
+ */
+function readPhase(element, elements, profile) {
+    const frame = profile.frame;
+    if (!frame)
+        return undefined;
+    const background = frameOf(element, elements, profile);
+    if (!background)
+        return undefined;
+    const def = frame.background;
+    const bound = background.elementBound;
+    const plot = backgroundPlot(def, bound.w, bound.h);
+    const [cx, cy] = centreOf(element.elementBound);
+    const along = frame.axis === 'x' ? cx : cy;
+    const origin = frame.axis === 'x' ? bound.x + plot.x0 : bound.y + plot.y0;
+    const span = frame.axis === 'x' ? plot.width : plot.height;
+    if (!(span > 0))
+        return undefined;
+    const ratio = (along - origin) / span;
+    // Inside the card but outside the PLOT — on the margin the axes are drawn in.
+    // No zone covers it, and inventing the nearest one would put a component in a
+    // phase it is visibly not in.
+    if (ratio < 0 || ratio > 1)
+        return undefined;
+    const zone = (def.zones ?? []).find(({ rect }) => {
+        const start = frame.axis === 'x' ? rect.x : rect.y;
+        const size = frame.axis === 'x' ? rect.w : rect.h;
+        // Half-open, so a component exactly on a divider reads as the phase it is
+        // entering — the same side the band below reports as the frontier.
+        return ratio >= start && (ratio < start + size || start + size >= 1);
+    });
+    if (!zone)
+        return undefined;
+    const bands = backgroundTransitionBands(def, bound)[frame.axis];
+    const band = bands.find(({ min, max }) => along >= min && along <= max);
+    return {
+        zoneId: zone.id,
+        ...(zone.label?.labelKey !== undefined
+            ? { labelKey: zone.label.labelKey }
+            : {}),
+        ...(zone.label?.fallback !== undefined
+            ? { labelFallback: zone.label.fallback }
+            : {}),
+        inTransitionBand: band !== undefined,
+        ...(band !== undefined ? { bandId: band.id } : {}),
+    };
+}
+/** The two ends of a connector, when both are bound to an element. */
+function endpointsOf(element) {
+    const source = element.source;
+    const target = element.target;
+    if (typeof source?.id !== 'string' || typeof target?.id !== 'string') {
+        return null;
+    }
+    if (!source.id || !target.id)
+        return null;
+    return { source: source.id, target: target.id };
+}
+/**
+ * Every typed edge touching the subject, read as a relation.
+ *
+ * An edge with an unbound end is skipped, exactly as ADR 0010 requires of W4:
+ * releasing the link tool over empty canvas produces one, and a stroke that
+ * links nothing states nothing.
+ */
+function readRelations(element, elements, profile) {
+    const relation = profile.relation;
+    if (!relation)
+        return [];
+    const byId = new Map(elements.map(el => [el.id, el]));
+    const [, subjectY] = centreOf(element.elementBound);
+    const relations = [];
+    for (const edge of elements) {
+        if (edge.role === undefined)
+            continue;
+        if (!roleIsA(edge.role, relation.edgeRole, profile.roles))
+            continue;
+        const ends = endpointsOf(edge);
+        if (!ends)
+            continue;
+        const isSource = ends.source === element.id;
+        const isTarget = ends.target === element.id;
+        // A self-loop states nothing about an order and would report the subject as
+        // its own supplier.
+        if (isSource === isTarget)
+            continue;
+        const otherId = isSource ? ends.target : ends.source;
+        const other = byId.get(otherId);
+        if (!other)
+            continue;
+        const side = isSource ? 'supplier' : 'consumer';
+        const [, otherY] = centreOf(other.elementBound);
+        // `y` grows downwards, so "higher on the map" is a SMALLER y. A supplier is
+        // expected below the subject, a consumer above it.
+        const contradictsGeometry = side === 'supplier'
+            ? otherY < subjectY - GEOMETRY_EPSILON
+            : otherY > subjectY + GEOMETRY_EPSILON;
+        relations.push({
+            edgeId: edge.id,
+            otherId,
+            otherName: readName(other, profile),
+            side,
+            contradictsGeometry,
+        });
+    }
+    return relations;
+}
+/**
+ * The naming line, when there is a single nature, a convention for it, and that
+ * convention is IN SCOPE for the language the host is serving.
+ *
+ * The scope check is the difference between a suggestion and a nuisance: a
+ * motif is a motif of one language, and the first one whose `lang` matches
+ * wins. A convention that declares no language is agnostic and always applies.
+ */
+function readNaming(element, profile, valueIds, lang) {
+    const nature = profile.nature;
+    if (!nature || valueIds.length !== 1)
+        return undefined;
+    const convention = nature.conventions.find(c => c.valueId === valueIds[0] && (c.lang === undefined || c.lang === lang));
+    if (!convention)
+        return undefined;
+    const name = readName(element, profile);
+    // Nothing to judge. An unnamed component is an unfinished drawing, not a
+    // naming mistake, and the panel has a better thing to say about it: nothing.
+    if (!name)
+        return undefined;
+    const pattern = compile(convention.pattern);
+    if (!pattern)
+        return undefined;
+    return {
+        name,
+        conforms: pattern.test(name),
+        hintKey: convention.hintKey,
+        hintFallback: convention.hintFallback,
+    };
+}
+/**
+ * Read one element. Pure: same elements, same profile, same options, same
+ * answer, and no write anywhere on any path through this function.
+ *
+ * `null` when the element does not carry the profile's subject role — the
+ * caller has nothing to show, which is what keeps the panel off every neutral
+ * rectangle on the board.
+ */
+export function readElement(element, elements, profile, options = {}) {
+    const roleId = element.role;
+    if (roleId === undefined)
+        return null;
+    if (!roleIsA(roleId, profile.appliesTo, profile.roles))
+        return null;
+    const tagId = profile.nature?.tagId;
+    const carried = tagId ? (readElementTags(element)[tagId] ?? []) : [];
+    const labelKey = profile.roles[roleId]?.labelKey;
+    return {
+        elementId: element.id,
+        name: readName(element, profile),
+        nodeType: {
+            roleId,
+            ...(labelKey !== undefined ? { labelKey } : {}),
+            specialises: specialisationChain(roleId, profile.roles),
+        },
+        nature: tagId !== undefined && carried.length > 0
+            ? { tagId, valueIds: carried }
+            : undefined,
+        relations: readRelations(element, elements, profile),
+        phase: readPhase(element, elements, profile),
+        naming: readNaming(element, profile, carried, options.lang),
+    };
+}
+/**
+ * **The value flow** — the same typed edges as {@link ElementReading.relations},
+ * said the way a value chain is read: from the bottom up.
+ *
+ * A Wardley map is an anchor at the top and everything the anchor needs
+ * underneath it, so the VALUE travels the other way round from the dependency
+ * arrow: a supplier hands its value up to the consumer that needs it. ADR 0010
+ * § 2 fixes which end is which — on a `wardley:dependency` the `source` is the
+ * consumer and the `target` is the supplier — so the flow is entirely a
+ * restatement of what {@link readRelations} already resolved:
+ *
+ * - the other end is a SUPPLIER (an edge leaving the subject) → value comes up
+ *   from it to the subject;
+ * - the other end is a CONSUMER (an edge arriving at the subject) → value goes
+ *   up from the subject to it.
+ *
+ * Derived, not stored: no second traversal of the board, no second convention
+ * to keep in step with ADR 0010, and an element with no typed edge yields an
+ * empty list — which the panel renders as no section at all.
+ */
+export function readValueFlows(reading) {
+    const subject = reading.name || reading.elementId;
+    return reading.relations.map(relation => {
+        const other = relation.otherName || relation.otherId;
+        return relation.side === 'supplier'
+            ? { edgeId: relation.edgeId, from: other, to: subject }
+            : { edgeId: relation.edgeId, from: subject, to: other };
+    });
+}
+/** The profile governing an element, or `null` — the first match wins. */
+export function readingProfileFor(element, profiles) {
+    const roleId = element.role;
+    if (roleId === undefined)
+        return null;
+    return (profiles.find(profile => roleIsA(roleId, profile.appliesTo, profile.roles)) ?? null);
+}
+/**
+ * Resolve the record's words against the tag def's own values.
+ *
+ * Three ways a word is accepted, in order: the value id itself, the id
+ * case-insensitively, then the value's LABEL case-insensitively — because a
+ * host storing the words a human picked from a multi-select is the ordinary
+ * case, not the exotic one. Anything else is `unknown`: this is a resolver, not
+ * a guesser, and there is no fuzzy match anywhere in it.
+ *
+ * Two deliberate edge cases:
+ *
+ * - **no def** (the framework's pack is not seeded in this deployment) — every
+ *   word is unknown. We cannot know the vocabulary, so proposing to write one of
+ *   its words would be inventing it;
+ * - **`values: 'open'`** — the def says any string is a value of this tag, so
+ *   everything resolves. That is the def's own claim, not ours.
+ */
+export function resolveRecordNature(def, values) {
+    const resolved = [];
+    const unknown = [];
+    const seen = new Set();
+    if (!def)
+        return { resolved, unknown: [...values] };
+    if (def.values === 'open')
+        return { resolved: [...values], unknown };
+    const byId = new Map();
+    const byLabel = new Map();
+    for (const value of def.values) {
+        byId.set(value.id.toLowerCase(), value.id);
+        const label = (value.label || '').toLowerCase();
+        // First declaration wins: a label repeated across two values is an
+        // authoring bug in the pack, and picking the later one silently would make
+        // the resolution depend on declaration order.
+        if (label && !byLabel.has(label))
+            byLabel.set(label, value.id);
+    }
+    for (const raw of values) {
+        const key = raw.toLowerCase();
+        const id = byId.get(key) ?? byLabel.get(key);
+        if (id === undefined) {
+            if (!unknown.includes(raw))
+                unknown.push(raw);
+            continue;
+        }
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        resolved.push(id);
+    }
+    return { resolved, unknown };
+}
+/** A record property flattened to the strings a comparison can work on. */
+function propertyStrings(snapshot, key) {
+    const property = snapshot.properties.find(p => p.key === key);
+    if (!property)
+        return [];
+    const { value } = property;
+    switch (value.kind) {
+        case 'text':
+            return value.value ? [value.value] : [];
+        case 'tags':
+            return value.value.filter(entry => entry.length > 0);
+        default:
+            // Every other kind is a value this comparison has no business
+            // interpreting. Unknown means silent, never "different".
+            return [];
+    }
+}
+/**
+ * The record's side of the comparison, read through the guarded seam.
+ *
+ * `undefined` on every degraded path — no binding, no provider, no configured
+ * fields, a dangling record, a still-loading one — and the caller shows the
+ * local reading alone. That is the `queryPivotProperties` contract: "this
+ * editor has no host data layer" is not an error to put in front of a user.
+ */
+export function readRecord(std, element, profile) {
+    if (!isPivotBound(element))
+        return undefined;
+    const keys = profile.recordKeys;
+    if (!keys?.nature && !keys?.phase)
+        return undefined;
+    const state = queryPivotProperties(std, element.pivotDocId);
+    if (!state)
+        return undefined;
+    const current = state.value;
+    if (current.status !== 'ready')
+        return undefined;
+    const raw = keys.nature ? propertyStrings(current.snapshot, keys.nature) : [];
+    const phase = keys.phase ? propertyStrings(current.snapshot, keys.phase) : [];
+    // The record speaks the HOST's alphabet; the element speaks the framework's.
+    // Translating happens here, once, so that every consumer downstream — the
+    // proposal, the confirmation and the drift comparison — works on value ids a
+    // def describes and on nothing else.
+    const tagId = profile.nature?.tagId;
+    const { resolved, unknown } = tagId !== undefined && raw.length
+        ? resolveRecordNature(getUniverseRegistry(std).tag(tagId), raw)
+        : { resolved: [], unknown: [] };
+    return {
+        pivotDocId: element.pivotDocId,
+        ...(resolved.length ? { nature: resolved } : {}),
+        ...(unknown.length ? { unknownNature: unknown } : {}),
+        ...(phase.length ? { phase: phase[0] } : {}),
+    };
+}
+/**
+ * Where the drawing and the record disagree.
+ *
+ * A field the record does not carry is never a disagreement: the record simply
+ * has not been filled in, and calling that "drift" would turn an empty property
+ * into a permanent complaint. A field the BOARD cannot read is not one either —
+ * a component dragged off the map has no phase to be in conflict with.
+ *
+ * Neither is a word the framework does not describe ({@link RecordReading.unknownNature}):
+ * comparing `wardley:nature/activity` against the host's `"Activity"` would
+ * report a permanent, false disagreement on an element that is correctly
+ * qualified — and would offer the user two ways out, both of which corrupt one
+ * side. `readRecord` has already resolved what CAN be compared; what could not
+ * is not a difference of opinion, it is a difference of alphabet.
+ *
+ * The phase comparison accepts either the zone id or the zone's own wording,
+ * because a host is free to store "Product" where the declaration says
+ * `product`, and neither spelling is more correct than the other.
+ */
+export function compareReading(reading, record) {
+    const fields = [];
+    const recorded = record.nature ?? [];
+    if (recorded.length) {
+        const read = reading.nature?.valueIds ?? [];
+        const same = read.length === recorded.length &&
+            read.every(value => recorded.includes(value));
+        if (!same) {
+            fields.push({
+                field: 'nature',
+                read: read.join(', '),
+                record: recorded.join(', '),
+            });
+        }
+    }
+    if (record.phase && reading.phase) {
+        const spellings = [
+            reading.phase.zoneId,
+            reading.phase.labelFallback ?? '',
+        ].map(value => value.toLowerCase());
+        if (!spellings.includes(record.phase.toLowerCase())) {
+            fields.push({
+                field: 'phase',
+                read: reading.phase.labelFallback ?? reading.phase.zoneId,
+                record: record.phase,
+            });
+        }
+    }
+    return fields;
+}
+/** A framework registers its reading profile here; nothing else registers one. */
+export const ReadingProfileIdentifier = createIdentifier('ReadingProfile');
+/**
+ * Register a framework's reading profile. Call it from the FLAG-GATED view
+ * extension, beside the rules and the profiles: reading a map is tooling, and a
+ * board whose framework is switched off keeps every one of its elements and
+ * simply stops being read (ADR 0009).
+ *
+ * ```ts
+ * context.register(ReadingProfileExtension(WARDLEY_READING));
+ * ```
+ */
+export function ReadingProfileExtension(profile) {
+    return {
+        setup: di => {
+            di.addImpl(ReadingProfileIdentifier(profile.id), () => profile);
+        },
+    };
+}
+export const PivotRecordPickerProvider = createIdentifier('LabrePivotRecordPicker');
+export function PivotRecordPickerExtension(picker) {
+    return {
+        setup: di => {
+            di.override(PivotRecordPickerProvider, () => picker);
+        },
+    };
+}
+/**
+ * Debounce of the drift trigger, in ms.
+ *
+ * Comfortably above a frame: the trigger is the one part of this feature that
+ * runs without being asked, so it stays off the critical path by construction —
+ * a drag of a bound component emits dozens of updates and must cost one check,
+ * after the hand has stopped. Longer than the validation engine's 120 ms
+ * because nothing here is a verdict: a record that is out of date can wait a
+ * fifth of a second longer than a rule can.
+ */
+export const READING_DRIFT_DELAY_MS = 200;
+/** Props whose change can move a reading away from a confirmed record. */
+const DRIFT_PROPS = new Set(['xywh', 'rotate', 'tags', 'role', 'pivotDocId']);
+const touchesReading = (payload) => {
+    const { props, oldValues } = payload;
+    if (!props && !oldValues)
+        return true;
+    return (Object.keys(props ?? {}).some(key => DRIFT_PROPS.has(key)) ||
+        Object.keys(oldValues ?? {}).some(key => DRIFT_PROPS.has(key)));
+};
+/**
+ * Owns the OPEN panel and the drift signal. It owns no reading: a reading is
+ * recomputed on demand from the document, so it can never be stale and can
+ * never be a second source of truth.
+ *
+ * Inert until a framework registers a {@link ReadingProfile} — a board with no
+ * framework enabled pays one empty-map check at mount and subscribes to
+ * nothing.
+ */
+export class ReadingManager extends LifeCycleWatcher {
+    constructor() {
+        super(...arguments);
+        /**
+         * The element whose proposal is open, or `null`. Session state, set by the
+         * `element.read` command and by nothing else: the panel NEVER opens itself,
+         * which is the whole of the PO's arbitration.
+         */
+        this.open$ = signal(null);
+        /**
+         * The last drift observed, or `null`. Informative and non-blocking: nothing
+         * anywhere refuses a gesture because of it.
+         */
+        this.drift$ = signal(null);
+        this._profiles = null;
+        this._subscriptions = [];
+        this._disposeSurfaceEffect = null;
+        this._pending = null;
+        this._dirty = new Set();
+    }
+    static { this.key = 'reading-manager'; }
+    /** Registered profiles, resolved once. Empty when every flag is off. */
+    get profiles() {
+        this._profiles ??= Array.from(this.std.provider.getAll(ReadingProfileIdentifier).values());
+        return this._profiles;
+    }
+    mounted() {
+        if (this.profiles.length === 0)
+            return;
+        // The surface is a SIGNAL, not a fact: it can be null at mount and arrive
+        // later, and it is replaced if the surface block is.
+        this._disposeSurfaceEffect = effect(() => {
+            this._resubscribe(this.std.get(GfxControllerIdentifier).surface$.value);
+        });
+    }
+    unmounted() {
+        this._disposeSurfaceEffect?.();
+        this._disposeSurfaceEffect = null;
+        this._unsubscribe();
+        this.open$.value = null;
+        this.drift$.value = null;
+        super.unmounted();
+    }
+    /** Open the proposal for one element. Reads nothing yet, writes nothing ever. */
+    open(elementId) {
+        this.open$.value = elementId;
+    }
+    close() {
+        this.open$.value = null;
+    }
+    /** The current surface, or `null` before one arrives. */
+    get _surface() {
+        return this.std.get(GfxControllerIdentifier).surface$.value;
+    }
+    /**
+     * The reading of one element, recomputed from the document every time it is
+     * asked for. Cheap enough to be called from a render: one pass over the
+     * surface for the relations, one containment test per frame.
+     */
+    reading(elementId) {
+        const surface = this._surface;
+        const element = surface?.getElementById(elementId);
+        if (!surface || !element)
+            return null;
+        const profile = readingProfileFor(element, this.profiles);
+        if (!profile)
+            return null;
+        return readElement(element, surface.elementModels, profile, {
+            lang: hostLanguage(this.std),
+        });
+    }
+    /** The profile governing an element, for the panel's confirmation actions. */
+    profileOf(elementId) {
+        const element = this._surface?.getElementById(elementId);
+        return element ? readingProfileFor(element, this.profiles) : null;
+    }
+    _unsubscribe() {
+        for (const subscription of this._subscriptions)
+            subscription.unsubscribe();
+        this._subscriptions = [];
+        if (this._pending) {
+            clearTimeout(this._pending);
+            this._pending = null;
+        }
+        this._dirty.clear();
+    }
+    _resubscribe(surface) {
+        this._unsubscribe();
+        // A new surface is a new document: a drift observed on the last one says
+        // nothing about this one.
+        this.drift$.value = null;
+        this.open$.value = null;
+        if (!surface)
+            return;
+        this._subscriptions.push(surface.elementUpdated.subscribe(payload => {
+            // Local only, for the reason the materiality publisher documents:
+            // `local` partitions the fleet into one watcher and N−1 silent
+            // observers, with no leader election — and a colleague's drag is their
+            // drift to notice, not ours.
+            if (!payload.local)
+                return;
+            if (!touchesReading(payload))
+                return;
+            this._schedule(payload.id);
+        }));
+        this._subscriptions.push(surface.elementRemoved.subscribe(({ id }) => {
+            this._dirty.delete(id);
+            if (this.drift$.value?.elementId === id)
+                this.drift$.value = null;
+            if (this.open$.value === id)
+                this.open$.value = null;
+        }));
+    }
+    /**
+     * Never in the same tick, and never in the same frame.
+     *
+     * The whole trigger is one timer: a drag emits an update per pointer move,
+     * and each one pushes the single pending check further away, so the work
+     * happens once, after the hand has stopped, and the 16 ms budget of the drag
+     * itself is untouched by construction rather than by measurement.
+     */
+    _schedule(id) {
+        this._dirty.add(id);
+        if (this._pending)
+            clearTimeout(this._pending);
+        this._pending = setTimeout(() => {
+            this._pending = null;
+            const ids = [...this._dirty];
+            this._dirty.clear();
+            for (const dirty of ids)
+                this._check(dirty);
+        }, READING_DRIFT_DELAY_MS);
+    }
+    _check(elementId) {
+        const surface = this._surface;
+        const element = surface?.getElementById(elementId);
+        if (!surface || !element)
+            return;
+        // Only a LINKED element can drift: without a record there is nothing to
+        // disagree with, and the reading is just a reading.
+        if (!isPivotBound(element)) {
+            if (this.drift$.value?.elementId === elementId)
+                this.drift$.value = null;
+            return;
+        }
+        const profile = readingProfileFor(element, this.profiles);
+        if (!profile)
+            return;
+        const reading = readElement(element, surface.elementModels, profile, {
+            lang: hostLanguage(this.std),
+        });
+        if (!reading)
+            return;
+        const record = readRecord(this.std, element, profile);
+        if (!record) {
+            if (this.drift$.value?.elementId === elementId)
+                this.drift$.value = null;
+            return;
+        }
+        const fields = compareReading(reading, record);
+        if (fields.length === 0) {
+            if (this.drift$.value?.elementId === elementId)
+                this.drift$.value = null;
+            return;
+        }
+        this.drift$.value = {
+            elementId,
+            pivotDocId: record.pivotDocId,
+            fields,
+        };
+    }
+}