@formicoidea/labre-core 0.34.1 → 0.35.0

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

@@ -8,6 +8,63 @@ export declare class GfxViewEventManager {
     private _callInReverseOrder;
     constructor(gfx: GfxController);
     dispatch(eventName: SupportedEvent, evt: PointerEventState): boolean | undefined;
+    /**
+     * Which view a POSITIONED event (click, dblclick, pointerdown/up) belongs to.
+     *
+     * The hovered stack answers whenever it is still true — the pointer has not
+     * moved off the view it was last seen on, which is the ordinary case and the
+     * one every framework gesture already relies on. What this adds is the
+     * fallback: when the top of the stack is NOT under the event's own
+     * coordinates, the target is resolved from those coordinates instead of the
+     * event being dropped.
+     *
+     * ## The bug this repairs
+     *
+     * The stack is only ever rebuilt by {@link _handlePointerMove}, so a pointer
+     * that arrives somewhere without a `pointermove` reaching this manager leaves
+     * it EMPTY or STALE — and every click and double-click on a canvas element is
+     * then delivered to nobody, or to whatever the pointer was last over. It
+     * happens for real: a `pointermove` emitted while the event dispatcher is not
+     * yet active is dropped before it gets here (the first gesture in a freshly
+     * mounted editor), an element created under a stationary pointer is never
+     * moved onto, and a viewport change slides the canvas under a pointer that
+     * never moves.
+     *
+     * The symptom is a very specific one, and it is what sent us here: SELECTING
+     * the element works — `handleElementSelection` re-picks by point on every
+     * click — while the element's own gestures do not, because they came through
+     * this stack. Two answers to "what is under the pointer", one of them stale.
+     * Reported on the C4 board's title band, where a click selected the sheet and
+     * a double-click renamed nothing.
+     *
+     * Deliberately NOT a rebuild of the stack: hover enter/leave is a `pointermove`
+     * story, and firing those from a click would announce arrivals and departures
+     * that never happened.
+     */
+    private _targetOf;
     private _handleDrag;
+    /**
+     * Whether a view answers for a MODEL point — 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.
+     */
+    private _answersAt;
+    /**
+     * The views under a MODEL point, in PAINT ORDER — the topmost last.
+     *
+     * One walk, used by the hover bookkeeping and by {@link _targetOf}, so "what
+     * is under the pointer" has exactly one answer however it is asked.
+     */
+    private _viewsAt;
     private _handlePointerMove;
 }

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

@@ -22,9 +22,49 @@ export class GfxViewEventManager {
             return this._handleDrag(eventName, evt);
         }
         else {
-            return last(this._hoveredElementsStack)?.dispatch(eventName, evt);
+            return this._targetOf(evt)?.dispatch(eventName, evt);
         }
     }
