@formicoidea/labre-core 0.41.0 → 0.42.0

package/dist/_pkgs/affine-model/elements/index.js

@@ -14,4 +14,5 @@ export * from './highlighter/index.js';
 export * from './mindmap/index.js';
 export * from './shape/index.js';
 export * from './text/index.js';
+export * from './uml/index.js';
 export * from './wardley/index.js';

package/dist/_pkgs/affine-model/elements/shape/shape.js

@@ -164,7 +164,7 @@ let ShapeElementModel = (() => {
             _isClosed_decorators = [field()];
             _smoothFlags_decorators = [field(null)];
             _controlPoints_decorators = [field()];
-            _xywh_decorators = [field()];
+            _xywh_decorators = [field('[0,0,0,0]')];
             __esDecorate(this, null, _color_decorators, { kind: "accessor", name: "color", static: false, private: false, access: { has: obj => "color" in obj, get: obj => obj.color, set: (obj, value) => { obj.color = value; } }, metadata: _metadata }, _color_initializers, _color_extraInitializers);
             __esDecorate(this, null, _fillColor_decorators, { kind: "accessor", name: "fillColor", static: false, private: false, access: { has: obj => "fillColor" in obj, get: obj => obj.fillColor, set: (obj, value) => { obj.fillColor = value; } }, metadata: _metadata }, _fillColor_initializers, _fillColor_extraInitializers);
             __esDecorate(this, null, _filled_decorators, { kind: "accessor", name: "filled", static: false, private: false, access: { has: obj => "filled" in obj, get: obj => obj.filled, set: (obj, value) => { obj.filled = value; } }, metadata: _metadata }, _filled_initializers, _filled_extraInitializers);

package/dist/_pkgs/affine-model/elements/text/text.js

@@ -81,7 +81,7 @@ let TextElementModel = (() => {
             _rotate_decorators = [field(0)];
             _text_decorators = [field()];
             _textAlign_decorators = [field()];
-            _xywh_decorators = [field()];
+            _xywh_decorators = [field('[0,0,0,0]')];
             __esDecorate(this, null, _color_decorators, { kind: "accessor", name: "color", static: false, private: false, access: { has: obj => "color" in obj, get: obj => obj.color, set: (obj, value) => { obj.color = value; } }, metadata: _metadata }, _color_initializers, _color_extraInitializers);
             __esDecorate(this, null, _fontFamily_decorators, { kind: "accessor", name: "fontFamily", static: false, private: false, access: { has: obj => "fontFamily" in obj, get: obj => obj.fontFamily, set: (obj, value) => { obj.fontFamily = value; } }, metadata: _metadata }, _fontFamily_initializers, _fontFamily_extraInitializers);
             __esDecorate(this, null, _fontSize_decorators, { kind: "accessor", name: "fontSize", static: false, private: false, access: { has: obj => "fontSize" in obj, get: obj => obj.fontSize, set: (obj, value) => { obj.fontSize = value; } }, metadata: _metadata }, _fontSize_initializers, _fontSize_extraInitializers);

package/dist/_pkgs/affine-model/elements/uml/band.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The NAME BAND carve-out, shared by the UML backgrounds that wear one.
+ *
+ * A framework background is picked by its BORDER and nothing else (issue #194),
+ * which is what keeps a transparent frame from stealing the clicks meant for
+ * what it is drawn round. Every frame that writes its name in a STRIP of its
+ * own then has to carve that strip back in, or the words are unreachable: a
+ * single click on them would select nothing at all.
+ *
+ * `UmlDiagramElementModel.includesPoint` was the first to do it and states the
+ * argument in full. This module is the same arithmetic, lifted out when the
+ * activity PARTITION (§15.6.4) and the state-machine REGION (§14.2.4) each
+ * arrived wanting it — and wanting it on two different edges, the partition's
+ * band following its own `orientation`. Three inline copies of a rotation
+ * unwind is three places for one of them to be fixed.
+ *
+ * The diagram frame keeps its own copy: it is a RED ZONE file whose hit test is
+ * pinned by a spec written against it, and rewriting a shipped carve-out to
+ * share code with a new one buys nothing a reader can see.
+ */
+/** What a band test needs of an element: its box and its rotation. */
+export interface UmlBandGeometry {
+    deserializedXYWH: readonly number[];
+    rotate?: number;
+}
+/**
+ * Whether a CANVAS point lies in the leading band of an element — the strip
+ * along its top edge (`'top'`) or along its left edge (`'left'`).
+ *
+ * The band is axis-aligned INSIDE the element, never on the canvas, so the
+ * element rotation is undone about the centre before anything is measured:
+ * without that the strip would stay pinned to the top of the screen while the
+ * name it is meant to pick turned away with the frame.
+ *
+ * Clamped to an element smaller than its own band, which is the degenerate case
+ * a renderer clamps too: an unclamped strip would hang off a squashed frame and
+ * pick it from empty canvas.
+ */
+export declare function umlInNameBand(model: UmlBandGeometry, side: 'top' | 'left', band: number, x: number, y: number): boolean;

package/dist/_pkgs/affine-model/elements/uml/band.js

@@ -0,0 +1,31 @@
+import { rotatePoint } from '../../../global/gfx/index.js';
+/**
+ * Whether a CANVAS point lies in the leading band of an element — the strip
+ * along its top edge (`'top'`) or along its left edge (`'left'`).
+ *
+ * The band is axis-aligned INSIDE the element, never on the canvas, so the
+ * element rotation is undone about the centre before anything is measured:
+ * without that the strip would stay pinned to the top of the screen while the
+ * name it is meant to pick turned away with the frame.
+ *
+ * Clamped to an element smaller than its own band, which is the degenerate case
+ * a renderer clamps too: an unclamped strip would hang off a squashed frame and
+ * pick it from empty canvas.
+ */
+export function umlInNameBand(model, side, band, x, y) {
+    const [ex, ey, w, h] = model.deserializedXYWH;
+    if (!(w > 0) || !(h > 0) || !(band > 0))
+        return false;
+    // Element-local coordinates, undoing the element rotation about its centre.
+    let lx = x - ex;
+    let ly = y - ey;
+    const rotate = model.rotate ?? 0;
+    if (rotate) {
+        const [ux, uy] = rotatePoint([x, y], [ex + w / 2, ey + h / 2], -rotate);
+        lx = ux - ex;
+        ly = uy - ey;
+    }
+    if (lx < 0 || lx > w || ly < 0 || ly > h)
+        return false;
+    return side === 'top' ? ly <= Math.min(band, h) : lx <= Math.min(band, w);
+}

package/dist/_pkgs/affine-model/elements/uml/diagram.d.ts

@@ -0,0 +1,158 @@
+import type { SerializedXYWH } from '../../../global/gfx/index.js';
+import type { PointTestOptions } from '../../../std/gfx/index.js';
+import type { FrameworkBackgroundProps } from '../framework-background/index.js';
+import { FrameworkBackgroundElementModel } from '../framework-background/index.js';
+/**
+ * Height of the diagram frame's heading band — the strip across the top of the
+ * frame the `<kind> <name>` tag is written in, in model units.
+ *
+ * Declared HERE, in the model, and re-exported by `@labre/affine-gfx-uml`
+ * rather than the other way round, for the reason `C4_BOARD_TITLE_BAND_HEIGHT`
+ * is: the frame's own hit test needs it (a diagram is clickable by its heading
+ * band as well as by its border), and `affine-model` cannot reach into
+ * `affine-block-surface` where the declaration is resolved. One number, owned
+ * by the layer that both the declaration and the hit test can read.
+ *
+ * It is the frame's TOP MARGIN — the inset the drawing gives up so the heading
+ * has somewhere to be written — so the strip that is painted, the strip that is
+ * picked and the strip that opens the rename are one number rather than three.
+ *
+ * 44 is the height of the cut-corner tag UML 2.5.1 Annex A draws the heading
+ * in: a 20-unit label with the rest as breathing room above and below.
+ * Changing it moves the heading, so it is a visual decision and not a hit-test
+ * one.
+ */
+export declare const UML_FRAME_BAND_HEIGHT = 44;
+/**
+ * Which kind of UML diagram this frame draws — the DECLARED fact, as opposed to
+ * the name, which is free text and says whatever its author wants it to.
+ *
+ * ## Where the values come from
+ *
+ * UML 2.5.1 Annex A gives the normative frame kind names, each with the
+ * abbreviation that may be written in its place:
+ *
+ *  - `activity` / `act`;
+ *  - `class` — the one kind Annex A gives NO abbreviation for, so the word
+ *    itself is the tag;
+ *  - `component` / `cmp`;
+ *  - `deployment` / `dep`;
+ *  - `interaction` / `sd`;
+ *  - `package` / `pkg`;
+ *  - `state machine` / `stm`;
+ *  - `use case` / `uc`.
+ *
+ * `obj` is NOT in that list. Annex A has no frame kind for the object diagram —
+ * the standard treats it as a class diagram showing instances — but every tool
+ * that draws one tags it `obj`, and an architect reading the sheet expects to
+ * see it. So `obj` is kept as a TOOL CONVENTION, recorded as such here so that
+ * nobody later "fixes" it against the spec without knowing it was a choice.
+ *
+ * ## Widening this union is additive
+ *
+ * Phase 1 shipped the first four kinds below; phase 2 APPENDED `cmp` and `dep`,
+ * the two structural frames of §11.6.4 and §19.2.4, then `act` and `stm`, the
+ * two behaviour frames of §15.2.4 and §14.2.4; phase 3 appends `sd`. Each
+ * arrives as a new VALUE of the existing `kind`
+ * string field — no new field, no schema change, no migration and no backfill.
+ * The same promise `C4NodeKind` and `BpmnNodeKind` already make.
+ *
+ * Appended, never reordered: the union is read as a set of strings by every
+ * consumer, and a document only ever stores one of them, so the ORDER below is a
+ * reading aid. Keeping it chronological is what lets a reviewer see at a glance
+ * which build a value arrived in.
+ *
+ * A value a client has never seen reads back as the string it is, and
+ * {@link UmlDiagramElementModel.heading} writes it verbatim, so a document
+ * created by a newer build still shows its own heading on an older one.
+ */
+export type UmlDiagramKind = 'class' | 'pkg' | 'obj' | 'uc' | 'cmp' | 'dep' | 'act' | 'stm' | 'sd';
+/**
+ * The word written in the heading tag, per kind.
+ *
+ * A table rather than the raw value so that a kind whose stored discriminant
+ * and whose printed tag ever diverge has one place to say so. Today they are
+ * the same four strings, and that is worth stating rather than assuming.
+ *
+ * `Partial` on purpose: a frame read off a document carries whatever string was
+ * written there, including a kind from a later phase this build has never heard
+ * of. Typing the lookup as total would make {@link
+ * UmlDiagramElementModel.heading}'s `?? this.kind` fallback look like dead
+ * defensive code, when it is the whole of the append-only promise.
+ */
+export declare const UML_DIAGRAM_KIND_TAG: Partial<Record<UmlDiagramKind, string>>;
+export type UmlDiagramProps = FrameworkBackgroundProps & {
+    /** The diagram name, written in the heading tag — edited inline on dblclick. */
+    name?: string;
+    /** Which kind of UML diagram this frame draws. */
+    kind?: UmlDiagramKind;
+};
+/**
+ * The UML diagram frame: the sheet one diagram is drawn on — a class diagram, a
+ * package diagram, an object diagram, a use case diagram, a component diagram, a
+ * deployment diagram. A framework
+ * background like every other one in the library: the user drops nodes on top
+ * of it, and a connector never snaps to it.
+ *
+ * It carries a NAME and a KIND, and the two are written together in the
+ * cut-corner tag at its top left, exactly as UML 2.5.1 Annex A draws it. That
+ * shared frame notation is the whole reason UML ships as ONE framework with a
+ * kind on the board rather than one framework per diagram family (ADR 0017):
+ * the kinds share a sheet and a heading, and they mix on it.
+ *
+ * What it LOOKS like is declared, not coded: see `UML_DIAGRAM_BACKGROUND` in
+ * `@labre/affine-gfx-uml`.
+ */
+export declare class UmlDiagramElementModel extends FrameworkBackgroundElementModel<UmlDiagramProps> {
+    get type(): string;
+    accessor name: string;
+    /**
+     * Which kind of diagram this frame draws — REQUIRED, unlike the C4 board's
+     * `level`, which is optional.
+     *
+     * The difference is what the field is for. A C4 board's level is a claim
+     * about the model an author may decline to make, so an absent one means "a
+     * free sketch". A UML frame's kind is part of its NOTATION: Annex A's heading
+     * is `<kind> <name>`, and a frame with no kind has no heading to draw. So it
+     * has a default, and `class` is the one — the diagram an architect reaches
+     * for first, and the only kind Annex A gives no abbreviation for.
+     */
+    accessor kind: UmlDiagramKind;
+    accessor resizeEnabled: boolean;
+    accessor rotate: number;
+    accessor xywh: SerializedXYWH;
+    /**
+     * The heading written in the cut-corner tag: `<kind> <name>`.
+     *
+     * DERIVED, not stored. Nothing here reaches the document: the two halves are
+     * `kind` and `name`, and a rename edits `name` alone — so there is one place
+     * a heading can be changed from, and nothing to keep in step with it.
+     *
+     * A kind this client does not know — a phase-2 value on a phase-1 build — is
+     * written VERBATIM rather than dropped or replaced by the default. The tag
+     * table is a spelling aid, not a gate: a newer document still shows its own
+     * heading here, which is the visible half of the append-only promise
+     * {@link UmlDiagramKind} makes.
+     */
+    get heading(): string;
+    /**
+     * A frame is picked by its BORDER — and by its HEADING BAND, the one carve-out
+     * it keeps.
+     *
+     * The same carve-out a C4 board makes, for the same reason and by the same
+     * arithmetic: the band is the only part of the sheet that is the SHEET rather
+     * than the diagram drawn on it. The heading is written there, nothing is ever
+     * dropped there by convention, and the drawing below is where the work goes —
+     * so a click there belongs to whatever node is under the pointer.
+     *
+     * Without this the heading would be unreachable, backgrounds being picked by
+     * their border band alone: the only thing left answering would be the view's
+     * double-click zone, which is the tight box of the DRAWN glyphs, and a single
+     * click on the heading would select nothing at all.
+     *
+     * The band is the top margin, full width — one number
+     * ({@link UML_FRAME_BAND_HEIGHT}), read from here by the framework
+     * declaration, so what is painted is what is selectable.
+     */
+    includesPoint(x: number, y: number, options?: PointTestOptions): boolean;
+}

package/dist/_pkgs/affine-model/elements/uml/diagram.js

@@ -0,0 +1,229 @@
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+import { rotatePoint } from '../../../global/gfx/index.js';
+import { field } from '../../../std/gfx/index.js';
+import { FrameworkBackgroundElementModel } from '../framework-background/index.js';
+/**
+ * Height of the diagram frame's heading band — the strip across the top of the
+ * frame the `<kind> <name>` tag is written in, in model units.
+ *
+ * Declared HERE, in the model, and re-exported by `@labre/affine-gfx-uml`
+ * rather than the other way round, for the reason `C4_BOARD_TITLE_BAND_HEIGHT`
+ * is: the frame's own hit test needs it (a diagram is clickable by its heading
+ * band as well as by its border), and `affine-model` cannot reach into
+ * `affine-block-surface` where the declaration is resolved. One number, owned
+ * by the layer that both the declaration and the hit test can read.
+ *
+ * It is the frame's TOP MARGIN — the inset the drawing gives up so the heading
+ * has somewhere to be written — so the strip that is painted, the strip that is
+ * picked and the strip that opens the rename are one number rather than three.
+ *
+ * 44 is the height of the cut-corner tag UML 2.5.1 Annex A draws the heading
+ * in: a 20-unit label with the rest as breathing room above and below.
+ * Changing it moves the heading, so it is a visual decision and not a hit-test
+ * one.
+ */
+export const UML_FRAME_BAND_HEIGHT = 44;
+/**
+ * The word written in the heading tag, per kind.
+ *
+ * A table rather than the raw value so that a kind whose stored discriminant
+ * and whose printed tag ever diverge has one place to say so. Today they are
+ * the same four strings, and that is worth stating rather than assuming.
+ *
+ * `Partial` on purpose: a frame read off a document carries whatever string was
+ * written there, including a kind from a later phase this build has never heard
+ * of. Typing the lookup as total would make {@link
+ * UmlDiagramElementModel.heading}'s `?? this.kind` fallback look like dead
+ * defensive code, when it is the whole of the append-only promise.
+ */
+export const UML_DIAGRAM_KIND_TAG = {
+    class: 'class',
+    pkg: 'pkg',
+    obj: 'obj',
+    uc: 'uc',
+    // Both are Annex A's own abbreviations, written exactly as the Annex writes
+    // them — `cmp` for the component diagram, `dep` for the deployment diagram.
+    cmp: 'cmp',
+    dep: 'dep',
+    // Annex A's own abbreviations again — `act` for the activity diagram, `stm`
+    // for the state machine diagram. `stm` is the one tag in the table that is
+    // NOT the kind spelled out: Annex A's frame kind is the two words `state
+    // machine`, and `stm` is the abbreviation it gives in their place.
+    act: 'act',
+    stm: 'stm',
+    // Annex A's abbreviation for the interaction frame, and the third tag in the
+    // table that is not the kind spelled out: the frame kind is `interaction`.
+    sd: 'sd',
+};
+/**
+ * The UML diagram frame: the sheet one diagram is drawn on — a class diagram, a
+ * package diagram, an object diagram, a use case diagram, a component diagram, a
+ * deployment diagram. A framework
+ * background like every other one in the library: the user drops nodes on top
+ * of it, and a connector never snaps to it.
+ *
+ * It carries a NAME and a KIND, and the two are written together in the
+ * cut-corner tag at its top left, exactly as UML 2.5.1 Annex A draws it. That
+ * shared frame notation is the whole reason UML ships as ONE framework with a
+ * kind on the board rather than one framework per diagram family (ADR 0017):
+ * the kinds share a sheet and a heading, and they mix on it.
+ *
+ * What it LOOKS like is declared, not coded: see `UML_DIAGRAM_BACKGROUND` in
+ * `@labre/affine-gfx-uml`.
+ */
+let UmlDiagramElementModel = (() => {
+    let _classSuper = FrameworkBackgroundElementModel;
+    let _name_decorators;
+    let _name_initializers = [];
+    let _name_extraInitializers = [];
+    let _kind_decorators;
+    let _kind_initializers = [];
+    let _kind_extraInitializers = [];
+    let _resizeEnabled_decorators;
+    let _resizeEnabled_initializers = [];
+    let _resizeEnabled_extraInitializers = [];
+    let _rotate_decorators;
+    let _rotate_initializers = [];
+    let _rotate_extraInitializers = [];
+    let _xywh_decorators;
+    let _xywh_initializers = [];
+    let _xywh_extraInitializers = [];
+    return class UmlDiagramElementModel extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _name_decorators = [field('Diagram')];
+            _kind_decorators = [field('class')];
+            _resizeEnabled_decorators = [field(true)];
+            _rotate_decorators = [field(0)];
+            _xywh_decorators = [field()];
+            __esDecorate(this, null, _name_decorators, { kind: "accessor", name: "name", static: false, private: false, access: { has: obj => "name" in obj, get: obj => obj.name, set: (obj, value) => { obj.name = value; } }, metadata: _metadata }, _name_initializers, _name_extraInitializers);
+            __esDecorate(this, null, _kind_decorators, { kind: "accessor", name: "kind", static: false, private: false, access: { has: obj => "kind" in obj, get: obj => obj.kind, set: (obj, value) => { obj.kind = value; } }, metadata: _metadata }, _kind_initializers, _kind_extraInitializers);
+            __esDecorate(this, null, _resizeEnabled_decorators, { kind: "accessor", name: "resizeEnabled", static: false, private: false, access: { has: obj => "resizeEnabled" in obj, get: obj => obj.resizeEnabled, set: (obj, value) => { obj.resizeEnabled = value; } }, metadata: _metadata }, _resizeEnabled_initializers, _resizeEnabled_extraInitializers);
+            __esDecorate(this, null, _rotate_decorators, { kind: "accessor", name: "rotate", static: false, private: false, access: { has: obj => "rotate" in obj, get: obj => obj.rotate, set: (obj, value) => { obj.rotate = value; } }, metadata: _metadata }, _rotate_initializers, _rotate_extraInitializers);
+            __esDecorate(this, null, _xywh_decorators, { kind: "accessor", name: "xywh", static: false, private: false, access: { has: obj => "xywh" in obj, get: obj => obj.xywh, set: (obj, value) => { obj.xywh = value; } }, metadata: _metadata }, _xywh_initializers, _xywh_extraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        get type() {
+            return 'umlDiagram';
+        }
+        #name_accessor_storage = __runInitializers(this, _name_initializers, 'Diagram');
+        get name() { return this.#name_accessor_storage; }
+        set name(value) { this.#name_accessor_storage = value; }
+        #kind_accessor_storage = (__runInitializers(this, _name_extraInitializers), __runInitializers(this, _kind_initializers, 'class'));
+        /**
+         * Which kind of diagram this frame draws — REQUIRED, unlike the C4 board's
+         * `level`, which is optional.
+         *
+         * The difference is what the field is for. A C4 board's level is a claim
+         * about the model an author may decline to make, so an absent one means "a
+         * free sketch". A UML frame's kind is part of its NOTATION: Annex A's heading
+         * is `<kind> <name>`, and a frame with no kind has no heading to draw. So it
+         * has a default, and `class` is the one — the diagram an architect reaches
+         * for first, and the only kind Annex A gives no abbreviation for.
+         */
+        get kind() { return this.#kind_accessor_storage; }
+        set kind(value) { this.#kind_accessor_storage = value; }
+        #resizeEnabled_accessor_storage = (__runInitializers(this, _kind_extraInitializers), __runInitializers(this, _resizeEnabled_initializers, true));
+        get resizeEnabled() { return this.#resizeEnabled_accessor_storage; }
+        set resizeEnabled(value) { this.#resizeEnabled_accessor_storage = value; }
+        #rotate_accessor_storage = (__runInitializers(this, _resizeEnabled_extraInitializers), __runInitializers(this, _rotate_initializers, 0));
+        get rotate() { return this.#rotate_accessor_storage; }
+        set rotate(value) { this.#rotate_accessor_storage = value; }
+        #xywh_accessor_storage = (__runInitializers(this, _rotate_extraInitializers), __runInitializers(this, _xywh_initializers, '[0,0,1400,900]'));
+        get xywh() { return this.#xywh_accessor_storage; }
+        set xywh(value) { this.#xywh_accessor_storage = value; }
+        /**
+         * The heading written in the cut-corner tag: `<kind> <name>`.
+         *
+         * DERIVED, not stored. Nothing here reaches the document: the two halves are
+         * `kind` and `name`, and a rename edits `name` alone — so there is one place
+         * a heading can be changed from, and nothing to keep in step with it.
+         *
+         * A kind this client does not know — a phase-2 value on a phase-1 build — is
+         * written VERBATIM rather than dropped or replaced by the default. The tag
+         * table is a spelling aid, not a gate: a newer document still shows its own
+         * heading here, which is the visible half of the append-only promise
+         * {@link UmlDiagramKind} makes.
+         */
+        get heading() {
+            return `${UML_DIAGRAM_KIND_TAG[this.kind] ?? this.kind} ${this.name}`.trim();
+        }
+        /**
+         * A frame is picked by its BORDER — and by its HEADING BAND, the one carve-out
+         * it keeps.
+         *
+         * The same carve-out a C4 board makes, for the same reason and by the same
+         * arithmetic: the band is the only part of the sheet that is the SHEET rather
+         * than the diagram drawn on it. The heading is written there, nothing is ever
+         * dropped there by convention, and the drawing below is where the work goes —
+         * so a click there belongs to whatever node is under the pointer.
+         *
+         * Without this the heading would be unreachable, backgrounds being picked by
+         * their border band alone: the only thing left answering would be the view's
+         * double-click zone, which is the tight box of the DRAWN glyphs, and a single
+         * click on the heading would select nothing at all.
+         *
+         * The band is the top margin, full width — one number
+         * ({@link UML_FRAME_BAND_HEIGHT}), read from here by the framework
+         * declaration, so what is painted is what is selectable.
+         */
+        includesPoint(x, y, options) {
+            if (super.includesPoint(x, y, options))
+                return true;
+            const [ex, ey, w, h] = this.deserializedXYWH;
+            // Element-local coordinates, undoing the element rotation about its centre
+            // — the band is axis-aligned inside the frame, not on the canvas.
+            let lx = x - ex;
+            let ly = y - ey;
+            const rotate = this.rotate ?? 0;
+            if (rotate) {
+                const [ux, uy] = rotatePoint([x, y], [ex + w / 2, ey + h / 2], -rotate);
+                lx = ux - ex;
+                ly = uy - ey;
+            }
+            if (lx < 0 || lx > w || ly < 0)
+                return false;
+            // Clamped to a frame shorter than its own heading — the degenerate case the
+            // renderer clamps too.
+            return ly <= Math.min(UML_FRAME_BAND_HEIGHT, h);
+        }
+        constructor() {
+            super(...arguments);
+            __runInitializers(this, _xywh_extraInitializers);
+        }
+    };
+})();
+export { UmlDiagramElementModel };

package/dist/_pkgs/affine-model/elements/uml/fragment.d.ts

@@ -0,0 +1,161 @@
+import type { SerializedXYWH } from '../../../global/gfx/index.js';
+import type { PointTestOptions } from '../../../std/gfx/index.js';
+import type { FrameworkBackgroundProps } from '../framework-background/index.js';
+import { FrameworkBackgroundElementModel } from '../framework-background/index.js';
+/**
+ * Height of a combined fragment's OPERATOR BAND — the strip across its top the
+ * pentagon tag is drawn in, in model units.
+ *
+ * Owned by the model for the reason {@link UML_FRAME_BAND_HEIGHT} is: the
+ * fragment's own hit test reads it (a fragment is clickable by its tag strip as
+ * well as by its border), and `affine-model` cannot reach into
+ * `affine-block-surface` where the declaration is resolved.
+ *
+ * The diagram frame's own 44, and deliberately: §17.6.4 draws the operator in
+ * the very same cut-corner pentagon Annex A draws a frame heading in — it IS a
+ * frame, nested in another one — and two numbers for one piece of furniture
+ * would drift.
+ */
+export declare const UML_FRAGMENT_BAND = 44;
+/**
+ * The INTERACTION OPERATOR of a combined fragment — the word written in its
+ * pentagon, and the whole of what the fragment says (UML 2.5.1 §17.6.4).
+ *
+ * The twelve operators of §17.6.4 plus `ref`, and the thirteenth is the one
+ * that is not an operator at all: §17.7.4's InteractionUse is a different
+ * metaclass drawn as the same rectangle with the same pentagon, and every tool
+ * offers it from the same menu. Keeping it here is what lets one element, one
+ * renderer and one toolbar cover both — the alternative being a second
+ * background that differs from this one by a string.
+ *
+ * Widened the way every other UML union is: appended, never reordered, and read
+ * back as whatever string the document carries. A fragment whose operator this
+ * build has never heard of still paints its rectangle and still writes its own
+ * word in the tag.
+ */
+export type UmlFragmentOperator = 'alt' | 'opt' | 'loop' | 'par' | 'break' | 'critical' | 'seq' | 'strict' | 'neg' | 'assert' | 'ignore' | 'consider' | 'ref';
+/**
+ * One OPERAND of a combined fragment — a horizontal band of it, separated from
+ * the next by a dashed line (§17.6.4).
+ *
+ * The shape of a `BackgroundInstanceZoneItem` in `@labre/affine-block-surface`,
+ * and deliberately the same three fields as {@link BpmnLane}: the primitive
+ * paints an instance partition from that structure, the audit reports it from
+ * that structure, and an operand with a shape of its own would be a fourth
+ * place the two have to agree.
+ *
+ * `name` is the operand's GUARD — `[x > 0]`, `[else]` — because that is the
+ * only thing §17.6.4 writes in an operand's own corner. `size` is a relative
+ * WEIGHT and not a height in model units: a fragment dragged taller
+ * redistributes the space between its operands instead of leaving a gap under
+ * the last one.
+ */
+export interface UmlFragmentOperand {
+    /** Stable id, generated at creation. Never the guard: a guard is rewritten. */
+    id: string;
+    /** The operand's guard, written in its top-left corner. */
+    name?: string;
+    /** Relative weight — see above. Must be a finite number greater than zero. */
+    size: number;
+}
+export type UmlFragmentProps = FrameworkBackgroundProps & {
+    /** Which operator the pentagon writes. */
+    operator?: UmlFragmentOperator;
+    /** The first operand's guard, or a `ref`'s interaction name. */
+    name?: string;
+    /** The fragment's partition into operands. Absent until a second is added. */
+    operands?: UmlFragmentOperand[];
+};
+/**
+ * A COMBINED FRAGMENT — the rectangle drawn round part of a sequence diagram
+ * with an operator in its corner (UML 2.5.1 §17.6.4), and, under the `ref`
+ * operator, the InteractionUse of §17.7.4.
+ *
+ * A framework background, and a TRANSPARENT one, like
+ * {@link UmlSubjectElementModel} and {@link UmlPartitionElementModel}: it is
+ * drawn OVER lifelines and messages that are already there, and an opaque card
+ * would hide the very conversation it is qualifying. Membership — which
+ * messages are inside the `alt`, which lifelines it covers — is geometry at
+ * read time (R11), never a stored list.
+ *
+ * ## Why the operator is a field and the operands are not elements
+ *
+ * The operator IS the fragment: `alt` and `loop` are the same rectangle saying
+ * two entirely different things, and nothing in the picture distinguishes them
+ * but the word. So it is stored, with `alt` as the default — the fragment an
+ * architect reaches for first, and the one §17.6.4 opens with.
+ *
+ * The operands are bands of that one rectangle, and they follow the BPMN pool's
+ * lanes exactly: an optional flat array, `undefined` rather than `[]` until the
+ * first one is added, so a fragment with a single operand stays byte-identical
+ * to one written before the field existed. The trade the pool's own note
+ * states applies here unchanged — two peers reordering the operands at the same
+ * moment resolve last-write-wins, one whole list winning over the other — and
+ * it is stated so it is reviewed rather than discovered.
+ *
+ * What it LOOKS like is declared, not coded: see `UML_FRAGMENT_FRAME` in
+ * `@labre/affine-gfx-uml`.
+ */
+export declare class UmlFragmentElementModel extends FrameworkBackgroundElementModel<UmlFragmentProps> {
+    get type(): string;
+    /**
+     * The operator — REQUIRED, with `alt` as the default, for the reason
+     * `UmlDiagramElementModel.kind` is required: it is part of the NOTATION
+     * rather than a claim an author may decline to make. A fragment with no
+     * operator has no word to write in its pentagon, and a pentagon with nothing
+     * in it is a rectangle with a bitten corner.
+     */
+    accessor operator: UmlFragmentOperator;
+    /**
+     * The first operand's guard, or — under `ref` — the name of the interaction
+     * being referred to.
+     *
+     * Seeded EMPTY, unlike every other UML frame's name: §17.6.4 draws a guard
+     * only where there is one to draw, and `[alt]` with an empty bracket under it
+     * would be the notation inventing a condition the author has not written. An
+     * empty string keeps the field in the document (the `@field` default is
+     * written) without putting words on the page.
+     */
+    accessor name: string;
+    accessor resizeEnabled: boolean;
+    accessor rotate: number;
+    /**
+     * Wide enough to cover three lifelines at the 200-unit spacing a sequence
+     * diagram is laid out on, and tall enough for three or four exchanges — the
+     * size an `alt` is actually drawn round.
+     */
+    accessor xywh: SerializedXYWH;
+    /**
+     * The fragment's partition into operands, top to bottom.
+     *
+     * `undefined`, not `[]`, and for the three reasons `BpmnPoolElementModel
+     * .lanes` states in full: `@field()` writes nothing for an undefined default,
+     * so a fragment with a single operand — which is every `opt`, every `loop`
+     * and every `ref` — is byte-identical to one created before this field
+     * existed; the value is flat JSON because a list of operands is one atomic
+     * choice about how one fragment is cut; and it is declared here rather than
+     * on the base class because an operand is a subdivision of a combined
+     * fragment and of nothing else.
+     *
+     * What it MEANS is declared, not coded: `UML_FRAGMENT_FRAME.instanceZones`
+     * in `@labre/affine-gfx-uml` names this prop, and the framework-background
+     * primitive paints the separators and the guards from it.
+     */
+    accessor operands: UmlFragmentOperand[] | undefined;
+    /**
+     * Picked by its BORDER — and by its OPERATOR BAND, the one carve-out it
+     * keeps.
+     *
+     * The same carve-out the diagram frame, the partition and the composite state
+     * all make, and for the same reason: the band is the only part of the
+     * fragment that is the FRAGMENT rather than the conversation drawn inside it.
+     * Without it the pentagon would be unreachable, a background being picked by
+     * its border alone — and a transparent fragment's border is a thin line round
+     * a region full of other people's messages.
+     *
+     * Nothing below the band is claimed, which matters here as much as on a
+     * partition: a fragment is drawn OVER lifelines, so every point that is not
+     * its own furniture has to fall through to whatever is under the pointer.
+     */
+    includesPoint(x: number, y: number, options?: PointTestOptions): boolean;
+}