@formicoidea/labre-core 0.31.0 → 0.32.0

package/dist/_pkgs/affine-gfx-connector/direction/direction-widget.js

@@ -0,0 +1,395 @@
+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 { translateKey } from '../../affine-shared/services/index.js';
+import { WidgetComponent, WidgetViewExtension } from '../../std/index.js';
+import { GfxControllerIdentifier } from '../../std/gfx/index.js';
+import { effect } from '@preact/signals-core';
+import { css, html, nothing, unsafeCSS } from 'lit';
+import { state } from 'lit/decorators.js';
+import { styleMap } from 'lit/directives/style-map.js';
+import { literal, unsafeStatic } from 'lit/static-html.js';
+import { EDGE_DIRECTION_COLOR, EdgeDirectionManager, labelAnchorOf, } from './direction-reveal.js';
+import { edgeVerbOf } from './typed-edge.js';
+export const EDGE_DIRECTION_WIDGET = 'affine-edge-direction-widget';
+/**
+ * Screen pixels between the bottom of the viewport and the armed-tool hint —
+ * clear of the edgeless toolbar, which is the one thing that lives down there.
+ * The hint hangs UPWARDS from that line (see the rule below), so the whole box
+ * is above the strip and not merely its top edge.
+ */
+const HINT_BOTTOM_GAP = 96;
+/** How wide the hint may get before the sentence wraps. */
+const HINT_MAX_WIDTH = 420;
+/** One line of hint, box included — the room it needs above its anchor line. */
+const HINT_MIN_HEIGHT = 48;
+/**
+ * **Under every toolbar** — the reverse of the reading panel's choice, for the
+ * reverse reason (PO recette of 02/08/2026, point 4).
+ *
+ * What this widget draws belongs to the CANVAS: a label glued to a link, in
+ * model units, turning and scaling with the map. The toolbars overhang the
+ * canvas, so a canvas mark that paints over the senior menu — which is what the
+ * PO photographed — is a layering mistake and not a matter of taste. The
+ * reading panel is the opposite case: a piece of UI the user is reading, which
+ * the toolbars may wait underneath.
+ *
+ * `0`, not `2`, and both numbers are about siblings rather than about depth.
+ * `.widgets-container` has `contain: layout`, so it is a stacking context and
+ * every widget host competes inside it: `edgeless-toolbar-widget` takes
+ * `z-index: 1` (its senior menu and sub-menus are appended inside its own
+ * subtree, so they ride on that 1), and `editor-toolbar` — the contextual one —
+ * takes `--affine-z-index-popover`, which the theme sets to 1000. `2` cleared
+ * the first of those and that is exactly the bug. `0` is under both, and still
+ * over the canvas: the container as a whole paints above `.edgeless-container`,
+ * which is its earlier sibling OUTSIDE it.
+ */
+const EDGE_DIRECTION_Z_INDEX = 0;
+/**
+ * The PROSE of `docs/adr/0010`'s M1 and M2, on the pattern
+ * `violation-detail-widget` established one directory away — and, since the
+ * chevron was folded into the label, the whole of what M2 draws.
+ *
+ * Two things, both of them WORDS and therefore both of them here rather than on
+ * the canvas (a tooltip rendered at a quarter size is not a smaller tooltip, it
+ * is an unreadable one):
+ *
+ * - **M2** — while a typed edge is hovered or selected, the role's VERB laid
+ *   along the link: `depends on`, in a box that ends in a point aimed at the
+ *   provider. Since the PO acceptance of 02/08/2026 this is the only mark the
+ *   reveal draws; the canvas chevron it used to sit on top of is folded into
+ *   that point (see `direction-reveal.ts`). Since the second pass of the same
+ *   recette it is the verb ALONE: the full sentence was longer than the links
+ *   it was laid on, so it covered the very components it named — and those
+ *   names are already drawn at both ends of the line.
+ * - **M1** — while a tool that draws a typed edge is armed, the sentence that
+ *   tells the user which way to drag. That is what turns the direction their
+ *   gesture writes into a statement they made.
+ *
+ * It knows no framework: the verb is a key declared by a ROLE
+ * (`EdgeDirectionDef`) and resolved through the host's catalogue.
+ */
+let EdgeDirectionWidget = (() => {
+    let _classSuper = WidgetComponent;
+    let __revealed_decorators;
+    let __revealed_initializers = [];
+    let __revealed_extraInitializers = [];
+    let __hint_decorators;
+    let __hint_initializers = [];
+    let __hint_extraInitializers = [];
+    return class EdgeDirectionWidget extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            __revealed_decorators = [state()];
+            __hint_decorators = [state()];
+            __esDecorate(this, null, __revealed_decorators, { kind: "accessor", name: "_revealed", static: false, private: false, access: { has: obj => "_revealed" in obj, get: obj => obj._revealed, set: (obj, value) => { obj._revealed = value; } }, metadata: _metadata }, __revealed_initializers, __revealed_extraInitializers);
+            __esDecorate(this, null, __hint_decorators, { kind: "accessor", name: "_hint", static: false, private: false, access: { has: obj => "_hint" in obj, get: obj => obj._hint, set: (obj, value) => { obj._hint = value; } }, metadata: _metadata }, __hint_initializers, __hint_extraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        static { this.styles = css `
+    :host {
+      position: absolute;
+      top: 0;
+      left: 0;
+      z-index: ${unsafeCSS(EDGE_DIRECTION_Z_INDEX)};
+      pointer-events: none;
+    }
+
+    /*
+     * The verb, laid along its link.
+     *
+     * Every length below is in MODEL units: render() multiplies the whole box
+     * by the viewport zoom, so the label keeps its proportion to the line it
+     * names instead of swelling into a banner when the user zooms out. That is
+     * the same rule the chevron it replaces obeyed, and the same one the
+     * validation marks obey.
+     *
+     * Filled rather than outlined, because the box is a SHAPE now: an arrow's
+     * point has no border to speak of, and a hairline diagonal at 40 % zoom is
+     * a smudge. Solid house blue with white text reads in both themes and
+     * cannot be mistaken for the map's own ink.
+     */
+    .edge-direction-label {
+      --edge-direction-point: 9px;
+      position: absolute;
+      box-sizing: border-box;
+      padding: 2px 8px;
+      border-radius: 3px;
+      background: ${unsafeCSS(EDGE_DIRECTION_COLOR)};
+      color: #fff;
+      font-family: var(--affine-font-family);
+      font-size: 12px;
+      font-weight: 500;
+      line-height: 1.4;
+      white-space: nowrap;
+      /* The box turns and scales about its own centre, which render() has
+         already put on the middle of the path. */
+      transform-origin: center center;
+      /* Strictly an annotation: it must never take a click away from the edge
+         it is describing. */
+      pointer-events: none;
+    }
+
+    /*
+     * Which END of the box is the point — never which end of the WORDS.
+     * data-arrow=end is the ordinary case: the link runs left-to-right on
+     * screen, so the target is past the last word. data-arrow=start is the same
+     * box on a link running the other way, turned 180° to stay readable: the
+     * target is now behind the first word, so the point moves there and the
+     * verb is left alone, spelled the way it is read.
+     */
+    .edge-direction-label[data-arrow='end'] {
+      padding-right: calc(8px + var(--edge-direction-point));
+      clip-path: polygon(
+        0 0,
+        calc(100% - var(--edge-direction-point)) 0,
+        100% 50%,
+        calc(100% - var(--edge-direction-point)) 100%,
+        0 100%
+      );
+    }
+
+    .edge-direction-label[data-arrow='start'] {
+      padding-left: calc(8px + var(--edge-direction-point));
+      clip-path: polygon(
+        var(--edge-direction-point) 0,
+        100% 0,
+        100% 100%,
+        var(--edge-direction-point) 100%,
+        0 50%
+      );
+    }
+
+    /*
+     * Positioned in SCREEN pixels from the widget host, which sits at the
+     * viewport's origin: left and top are handed in by render() off
+     * gfx.viewport, exactly like the validation badge's are.
+     *
+     * It cannot be positioned against the host itself. That host is a
+     * zero-sized absolutely positioned box (the house pattern for a widget that
+     * must not intercept the canvas), so bottom: 96px put the banner 96 px
+     * ABOVE the viewport's top edge, and left: 50% of a zero width put it on
+     * the left border — off screen twice over.
+     */
+    .edge-direction-hint {
+      position: absolute;
+      /*
+       * Hangs UPWARDS from the line render() computes, rather than downwards
+       * from it. The widget now paints UNDER the toolbars (see
+       * EDGE_DIRECTION_Z_INDEX), so a box whose lower third crossed the
+       * 80px-tall toolbar strip would have that third clipped away by it — and
+       * the clipped third is where a two-line hint puts its second line.
+       * HINT_BOTTOM_GAP is the strip's clearance, so anchoring the box's
+       * BOTTOM there puts the whole of it in the clear whatever it says.
+       */
+      transform: translate(-50%, -100%);
+      /*
+       * width, not max-width alone. An absolutely positioned box shrinks to fit
+       * its CONTAINING BLOCK, and this one's containing block is the zero-sized
+       * widget host — so the banner collapsed to its longest word (95 px) and
+       * grew five lines tall, which is how it ended up below the bottom edge it
+       * was supposed to sit above. max-content sizes it to the sentence; the cap
+       * comes from render(), which knows how wide the viewport is.
+       */
+      width: max-content;
+      /* So the viewport-derived max-width caps the BOX, padding and border
+         included — the number render() computes is a screen budget, not a
+         content budget. */
+      box-sizing: border-box;
+      padding: 6px 12px;
+      border-radius: 8px;
+      border: 1px solid var(--affine-border-color);
+      background: var(--affine-background-overlay-panel-color, #fff);
+      box-shadow: var(--affine-shadow-1);
+      color: var(--affine-text-secondary-color);
+      font-family: var(--affine-font-family);
+      font-size: 13px;
+      line-height: 1.4;
+      text-align: center;
+      pointer-events: none;
+    }
+  `; }
+        #_revealed_accessor_storage = __runInitializers(this, __revealed_initializers, []);
+        get _revealed() { return this.#_revealed_accessor_storage; }
+        set _revealed(value) { this.#_revealed_accessor_storage = value; }
+        #_hint_accessor_storage = (__runInitializers(this, __revealed_extraInitializers), __runInitializers(this, __hint_initializers, null));
+        get _hint() { return this.#_hint_accessor_storage; }
+        set _hint(value) { this.#_hint_accessor_storage = value; }
+        get gfx() {
+            return this.std.get(GfxControllerIdentifier);
+        }
+        get _manager() {
+            return this.std.getOptional(EdgeDirectionManager) ?? null;
+        }
+        /**
+         * Idempotent wiring, called from both `firstUpdated` and a later
+         * `connectedCallback`: `WithDisposable` throws its group away on disconnect
+         * while lit runs `firstUpdated` once, so wiring done only there never comes
+         * back if the widget is detached and re-attached.
+         */
+        _wire() {
+            const manager = this._manager;
+            if (!manager)
+                return;
+            this._disposables.add(effect(() => {
+                const next = manager.revealed$.value;
+                if (next.length === 0 && this._revealed.length === 0)
+                    return;
+                this._revealed = next;
+            }));
+            this._disposables.add(effect(() => {
+                this._hint = manager.armedHint$.value;
+            }));
+            this._disposables.add(this.gfx.viewport.viewportUpdated.subscribe(() => {
+                // The label is pinned to a model point AND scaled by the zoom, so a pan
+                // or a zoom moves it — and the hint is pinned to the viewport's own
+                // size, so a RESIZE moves that one. Both are on screen only while
+                // something is revealed
+                // or a tool is armed, so a quiet board re-renders nothing.
+                if (this._revealed.length > 0 || this._hint !== null) {
+                    this.requestUpdate();
+                }
+            }));
+            const surface = this.gfx.surface;
+            if (surface) {
+                const subscription = surface.elementUpdated.subscribe(() => {
+                    // An endpoint re-drag reroutes the path under the label. Cheap: lit
+                    // batches this into one render per frame, and it only runs while
+                    // something is actually revealed.
+                    if (this._revealed.length > 0)
+                        this.requestUpdate();
+                });
+                this._disposables.add(() => subscription.unsubscribe());
+            }
+        }
+        connectedCallback() {
+            super.connectedCallback();
+            if (this.hasUpdated)
+                this._wire();
+        }
+        firstUpdated() {
+            this._wire();
+        }
+        /**
+         * The word a revealed edge is labelled with, in the framework's own words —
+         * the role's verb, said in the host's language.
+         *
+         * `''` when the role declares neither verb nor label, in which case the
+         * caller draws nothing at all.
+         */
+        _verbFor(edge) {
+            const verb = edgeVerbOf(edge);
+            return verb ? translateKey(this.std, verb.key, verb.fallback) : '';
+        }
+        _renderLabel(edgeId) {
+            const manager = this._manager;
+            const edge = manager
+                ?.revealedEdges()
+                .find(candidate => candidate.model.id === edgeId);
+            if (!edge)
+                return nothing;
+            const anchor = labelAnchorOf(edge.model);
+            if (!anchor)
+                return nothing;
+            const verb = this._verbFor(edge);
+            if (!verb)
+                return nothing;
+            const { viewport } = this.gfx;
+            const [x, y] = viewport.toViewCoord(anchor.at[0], anchor.at[1]);
+            // Two decimals: below what a reader can see on a 12 px box, and it keeps
+            // the attribute readable in devtools instead of `45.00000000000001deg`.
+            const degrees = ((anchor.angle * 180) / Math.PI).toFixed(2);
+            return html `<div
+      class="edge-direction-label"
+      data-testid="edge-direction-label"
+      data-edge-id=${edgeId}
+      data-arrow=${anchor.flipped ? 'start' : 'end'}
+      title=${edge.role.labelKey
+                ? translateKey(this.std, edge.role.labelKey, edge.role.labelFallback)
+                : verb}
+      style=${styleMap({
+                left: `${x}px`,
+                top: `${y}px`,
+                // Read right to left, as CSS composes it: scale by the zoom and turn
+                // onto the line, both about the box's centre, and only THEN slide that
+                // centre onto the anchor. The lengths in the class are model units, so
+                // `scale` is what makes them model units on screen.
+                transform: `translate(-50%, -50%) rotate(${degrees}deg) scale(${viewport.zoom})`,
+            })}
+    >
+      ${verb}
+    </div>`;
+        }
+        /**
+         * The armed tool's hint, centred near the bottom of the EDITOR VIEWPORT —
+         * above the toolbar, where the user's eyes already are while they aim.
+         *
+         * The viewport rect is the only frame available to a widget host that is a
+         * zero-sized box at its origin, and it is the one the other canvas
+         * affordances measure against (`violation-detail-widget` flips its bubble
+         * against `viewport.width` / `viewport.height` the same way).
+         */
+        _renderHint(hint) {
+            const { viewport } = this.gfx;
+            return html `<div
+      class="edge-direction-hint"
+      data-testid="edge-direction-hint"
+      style=${styleMap({
+                left: `${viewport.width / 2}px`,
+                // The BOTTOM of the box, since the rule above hangs it upwards. The
+                // floor is what keeps a very short editor pushing the banner down
+                // rather than off its top edge, which is what `0` would now do.
+                top: `${Math.max(HINT_MIN_HEIGHT, viewport.height - HINT_BOTTOM_GAP)}px`,
+                // The cap a percentage cannot express here: the containing block is the
+                // zero-sized host, so the only honest width bound is the viewport's.
+                maxWidth: `${Math.max(120, Math.min(HINT_MAX_WIDTH, viewport.width - 32))}px`,
+            })}
+    >
+      ${translateKey(this.std, hint.key, hint.fallback)}
+    </div>`;
+        }
+        render() {
+            if (this._revealed.length === 0 && this._hint === null)
+                return nothing;
+            return html `${this._revealed.map(id => this._renderLabel(id))}
+    ${this._hint ? this._renderHint(this._hint) : nothing}`;
+        }
+        constructor() {
+            super(...arguments);
+            __runInitializers(this, __hint_extraInitializers);
+        }
+    };
+})();
+export { EdgeDirectionWidget };
+export const edgeDirectionWidget = WidgetViewExtension('affine:page', EDGE_DIRECTION_WIDGET, literal `${unsafeStatic(EDGE_DIRECTION_WIDGET)}`);

package/dist/_pkgs/affine-gfx-connector/direction/index.d.ts

@@ -0,0 +1,4 @@
+export { EDGE_DIRECTION_COLOR, EdgeDirectionManager, type EdgeLabelAnchor, labelAnchorOf, } from './direction-reveal.js';
+export { EDGE_DIRECTION_WIDGET, EdgeDirectionWidget, edgeDirectionWidget, } from './direction-widget.js';
+export { edgeDirectionCommands, INVERT_EDGE_DIRECTION, invertEdge, invertEdgeDirectionParams, invertibleEdges, type InvertEdgeDirectionParams, } from './invert-direction.js';
+export { asTypedEdge, edgeIsBound, type EdgeVerb, edgeVerbOf, roleVocabularies, type TypedEdge, } from './typed-edge.js';

package/dist/_pkgs/affine-gfx-connector/direction/index.js

@@ -0,0 +1,4 @@
+export { EDGE_DIRECTION_COLOR, EdgeDirectionManager, labelAnchorOf, } from './direction-reveal.js';
+export { EDGE_DIRECTION_WIDGET, EdgeDirectionWidget, edgeDirectionWidget, } from './direction-widget.js';
+export { edgeDirectionCommands, INVERT_EDGE_DIRECTION, invertEdge, invertEdgeDirectionParams, invertibleEdges, } from './invert-direction.js';
+export { asTypedEdge, edgeIsBound, edgeVerbOf, roleVocabularies, } from './typed-edge.js';

package/dist/_pkgs/affine-gfx-connector/direction/invert-direction.d.ts

@@ -0,0 +1,72 @@
+import type { ConnectorElementModel } from '../../affine-model/index.js';
+import type { AnyCommandDescriptor, BlockStdScope } from '../../std/index.js';
+import { z } from 'zod';
+import { type TypedEdge } from './typed-edge.js';
+/**
+ * **M3 of `docs/adr/0010` — "let them fix it".**
+ *
+ * `edge.invert-direction` swaps `source` ↔ `target` on a selected typed edge,
+ * and swaps `frontEndpointStyle` ↔ `rearEndpointStyle` with them, in ONE undo
+ * step. It is the only supported inversion, and it is what makes the direction
+ * a typed edge persists a statement the user can take back rather than a
+ * by-product of which end their finger landed on first.
+ *
+ * ## What it deliberately does NOT touch
+ *
+ * `curveControlPoint` is an ABSOLUTE pass-through point at t = 0.5, and the
+ * tangent formulas are symmetric under a `P0` ↔ `P3` exchange
+ * (`connector-manager.ts`), so swapping the ends leaves exactly the same curve
+ * on screen. "Mirroring" it would visibly move the curve — that would be a bug,
+ * not a fix, and a unit test pins the rendered path against the day somebody
+ * tidies this up.
+ *
+ * ## Why it writes through the surface and not through `EdgelessCRUDIdentifier`
+ *
+ * `crud.updateElement` calls `recordLastProps`, which would make the swapped
+ * endpoint styles the DEFAULT for every connector drawn afterwards — the exact
+ * defect `b.flip-direction` has today. An inversion is a statement about one
+ * relation, never a style preference.
+ */
+export declare const invertEdgeDirectionParams: z.ZodObject<{
+    /**
+     * Explicit targets, for a host or an agent acting on something other than the
+     * live selection. **Omitted** — the key absent — the command acts on the
+     * current canvas selection. An EMPTY array means "these zero elements": the
+     * command does nothing and does not fall back to the selection.
+     */
+    elementIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    elementIds?: string[] | undefined;
+}, {
+    elementIds?: string[] | undefined;
+}>;
+export type InvertEdgeDirectionParams = z.infer<typeof invertEdgeDirectionParams>;
+/**
+ * The typed edges this gesture would rewrite.
+ *
+ * Typed edges and nothing else: on a generalist connector `source` and `target`
+ * carry no claim, so there is no relation to invert and the two ends are
+ * already interchangeable labels. Reversing one would be a gesture with no
+ * meaning attached.
+ *
+ * BOUND typed edges, at that. An edge with a free end relates nothing, so
+ * swapping its ends moves no relation and shows nothing on screen — the line
+ * does not budge, and the reveal (M2) and W4 both look straight past it. An
+ * entry that offers to reverse it is an entry that does nothing when clicked,
+ * which is worse than an absent one.
+ */
+export declare function invertibleEdges(std: BlockStdScope, elementIds?: string[]): TypedEdge[];
+/**
+ * Swap the two ends of one typed edge. Pure model write, no capture, no
+ * telemetry — exported so a unit test can assert the involution without an
+ * editor around it.
+ */
+export declare function invertEdge(model: ConnectorElementModel): void;
+/** The registered id, so a toolbar entry can invoke it rather than copy it. */
+export declare const INVERT_EDGE_DIRECTION = "edge.invert-direction";
+/**
+ * The registry's element type erases the parameter contract, and `run`
+ * re-validates with the zod schema rather than trusting the static type — what
+ * an agent-invocable command has to do anyway.
+ */
+export declare const edgeDirectionCommands: AnyCommandDescriptor[];

package/dist/_pkgs/affine-gfx-connector/direction/invert-direction.js

@@ -0,0 +1,187 @@
+import { TelemetryProvider } from '../../affine-shared/services/index.js';
+import { GfxControllerIdentifier } from '../../std/gfx/index.js';
+import { z } from 'zod';
+import { asTypedEdge, edgeIsBound, roleVocabularies, } from './typed-edge.js';
+/**
+ * **M3 of `docs/adr/0010` — "let them fix it".**
+ *
+ * `edge.invert-direction` swaps `source` ↔ `target` on a selected typed edge,
+ * and swaps `frontEndpointStyle` ↔ `rearEndpointStyle` with them, in ONE undo
+ * step. It is the only supported inversion, and it is what makes the direction
+ * a typed edge persists a statement the user can take back rather than a
+ * by-product of which end their finger landed on first.
+ *
+ * ## What it deliberately does NOT touch
+ *
+ * `curveControlPoint` is an ABSOLUTE pass-through point at t = 0.5, and the
+ * tangent formulas are symmetric under a `P0` ↔ `P3` exchange
+ * (`connector-manager.ts`), so swapping the ends leaves exactly the same curve
+ * on screen. "Mirroring" it would visibly move the curve — that would be a bug,
+ * not a fix, and a unit test pins the rendered path against the day somebody
+ * tidies this up.
+ *
+ * ## Why it writes through the surface and not through `EdgelessCRUDIdentifier`
+ *
+ * `crud.updateElement` calls `recordLastProps`, which would make the swapped
+ * endpoint styles the DEFAULT for every connector drawn afterwards — the exact
+ * defect `b.flip-direction` has today. An inversion is a statement about one
+ * relation, never a style preference.
+ */
+export const invertEdgeDirectionParams = z.object({
+    /**
+     * Explicit targets, for a host or an agent acting on something other than the
+     * live selection. **Omitted** — the key absent — the command acts on the
+     * current canvas selection. An EMPTY array means "these zero elements": the
+     * command does nothing and does not fall back to the selection.
+     */
+    elementIds: z.array(z.string()).optional(),
+});
+/** Whether this document may be written to at all. */
+const isInvertible = (std) => !std.store.readonly;
+/**
+ * The typed edges this gesture would rewrite.
+ *
+ * Typed edges and nothing else: on a generalist connector `source` and `target`
+ * carry no claim, so there is no relation to invert and the two ends are
+ * already interchangeable labels. Reversing one would be a gesture with no
+ * meaning attached.
+ *
+ * BOUND typed edges, at that. An edge with a free end relates nothing, so
+ * swapping its ends moves no relation and shows nothing on screen — the line
+ * does not budge, and the reveal (M2) and W4 both look straight past it. An
+ * entry that offers to reverse it is an entry that does nothing when clicked,
+ * which is worse than an absent one.
+ */
+export function invertibleEdges(std, elementIds) {
+    const gfx = std.get(GfxControllerIdentifier);
+    const vocabularies = roleVocabularies(std);
+    if (vocabularies.length === 0)
+        return [];
+    const models = elementIds
+        ? elementIds.map(id => gfx.surface?.getElementById(id))
+        : gfx.selection.selectedElements;
+    const edges = [];
+    for (const model of models) {
+        const edge = asTypedEdge(vocabularies, model);
+        if (edge && edgeIsBound(edge.model) && !edge.model.isLocked()) {
+            edges.push(edge);
+        }
+    }
+    return edges;
+}
+/**
+ * A plain copy of one endpoint. The stored value comes out of a `Y.Map` and is
+ * about to be written into the OTHER slot of the same element, so it is copied
+ * key by key rather than moved: the two accessors must never end up sharing one
+ * object, and an absent key must stay absent instead of becoming `undefined`.
+ */
+function copyConnection(connection) {
+    const copy = {};
+    if (connection?.id !== undefined)
+        copy.id = connection.id;
+    if (connection?.position !== undefined) {
+        copy.position = [connection.position[0], connection.position[1]];
+    }
+    return copy;
+}
+/**
+ * Swap the two ends of one typed edge. Pure model write, no capture, no
+ * telemetry — exported so a unit test can assert the involution without an
+ * editor around it.
+ */
+export function invertEdge(model) {
+    const source = copyConnection(model.source);
+    const target = copyConnection(model.target);
+    model.surface.updateElement(model.id, {
+        source: target,
+        target: source,
+        // The mark follows the relation. Leaving the styles behind would move the
+        // only visible sign of the direction away from the end that now carries it
+        // — the picture and the data would disagree, which is precisely what
+        // `b.flip-direction` does on a typed edge.
+        frontEndpointStyle: model.rearEndpointStyle,
+        rearEndpointStyle: model.frontEndpointStyle,
+    });
+}
+/** The registered id, so a toolbar entry can invoke it rather than copy it. */
+export const INVERT_EDGE_DIRECTION = 'edge.invert-direction';
+const invertEdgeDirection = {
+    id: INVERT_EDGE_DIRECTION,
+    owner: 'core',
+    kind: 'action',
+    // NOT under `com.labre.keyboardShortcuts.*`: like `pivot.bind`, this one is
+    // keyless by intent and lives on the contextual toolbar, in the palette and
+    // in the agent — filing it under "keyboard shortcuts" would mislead a
+    // translator.
+    labelKey: 'com.labre.command.edge.invert-direction',
+    labelFallback: 'Reverse direction',
+    descriptionKey: 'com.labre.command.edge.invert-direction.description',
+    descriptionFallback: 'Swap the two ends of this relation: what was the subject becomes the object.',
+    surfaces: ['contextual-toolbar', 'palette', 'agent'],
+    scope: 'edgeless',
+    // Keyless by intent — still bindable from Settings › Shortcuts, which is what
+    // `toShortcutDescriptor` being total buys.
+    defaultKeys: { mac: [], other: [] },
+    availability: 'selection',
+    // Narrows `'selection'`, never contradicts it: a read-only document and a
+    // selection holding no typed edge both have nothing to invert. Read-only
+    // rides here rather than on `availability` for the reason `pivot.bind`
+    // documents — the union does not compose, and `'selection'` is the
+    // precondition a catalogue has to show.
+    when: std => isInvertible(std) && invertibleEdges(std).length > 0,
+    params: invertEdgeDirectionParams,
+    run: (std, invocation, params) => {
+        // `params ?? {}`, and the `??` is load-bearing: every in-library call site
+        // invokes this command with NO arguments — the contextual toolbar, the
+        // palette and `toShortcutDescriptor`'s handler all call
+        // `runCommand(std, command, invocation)` — and `safeParse(undefined)` fails
+        // on the OBJECT itself, not on a field. Parsing the argument as it arrives
+        // made the command a silent no-op everywhere except a caller that passed
+        // `elementIds` explicitly, which was exactly the one shape the first tests
+        // exercised. The schema's own optionality is what makes `{}` valid, so this
+        // reads "no arguments" rather than "invalid arguments".
+        const parsed = invertEdgeDirectionParams.safeParse(params ?? {});
+        if (!parsed.success) {
+            console.error('edge.invert-direction: invalid params', parsed.error.issues);
+            return;
+        }
+        // The load-bearing half of the read-only gate: `when` is consulted by the
+        // SURFACES, and `runCommand` consults neither it nor `availability` — the
+        // palette and the agent reach `run` directly.
+        if (!isInvertible(std))
+            return;
+        const edges = invertibleEdges(std, parsed.data.elementIds);
+        if (edges.length === 0)
+            return;
+        // BEFORE the writes, not after: `Store.transact` is not an undo boundary,
+        // and without this an inversion issued within 500 ms of a drag would be
+        // undone TOGETHER with the drag. One capture for the whole gesture is also
+        // what makes several selected edges reverse in a single undo step.
+        std.store.captureSync();
+        for (const { model } of edges)
+            invertEdge(model);
+        // The ONE emission for this gesture, and not through `runCommand`'s
+        // bottleneck: that emitter maps a static `{ framework, element }` onto the
+        // three CREATION events, and an inversion creates nothing.
+        const roles = new Set(edges.map(edge => edge.role.id));
+        const role = roles.size === 1 ? [...roles][0] : undefined;
+        std.getOptional(TelemetryProvider)?.track('EdgeDirectionInverted', {
+            page: 'whiteboard editor',
+            ...(role !== undefined ? { role } : {}),
+            ...(role !== undefined
+                ? { framework: role.split(':')[0] }
+                : {}),
+            elementCount: edges.length,
+            control: invocation.source,
+            module: invocation.surface,
+        });
+    },
+};
+/**
+ * The registry's element type erases the parameter contract, and `run`
+ * re-validates with the zod schema rather than trusting the static type — what
+ * an agent-invocable command has to do anyway.
+ */
+export const edgeDirectionCommands = [
+    invertEdgeDirection,
+];