@formicoidea/labre-core 0.32.0 → 0.34.1

package/dist/_pkgs/std/gfx/highlight.d.ts

@@ -0,0 +1,84 @@
+import { Signal } from '@preact/signals-core';
+import type { GfxController } from './controller.js';
+import { GfxExtension } from './extension.js';
+import type { GfxModel } from './model/model.js';
+/**
+ * How long a highlight stays visible when no `duration` is given.
+ */
+export declare const DEFAULT_HIGHLIGHT_DURATION = 2000;
+/**
+ * Viewport padding used when `reframe` is requested without an explicit one.
+ * Expressed in percentage of the viewport (see `Viewport.setViewportByBound`).
+ */
+export declare const DEFAULT_HIGHLIGHT_PADDING: [number, number, number, number];
+export interface HighlightElementsOptions {
+    /**
+     * Reframe the viewport on the union of the target bounds before emphasizing
+     * them. Defaults to `false`, the highlight is then purely visual.
+     */
+    reframe?: boolean;
+    /**
+     * How long the emphasis stays visible, in milliseconds.
+     * Defaults to {@link DEFAULT_HIGHLIGHT_DURATION}.
+     * Pass `0` to keep it until the next `highlightElements` or `clear` call.
+     */
+    duration?: number;
+    /**
+     * Padding applied by the reframe, only used when `reframe` is `true`.
+     * Defaults to {@link DEFAULT_HIGHLIGHT_PADDING}.
+     */
+    padding?: [number, number, number, number];
+    /**
+     * Animate the reframe, only used when `reframe` is `true`. Defaults to `true`.
+     */
+    smooth?: boolean;
+}
+/**
+ * Transient, read-only emphasis on a set of graphic elements.
+ *
+ * The manager owns the state only: it never writes to the store and never
+ * touches the selection model, so it is safe on a read-only or non-interactive
+ * editor (an embedded preview window, for instance). The actual ring is drawn
+ * by a renderer subscribing to {@link ElementHighlightManager.highlighted$},
+ * which keeps this extension free of any rendering concern.
+ */
+export declare class ElementHighlightManager extends GfxExtension {
+    static key: string;
+    private _timer;
+    /**
+     * Ids of the elements currently emphasized. Empty when nothing is
+     * highlighted. Only ids that resolved to an actual graphic element at call
+     * time are kept.
+     */
+    readonly highlighted$: Signal<readonly string[]>;
+    /**
+     * The models behind {@link highlighted$}, resolved on read so that elements
+     * deleted meanwhile simply drop out of the highlight.
+     */
+    get highlightedElements(): GfxModel[];
+    static extendGfx(gfx: GfxController): void;
+    private _clearTimer;
+    /**
+     * Drop the current emphasis immediately.
+     */
+    clear(): void;
+    /**
+     * Emphasize the given elements for a while.
+     *
+     * Unknown ids and non-graphic blocks are ignored; if none of the ids
+     * resolves, any running highlight is cleared and nothing else happens.
+     * Calling it again replaces the previous highlight and restarts the timer.
+     */
+    highlightElements(ids: string[], opts?: HighlightElementsOptions): void;
+    unmounted(): void;
+}
+declare module './controller.js' {
+    interface GfxController {
+        readonly highlight: ElementHighlightManager;
+        /**
+         * Transiently emphasize a set of elements without mutating the document
+         * nor the selection. Shorthand for `gfx.highlight.highlightElements`.
+         */
+        highlightElements(ids: string[], opts?: HighlightElementsOptions): void;
+    }
+}

package/dist/_pkgs/std/gfx/highlight.js

