@formicoidea/labre-core 0.41.0 → 0.43.1

package/dist/_pkgs/affine-model/elements/connector/connector.d.ts

@@ -5,6 +5,7 @@ import { GfxPrimitiveElementModel } from '../../../std/gfx/index.js';
 import * as Y from 'yjs';
 import { ConnectorLabelOffsetAnchor, ConnectorMode, type PointStyle, StrokeStyle, type TextStyleProps } from '../../consts/index.js';
 import { type Color } from '../../themes/index.js';
+import { type ConnectorLabelEnd } from './end-label.js';
 export type SerializedConnection = {
     id?: string;
     position?: `[${number},${number}]` | PointLocation;
@@ -30,6 +31,16 @@ export type ConnectorLabelProps = {
     labelOffset?: ConnectorLabelOffsetProps;
     labelStyle?: TextStyleProps;
     labelConstraints?: ConnectorLabelConstraintsProps;
+    /**
+     * The two END labels — a multiplicity, a role name, a qualifier — each
+     * anchored beside the endpoint it belongs to. See ADR 0020; they are FLAT
+     * rather than two nested records for the reason spelled out on the
+     * accessors.
+     */
+    sourceLabel?: Y.Text;
+    sourceLabelXYWH?: XYWH;
+    targetLabel?: Y.Text;
+    targetLabelXYWH?: XYWH;
 };
 export type SerializedConnectorElement = SerializedElement & {
     source: SerializedConnection;
@@ -78,6 +89,73 @@ export declare class ConnectorElementModel extends GfxPrimitiveElementModel<Conn
     getPointByOffsetDistance(offsetDistance?: number, bounds?: Bound): IVec;
     getRelativePointLocation(point: IVec): PointLocation;
     hasLabel(): boolean;
+    /** The content of one end's label, or `undefined` when it has none. */
+    endLabelText(end: ConnectorLabelEnd): Y.Text | undefined;
+    /** The box of one end's label, or `undefined` when nothing placed it yet. */
+    endLabelXYWH(end: ConnectorLabelEnd): XYWH | undefined;
+    /**
+     * Whether one end carries a label that should be PAINTED — the end-label
+     * twin of `hasLabel()`, gated on the same `labelDisplay` (one switch hides
+     * every caption on a connector, which is what the toolbar's toggle means)
+     * and on `endLabelEditing` instead of `labelEditing`, so mounting the editor
+     * on one end does not blank the other two labels.
+     */
+    hasEndLabel(end: ConnectorLabelEnd): boolean;
+    hasSourceLabel(): boolean;
+    hasTargetLabel(): boolean;
+    /** The boxes of the end labels that are currently painted, in end order. */
+    endLabelBoxes(): XYWH[];
+    endLabelIncludesPoint(end: ConnectorLabelEnd, point: IVec): boolean;
+    sourceLabelIncludesPoint(point: IVec): boolean;
+    targetLabelIncludesPoint(point: IVec): boolean;
+    /**
+     * Whether a point is reaching for one of the ENDS — the arrowhead, and the
+     * label that belongs beside it whether or not it exists yet.
+     *
+     * ## Why a hairline has to claim more than itself
+     *
+     * A connector is a stroke a few units wide, so its hit test is the line and
+     * nothing else — and an end label is the one thing on a connector that a user
+     * aims at BEFORE it exists (`docs/adr/0018`: they aim at the arrowhead). The
+     * picker that turns a double-click into "the source label" was written
+     * generously for exactly that, and it never got the chance: past `8` units off
+     * the stroke (plus half its width when the caller asks for a threshold —
+     * {@link includesPoint}'s own tolerance) nothing answered here, so the event
+     * reached no view at all and the editor's double-click-on-empty-canvas handler
+     * dropped a text block at the arrowhead instead. A text box appears, it is not
+     * the label, and the contextual menu's own entry works — which is precisely
+     * what the PO reported on 14/09/2026.
+     *
+     * ## …and why only a connector a FRAMEWORK typed claims it
+     *
+     * A `CONNECTOR_END_LABEL_GRAB` disc around each endpoint is a large
+     * thing to take out of the canvas, and the only gesture that needs it is the
+     * one that opens an END label — which is a notation's caption, never a plain
+     * arrow's. A connector carrying a `role` is exactly a connector some framework
+     * wrote (`uml:association`, `bpmn:sequenceFlow`); a generalist one keeps the
+     * hairline it has always had, so a double-click beside a whiteboard arrow
+     * still means "add text here" and a click there still reaches whatever is
+     * under it.
+     *
+     * ## …and why it gives the bound element right of way
+     *
+     * An endpoint sits ON the border of the node it is attached to, so half of
+     * every grab disc is INSIDE that node — and a node's body is the target of its
+     * own gestures (a UML classifier opens its name compartment there). Claiming
+     * that half would take the gesture away from the artefact and give it to the
+     * line touching it. So the disc stops at the bound element's own box, and what
+     * is left is the half the notation writes a multiplicity in: outside the box,
+     * beside the arrowhead.
+     *
+     * Resolved through the surface rather than remembered, and BOTH ways: a
+     * canvas element by id, and a BLOCK — a note, an image, an embed, a frame —
+     * through the store, because those are ends a framework binds too and the
+     * element resolver alone answers `undefined` for every one of them. It did,
+     * and the whole disc was then claimed inside the note. `null` is for an end
+     * bound to NOTHING: an unattached end is a free arrowhead in open canvas, and
+     * the whole disc around it is the author's target.
+     */
+    endGrabIncludesPoint(point: IVec): boolean;
     includesPoint(x: number, y: number, options?: PointTestOptions | undefined): boolean;
     labelIncludesPoint(point: IVec): boolean;
     moveTo(bound: Bound): void;
@@ -124,6 +202,16 @@ export declare class ConnectorElementModel extends GfxPrimitiveElementModel<Conn
      * Local control display and hide, mainly used in editing scenarios.
      */
     accessor labelEditing: boolean;
+    /**
+     * The end whose label is currently open in the DOM editor, if any — the
+     * end-label twin of `labelEditing`, and `@local()` for the same reason: it
+     * is a property of this client's editing session, not of the document.
+     *
+     * One selector rather than two booleans because only one label can be edited
+     * at a time, and because it is the same `'source' | 'target'` the editor's
+     * `which` argument carries.
+     */
+    accessor endLabelEditing: ConnectorLabelEnd | null;
     accessor mode: ConnectorMode;
     accessor path: PointLocation[];
     accessor rearEndpointStyle: PointStyle;
@@ -131,10 +219,57 @@ export declare class ConnectorElementModel extends GfxPrimitiveElementModel<Conn
     accessor rough: boolean | undefined;
     accessor roughness: number;
     accessor source: Connection;
+    /**
+     * The content of the label beside the SOURCE end — a multiplicity, a role
+     * name, a qualifier. `undefined` on every connector that has none, which is
+     * almost all of them.
+     *
+     * ### Why four flat fields and not two records
+     *
+     * A `Y.Text` nested inside a `Y.Map` inside the element's map would not be
+     * observed. The bridge that republishes a text edit as an element update is
+     * `watchText` in `syncElementFromY`
+     * (`packages/framework/std/src/gfx/model/surface/element-model.ts`): it walks
+     * the element's OWN `Y.Map`, and subscribes to every top-level value that is
+     * `instanceof Y.Text` — the centre `text` gets its observation from there and
+     * from nowhere else, which is why `text` carries no `@observe` decorator.
+     *
+     * Keeping the two end texts as top-level keys therefore buys the exact same
+     * observation, for free, on the exact same code path: type into an end label
+     * and the connector repaints, on this client and on every peer. A nested
+     * record would have needed an `@observe` bridge of its own, a second way of
+     * doing the one thing the centre label already does. ADR 0020.
+     *
+     * ### Absent by default
+     *
+     * `undefined` means the key is never written into the Y.Map at all (see the
+     * `@field()` `init`), so a connector that has no end label serialises
+     * byte-identically to one created before these fields existed: no migration,
+     * and an older build opens the document as a connector with two keys it does
+     * not read.
+     */
+    accessor sourceLabel: Y.Text | undefined;
+    /**
+     * The box of the source-end label, in the same absolute coordinates as
+     * `labelXYWH`. Absent until something places it — the pure default is
+     * `connectorEndLabelBox(path, 'source', size)`.
+     */
+    accessor sourceLabelXYWH: XYWH | undefined;
     accessor stroke: Color;
     accessor strokeStyle: StrokeStyle;
     accessor strokeWidth: number;
     accessor target: Connection;
+    /**
+     * The content of the label beside the TARGET end. See `sourceLabel` for why
+     * this is a flat `Y.Text` and what its absence guarantees.
+     */
+    accessor targetLabel: Y.Text | undefined;
+    /**
+     * The box of the target-end label, in the same absolute coordinates as
+     * `labelXYWH`. Absent until something places it — the pure default is
+     * `connectorEndLabelBox(path, 'target', size)`.
+     */
+    accessor targetLabelXYWH: XYWH | undefined;
     /**
      * The content of the label.
      */

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

@@ -37,6 +37,7 @@ import { derive, field, GfxPrimitiveElementModel, local } from '../../../std/gfx
 import * as Y from 'yjs';
 import { CONNECTOR_LABEL_MAX_WIDTH, ConnectorLabelOffsetAnchor, ConnectorMode, DEFAULT_CONNECTOR_MODE, DEFAULT_ROUGHNESS, FontFamily, FontStyle, FontWeight, StrokeStyle, TextAlign, } from '../../consts/index.js';
 import { DefaultTheme } from '../../themes/index.js';
+import { connectorEndNear } from './end-label.js';
 export const getConnectorModeName = (mode) => {
     return {
         [ConnectorMode.Straight]: 'Straight',
@@ -73,6 +74,9 @@ let ConnectorElementModel = (() => {
     let _labelEditing_decorators;
     let _labelEditing_initializers = [];
     let _labelEditing_extraInitializers = [];
+    let _endLabelEditing_decorators;
+    let _endLabelEditing_initializers = [];
+    let _endLabelEditing_extraInitializers = [];
     let _mode_decorators;
     let _mode_initializers = [];
     let _mode_extraInitializers = [];
@@ -94,6 +98,12 @@ let ConnectorElementModel = (() => {
     let _source_decorators;
     let _source_initializers = [];
     let _source_extraInitializers = [];
+    let _sourceLabel_decorators;
+    let _sourceLabel_initializers = [];
+    let _sourceLabel_extraInitializers = [];
+    let _sourceLabelXYWH_decorators;
+    let _sourceLabelXYWH_initializers = [];
+    let _sourceLabelXYWH_extraInitializers = [];
     let _stroke_decorators;
     let _stroke_initializers = [];
     let _stroke_extraInitializers = [];
@@ -106,6 +116,12 @@ let ConnectorElementModel = (() => {
     let _target_decorators;
     let _target_initializers = [];
     let _target_extraInitializers = [];
+    let _targetLabel_decorators;
+    let _targetLabel_initializers = [];
+    let _targetLabel_extraInitializers = [];
+    let _targetLabelXYWH_decorators;
+    let _targetLabelXYWH_initializers = [];
+    let _targetLabelXYWH_extraInitializers = [];
     let _text_decorators;
     let _text_initializers = [];
     let _text_extraInitializers = [];
@@ -137,6 +153,7 @@ let ConnectorElementModel = (() => {
                 })];
             _labelXYWH_decorators = [field()];
             _labelEditing_decorators = [local()];
+            _endLabelEditing_decorators = [local()];
             _mode_decorators = [field()];
             _path_decorators = [derive((path, instance) => {
                     const { x, y } = instance;
@@ -149,10 +166,14 @@ let ConnectorElementModel = (() => {
             _rough_decorators = [field()];
             _roughness_decorators = [field()];
             _source_decorators = [field()];
+            _sourceLabel_decorators = [field()];
+            _sourceLabelXYWH_decorators = [field()];
             _stroke_decorators = [field()];
             _strokeStyle_decorators = [field()];
             _strokeWidth_decorators = [field()];
             _target_decorators = [field()];
+            _targetLabel_decorators = [field()];
+            _targetLabelXYWH_decorators = [field()];
             _text_decorators = [field()];
             _xywh_decorators = [local()];
             __esDecorate(this, null, _absolutePath_decorators, { kind: "accessor", name: "absolutePath", static: false, private: false, access: { has: obj => "absolutePath" in obj, get: obj => obj.absolutePath, set: (obj, value) => { obj.absolutePath = value; } }, metadata: _metadata }, _absolutePath_initializers, _absolutePath_extraInitializers);
@@ -164,6 +185,7 @@ let ConnectorElementModel = (() => {
             __esDecorate(this, null, _labelStyle_decorators, { kind: "accessor", name: "labelStyle", static: false, private: false, access: { has: obj => "labelStyle" in obj, get: obj => obj.labelStyle, set: (obj, value) => { obj.labelStyle = value; } }, metadata: _metadata }, _labelStyle_initializers, _labelStyle_extraInitializers);
             __esDecorate(this, null, _labelXYWH_decorators, { kind: "accessor", name: "labelXYWH", static: false, private: false, access: { has: obj => "labelXYWH" in obj, get: obj => obj.labelXYWH, set: (obj, value) => { obj.labelXYWH = value; } }, metadata: _metadata }, _labelXYWH_initializers, _labelXYWH_extraInitializers);
             __esDecorate(this, null, _labelEditing_decorators, { kind: "accessor", name: "labelEditing", static: false, private: false, access: { has: obj => "labelEditing" in obj, get: obj => obj.labelEditing, set: (obj, value) => { obj.labelEditing = value; } }, metadata: _metadata }, _labelEditing_initializers, _labelEditing_extraInitializers);
+            __esDecorate(this, null, _endLabelEditing_decorators, { kind: "accessor", name: "endLabelEditing", static: false, private: false, access: { has: obj => "endLabelEditing" in obj, get: obj => obj.endLabelEditing, set: (obj, value) => { obj.endLabelEditing = value; } }, metadata: _metadata }, _endLabelEditing_initializers, _endLabelEditing_extraInitializers);
             __esDecorate(this, null, _mode_decorators, { kind: "accessor", name: "mode", static: false, private: false, access: { has: obj => "mode" in obj, get: obj => obj.mode, set: (obj, value) => { obj.mode = value; } }, metadata: _metadata }, _mode_initializers, _mode_extraInitializers);
             __esDecorate(this, null, _path_decorators, { kind: "accessor", name: "path", static: false, private: false, access: { has: obj => "path" in obj, get: obj => obj.path, set: (obj, value) => { obj.path = value; } }, metadata: _metadata }, _path_initializers, _path_extraInitializers);
             __esDecorate(this, null, _rearEndpointStyle_decorators, { kind: "accessor", name: "rearEndpointStyle", static: false, private: false, access: { has: obj => "rearEndpointStyle" in obj, get: obj => obj.rearEndpointStyle, set: (obj, value) => { obj.rearEndpointStyle = value; } }, metadata: _metadata }, _rearEndpointStyle_initializers, _rearEndpointStyle_extraInitializers);
@@ -171,10 +193,14 @@ let ConnectorElementModel = (() => {
             __esDecorate(this, null, _rough_decorators, { kind: "accessor", name: "rough", static: false, private: false, access: { has: obj => "rough" in obj, get: obj => obj.rough, set: (obj, value) => { obj.rough = value; } }, metadata: _metadata }, _rough_initializers, _rough_extraInitializers);
             __esDecorate(this, null, _roughness_decorators, { kind: "accessor", name: "roughness", static: false, private: false, access: { has: obj => "roughness" in obj, get: obj => obj.roughness, set: (obj, value) => { obj.roughness = value; } }, metadata: _metadata }, _roughness_initializers, _roughness_extraInitializers);
             __esDecorate(this, null, _source_decorators, { kind: "accessor", name: "source", static: false, private: false, access: { has: obj => "source" in obj, get: obj => obj.source, set: (obj, value) => { obj.source = value; } }, metadata: _metadata }, _source_initializers, _source_extraInitializers);
+            __esDecorate(this, null, _sourceLabel_decorators, { kind: "accessor", name: "sourceLabel", static: false, private: false, access: { has: obj => "sourceLabel" in obj, get: obj => obj.sourceLabel, set: (obj, value) => { obj.sourceLabel = value; } }, metadata: _metadata }, _sourceLabel_initializers, _sourceLabel_extraInitializers);
+            __esDecorate(this, null, _sourceLabelXYWH_decorators, { kind: "accessor", name: "sourceLabelXYWH", static: false, private: false, access: { has: obj => "sourceLabelXYWH" in obj, get: obj => obj.sourceLabelXYWH, set: (obj, value) => { obj.sourceLabelXYWH = value; } }, metadata: _metadata }, _sourceLabelXYWH_initializers, _sourceLabelXYWH_extraInitializers);
             __esDecorate(this, null, _stroke_decorators, { kind: "accessor", name: "stroke", static: false, private: false, access: { has: obj => "stroke" in obj, get: obj => obj.stroke, set: (obj, value) => { obj.stroke = value; } }, metadata: _metadata }, _stroke_initializers, _stroke_extraInitializers);
             __esDecorate(this, null, _strokeStyle_decorators, { kind: "accessor", name: "strokeStyle", static: false, private: false, access: { has: obj => "strokeStyle" in obj, get: obj => obj.strokeStyle, set: (obj, value) => { obj.strokeStyle = value; } }, metadata: _metadata }, _strokeStyle_initializers, _strokeStyle_extraInitializers);
             __esDecorate(this, null, _strokeWidth_decorators, { kind: "accessor", name: "strokeWidth", static: false, private: false, access: { has: obj => "strokeWidth" in obj, get: obj => obj.strokeWidth, set: (obj, value) => { obj.strokeWidth = value; } }, metadata: _metadata }, _strokeWidth_initializers, _strokeWidth_extraInitializers);
             __esDecorate(this, null, _target_decorators, { kind: "accessor", name: "target", static: false, private: false, access: { has: obj => "target" in obj, get: obj => obj.target, set: (obj, value) => { obj.target = value; } }, metadata: _metadata }, _target_initializers, _target_extraInitializers);
+            __esDecorate(this, null, _targetLabel_decorators, { kind: "accessor", name: "targetLabel", static: false, private: false, access: { has: obj => "targetLabel" in obj, get: obj => obj.targetLabel, set: (obj, value) => { obj.targetLabel = value; } }, metadata: _metadata }, _targetLabel_initializers, _targetLabel_extraInitializers);
+            __esDecorate(this, null, _targetLabelXYWH_decorators, { kind: "accessor", name: "targetLabelXYWH", static: false, private: false, access: { has: obj => "targetLabelXYWH" in obj, get: obj => obj.targetLabelXYWH, set: (obj, value) => { obj.targetLabelXYWH = value; } }, metadata: _metadata }, _targetLabelXYWH_initializers, _targetLabelXYWH_extraInitializers);
             __esDecorate(this, null, _text_decorators, { kind: "accessor", name: "text", static: false, private: false, access: { has: obj => "text" in obj, get: obj => obj.text, set: (obj, value) => { obj.text = value; } }, metadata: _metadata }, _text_initializers, _text_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 });
@@ -190,6 +216,9 @@ let ConnectorElementModel = (() => {
             if (this.hasLabel()) {
                 bounds = bounds.unite(Bound.fromXYWH(this.labelXYWH));
             }
+            for (const box of this.endLabelBoxes()) {
+                bounds = bounds.unite(Bound.fromXYWH(box));
+            }
             return bounds;
         }
         get type() {
@@ -199,12 +228,21 @@ let ConnectorElementModel = (() => {
             if (typeof props.text === 'string') {
                 props.text = new Y.Text(props.text);
             }
+            // The two end labels take the same courtesy the centre one does: a caller
+            // may hand a plain string and get a `Y.Text` on the element.
+            if (typeof props.sourceLabel === 'string') {
+                props.sourceLabel = new Y.Text(props.sourceLabel);
+            }
+            if (typeof props.targetLabel === 'string') {
+                props.targetLabel = new Y.Text(props.targetLabel);
+            }
             return props;
         }
         containsBound(bounds) {
             return (this.absolutePath.some(point => bounds.containsPoint(point)) ||
                 (this.hasLabel() &&
-                    Bound.fromXYWH(this.labelXYWH).points.some(p => bounds.containsPoint(p))));
+                    Bound.fromXYWH(this.labelXYWH).points.some(p => bounds.containsPoint(p))) ||
+                this.endLabelBoxes().some(box => Bound.fromXYWH(box).points.some(p => bounds.containsPoint(p))));
         }
         getLineIntersections(start, end) {
             const { mode, absolutePath: path } = this;
@@ -218,6 +256,13 @@ let ConnectorElementModel = (() => {
             if (!intersected && this.hasLabel()) {
                 intersected = linePolylineIntersects(start, end, Bound.fromXYWH(this.labelXYWH).points);
             }
+            if (!intersected) {
+                for (const box of this.endLabelBoxes()) {
+                    intersected = linePolylineIntersects(start, end, Bound.fromXYWH(box).points);
+                    if (intersected)
+                        break;
+                }
+            }
             return intersected;
         }
         /**
@@ -336,9 +381,120 @@ let ConnectorElementModel = (() => {
                 this.text &&
                 this.text.length);
         }
+        /** The content of one end's label, or `undefined` when it has none. */
+        endLabelText(end) {
+            return end === 'source' ? this.sourceLabel : this.targetLabel;
+        }
+        /** The box of one end's label, or `undefined` when nothing placed it yet. */
+        endLabelXYWH(end) {
+            return end === 'source' ? this.sourceLabelXYWH : this.targetLabelXYWH;
+        }
+        /**
+         * Whether one end carries a label that should be PAINTED — the end-label
+         * twin of `hasLabel()`, gated on the same `labelDisplay` (one switch hides
+         * every caption on a connector, which is what the toolbar's toggle means)
+         * and on `endLabelEditing` instead of `labelEditing`, so mounting the editor
+         * on one end does not blank the other two labels.
+         */
+        hasEndLabel(end) {
+            const text = this.endLabelText(end);
+            return Boolean(this.endLabelEditing !== end &&
+                this.labelDisplay &&
+                this.endLabelXYWH(end) &&
+                text &&
+                text.length);
+        }
+        hasSourceLabel() {
+            return this.hasEndLabel('source');
+        }
+        hasTargetLabel() {
+            return this.hasEndLabel('target');
+        }
+        /** The boxes of the end labels that are currently painted, in end order. */
+        endLabelBoxes() {
+            const boxes = [];
+            if (this.hasSourceLabel())
+                boxes.push(this.sourceLabelXYWH);
+            if (this.hasTargetLabel())
+                boxes.push(this.targetLabelXYWH);
+            return boxes;
+        }
+        endLabelIncludesPoint(end, point) {
+            return (this.hasEndLabel(end) &&
+                Bound.fromXYWH(this.endLabelXYWH(end)).isPointInBound(point));
+        }
+        sourceLabelIncludesPoint(point) {
+            return this.endLabelIncludesPoint('source', point);
+        }
+        targetLabelIncludesPoint(point) {
+            return this.endLabelIncludesPoint('target', point);
+        }
+        /**
+         * Whether a point is reaching for one of the ENDS — the arrowhead, and the
+         * label that belongs beside it whether or not it exists yet.
+         *
+         * ## Why a hairline has to claim more than itself
+         *
+         * A connector is a stroke a few units wide, so its hit test is the line and
+         * nothing else — and an end label is the one thing on a connector that a user
+         * aims at BEFORE it exists (`docs/adr/0018`: they aim at the arrowhead). The
+         * picker that turns a double-click into "the source label" was written
+         * generously for exactly that, and it never got the chance: past `8` units off
+         * the stroke (plus half its width when the caller asks for a threshold —
+         * {@link includesPoint}'s own tolerance) nothing answered here, so the event
+         * reached no view at all and the editor's double-click-on-empty-canvas handler
+         * dropped a text block at the arrowhead instead. A text box appears, it is not
+         * the label, and the contextual menu's own entry works — which is precisely
+         * what the PO reported on 14/09/2026.
+         *
+         * ## …and why only a connector a FRAMEWORK typed claims it
+         *
+         * A `CONNECTOR_END_LABEL_GRAB` disc around each endpoint is a large
+         * thing to take out of the canvas, and the only gesture that needs it is the
+         * one that opens an END label — which is a notation's caption, never a plain
+         * arrow's. A connector carrying a `role` is exactly a connector some framework
+         * wrote (`uml:association`, `bpmn:sequenceFlow`); a generalist one keeps the
+         * hairline it has always had, so a double-click beside a whiteboard arrow
+         * still means "add text here" and a click there still reaches whatever is
+         * under it.
+         *
+         * ## …and why it gives the bound element right of way
+         *
+         * An endpoint sits ON the border of the node it is attached to, so half of
+         * every grab disc is INSIDE that node — and a node's body is the target of its
+         * own gestures (a UML classifier opens its name compartment there). Claiming
+         * that half would take the gesture away from the artefact and give it to the
+         * line touching it. So the disc stops at the bound element's own box, and what
+         * is left is the half the notation writes a multiplicity in: outside the box,
+         * beside the arrowhead.
+         *
+         * Resolved through the surface rather than remembered, and BOTH ways: a
+         * canvas element by id, and a BLOCK — a note, an image, an embed, a frame —
+         * through the store, because those are ends a framework binds too and the
+         * element resolver alone answers `undefined` for every one of them. It did,
+         * and the whole disc was then claimed inside the note. `null` is for an end
+         * bound to NOTHING: an unattached end is a free arrowhead in open canvas, and
+         * the whole disc around it is the author's target.
+         */
+        endGrabIncludesPoint(point) {
+            if (this.role === undefined)
+                return false;
+            const end = connectorEndNear(this.absolutePath, point);
+            if (!end)
+                return false;
+            const id = this[end].id;
+            const boundTo = id
+                ? (this.surface?.getElementById(id) ??
+                    this.surface?.store.getBlock(id)?.model)
+                : null;
+            return !boundTo?.elementBound?.isPointInBound(point);
+        }
         includesPoint(x, y, options) {
             const currentPoint = [x, y];
-            if (this.labelIncludesPoint(currentPoint)) {
+            if (this.labelIncludesPoint(currentPoint) ||
+                this.sourceLabelIncludesPoint(currentPoint) ||
+                this.targetLabelIncludesPoint(currentPoint) ||
+                this.endGrabIncludesPoint(currentPoint)) {
                 return true;
             }
             const { mode, strokeWidth, absolutePath: path } = this;
@@ -382,6 +538,19 @@ let ConnectorElementModel = (() => {
                 const [x, y, w, h] = this.labelXYWH;
                 this.labelXYWH = [x + offset[0], y + offset[1], w, h];
             }
+            // The end labels ride along. Dragging the whole connector moves BOTH of
+            // its endpoints by the same offset, so "an end label follows its endpoint"
+            // and "translate by the connector's offset" are the same movement here;
+            // they part company only when a single endpoint moves, which is the path
+            // generator's business, not this one's.
+            if (this.hasSourceLabel()) {
+                const [x, y, w, h] = this.sourceLabelXYWH;
+                this.sourceLabelXYWH = [x + offset[0], y + offset[1], w, h];
+            }
+            if (this.hasTargetLabel()) {
+                const [x, y, w, h] = this.targetLabelXYWH;
+                this.targetLabelXYWH = [x + offset[0], y + offset[1], w, h];
+            }
         }
         resize(originalPath, matrix) {
             this.updatingPath = false;
@@ -489,6 +658,18 @@ let ConnectorElementModel = (() => {
          */
         get labelEditing() { return this.#labelEditing_accessor_storage; }
         set labelEditing(value) { this.#labelEditing_accessor_storage = value; }
+        #endLabelEditing_accessor_storage;
+        /**
+         * The end whose label is currently open in the DOM editor, if any — the
+         * end-label twin of `labelEditing`, and `@local()` for the same reason: it
+         * is a property of this client's editing session, not of the document.
+         *
+         * One selector rather than two booleans because only one label can be edited
+         * at a time, and because it is the same `'source' | 'target'` the editor's
+         * `which` argument carries.
+         */
+        get endLabelEditing() { return this.#endLabelEditing_accessor_storage; }
+        set endLabelEditing(value) { this.#endLabelEditing_accessor_storage = value; }
         #mode_accessor_storage;
         get mode() { return this.#mode_accessor_storage; }
         set mode(value) { this.#mode_accessor_storage = value; }
@@ -510,6 +691,46 @@ let ConnectorElementModel = (() => {
         #source_accessor_storage;
         get source() { return this.#source_accessor_storage; }
         set source(value) { this.#source_accessor_storage = value; }
+        #sourceLabel_accessor_storage;
+        /**
+         * The content of the label beside the SOURCE end — a multiplicity, a role
+         * name, a qualifier. `undefined` on every connector that has none, which is
+         * almost all of them.
+         *
+         * ### Why four flat fields and not two records
+         *
+         * A `Y.Text` nested inside a `Y.Map` inside the element's map would not be
+         * observed. The bridge that republishes a text edit as an element update is
+         * `watchText` in `syncElementFromY`
+         * (`packages/framework/std/src/gfx/model/surface/element-model.ts`): it walks
+         * the element's OWN `Y.Map`, and subscribes to every top-level value that is
+         * `instanceof Y.Text` — the centre `text` gets its observation from there and
+         * from nowhere else, which is why `text` carries no `@observe` decorator.
+         *
+         * Keeping the two end texts as top-level keys therefore buys the exact same
+         * observation, for free, on the exact same code path: type into an end label
+         * and the connector repaints, on this client and on every peer. A nested
+         * record would have needed an `@observe` bridge of its own, a second way of
+         * doing the one thing the centre label already does. ADR 0020.
+         *
+         * ### Absent by default
+         *
+         * `undefined` means the key is never written into the Y.Map at all (see the
+         * `@field()` `init`), so a connector that has no end label serialises
+         * byte-identically to one created before these fields existed: no migration,
+         * and an older build opens the document as a connector with two keys it does
+         * not read.
+         */
+        get sourceLabel() { return this.#sourceLabel_accessor_storage; }
+        set sourceLabel(value) { this.#sourceLabel_accessor_storage = value; }
+        #sourceLabelXYWH_accessor_storage;
+        /**
+         * The box of the source-end label, in the same absolute coordinates as
+         * `labelXYWH`. Absent until something places it — the pure default is
+         * `connectorEndLabelBox(path, 'source', size)`.
+         */
+        get sourceLabelXYWH() { return this.#sourceLabelXYWH_accessor_storage; }
+        set sourceLabelXYWH(value) { this.#sourceLabelXYWH_accessor_storage = value; }
         #stroke_accessor_storage;
         get stroke() { return this.#stroke_accessor_storage; }
         set stroke(value) { this.#stroke_accessor_storage = value; }
@@ -522,6 +743,21 @@ let ConnectorElementModel = (() => {
         #target_accessor_storage;
         get target() { return this.#target_accessor_storage; }
         set target(value) { this.#target_accessor_storage = value; }
+        #targetLabel_accessor_storage;
+        /**
+         * The content of the label beside the TARGET end. See `sourceLabel` for why
+         * this is a flat `Y.Text` and what its absence guarantees.
+         */
+        get targetLabel() { return this.#targetLabel_accessor_storage; }
+        set targetLabel(value) { this.#targetLabel_accessor_storage = value; }
+        #targetLabelXYWH_accessor_storage;
+        /**
+         * The box of the target-end label, in the same absolute coordinates as
+         * `labelXYWH`. Absent until something places it — the pure default is
+         * `connectorEndLabelBox(path, 'target', size)`.
+         */
+        get targetLabelXYWH() { return this.#targetLabelXYWH_accessor_storage; }
+        set targetLabelXYWH(value) { this.#targetLabelXYWH_accessor_storage = value; }
         #text_accessor_storage;
         /**
          * The content of the label.
@@ -547,7 +783,8 @@ let ConnectorElementModel = (() => {
             this.#labelStyle_accessor_storage = (__runInitializers(this, _labelOffset_extraInitializers), __runInitializers(this, _labelStyle_initializers, void 0));
             this.#labelXYWH_accessor_storage = (__runInitializers(this, _labelStyle_extraInitializers), __runInitializers(this, _labelXYWH_initializers, undefined));
             this.#labelEditing_accessor_storage = (__runInitializers(this, _labelXYWH_extraInitializers), __runInitializers(this, _labelEditing_initializers, false));
-            this.#mode_accessor_storage = (__runInitializers(this, _labelEditing_extraInitializers), __runInitializers(this, _mode_initializers, DEFAULT_CONNECTOR_MODE));
+            this.#endLabelEditing_accessor_storage = (__runInitializers(this, _labelEditing_extraInitializers), __runInitializers(this, _endLabelEditing_initializers, null));
+            this.#mode_accessor_storage = (__runInitializers(this, _endLabelEditing_extraInitializers), __runInitializers(this, _mode_initializers, DEFAULT_CONNECTOR_MODE));
             this.#path_accessor_storage = (__runInitializers(this, _mode_extraInitializers), __runInitializers(this, _path_initializers, []));
             this.#rearEndpointStyle_accessor_storage = (__runInitializers(this, _path_extraInitializers), __runInitializers(this, _rearEndpointStyle_initializers, void 0));
             this.#rotate_accessor_storage = (__runInitializers(this, _rearEndpointStyle_extraInitializers), __runInitializers(this, _rotate_initializers, 0));
@@ -556,13 +793,17 @@ let ConnectorElementModel = (() => {
             this.#source_accessor_storage = (__runInitializers(this, _roughness_extraInitializers), __runInitializers(this, _source_initializers, {
                 position: [0, 0],
             }));
-            this.#stroke_accessor_storage = (__runInitializers(this, _source_extraInitializers), __runInitializers(this, _stroke_initializers, DefaultTheme.connectorColor));
+            this.#sourceLabel_accessor_storage = (__runInitializers(this, _source_extraInitializers), __runInitializers(this, _sourceLabel_initializers, undefined));
+            this.#sourceLabelXYWH_accessor_storage = (__runInitializers(this, _sourceLabel_extraInitializers), __runInitializers(this, _sourceLabelXYWH_initializers, undefined));
+            this.#stroke_accessor_storage = (__runInitializers(this, _sourceLabelXYWH_extraInitializers), __runInitializers(this, _stroke_initializers, DefaultTheme.connectorColor));
             this.#strokeStyle_accessor_storage = (__runInitializers(this, _stroke_extraInitializers), __runInitializers(this, _strokeStyle_initializers, StrokeStyle.Solid));
             this.#strokeWidth_accessor_storage = (__runInitializers(this, _strokeStyle_extraInitializers), __runInitializers(this, _strokeWidth_initializers, 4));
             this.#target_accessor_storage = (__runInitializers(this, _strokeWidth_extraInitializers), __runInitializers(this, _target_initializers, {
                 position: [0, 0],
             }));
-            this.#text_accessor_storage = (__runInitializers(this, _target_extraInitializers), __runInitializers(this, _text_initializers, undefined));
+            this.#targetLabel_accessor_storage = (__runInitializers(this, _target_extraInitializers), __runInitializers(this, _targetLabel_initializers, undefined));
+            this.#targetLabelXYWH_accessor_storage = (__runInitializers(this, _targetLabel_extraInitializers), __runInitializers(this, _targetLabelXYWH_initializers, undefined));
+            this.#text_accessor_storage = (__runInitializers(this, _targetLabelXYWH_extraInitializers), __runInitializers(this, _text_initializers, undefined));
             this.#xywh_accessor_storage = (__runInitializers(this, _text_extraInitializers), __runInitializers(this, _xywh_initializers, '[0,0,0,0]'));
             __runInitializers(this, _xywh_extraInitializers);
         }

package/dist/_pkgs/affine-model/elements/connector/end-label.d.ts

@@ -0,0 +1,83 @@
+import type { IVec, XYWH } from '../../../global/gfx/index.js';
+/**
+ * Which of a connector's two ends a label belongs to.
+ *
+ * `source` and `target` are the names the connector already uses for its two
+ * `Connection`s, so an end label's identity is the identity of the endpoint it
+ * follows — never a left/right or a first/last, which flip when the author
+ * reverses the edge.
+ */
+export type ConnectorLabelEnd = 'source' | 'target';
+/**
+ * How far along the path, from its endpoint, an end label is anchored by
+ * default — in model units, i.e. board units at zoom 1.
+ *
+ * Far enough to clear the endpoint head (a `DEFAULT_ARROW_SIZE` head on a
+ * 4-unit stroke is about 10 units long), close enough that the reader attaches
+ * the text to that end rather than to the middle of the line.
+ */
+export declare const DEFAULT_CONNECTOR_END_LABEL_DISTANCE = 12;
+/**
+ * How close to an endpoint a gesture has to land to mean "that end" — in model
+ * units, so it is a constant on the board and not on the screen (zooming out
+ * does not widen the target).
+ *
+ * `docs/adr/0018` phase 2. Deliberately generous, and for a reason a hairline
+ * makes plain: the end label a user is reaching for is usually not there yet, so
+ * there is no box to aim at, and the thing they aim at instead is the ARROWHEAD.
+ *
+ * It lives here, beside the box the same clause places, because it is one fact
+ * about the same notation and because BOTH the hit test that delivers the
+ * gesture ({@link connectorEndNear}) and the picker that decides what it meant
+ * (`pickConnectorLabelWhich`, in the gfx pack) have to agree about it. They did
+ * not until the PO's recette of 14/09/2026: the picker was generous and the hit
+ * test was the line itself — `8` units off the stroke, plus half the stroke's
+ * width when the caller asks for a threshold — so anywhere past that the
+ * double-click reached nobody and the editor's own "add text here" answered it
+ * instead.
+ */
+export declare const CONNECTOR_END_LABEL_GRAB = 24;
+/**
+ * Which END of a path a point is reaching for, or `null` for none.
+ *
+ * The nearer end wins a tie-free comparison; a point within reach of both ends
+ * of a very short connector gets the nearer one, which is the same rule
+ * `pickConnectorLabelWhich` applies and the only one that stays stable as the
+ * author drags the line.
+ *
+ * Pure, and exported, because it is the whole of a gesture's reach and a spec
+ * should be able to ask it without driving a pointer.
+ */
+export declare function connectorEndNear(path: readonly IVec[], point: IVec, grab?: number): ConnectorLabelEnd | null;
+/**
+ * The default box for a connector end label — where it sits when nothing has
+ * placed it yet.
+ *
+ * Pure geometry, deliberately: the editor seeding a new end label
+ * (`mountConnectorLabelEditor`), the canvas renderer painting one that has no
+ * stored box, and the path generator re-anchoring one after a re-route all
+ * need the SAME answer, and none of them should have to reimplement it. No DOM,
+ * no model, no measurement — the caller brings the text's measured size.
+ *
+ * The box is anchored `distance` units along the path from that end's endpoint
+ * and pushed off the line by half its own height, so it sits BESIDE the stroke
+ * instead of on it. The push uses the path's tangent taken in the **source →
+ * target** orientation for both ends, which is what keeps the two labels on the
+ * same side of the line: a `0..*` above one end and a `1` below the other reads
+ * as two unrelated notes.
+ *
+ * @param path the connector's path in the coordinate space the returned box
+ *   belongs to — `absolutePath` for a persisted `labelXYWH`-style box. Accepts
+ *   `PointLocation[]`; only the coordinates are read, never the tangents.
+ * @param end which endpoint the label belongs to.
+ * @param size the label's measured size.
+ * @param distance how far along the path to anchor it. A path shorter than
+ *   `distance` anchors the box at its FAR endpoint rather than off the line —
+ *   a two-unit-long connector puts both labels in the same place, which is
+ *   honest about there being no room, and is the only way the box stays on the
+ *   stroke it annotates.
+ */
+export declare function connectorEndLabelBox(path: readonly IVec[], end: ConnectorLabelEnd, size: {
+    w: number;
+    h: number;
+}, distance?: number): XYWH;