@formicoidea/labre-core 0.30.1 → 0.32.0

package/dist/_pkgs/std/gfx/model/surface/element-model.js

@@ -36,12 +36,60 @@ var _a;
 import { DisposableGroup } from '../../../../global/disposable/index.js';
 import { Bound, deserializeXYWH, getBoundWithRotation, getPointsFromBoundWithRotation, linePolygonIntersects, PointLocation, polygonGetPointTangent, polygonNearestPoint, randomSeed, rotatePoints, } from '../../../../global/gfx/index.js';
 import { createMutex } from 'lib0/mutex';
-import isEqual from 'lodash-es/isEqual';
+import isEqual from 'lodash-es/isEqual.js';
 import { Subject } from 'rxjs';
 import * as Y from 'yjs';
 import { descendantElementsImpl, hasDescendantElementImpl, isLockedByAncestorImpl, isLockedBySelfImpl, isLockedImpl, lockElementImpl, unlockElementImpl, } from '../../../utils/tree.js';
 import { gfxGroupCompatibleSymbol } from '../base.js';
-import { convertProps, field, getDerivedProps, getFieldPropsSet, local, updateDerivedProps, watch, } from './decorators/index.js';
+import { convertProps, field, getDerivedProps, getFieldPropsSet, hasObserveMeta, local, observe, startObserve, updateDerivedProps, watch, } from './decorators/index.js';
+/**
+ * Declared `@field()`s that {@link GfxPrimitiveElementModel.clearField} refuses
+ * to remove, because they have no meaningful ABSENT state: every one of them is
+ * read unconditionally, with no fallback, by code that has no way to cope.
+ *
+ * - `index` — the fractional z-order key. Gone, the element's stacking is
+ *   `undefined` and the layer manager sorts it nowhere, silently.
+ * - `xywh` — gone, `elementBound` collapses to `{0,0,0,0}` and the renderer
+ *   throws `"undefined" is not valid JSON` on every frame.
+ * - `seed` — the roughness seed; gone, the hand-drawn renderers produce a
+ *   different shape on every repaint.
+ *
+ * An optional field is exactly one whose accessor declares a usable default (or
+ * `undefined`), and those stay clearable. This list is the short answer to
+ * "which declared fields are not optional"; it is a deny-list on purpose, so a
+ * new optional field needs no ceremony and a new structural one is a deliberate
+ * addition here.
+ */
+const UNCLEARABLE_ELEMENT_FIELDS = new Set(['index', 'seed', 'xywh']);
+/**
+ * Republish a nested-`Y.Map` field change as an element-level change.
+ *
+ * `syncElementFromY` observes the element's OWN `Y.Map` only, so mutating a
+ * value INSIDE {@link GfxPrimitiveElementModel.tags} — which is the whole point
+ * of storing it as a nested map, since that is what makes two people qualifying
+ * one element on two different tags both keep their work — emits nothing. This
+ * is the `Y.Map` counterpart of the `watchText` bridge the same file already
+ * ships for nested `Y.Text`, and it is what puts a per-tag write on the same
+ * footing as every other field: one `elementUpdated`, carrying the transaction's
+ * own `local` flag, for the renderer, the rules engine and
+ * `PivotMaterialityPublisher` alike.
+ *
+ * `transaction === null` is the observer ATTACHING, not a change (see
+ * `startObserve`); republishing there would fire on every mount and on every
+ * re-attach.
+ */
+function observeTags(_, instance, transaction) {
+    if (transaction === null)
+        return;
+    instance['_onChange']({
+        props: { tags: instance.tags },
+        // Deliberately empty, exactly like `watchText`: Yjs gives the delta of the
+        // NESTED map, and inventing a previous value for the whole field would be
+        // a guess. Consumers that need the old set read it from their own state.
+        oldValues: {},
+        local: transaction.local,
+    });
+}
 let GfxPrimitiveElementModel = (() => {
     let _display_decorators;
     let _display_initializers = [];
@@ -61,6 +109,24 @@ let GfxPrimitiveElementModel = (() => {
     let _linkedDocId_decorators;
     let _linkedDocId_initializers = [];
     let _linkedDocId_extraInitializers = [];
+    let _pivotDocId_decorators;
+    let _pivotDocId_initializers = [];
+    let _pivotDocId_extraInitializers = [];
+    let _role_decorators;
+    let _role_initializers = [];
+    let _role_extraInitializers = [];
+    let _tags_decorators;
+    let _tags_initializers = [];
+    let _tags_extraInitializers = [];
+    let _validationExceptions_decorators;
+    let _validationExceptions_initializers = [];
+    let _validationExceptions_extraInitializers = [];
+    let _validationProfile_decorators;
+    let _validationProfile_initializers = [];
+    let _validationProfile_extraInitializers = [];
+    let _qualityChecklist_decorators;
+    let _qualityChecklist_initializers = [];
+    let _qualityChecklist_extraInitializers = [];
     let _lockedBySelf_decorators;
     let _lockedBySelf_initializers = [];
     let _lockedBySelf_extraInitializers = [];
@@ -84,6 +150,12 @@ let GfxPrimitiveElementModel = (() => {
             _index_decorators = [field()];
             _externalLink_decorators = [field()];
             _linkedDocId_decorators = [field()];
+            _pivotDocId_decorators = [field()];
+            _role_decorators = [field()];
+            _tags_decorators = [observe(observeTags), field()];
+            _validationExceptions_decorators = [field()];
+            _validationProfile_decorators = [field()];
+            _qualityChecklist_decorators = [field()];
             _lockedBySelf_decorators = [field()];
             _opacity_decorators = [local()];
             _responseExtension_decorators = [local()];
@@ -94,6 +166,12 @@ let GfxPrimitiveElementModel = (() => {
             __esDecorate(this, null, _index_decorators, { kind: "accessor", name: "index", static: false, private: false, access: { has: obj => "index" in obj, get: obj => obj.index, set: (obj, value) => { obj.index = value; } }, metadata: _metadata }, _index_initializers, _index_extraInitializers);
             __esDecorate(this, null, _externalLink_decorators, { kind: "accessor", name: "externalLink", static: false, private: false, access: { has: obj => "externalLink" in obj, get: obj => obj.externalLink, set: (obj, value) => { obj.externalLink = value; } }, metadata: _metadata }, _externalLink_initializers, _externalLink_extraInitializers);
             __esDecorate(this, null, _linkedDocId_decorators, { kind: "accessor", name: "linkedDocId", static: false, private: false, access: { has: obj => "linkedDocId" in obj, get: obj => obj.linkedDocId, set: (obj, value) => { obj.linkedDocId = value; } }, metadata: _metadata }, _linkedDocId_initializers, _linkedDocId_extraInitializers);
+            __esDecorate(this, null, _pivotDocId_decorators, { kind: "accessor", name: "pivotDocId", static: false, private: false, access: { has: obj => "pivotDocId" in obj, get: obj => obj.pivotDocId, set: (obj, value) => { obj.pivotDocId = value; } }, metadata: _metadata }, _pivotDocId_initializers, _pivotDocId_extraInitializers);
+            __esDecorate(this, null, _role_decorators, { kind: "accessor", name: "role", static: false, private: false, access: { has: obj => "role" in obj, get: obj => obj.role, set: (obj, value) => { obj.role = value; } }, metadata: _metadata }, _role_initializers, _role_extraInitializers);
+            __esDecorate(this, null, _tags_decorators, { kind: "accessor", name: "tags", static: false, private: false, access: { has: obj => "tags" in obj, get: obj => obj.tags, set: (obj, value) => { obj.tags = value; } }, metadata: _metadata }, _tags_initializers, _tags_extraInitializers);
+            __esDecorate(this, null, _validationExceptions_decorators, { kind: "accessor", name: "validationExceptions", static: false, private: false, access: { has: obj => "validationExceptions" in obj, get: obj => obj.validationExceptions, set: (obj, value) => { obj.validationExceptions = value; } }, metadata: _metadata }, _validationExceptions_initializers, _validationExceptions_extraInitializers);
+            __esDecorate(this, null, _validationProfile_decorators, { kind: "accessor", name: "validationProfile", static: false, private: false, access: { has: obj => "validationProfile" in obj, get: obj => obj.validationProfile, set: (obj, value) => { obj.validationProfile = value; } }, metadata: _metadata }, _validationProfile_initializers, _validationProfile_extraInitializers);
+            __esDecorate(this, null, _qualityChecklist_decorators, { kind: "accessor", name: "qualityChecklist", static: false, private: false, access: { has: obj => "qualityChecklist" in obj, get: obj => obj.qualityChecklist, set: (obj, value) => { obj.qualityChecklist = value; } }, metadata: _metadata }, _qualityChecklist_initializers, _qualityChecklist_extraInitializers);
             __esDecorate(this, null, _lockedBySelf_decorators, { kind: "accessor", name: "lockedBySelf", static: false, private: false, access: { has: obj => "lockedBySelf" in obj, get: obj => obj.lockedBySelf, set: (obj, value) => { obj.lockedBySelf = value; } }, metadata: _metadata }, _lockedBySelf_initializers, _lockedBySelf_extraInitializers);
             __esDecorate(this, null, _opacity_decorators, { kind: "accessor", name: "opacity", static: false, private: false, access: { has: obj => "opacity" in obj, get: obj => obj.opacity, set: (obj, value) => { obj.opacity = value; } }, metadata: _metadata }, _opacity_initializers, _opacity_extraInitializers);
             __esDecorate(this, null, _responseExtension_decorators, { kind: "accessor", name: "responseExtension", static: false, private: false, access: { has: obj => "responseExtension" in obj, get: obj => obj.responseExtension, set: (obj, value) => { obj.responseExtension = value; } }, metadata: _metadata }, _responseExtension_initializers, _responseExtension_extraInitializers);
@@ -104,8 +182,10 @@ let GfxPrimitiveElementModel = (() => {
             return true;
         }
         get deserializedXYWH() {
-            if (!this._lastXYWH || this.xywh !== this._lastXYWH) {
-                const xywh = this.xywh;
+            // Read `xywh` once: on a group it is a derived getter that may recompute
+            // the union of every child bound, so reading it twice doubles the cost.
+            const xywh = this.xywh;
+            if (!this._lastXYWH || xywh !== this._lastXYWH) {
                 this._local.set('deserializedXYWH', deserializeXYWH(xywh));
                 this._lastXYWH = xywh;
             }
@@ -174,7 +254,13 @@ let GfxPrimitiveElementModel = (() => {
             this.#index_accessor_storage = (__runInitializers(this, _hidden_extraInitializers), __runInitializers(this, _index_initializers, void 0));
             this.#externalLink_accessor_storage = (__runInitializers(this, _index_extraInitializers), __runInitializers(this, _externalLink_initializers, undefined));
             this.#linkedDocId_accessor_storage = (__runInitializers(this, _externalLink_extraInitializers), __runInitializers(this, _linkedDocId_initializers, undefined));
-            this.#lockedBySelf_accessor_storage = (__runInitializers(this, _linkedDocId_extraInitializers), __runInitializers(this, _lockedBySelf_initializers, false));
+            this.#pivotDocId_accessor_storage = (__runInitializers(this, _linkedDocId_extraInitializers), __runInitializers(this, _pivotDocId_initializers, undefined));
+            this.#role_accessor_storage = (__runInitializers(this, _pivotDocId_extraInitializers), __runInitializers(this, _role_initializers, undefined));
+            this.#tags_accessor_storage = (__runInitializers(this, _role_extraInitializers), __runInitializers(this, _tags_initializers, undefined));
+            this.#validationExceptions_accessor_storage = (__runInitializers(this, _tags_extraInitializers), __runInitializers(this, _validationExceptions_initializers, undefined));
+            this.#validationProfile_accessor_storage = (__runInitializers(this, _validationExceptions_extraInitializers), __runInitializers(this, _validationProfile_initializers, undefined));
+            this.#qualityChecklist_accessor_storage = (__runInitializers(this, _validationProfile_extraInitializers), __runInitializers(this, _qualityChecklist_initializers, undefined));
+            this.#lockedBySelf_accessor_storage = (__runInitializers(this, _qualityChecklist_extraInitializers), __runInitializers(this, _lockedBySelf_initializers, false));
             this.#opacity_accessor_storage = (__runInitializers(this, _lockedBySelf_extraInitializers), __runInitializers(this, _opacity_initializers, 1));
             this.#responseExtension_accessor_storage = (__runInitializers(this, _opacity_extraInitializers), __runInitializers(this, _responseExtension_initializers, [0, 0]));
             this.#seed_accessor_storage = (__runInitializers(this, _responseExtension_extraInitializers), __runInitializers(this, _seed_initializers, void 0));
@@ -185,6 +271,12 @@ let GfxPrimitiveElementModel = (() => {
             this.surface = model;
             this._stashed = stashedStore;
             this._onChange = onChange;
+            // DO NOT turn these two into field initializers. `@field()` deliberately
+            // does NOT write an `undefined` default into the Y.Map (see
+            // `./decorators/field.ts`), and both accessors are declared without an
+            // initializer — so these assignments, which go through the SETTER, are the
+            // only reason `index` and `seed` reach the document at all. Losing `index`
+            // would silently corrupt z-order on every new element.
             this.index = 'a0';
             this.seed = randomSeed();
         }
@@ -288,6 +380,63 @@ let GfxPrimitiveElementModel = (() => {
         unlock() {
             unlockElementImpl(this.surface.store, this);
         }
+        /**
+         * Remove an OPTIONAL `@field()` from the document entirely.
+         *
+         * The missing half of `@field()`. Its setter is unconditional — assigning
+         * `undefined` still calls `yMap.set(prop, undefined)` — so "clearing" an
+         * optional field through the accessor leaves the KEY behind. The getter reads
+         * `undefined` and nothing misbehaves, but the element is no longer
+         * byte-identical to one that never had the field: the phantom key syncs to
+         * every peer and ships in every snapshot. `init` is already careful to write
+         * nothing for an `undefined` default; this is how a field gets back to that
+         * state once it has been set.
+         *
+         * Emits a `delete` action rather than an `update`, so a consumer filtering on
+         * `props` will see an EMPTY payload and must inspect `oldValues` — the same
+         * shape an undo of the original write produces.
+         *
+         * ## What it refuses, and why that is load-bearing
+         *
+         * This is a direct write path into the element's Y.Map, on the class that
+         * carries the document format, exported by `@labre/std` and therefore
+         * callable by a host. `_assignElementProp` learned the same lesson in the
+         * unknown-props change (see `docs/spikes/us-1-8-unknown-props-preservation.md`,
+         * whose deny-list is explicitly security rather than hygiene); an unguarded
+         * delete re-opens the door from the other side. So:
+         *
+         * - a key the element class does not DECLARE as a `@field()` is refused. It
+         *   is either an unknown key preserved verbatim for a newer client — deleting
+         *   it is exactly the data loss that change exists to prevent — or not
+         *   document data at all;
+         * - a STRUCTURAL field is refused even though it is declared
+         *   ({@link UNCLEARABLE_ELEMENT_FIELDS}).
+         *
+         * Refusal is a no-op plus a `console.warn`, the same way an unencodable value
+         * is dropped rather than thrown: a misuse must not take the board down, and
+         * must not silently corrupt it either.
+         */
+        clearField(prop) {
+            if (UNCLEARABLE_ELEMENT_FIELDS.has(prop)) {
+                console.warn(`Refusing to clear the structural element field "${prop}": it has no meaningful absent state.`);
+                return;
+            }
+            if (!getFieldPropsSet(this).has(prop)) {
+                console.warn(`Refusing to clear "${prop}": not a declared @field() on this element. Unknown keys are preserved deliberately.`);
+                return;
+            }
+            if (!this.yMap.has(prop))
+                return;
+            if (this.yMap.doc) {
+                this.surface.store.transact(() => {
+                    this.yMap.delete(prop);
+                });
+                // The Y.Map observer prunes `_preserved` on the delete action.
+                return;
+            }
+            this.yMap.delete(prop);
+            this._preserved.delete(prop);
+        }
         #display_accessor_storage;
         get display() { return this.#display_accessor_storage; }
         set display(value) { this.#display_accessor_storage = value; }
@@ -317,6 +466,203 @@ let GfxPrimitiveElementModel = (() => {
         #linkedDocId_accessor_storage;
         get linkedDocId() { return this.#linkedDocId_accessor_storage; }
         set linkedDocId(value) { this.#linkedDocId_accessor_storage = value; }
+        #pivotDocId_accessor_storage;
+        /**
+         * Identity binding to a host-owned **pivot record**: this element is an
+         * *occurrence* of the document `pivotDocId`. Many elements, across many
+         * boards, may carry the same `pivotDocId` — that is the point. A Wardley
+         * `component` drawn on three maps is the same component (MF1, ADR 0005).
+         *
+         * Opaque to the library: the framework never dereferences it, never fetches
+         * it, never renders it. Reading it is the host's job, through
+         * `PivotPropertiesProvider` (`@labre/affine-shared/services`, ADR 0006).
+         * No renderer, no hit-test, no layout and no exporter may read it; it
+         * participates in no `@derive`, `@convert` or `@watch` chain, so it cannot
+         * move, resize or restyle anything.
+         *
+         * Orthogonal to {@link linkedDocId} / {@link externalLink}, which are a
+         * *hyperlink* (navigation), not an identity. They differ on every axis that
+         * matters — cardinality (a hyperlink is one target per element and is
+         * exclusive with `externalLink`; a binding is many-elements-to-one-record),
+         * lifecycle (a hyperlink is picked from a search modal, a binding is created
+         * by promotion) and consumers (an arrow that navigates vs. a hover card and
+         * a rules engine). An element may legitimately carry both, and code reading
+         * one as a stand-in for the other is a bug.
+         *
+         * Declared on the BASE class for the same reason as {@link role}: an element
+         * re-created from props (paste, duplicate, alt-drag clone, template
+         * insertion) only reaches the Y.Map through keys that have a declared
+         * accessor, so a binding declared per subclass would be silently dropped on
+         * copy — and the loss would be invisible until the next reload.
+         *
+         * `undefined` = unbound, and no key is written for it, so an element that
+         * never binds stays byte-identical to one created before the field existed:
+         * optional field, no schema version bump, no migration. Clearing it goes
+         * through {@link clearField}, which removes the key rather than leaving a
+         * tombstone.
+         *
+         * A binding to a record that does not (yet) exist — or was deleted, or is
+         * invisible to this user — is a legal, persisted state: the library never
+         * validates it and never deletes host data. It resolves to `missing` at read
+         * time (ADR 0006).
+         */
+        get pivotDocId() { return this.#pivotDocId_accessor_storage; }
+        set pivotDocId(value) { this.#pivotDocId_accessor_storage = value; }
+        #role_accessor_storage;
+        /**
+         * Semantic role of the element, `<framework>:<role>` (see `./role.ts`).
+         * `undefined` = neutral: generalist elements carry no role, and no key is
+         * written for them at creation.
+         *
+         * Declared on the BASE class on purpose, even though only framework modules
+         * set it: an element re-created from props (paste, duplicate, template
+         * insertion) only reaches the Y.Map through keys that have a declared
+         * accessor, so a role declared per subclass would be silently dropped on
+         * copy. Flat string on purpose — element serialization is one level deep.
+         */
+        get role() { return this.#role_accessor_storage; }
+        set role(value) { this.#role_accessor_storage = value; }
+        #tags_accessor_storage;
+        /**
+         * Level 3 — **contextual qualification** (ADR 0007 § 4). Tag def id → the
+         * value ids selected for it, e.g. `{ 'wardley:nature': ['wardley:nature/data'] }`.
+         *
+         * Both halves of a key are namespaced by framework on purpose: two universes
+         * WILL collide on a word like `activity` — `edgy:activity` is already an EDGY
+         * base element while `activity` is one of Wardley's four natures — and
+         * namespacing is what makes that collision harmless rather than decorative.
+         *
+         * Absent and empty are equivalent (both mean "unqualified"), and the default
+         * is `undefined`, **never** `new Y.Map()`: `@field()`'s `init` writes nothing
+         * for an `undefined` default, so an element that is never qualified — every
+         * brush stroke, every connector — stays byte-identical to one created before
+         * the field existed. A non-`undefined` default on this base class would
+         * reinstate that cost on every element of every document. The qualification
+         * writer (`setElementTag`, `./tags.js`) creates the map on first use and
+         * removes the key again when the last tag goes.
+         *
+         * ## Why a NESTED `Y.Map` and not a plain object
+         *
+         * `@field()` writes straight into the element's `Y.Map` with no `native2Y` in
+         * the path, so a plain object here really would be ONE opaque value: two
+         * people qualifying the same element on two DIFFERENT tags would silently
+         * lose one of the two. A nested map merges per tag, which is what the shape
+         * has to do — there is no migration runner for surface elements, so it is
+         * chosen once. The `string[]` of a SINGLE tag stays last-write-wins, and that
+         * is correct: one tag's value set is one atomic choice.
+         *
+         * Exactly one level of Y-awareness, with plain arrays as values — shallower
+         * than `MindmapElementModel.children` (`Y.Map<NodeDetail>`), which already
+         * ships, and inside what `surface-transformer`'s `SURFACE_YMAP_UNIQ_IDENTIFIER`
+         * envelope round-trips generically.
+         *
+         * Declared on the BASE class for the same reason as {@link role} and
+         * {@link pivotDocId}: an element re-created from props (paste, duplicate,
+         * alt-drag clone, template insertion) only reaches the `Y.Map` through keys
+         * that have a declared accessor, and a qualification the user authored is
+         * exactly the kind of thing that must survive a copy. `SurfaceBlockModel`'s
+         * `_propsToY` rebuilds the map from the plain JSON `serialize()` produces, so
+         * a copy is a copy of the values and never a second reference to one map.
+         *
+         * Opaque to the framework: no renderer, no hit-test, no layout and no
+         * exporter reads it, and it participates in no `@derive` / `@convert` chain.
+         * Values whose def has vanished still load and are displayed as raw ids —
+         * defs are runtime configuration and are NEVER persisted.
+         */
+        get tags() { return this.#tags_accessor_storage; }
+        set tags(value) { this.#tags_accessor_storage = value; }
+        #validationExceptions_accessor_storage;
+        /**
+         * Validation rules this element is excused from (PF8, "no rule is a wall").
+         *
+         * Declared on the BASE class for the same reason as {@link role}: an element
+         * re-created from props (paste, duplicate, template insertion) only reaches
+         * the Y.Map through keys that have a declared accessor, so an exception
+         * declared per subclass would be silently dropped on copy — and an arbitration
+         * the user made explicitly is exactly the kind of thing that must survive a
+         * copy.
+         *
+         * `undefined` = no exception, and no key is written for it, so an element that
+         * never got one stays byte-identical to one created before the field existed:
+         * optional field, no schema version bump, no migration.
+         *
+         * Flat JSON on purpose — element serialization is one level deep, and a value
+         * a Yjs update can encode is the contract enforced by `_assignElementProp`.
+         * The engine that reads it lives in `@labre/affine-block-surface`; the base
+         * model only carries the data, and knows nothing about rules.
+         */
+        get validationExceptions() { return this.#validationExceptions_accessor_storage; }
+        set validationExceptions(value) { this.#validationExceptions_accessor_storage = value; }
+        #validationProfile_accessor_storage;
+        /**
+         * Id of the validation PROFILE this element's framework is checked against
+         * (PF9) — a set of enabled rules and their severities, declared as data by
+         * the framework.
+         *
+         * Carried by the framework's BACKGROUND element, i.e. the root instance, and
+         * not by the document: two maps on one canvas are two independent pieces of
+         * work, and a sketch has to be able to sit next to a deliverable without
+         * either of them dictating the other's requirements (PF9.1). The engine reads
+         * it off the background a finding was measured against, which it already
+         * names (`Violation.backgroundId`).
+         *
+         * Declared on the BASE class for the same reason as {@link role} and
+         * {@link validationExceptions}: an element re-created from props (paste,
+         * duplicate, template insertion) only reaches the Y.Map through keys that
+         * have a declared accessor, so a profile declared per subclass would be
+         * silently dropped on copy — and duplicating a strict map must give a strict
+         * map.
+         *
+         * `undefined` = "no explicit choice", which resolves to the framework's
+         * DEFAULT profile — the most permissive reasonable one, because the sketch
+         * wins. No key is written for it, so a document authored before this field
+         * existed stays byte-identical: optional field, no schema version bump, no
+         * migration. Choosing the default back again removes the key rather than
+         * writing it.
+         *
+         * Flat string on purpose — element serialization is one level deep. The
+         * engine that interprets it lives in `@labre/affine-block-surface`; the base
+         * model only carries the id, and knows nothing about profiles.
+         */
+        get validationProfile() { return this.#validationProfile_accessor_storage; }
+        set validationProfile(value) { this.#validationProfile_accessor_storage = value; }
+        #qualityChecklist_accessor_storage;
+        /**
+         * The map-quality NUDGES the user has ticked off on this instance (PF7.10) —
+         * ids of declarative reminders their framework ships, never rules the engine
+         * evaluates.
+         *
+         * A nudge is an expectation the tool cannot judge ("the map has a title that
+         * frames the study"): the content can exist without being good, so nothing
+         * here is ever computed. Ticking one is the same gesture as granting an
+         * exception — the user says "I have taken care of this" and the tool records
+         * it rather than pretending to check it.
+         *
+         * Carried by the framework's BACKGROUND element, i.e. the root instance, for
+         * the same reason {@link validationProfile} is: two maps on one canvas are two
+         * independent pieces of work, and a checklist ticked on one says nothing about
+         * the other.
+         *
+         * Declared on the BASE class for the same reason as {@link role} and
+         * {@link validationExceptions}: an element re-created from props (paste,
+         * duplicate, template insertion) only reaches the Y.Map through keys that have
+         * a declared accessor, so a checklist declared per subclass would be silently
+         * dropped on copy.
+         *
+         * `undefined` = nothing ticked, and no key is written for it, so a document
+         * authored before this field existed stays byte-identical: optional field, no
+         * schema version bump, no migration. Unticking the last one goes through
+         * {@link clearField}, which removes the key rather than leaving a tombstone.
+         *
+         * Flat JSON — an array of strings — on purpose: element serialization is one
+         * level deep, and a value a Yjs update can encode is the contract enforced by
+         * `_assignElementProp`. The library that interprets the ids lives in
+         * `@labre/affine-block-surface`; the base model only carries them, and knows
+         * nothing about nudges. Ids of nudges no framework declares any more are kept,
+         * not pruned: the tooling comes and goes with a flag, the decision does not.
+         */
+        get qualityChecklist() { return this.#qualityChecklist_accessor_storage; }
+        set qualityChecklist(value) { this.#qualityChecklist_accessor_storage = value; }
         #lockedBySelf_accessor_storage;
         get lockedBySelf() { return this.#lockedBySelf_accessor_storage; }
         set lockedBySelf(value) { this.#lockedBySelf_accessor_storage = value; }
@@ -337,6 +683,17 @@ export class GfxGroupLikeElementModel extends GfxPrimitiveElementModel {
         super(...arguments);
         this._childIds = [];
         this._mutex = createMutex();
+        /**
+         * Whether the cached `xywh` must be recomputed from the children.
+         *
+         * The bound of a group is the union of its children bounds, which used to be
+         * recomputed on **every** read of `xywh` — and `xywh` is read many times per
+         * frame (renderer, hit test, toolbar anchor, selection rect…). It is now
+         * computed once per mutation: the surface marks the group dirty (or
+         * refreshes it eagerly) whenever a child changes, see
+         * {@link invalidateXYWH} / {@link refreshXYWH}.
+         */
+        this._xywhDirty = true;
         this[_a] = true;
     }
     static { _a = gfxGroupCompatibleSymbol; }
@@ -361,26 +718,47 @@ export class GfxGroupLikeElementModel extends GfxPrimitiveElementModel {
     }
     get xywh() {
         this._mutex(() => {
-            const curXYWH = this._local.get('xywh') ?? '[0,0,0,0]';
-            const newXYWH = this._getXYWH().serialize();
-            if (curXYWH !== newXYWH || !this._local.has('xywh')) {
-                this._local.set('xywh', newXYWH);
-                if (curXYWH !== newXYWH) {
-                    this._onChange({
-                        props: {
-                            xywh: newXYWH,
-                        },
-                        oldValues: {
-                            xywh: curXYWH,
-                        },
-                        local: true,
-                    });
-                }
+            if (this._xywhDirty || !this._local.has('xywh')) {
+                this._recomputeXYWH(true);
             }
         });
         return this._local.get('xywh') ?? '[0,0,0,0]';
     }
     set xywh(_) { }
+    /**
+     * Recompute the cached bound and notify the listeners when it moved.
+     *
+     * Always run it through {@link _mutex}: the notification re-enters the
+     * `xywh` getter (a parent group unites this bound again), and the mutex is
+     * what keeps that read from recomputing this very group a second time.
+     */
+    _recomputeXYWH(local) {
+        const oldXYWH = this._local.get('xywh') ?? '[0,0,0,0]';
+        const hadXYWH = this._local.has('xywh');
+        const nextXYWH = this._getXYWH().serialize();
+        this._xywhDirty = false;
+        if (hadXYWH && oldXYWH === nextXYWH) {
+            return;
+        }
+        // Set before notifying: the listeners read `xywh` back, and the mutex
+        // makes that read return the cached value instead of recomputing.
+        this._local.set('xywh', nextXYWH);
+        if (oldXYWH !== nextXYWH) {
+            this._onChange({
+                props: {
+                    xywh: nextXYWH,
+                },
+                oldValues: {
+                    xywh: oldXYWH,
+                },
+                local,
+            });
+        }
+    }
+    /**
+     * Pure: it only reads the children. The cache is written by
+     * {@link _recomputeXYWH}, which is the single place allowed to store it.
+     */
     _getXYWH() {
         let bound;
         this.childElements.forEach(child => {
@@ -389,14 +767,29 @@ export class GfxGroupLikeElementModel extends GfxPrimitiveElementModel {
             }
             bound = bound ? bound.unite(child.elementBound) : child.elementBound;
         });
-        if (bound) {
-            this._local.set('xywh', bound.serialize());
-        }
-        else {
-            this._local.delete('xywh');
-        }
         return bound ?? new Bound(0, 0, 0, 0);
     }
+    /**
+     * Mark the cached bound as stale without recomputing it. The next read of
+     * `xywh` pays for the recomputation, and notifies the listeners if the
+     * bound actually moved.
+     *
+     * Use it for the changes that only *may* move the bound (a custom prop a
+     * subclass folds into its own `elementBound`); use {@link refreshXYWH} for
+     * the changes that are known to move it.
+     */
+    invalidateXYWH() {
+        this._xywhDirty = true;
+    }
+    /**
+     * Recompute the cached bound right away, and notify the listeners when it
+     * moved. `local` is the origin of the mutation that moved it.
+     */
+    refreshXYWH(local) {
+        this._mutex(() => {
+            this._recomputeXYWH(local);
+        });
+    }
     /**
      * The actual field that stores the children of the group.
      * It should be a ymap decorated with `@field`.
@@ -418,6 +811,7 @@ export class GfxGroupLikeElementModel extends GfxPrimitiveElementModel {
     setChildIds(value, fromLocal) {
         const oldChildIds = this.childIds;
         this._childIds = value;
+        this.invalidateXYWH();
         this._onChange({
             props: {
                 childIds: value,
@@ -446,12 +840,29 @@ export function syncElementFromY(model, callback) {
                     disposables[key]?.();
                     disposables[key] = watchText(key, value, callback);
                 }
+                // A nested Y type declared with `@observe` gets a FRESH instance every
+                // time the key itself is rewritten — by a remote peer, or by undo/redo,
+                // neither of which goes through the accessor's setter (the only other
+                // caller of `startObserve`). Without this the observer is left on a
+                // detached type and every later in-place mutation goes unseen: set a
+                // tag, undo, redo, set another one, and the second write is invisible
+                // to the publisher. Guarded on identity so re-setting the same instance
+                // does not needlessly re-run the observer's initialising call.
+                if (model['_preserved'].get(key) !== value &&
+                    hasObserveMeta(key, model)) {
+                    startObserve(key, model);
+                }
                 model['_preserved'].set(key, value);
                 props[key] = value;
                 oldValues[key] = oldValue;
             }
             else {
+                // `_preserved` is pruned FIRST: `startObserve` re-reads the accessor,
+                // which falls back to `_preserved`, so the other order would re-attach
+                // the observer to the very map that has just been deleted.
                 model['_preserved'].delete(key);
+                if (hasObserveMeta(key, model))
+                    startObserve(key, model);
                 oldValues[key] = oldValue;
             }
         });

package/dist/_pkgs/std/gfx/model/surface/pivot.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Backlinks over `pivotDocId` — **computed, never persisted** (MF1, ADR 0005 § 5).
+ *
+ * The library ships one pure, synchronous collector and nothing else: no index,
+ * no reverse map, no cache, and nothing written back into the document. That is
+ * not an optimisation left for later, it is the invariant: "which boards
+ * mention this component" is a recomputation, always, so it can never drift
+ * from the document and can never be corrupted by a bad write — because there
+ * is no write.
+ *
+ * Cross-document aggregation ("every board where this component appears") is
+ * the host's job, built from per-document calls to
+ * {@link collectPivotOccurrences}. The repository has no backlink
+ * infrastructure and this module deliberately does not introduce one.
+ */
+import type { GfxPrimitiveElementModel } from './element-model.js';
+import type { SurfaceBlockModel } from './surface-model.js';
+/** One element that is an occurrence of one pivot record. */
+export type PivotOccurrence = {
+    /** The bound pivot record. */
+    pivotDocId: string;
+    /** The surface element that is an occurrence of it. */
+    elementId: string;
+    /** Element type, e.g. `'shape'`, `'wardleyNode'`, `'edgyNode'`. */
+    elementType: string;
+};
+/** A surface element whose binding is known to be present. */
+export type PivotBoundElement = GfxPrimitiveElementModel & {
+    pivotDocId: string;
+};
+/**
+ * Whether the element carries a binding. Narrowing type guard, so a caller that
+ * has checked does not have to re-assert the string.
+ *
+ * An empty string is NOT a binding: `@field()` writes whatever it is given, and
+ * a host that passes `''` means "none". Treating it as a record id would send
+ * the provider looking for a document that cannot exist.
+ */
+export declare function isPivotBound(el: GfxPrimitiveElementModel): el is PivotBoundElement;
+/**
+ * Every occurrence on one surface, in element order. O(n) over the surface's
+ * elements; allocates nothing persistent.
+ *
+ * @param pivotDocId Restrict to one record. Omitted, every bound element is
+ *   returned — which is what a host rebuilding its derived state wants
+ *   (ADR 0006 § 4.2: the element is always the source of truth).
+ */
+export declare function collectPivotOccurrences(surface: SurfaceBlockModel, pivotDocId?: string): PivotOccurrence[];

package/dist/_pkgs/std/gfx/model/surface/pivot.js

@@ -0,0 +1,34 @@
+/**
+ * Whether the element carries a binding. Narrowing type guard, so a caller that
+ * has checked does not have to re-assert the string.
+ *
+ * An empty string is NOT a binding: `@field()` writes whatever it is given, and
+ * a host that passes `''` means "none". Treating it as a record id would send
+ * the provider looking for a document that cannot exist.
+ */
+export function isPivotBound(el) {
+    return typeof el.pivotDocId === 'string' && el.pivotDocId.length > 0;
+}
+/**
+ * Every occurrence on one surface, in element order. O(n) over the surface's
+ * elements; allocates nothing persistent.
+ *
+ * @param pivotDocId Restrict to one record. Omitted, every bound element is
+ *   returned — which is what a host rebuilding its derived state wants
+ *   (ADR 0006 § 4.2: the element is always the source of truth).
+ */
+export function collectPivotOccurrences(surface, pivotDocId) {
+    const occurrences = [];
+    for (const element of surface.elementModels) {
+        if (!isPivotBound(element))
+            continue;
+        if (pivotDocId !== undefined && element.pivotDocId !== pivotDocId)
+            continue;
+        occurrences.push({
+            pivotDocId: element.pivotDocId,
+            elementId: element.id,
+            elementType: element.type,
+        });
+    }
+    return occurrences;
+}