@@ -0,0 +1,112 @@
+import { getCommonBoundWithRotation } from '../../global/gfx/index.js';
+import { Signal } from '@preact/signals-core';
+import { GfxExtension, GfxExtensionIdentifier } from './extension.js';
+import { GfxBlockElementModel } from './model/gfx-block-model.js';
+import { GfxPrimitiveElementModel } from './model/surface/element-model.js';
+/**
+ * How long a highlight stays visible when no `duration` is given.
+ */
+export const DEFAULT_HIGHLIGHT_DURATION = 2000;
+/**
+ * Viewport padding used when `reframe` is requested without an explicit one.
+ * Expressed in percentage of the viewport (see `Viewport.setViewportByBound`).
+ */
+export const DEFAULT_HIGHLIGHT_PADDING = [
+    0.15, 0.15, 0.15, 0.15,
+];
+/**
+ * Only models that live on the canvas can carry an emphasis ring.
+ * Anything else queried by id (plain blocks, unknown ids) is ignored.
+ */
+function isRenderableGfxModel(model) {
+    return (model instanceof GfxPrimitiveElementModel ||
+        model instanceof GfxBlockElementModel);
+}
+/**
+ * Transient, read-only emphasis on a set of graphic elements.
+ *
+ * The manager owns the state only: it never writes to the store and never
+ * touches the selection model, so it is safe on a read-only or non-interactive
+ * editor (an embedded preview window, for instance). The actual ring is drawn
+ * by a renderer subscribing to {@link ElementHighlightManager.highlighted$},
+ * which keeps this extension free of any rendering concern.
+ */
+export class ElementHighlightManager extends GfxExtension {
+    constructor() {
+        super(...arguments);
+        this._timer = null;
+        /**
+         * Ids of the elements currently emphasized. Empty when nothing is
+         * highlighted. Only ids that resolved to an actual graphic element at call
+         * time are kept.
+         */
+        this.highlighted$ = new Signal([]);
+    }
+    static { this.key = 'elementHighlight'; }
+    /**
+     * The models behind {@link highlighted$}, resolved on read so that elements
+     * deleted meanwhile simply drop out of the highlight.
+     */
+    get highlightedElements() {
+        return this.highlighted$.value
+            .map(id => this.gfx.getElementById(id))
+            .filter(isRenderableGfxModel);
+    }
+    static extendGfx(gfx) {
+        Object.defineProperty(gfx, 'highlight', {
+            get() {
+                return this.std.get(GfxExtensionIdentifier('elementHighlight'));
+            },
+        });
+        Object.defineProperty(gfx, 'highlightElements', {
+            value: (ids, opts) => gfx.highlight.highlightElements(ids, opts),
+        });
+    }
+    _clearTimer() {
+        if (this._timer !== null) {
+            clearTimeout(this._timer);
+            this._timer = null;
+        }
+    }
+    /**
+     * Drop the current emphasis immediately.
+     */
+    clear() {
+        this._clearTimer();
+        if (this.highlighted$.peek().length === 0)
+            return;
+        this.highlighted$.value = [];
+    }
+    /**
+     * Emphasize the given elements for a while.
+     *
+     * Unknown ids and non-graphic blocks are ignored; if none of the ids
+     * resolves, any running highlight is cleared and nothing else happens.
+     * Calling it again replaces the previous highlight and restarts the timer.
+     */
+    highlightElements(ids, opts = {}) {
+        this._clearTimer();
+        const elements = ids
+            .map(id => this.gfx.getElementById(id))
+            .filter(isRenderableGfxModel);
+        if (elements.length === 0) {
+            this.highlighted$.value = [];
+            return;
+        }
+        if (opts.reframe) {
+            this.gfx.viewport.setViewportByBound(getCommonBoundWithRotation(elements), opts.padding ?? DEFAULT_HIGHLIGHT_PADDING, opts.smooth ?? true);
+        }
+        this.highlighted$.value = elements.map(element => element.id);
+        const duration = opts.duration ?? DEFAULT_HIGHLIGHT_DURATION;
+        if (duration > 0) {
+            this._timer = setTimeout(() => {
+                this._timer = null;
+                this.clear();
+            }, duration);
+        }
+    }
+    unmounted() {
+        this._clearTimer();
+        this.highlighted$.value = [];
+    }
+}

package/dist/_pkgs/std/gfx/index.d.ts

@@ -5,6 +5,7 @@ export { GfxController } from './controller.js';
 export type { CursorType, StandardCursor } from './cursor.js';
 export { GfxExtension, GfxExtensionIdentifier } from './extension.js';
 export { GridManager } from './grid.js';
