@formicoidea/labre-core 0.31.0 → 0.33.0

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

@@ -41,7 +41,55 @@ 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,27 @@ 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 _interchange_decorators;
+    let _interchange_initializers = [];
+    let _interchange_extraInitializers = [];
     let _lockedBySelf_decorators;
     let _lockedBySelf_initializers = [];
     let _lockedBySelf_extraInitializers = [];
@@ -84,6 +153,13 @@ 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()];
+            _interchange_decorators = [field()];
             _lockedBySelf_decorators = [field()];
             _opacity_decorators = [local()];
             _responseExtension_decorators = [local()];
@@ -94,6 +170,13 @@ 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, _interchange_decorators, { kind: "accessor", name: "interchange", static: false, private: false, access: { has: obj => "interchange" in obj, get: obj => obj.interchange, set: (obj, value) => { obj.interchange = value; } }, metadata: _metadata }, _interchange_initializers, _interchange_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 +187,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 +259,14 @@ 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.#interchange_accessor_storage = (__runInitializers(this, _qualityChecklist_extraInitializers), __runInitializers(this, _interchange_initializers, undefined));
+            this.#lockedBySelf_accessor_storage = (__runInitializers(this, _interchange_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 +277,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 +386,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 +472,271 @@ 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; }
+        #interchange_accessor_storage;
+        /**
+         * Verbatim foreign matter from an interchange import, keyed by FORMAT id
+         * (`bpmn`, `owm`, …) — never by framework, because a `.bpmn` and an OWM file
+         * make different promises about the same element (ADR 0012 § D2).
+         *
+         * This field is dumb storage, and that is the whole design. ADR 0012 sorts
+         * every node of an imported file into three states — **mapped** (there is a
+         * Labre artefact, re-emitted from the drawing), **carried** (no artefact,
+         * kept verbatim here, re-emitted in place) and **quarantined** (kept, but
+         * re-emitting it would contradict the document, so it is not). That contract
+         * lives entirely in the importers and exporters; the base model neither
+         * classifies, validates, dereferences nor re-emits anything, and knows no
+         * format. No renderer, hit-test, layout or `@derive` / `@convert` chain reads
+         * it, so nothing here can move, resize or restyle an element.
+         *
+         * Declared on the BASE class for the same reason as {@link role} and
+         * {@link validationExceptions}, and for one more: a BPMN `sequenceFlow`
+         * carrying a `conditionExpression` is a plain **connector**, and
+         * `ConnectorElementModel` is shared plumbing that will never be a BPMN class.
+         * 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 payload declared per subclass would be silently
+         * dropped on copy — the exact loss `docs/spikes/us-1-8-unknown-props-preservation.md`
+         * exists to prevent. Declaring it, rather than leaning on that spike's
+         * verbatim fallback for undeclared keys, is what makes it a contract: a field
+         * nothing declares is a field nothing can test, strip or find.
+         *
+         * `undefined` = this element never met an import, and no key is written for
+         * it, so it stays byte-identical to one created before the field existed:
+         * optional field, no schema version bump, no migration. An import writes no
+         * key for a visual-tier capability, and none for an element that carried
+         * nothing. Clearing goes through {@link clearField}, which removes the key
+         * rather than leaving a tombstone.
+         *
+         * Flat JSON on purpose — a value a Yjs update can encode is the contract
+         * enforced by `_assignElementProp`, and the whole payload is ONE Y.Map entry,
+         * written once at import and never mutated afterwards. Two peers writing it
+         * concurrently therefore resolve last-write-wins on the whole blob, which is
+         * `lanes`' trade (ADR 0007): nobody edits this value, so the window is the
+         * import itself.
+         *
+         * ## Writing it, for the importer
+         *
+         * - **Write the whole blob in one assignment**, the way an import already
+         *   produces it. Never read-modify-write it key by key: the Y.Map entry is the
+         *   entire `Record`, so a partial update is still a last-write-wins overwrite
+         *   of everything, and two of them racing lose a whole format's payload rather
+         *   than merging.
+         * - **Key what you carry by its {@link InterchangeScope}.** One Labre element
+         *   stands for several source elements, and an unscoped map lets what came off
+         *   one overwrite what came off another — a silent loss, into a persisted
+         *   value, of exactly the data this field exists to keep. The scope is also
+         *   the only record of where a fragment has to be put back.
+         * - **Write no key at all** when there is nothing to carry — an element the
+         *   import mapped cleanly, or any visual-tier capability, which by contract
+         *   writes none (ADR 0012 P2). Absent and empty are NOT equivalent here:
+         *   `{}` costs every element a Y.Map entry and makes P2's "writes no
+         *   `interchange` key" untestable.
+         * - **Removing it is {@link clearField}**, never an assignment to `undefined`
+         *   — the former deletes the key, the latter can leave a tombstone.
+         * - **Nothing caps the size of this value** (ADR 0012, open question 3). A
+         *   pathological file would produce a document that is mostly foreign matter;
+         *   a cap that dropped data would contradict D2, so the only honest cap is a
+         *   refusal at import time. That is the importer's call, not the model's.
+         */
+        get interchange() { return this.#interchange_accessor_storage; }
+        set interchange(value) { this.#interchange_accessor_storage = value; }
         #lockedBySelf_accessor_storage;
         get lockedBySelf() { return this.#lockedBySelf_accessor_storage; }
         set lockedBySelf(value) { this.#lockedBySelf_accessor_storage = value; }
@@ -337,6 +757,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 +792,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 +841,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 +885,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 +914,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;
             }
         });