+    /**
+     * Which view a POSITIONED event (click, dblclick, pointerdown/up) belongs to.
+     *
+     * The hovered stack answers whenever it is still true — the pointer has not
+     * moved off the view it was last seen on, which is the ordinary case and the
+     * one every framework gesture already relies on. What this adds is the
+     * fallback: when the top of the stack is NOT under the event's own
+     * coordinates, the target is resolved from those coordinates instead of the
+     * event being dropped.
+     *
+     * ## The bug this repairs
+     *
+     * The stack is only ever rebuilt by {@link _handlePointerMove}, so a pointer
+     * that arrives somewhere without a `pointermove` reaching this manager leaves
+     * it EMPTY or STALE — and every click and double-click on a canvas element is
+     * then delivered to nobody, or to whatever the pointer was last over. It
+     * happens for real: a `pointermove` emitted while the event dispatcher is not
+     * yet active is dropped before it gets here (the first gesture in a freshly
+     * mounted editor), an element created under a stationary pointer is never
+     * moved onto, and a viewport change slides the canvas under a pointer that
+     * never moves.
+     *
+     * The symptom is a very specific one, and it is what sent us here: SELECTING
+     * the element works — `handleElementSelection` re-picks by point on every
+     * click — while the element's own gestures do not, because they came through
+     * this stack. Two answers to "what is under the pointer", one of them stale.
+     * Reported on the C4 board's title band, where a click selected the sheet and
+     * a double-click renamed nothing.
+     *
+     * Deliberately NOT a rebuild of the stack: hover enter/leave is a `pointermove`
+     * story, and firing those from a click would announce arrivals and departures
+     * that never happened.
+     */
+    _targetOf(evt) {
+        const [x, y] = this.gfx.viewport.toModelCoord(evt.x, evt.y);
+        const hovered = last(this._hoveredElementsStack) ?? null;
+        if (hovered && this._answersAt(hovered, x, y))
+            return hovered;
+        return last(this._viewsAt(x, y)) ?? null;
+    }
     _handleDrag(evtName, _evt) {
         switch (evtName) {
             case 'dragstart': {
@@ -44,9 +84,39 @@ export class GfxViewEventManager {
             }
         }
     }
-    _handlePointerMove(_evt) {
-        const [x, y] = this.gfx.viewport.toModelCoord(_evt.x, _evt.y);
-        const hoveredElmViews = this.gfx.grid
+    /**
+     * Whether a view answers for a MODEL point — 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.
+     */
+    _answersAt(view, x, y) {
+        const model = view.model;
+        return (view.includesPoint(x, y, {
+            hitThreshold: 10,
+            responsePadding: [5, 5],
+        }, this.gfx.std.host) ||
+            ('externalBound' in model
+                ? (model.externalBound?.isPointInBound([x, y]) ?? false)
+                : false));
+    }
+    /**
+     * The views under a MODEL point, in PAINT ORDER — the topmost last.
+     *
+     * One walk, used by the hover bookkeeping and by {@link _targetOf}, so "what
+     * is under the pointer" has exactly one answer however it is asked.
+     */
+    _viewsAt(x, y) {
+        return (this.gfx.grid
             .search(new Bound(x - 5, y - 5, 10, 10), {
             filter: ['canvas', 'local'],
         })
@@ -54,33 +124,18 @@ export class GfxViewEventManager {
             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)) {
+            if (this._answersAt(view, x, y))
                 pre.push(view);
-            }
             return pre;
         }, [])
             // Sort by paint order (same convention as `getElementByPoint`) so the
             // stack's last entry — the click/dblclick target — is the TOPMOST view,
             // not whichever the grid returned last (e.g. a background under a node).
-            .sort((a, b) => compare(a.model, b.model));
+            .sort((a, b) => compare(a.model, b.model)));
+    }
+    _handlePointerMove(_evt) {
+        const [x, y] = this.gfx.viewport.toModelCoord(_evt.x, _evt.y);
+        const hoveredElmViews = this._viewsAt(x, y);
         const currentStackedViews = new Set(this._hoveredElementsStack);
         const visited = new Set();
         this._callInReverseOrder(view => {

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

@@ -12,8 +12,13 @@
  * the host's job, built from per-document calls to
  * {@link collectPivotOccurrences}. The repository has no backlink
  * infrastructure and this module deliberately does not introduce one.
+ *
+ * Beside the collector sit the two READ predicates over the same field —
+ * {@link isPivotBound}, the strict one, and {@link resolvePivotBinding}, the
+ * one that tolerates a binding carried by a composite. Both are pure functions
+ * of the document, and neither writes.
  */
-import type { GfxPrimitiveElementModel } from './element-model.js';
+import { GfxPrimitiveElementModel } from './element-model.js';
 import type { SurfaceBlockModel } from './surface-model.js';
 /** One element that is an occurrence of one pivot record. */
 export type PivotOccurrence = {
@@ -37,6 +42,55 @@ export type PivotBoundElement = GfxPrimitiveElementModel & {
  * the provider looking for a document that cannot exist.
  */
 export declare function isPivotBound(el: GfxPrimitiveElementModel): el is PivotBoundElement;
+/**
+ * The binding that governs an element — **a READING tolerance, and the only
+ * one** (PO arbitration of 02/09/2026).
+ *
+ * Returns the element itself when it carries a binding, otherwise the first
+ * bound element in its chain of ancestor groups, otherwise `undefined`.
+ *
+ * ## Why a chain at all
+ *
+ * ADR 0005/0006 put the binding ON THE ELEMENT, and that has not changed. What
+ * the format never said is WHICH element of a COMPOSITE carries it — and every
+ * business framework draws its artefacts as composites: a Wardley component is
+ * a `group` holding the `wardleyNode` circle and a free `text` label, a C4
+ * component is a shape plus three texts. Two different elements can therefore
+ * legitimately be "the component":
+ *
+ * - the one carrying the ROLE (`wardley:component`), which is what the reading
+ *   engine and the toolbar resolve to, through the group;
+ * - the one a plain click SELECTS, which is the GROUP — and therefore what a
+ *   host's own "link this to a record" gesture naturally stamps.
+ *
+ * A reader that only looked at the role-carrying element reported "Not linked
+ * to a record" on a component the host had bound by the group, with the link
+ * plainly there in the document. That is the bug this function exists for. It
+ * is a filter on the way IN, never a rule about where a binding belongs: the
+ * WRITE contract is untouched — `pivot.bind` and the panel's "Link to a record"
+ * still stamp the role-carrying element.
+ *
+ * ## Why the child wins
+ *
+ * The most SPECIFIC binding wins, so an element bound in its own right is never
+ * shadowed by the group it happens to sit in. Deliberately asymmetric with the
+ * ancestor walk: a group that gathers two bound components is a container, not
+ * an occurrence of either, and each child keeps answering for itself.
+ *
+ * ## Scope
+ *
+ * Reading only. `collectPivotOccurrences` and the host-facing seam
+ * (materiality patches, backlinks) stay strictly element-by-element: they are
+ * the ADR 0006 contract the host builds its own derived state on, and widening
+ * them would change what "an occurrence" means without a decision.
+ *
+ * Cheap and allocation-light: the chain is at most a handful of groups deep and
+ * the visited set is only built when the element has an ancestor at all. The
+ * guard is not decoration — a corrupted document can hold a cycle in the group
+ * relation (`SurfaceBlockModel.getGroups` carries the same guard), and a reader
+ * on the render path must degrade to `undefined`, never hang.
+ */
+export declare function resolvePivotBinding(element: GfxPrimitiveElementModel): PivotBoundElement | undefined;
 /**
  * Every occurrence on one surface, in element order. O(n) over the surface's
  * elements; allocates nothing persistent.

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

@@ -1,3 +1,24 @@
+/**
+ * Backlinks over `pivotDocId` — **computed, never persisted** (MF1, ADR 0005 § 5).
+ *
+ * The library ships one pure, synchronous collector and nothing else: no index,
+ * no reverse map, no cache, and nothing written back into the document. That is
+ * not an optimisation left for later, it is the invariant: "which boards
+ * mention this component" is a recomputation, always, so it can never drift
+ * from the document and can never be corrupted by a bad write — because there
+ * is no write.
+ *
+ * Cross-document aggregation ("every board where this component appears") is
+ * the host's job, built from per-document calls to
+ * {@link collectPivotOccurrences}. The repository has no backlink
+ * infrastructure and this module deliberately does not introduce one.
+ *
+ * Beside the collector sit the two READ predicates over the same field —
+ * {@link isPivotBound}, the strict one, and {@link resolvePivotBinding}, the
+ * one that tolerates a binding carried by a composite. Both are pure functions
+ * of the document, and neither writes.
+ */
+import { GfxPrimitiveElementModel } from './element-model.js';
 /**
  * Whether the element carries a binding. Narrowing type guard, so a caller that
  * has checked does not have to re-assert the string.
@@ -9,6 +30,72 @@
 export function isPivotBound(el) {
     return typeof el.pivotDocId === 'string' && el.pivotDocId.length > 0;
 }
+/**
+ * The binding that governs an element — **a READING tolerance, and the only
+ * one** (PO arbitration of 02/09/2026).
+ *
+ * Returns the element itself when it carries a binding, otherwise the first
+ * bound element in its chain of ancestor groups, otherwise `undefined`.
+ *
+ * ## Why a chain at all
+ *
+ * ADR 0005/0006 put the binding ON THE ELEMENT, and that has not changed. What
+ * the format never said is WHICH element of a COMPOSITE carries it — and every
+ * business framework draws its artefacts as composites: a Wardley component is
+ * a `group` holding the `wardleyNode` circle and a free `text` label, a C4
+ * component is a shape plus three texts. Two different elements can therefore
+ * legitimately be "the component":
+ *
+ * - the one carrying the ROLE (`wardley:component`), which is what the reading
+ *   engine and the toolbar resolve to, through the group;
+ * - the one a plain click SELECTS, which is the GROUP — and therefore what a
+ *   host's own "link this to a record" gesture naturally stamps.
+ *
+ * A reader that only looked at the role-carrying element reported "Not linked
+ * to a record" on a component the host had bound by the group, with the link
+ * plainly there in the document. That is the bug this function exists for. It
+ * is a filter on the way IN, never a rule about where a binding belongs: the
+ * WRITE contract is untouched — `pivot.bind` and the panel's "Link to a record"
+ * still stamp the role-carrying element.
+ *
+ * ## Why the child wins
+ *
+ * The most SPECIFIC binding wins, so an element bound in its own right is never
+ * shadowed by the group it happens to sit in. Deliberately asymmetric with the
+ * ancestor walk: a group that gathers two bound components is a container, not
+ * an occurrence of either, and each child keeps answering for itself.
+ *
+ * ## Scope
+ *
+ * Reading only. `collectPivotOccurrences` and the host-facing seam
+ * (materiality patches, backlinks) stay strictly element-by-element: they are
+ * the ADR 0006 contract the host builds its own derived state on, and widening
+ * them would change what "an occurrence" means without a decision.
+ *
+ * Cheap and allocation-light: the chain is at most a handful of groups deep and
+ * the visited set is only built when the element has an ancestor at all. The
+ * guard is not decoration — a corrupted document can hold a cycle in the group
+ * relation (`SurfaceBlockModel.getGroups` carries the same guard), and a reader
+ * on the render path must degrade to `undefined`, never hang.
+ */
+export function resolvePivotBinding(element) {
+    if (isPivotBound(element))
+        return element;
+    const visited = new Set([element.id]);
+    let ancestor = element.group;
+    while (ancestor && !visited.has(ancestor.id)) {
+        visited.add(ancestor.id);
+        // A group may be a BLOCK (a frame): only a canvas element declares
+        // `pivotDocId`, so anything else can never be bound — the walk steps over
+        // it rather than stopping, because what sits above it still can be.
+        if (ancestor instanceof GfxPrimitiveElementModel &&
+            isPivotBound(ancestor)) {
+            return ancestor;
+        }
+        ancestor = ancestor.group;
+    }
+    return undefined;
+}
 /**
  * Every occurrence on one surface, in element order. O(n) over the surface's
  * elements; allocates nothing persistent.

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

@@ -62,7 +62,7 @@ export type RoleKind = 'node' | 'edge' | 'text';
  * catalogue always wins, and a catalogue-less playground still reads.
  */
 export interface EdgeDirectionDef {
-    /** i18n key of the verb — `'depends on'`. Resolved by the host. */
+    /** i18n key of the verb — `'needs'`. Resolved by the host. */
     verbKey: string;
     /** The framework's own wording for {@link verbKey}. */
     verbFallback?: string;
@@ -75,6 +75,17 @@ export interface EdgeDirectionDef {
     gestureHintKey?: string;
     /** The framework's own wording for {@link gestureHintKey}. */
     gestureHintFallback?: string;
+    /**
+     * CSS colour of the chip the reveal draws this verb in (M2). Absent — which
+     * is every role but one — keeps the house affordance blue the mechanism has
+     * always used, so declaring nothing repaints nothing.
+     *
+     * A colour belongs to the ROLE rather than to the widget because the chip is
+     * per-relation: the PO may want one framework's central relation to stand out
+     * without every other framework's edges changing with it. The chip's text is
+     * white, so a colour declared here must be dark enough to carry it.
+     */
+    chipColor?: string;
 }
 export interface RoleDef {
     /** Namespaced id, `<framework>:<role>`. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formicoidea/labre-core",
   "description": "Labre editor — the full BlockSuite-derived editor as one package.",
-  "version": "0.34.1",
+  "version": "0.35.0",
   "type": "module",
   "sideEffects": false,
   "author": "lajola",