+export { DEFAULT_HIGHLIGHT_DURATION, DEFAULT_HIGHLIGHT_PADDING, ElementHighlightManager, type HighlightElementsOptions, } from './highlight.js';
 export { GfxControllerIdentifier } from './identifiers.js';
 export type { BoxSelectionContext, DragEndContext, DragExtensionInitializeContext, DragInitializationOption, DragMoveContext, DragStartContext, ExtensionDragEndContext, ExtensionDragMoveContext, ExtensionDragStartContext, GfxInteractivityContext, GfxViewInteractionConfig, ResizeConstraint, ResizeEndContext, ResizeHandle, ResizeMoveContext, ResizeStartContext, RotateConstraint, RotateEndContext, RotateMoveContext, RotateStartContext, SelectContext, } from './interactivity/index.js';
 export { GfxViewEventManager, GfxViewInteractionExtension, InteractivityExtension, InteractivityIdentifier, InteractivityManager, } from './interactivity/index.js';
@@ -14,7 +15,7 @@ export { gfxGroupCompatibleSymbol, isGfxGroupCompatibleModel, } from './model/ba
 export { GfxBlockElementModel, type GfxCommonBlockProps, GfxCompatibleBlockModel as GfxCompatible, type GfxCompatibleProps, } from './model/gfx-block-model.js';
 export { type GfxModel, isPrimitiveModel } from './model/model.js';
 export { convert, convertProps, derive, field, getDerivedProps, getFieldPropsSet, getLocalPropsSet, initializeObservers, initializeWatchers, local, observe, updateDerivedProps, watch, } from './model/surface/decorators/index.js';
-export { type BaseElementProps, GfxGroupLikeElementModel, GfxPrimitiveElementModel, type SerializedElement, type ValidationException, } from './model/surface/element-model.js';
+export { type BaseElementProps, type ForeignInterchange, type InterchangeScope, GfxGroupLikeElementModel, GfxPrimitiveElementModel, type SerializedElement, type ValidationException, } from './model/surface/element-model.js';
 export { GfxLocalElementModel, prop, } from './model/surface/local-element-model.js';
 export { collectPivotOccurrences, isPivotBound, type PivotBoundElement, type PivotOccurrence, } from './model/surface/pivot.js';
 export { type EdgeDirectionDef, findRoleDef, isTypedEdgeRole, type RoleDef, type RoleDefs, type RoleId, roleIsA, type RoleKind, RoleVocabularyExtension, RoleVocabularyIdentifier, } from './model/surface/role.js';

package/dist/_pkgs/std/gfx/index.js

@@ -4,6 +4,7 @@ export { batchAddChildren, batchRemoveChildren, canSafeAddToContainer, descendan
 export { GfxController } from './controller.js';
 export { GfxExtension, GfxExtensionIdentifier } from './extension.js';
 export { GridManager } from './grid.js';
+export { DEFAULT_HIGHLIGHT_DURATION, DEFAULT_HIGHLIGHT_PADDING, ElementHighlightManager, } from './highlight.js';
 export { GfxControllerIdentifier } from './identifiers.js';
 export { GfxViewEventManager, GfxViewInteractionExtension, InteractivityExtension, InteractivityIdentifier, InteractivityManager, } from './interactivity/index.js';
 export { LayerManager } from './layer.js';

package/dist/_pkgs/std/gfx/interactivity/gfx-view-event-handler.js

@@ -51,15 +51,29 @@ export class GfxViewEventManager {
             filter: ['canvas', 'local'],
         })
             .reduce((pre, model) => {
-            if (model.includesPoint(x, y, {
+            const view = this.gfx.view.get(model);
+            if (!view)
+                return pre;
+            // The VIEW's hit test, not the model's.
+            //
+            // `GfxElementModelView.includesPoint` delegates to the model by
+            // default, so for every view that does not override it this is the
+            // same answer as before. It is the seam a framework needs when the
+            // area that SELECTS an element and the area that its own gestures
+            // answer on are not the same rectangle: a framework background is
+            // picked by its border alone (issue #194), yet its editable labels
+            // must keep receiving the double-click that renames them, and a BPMN
+            // pool's lane separators must keep receiving the drag that moves them.
+            // Those zones are drawn by the framework's view, so that is where they
+            // are declared — the model layer stays free of geometry it cannot see.
+            if (view.includesPoint(x, y, {
                 hitThreshold: 10,
                 responsePadding: [5, 5],
             }, this.gfx.std.host) ||
                 ('externalBound' in model
                     ? model.externalBound?.isPointInBound([x, y])
                     : false)) {
-                const view = this.gfx.view.get(model);
-                view && pre.push(view);
+                pre.push(view);
             }
             return pre;
         }, [])

package/dist/_pkgs/std/gfx/model/surface/element-model.d.ts

@@ -34,6 +34,100 @@ export type ValidationException = {
     /** Epoch ms, taken at the moment of the gesture. */
     at: number;
 };
+/**
+ * A SCOPE: which part of the source document a carried fragment came off.
+ *
+ * One Labre element routinely stands for several source elements — a BPMN pool
+ * is a `participant` AND its `process`, plus a `laneSet`, every `lane`, the
+ * `BPMNShape` that draws it, and (for the first pool of a document) the
+ * `collaboration` and `definitions` themselves. Everything they carry lands in
+ * ONE payload, so an unscoped `Record<name, value>` has two defects, and the
+ * first one destroys data: two lanes carrying the same foreign attribute
+ * overwrite each other silently, and nothing records which element an attribute
+ * belonged to, so no exporter can ever put it back where it came from.
+ *
+ * A scope is therefore either of exactly two things, and they cannot collide:
+ *
+ * - **the source element's id, verbatim** — the normal case, and the one that
+ *   lets an exporter put a fragment back on the element that had it;
+ * - **an `@`-prefixed ROLE key** for a source element with no id of its own, or
+ *   one whose identity is its relation to this element rather than a name:
+ *   `@self` (the element this payload is on), `@shape` (the diagram element
+ *   that draws it), and whatever else the format needs. **`@` is not an XML
+ *   NameStartChar**, so a role key can never be mistaken for an id, whatever a
+ *   file calls its elements.
+ *
+ * The role vocabulary past `@self` and `@shape` belongs to each format's
+ * importer, which is the only thing that knows what parts a document has;
+ * `.bpmn`'s is documented in `gfx/bpmn/src/import.ts`. The base model stores
+ * strings and never learns what any of them mean.
+ */
+export type InterchangeScope = string;
+/**
+ * Verbatim foreign matter one interchange import kept on one element, for one
+ * format (ADR 0012 § D2).
+ *
+ * Document DATA in the same sense {@link ValidationException} is: it records
+ * what a file actually said, so it outlives the tab, the framework flag and the
+ * client version that imported it. Deliberately format-agnostic — the base
+ * model stores fragments and attributes, and never learns what they mean.
+ *
+ * Every member is optional and absent rather than empty: an importer writes the
+ * ones it has, and a reader that finds none of them has an element that met an
+ * import and carried nothing.
+ *
+ * The three carrying members are keyed by {@link InterchangeScope}, so that
+ * what came off two different source elements stays apart. That shape is what
+ * makes the payload sufficient for re-emission, and it is the one thing here
+ * that could not be changed later: this value is persisted, so a document
+ * written under a shape that loses data cannot be repaired without the original
+ * file. One `Y.Map` entry all the same — the whole record is written once, as a
+ * blob, and never mutated.
+ */
+export type ForeignInterchange = {
+    /**
+     * The element's id in the SOURCE file, verbatim. The surface element keeps
+     * its own nanoid — surface identity is Labre's and never the file's — and an
+     * export prefers this id back when it is still usable, which is what makes
+     * the id map a fixed point after one cycle (ADR 0012 § D3).
+     */
+    id?: string;
+    /**
+     * The source element's name, when the element itself was CARRIED rather than
+     * mapped, e.g. `bpmn:boundaryEvent`.
+     */
+    element?: string;
+    /**
+     * Attributes the importer does not model — foreign-namespaced and standard
+     * alike — by {@link InterchangeScope}, then by attribute name.
+     *
+     * `{ 'Lane_1': { 'camunda:owner': 'alice' }, 'Lane_2': { 'camunda:owner':
+     * 'bob' } }`: two lanes of one pool, two owners, and both still here.
+     */
+    attrs?: Record<InterchangeScope, Record<string, string>>;
+    /**
+     * Child fragments, serialized — extension subtrees, unmodelled children, and
+     * whole carried elements — by the {@link InterchangeScope} of the element
+     * they were children OF. The scope is where an exporter has to put them back.
+     */
+    children?: Record<InterchangeScope, string[]>;
+    /**
+     * Diagram-interchange fragments, by the {@link InterchangeScope} of what they
+     * draw: `@shape` for the parts of this element's own diagram element that the
+     * importer did not model, a source id for the diagram of something carried.
+     */
+    di?: Record<InterchangeScope, string[]>;
+    /**
+     * Fragments kept but deliberately NOT re-emitted, each with the reason
+     * (ADR 0012 § D5). Preserved so a reader can see what was dropped and why;
+     * never a place the exporter reads for output — which is why this one is a
+     * flat list and needs no scope: nothing has to know where to put it back.
+     */
+    quarantined?: {
+        fragment: string;
+        reason: string;
+    }[];
+};
 export type SerializedElement = Record<string, unknown> & {
     type: string;
     xywh: SerializedXYWH;
@@ -351,6 +445,72 @@ export declare abstract class GfxPrimitiveElementModel<Props extends BaseElement
      * not pruned: the tooling comes and goes with a flag, the decision does not.
      */
     accessor qualityChecklist: string[] | undefined;
+    /**
+     * 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.
+     */
+    accessor interchange: Record<string, ForeignInterchange> | undefined;
     accessor lockedBySelf: boolean | undefined;
     accessor opacity: number;
     accessor responseExtension: [number, number];

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

@@ -127,6 +127,9 @@ let GfxPrimitiveElementModel = (() => {
     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 = [];
@@ -156,6 +159,7 @@ let GfxPrimitiveElementModel = (() => {
             _validationExceptions_decorators = [field()];
             _validationProfile_decorators = [field()];
             _qualityChecklist_decorators = [field()];
+            _interchange_decorators = [field()];
             _lockedBySelf_decorators = [field()];
             _opacity_decorators = [local()];
             _responseExtension_decorators = [local()];
@@ -172,6 +176,7 @@ let GfxPrimitiveElementModel = (() => {
             __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);
@@ -260,7 +265,8 @@ let GfxPrimitiveElementModel = (() => {
             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.#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));
@@ -663,6 +669,74 @@ let GfxPrimitiveElementModel = (() => {
          */
         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; }

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

@@ -20,9 +20,11 @@
  */
 import { createIdentifier } from '../../../../global/di/index.js';
 /**
- * Deepest specialisation chain {@link roleIsA} walks. Real vocabularies are
- * one or two levels deep; the bound exists so a malformed `parent` cycle
- * cannot hang the caller. Chains longer than this are NOT supported.
+ * Deepest specialisation chain {@link roleIsA} walks. Real vocabularies run two
+ * or three levels deep — BPMN's descriptive profile is three on two branches
+ * (`bpmn:message-start-event` → `bpmn:start-event` → `bpmn:event`) — and the
+ * bound is far above them, so that a malformed `parent` cycle cannot hang the
+ * caller. Chains longer than this are NOT supported.
  */
 const MAX_ROLE_DEPTH = 32;
 /**

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

@@ -67,7 +67,8 @@ const UNSAFE_ELEMENT_PROP_KEYS = new Set([
  * (data descriptor, no setter) and a getter-only accessor both answer `false`.
  */
 function isDeclaredElementProp(element, key) {
-    if (getFieldPropsSet(element).has(key) || getLocalPropsSet(element).has(key)) {
+    if (getFieldPropsSet(element).has(key) ||
+        getLocalPropsSet(element).has(key)) {
         return true;
     }
     for (let proto = Object.getPrototypeOf(element); proto !== null; proto = Object.getPrototypeOf(proto)) {

package/dist/_pkgs/std/gfx/selection.js

@@ -1,5 +1,5 @@
 import { DisposableGroup } from '../../global/disposable/index.js';
-import { getCommonBoundWithRotation, } from '../../global/gfx/index.js';
+import { getCommonBoundWithRotation } from '../../global/gfx/index.js';
 import { assertType } from '../../global/utils/index.js';
 import groupBy from 'lodash-es/groupBy.js';
 import { Subject } from 'rxjs';

package/dist/_pkgs/std/gfx/viewport.js

@@ -1,4 +1,4 @@
-import { Bound, clamp, Vec, } from '../../global/gfx/index.js';
+import { Bound, clamp, Vec } from '../../global/gfx/index.js';
 import debounce from 'lodash-es/debounce.js';
 import { BehaviorSubject, debounceTime, Subject } from 'rxjs';
 function cutoff(value, ref, sign) {

package/dist/_pkgs/std/inline/extensions/inline-manager.js

@@ -1,4 +1,4 @@
-import { createIdentifier, } from '../../../global/di/index.js';
+import { createIdentifier } from '../../../global/di/index.js';
 import { baseTextAttributes, } from '../../../store/index.js';
 import { z } from 'zod';
 import { StdIdentifier } from '../../identifier.js';

package/dist/_pkgs/std/inline/extensions/markdown-matcher.js

@@ -1,4 +1,4 @@
-import { createIdentifier, } from '../../../global/di/index.js';
+import { createIdentifier } from '../../../global/di/index.js';
 export const MarkdownMatcherIdentifier = createIdentifier('AffineMarkdownMatcher');
 export function InlineMarkdownExtension(matcher) {
     const identifier = MarkdownMatcherIdentifier(matcher.name);

package/dist/_pkgs/std/scope/std-scope.d.ts

@@ -5,6 +5,7 @@ import { CommandManager } from '../command/index.js';
 import { UIEventDispatcher } from '../event/index.js';
 import { DndController } from '../extension/dnd/index.js';
 import { ServiceManager } from '../extension/service-manager.js';
+import { ElementHighlightManager } from '../gfx/highlight.js';
 import { GridManager, LayerManager } from '../gfx/index.js';
 import { GfxSelectionManager } from '../gfx/selection.js';
 import { SurfaceMiddlewareExtension } from '../gfx/surface-middleware.js';
@@ -17,7 +18,7 @@ export interface BlockStdOptions {
     extensions: ExtensionType[];
 }
 export declare class BlockStdScope {
-    static internalExtensions: (typeof ViewStore | typeof UIEventDispatcher | typeof RangeManager | typeof CommandManager | typeof GridManager | typeof LayerManager | typeof ServiceManager | typeof GfxSelectionManager | typeof SurfaceMiddlewareExtension | typeof ViewManager)[];
+    static internalExtensions: (typeof ViewStore | typeof UIEventDispatcher | typeof RangeManager | typeof CommandManager | typeof GridManager | typeof LayerManager | typeof ServiceManager | typeof ElementHighlightManager | typeof GfxSelectionManager | typeof SurfaceMiddlewareExtension | typeof ViewManager)[];
     readonly container: Container;
     readonly store: Store;
     readonly provider: ServiceProvider;

package/dist/_pkgs/std/scope/std-scope.js

@@ -8,6 +8,7 @@ import { DndController } from '../extension/dnd/index.js';
 import { EditorLifeCycleExtension } from '../extension/editor-life-cycle.js';
 import { ServiceManager } from '../extension/service-manager.js';
 import { GfxController } from '../gfx/controller.js';
+import { ElementHighlightManager } from '../gfx/highlight.js';
 import { GridManager, LayerManager } from '../gfx/index.js';
 import { GfxSelectionManager } from '../gfx/selection.js';
 import { SurfaceMiddlewareExtension } from '../gfx/surface-middleware.js';
@@ -25,6 +26,7 @@ const internalExtensions = [
     Clipboard,
     GfxController,
     GfxSelectionManager,
+    ElementHighlightManager,
     GridManager,
     LayerManager,
     SurfaceMiddlewareExtension,

package/dist/_pkgs/std/utils/gfx.js

@@ -1,5 +1,7 @@
 import { effect } from '@preact/signals-core';
 import { SurfaceBlockModel } from '../gfx/model/surface/surface-model.js';
+// The explicit return type keeps declaration emit off signals-core's
+// `DisposeFn`, whose `[Symbol.dispose]` member tsc cannot serialize.
 export function onSurfaceAdded(doc, callback) {
     let found = false;
     let foundId = '';