From 69b9003decf5e5e51d54b866caf5aaa13dd82d51 Mon Sep 17 00:00:00 2001
From: Roman Bruckner <bruckner.roman@gmail.com>
Date: Tue, 11 Aug 2026 18:52:22 +0200
Subject: [PATCH 1/2] fix: let the guard option veto a blank pointerdown;
 buttons that click and drag

Backport of #3438 (targets dev) onto master. Net change of the PR's 10
commits, applied to master's identical core/preset base.

- joint-core: split guard() into guardExplicit() (event-level veto/allow)
  + guard() (event + target), so options.guard can veto a blank pointerdown;
  split FORM_CONTROL_TAG_NAMES vs PREVENT_INTERACTION_TAG_NAMES and match
  both across the target path (not just evt.target); drop OPTION.
- joint-react: preset guards portaled overlay content via guardExplicit,
  lets a <button> in a node/magnet both click and drag (drops BUTTON from
  PREVENT_INTERACTION_TAG_NAMES, swallows the trailing click after a move).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/joint-core/src/dia/Paper.mjs         |  89 ++++--
 packages/joint-core/test/jointjs/paper.js     | 210 ++++++++++++++
 packages/joint-core/test/ts/index.test.ts     |   5 +
 packages/joint-core/types/dia.d.ts            |   9 +-
 .../paper-html-content-events.test.tsx        | 127 +++++++++
 .../src/hooks/__tests__/use-markup.test.tsx   |  10 +-
 packages/joint-react/src/hooks/use-markup.ts  |  30 ++
 .../paper-button-interactions.test.tsx        | 135 +++++++++
 packages/joint-react/src/presets/paper.ts     |  73 ++++-
 .../examples/buttons-in-magnets/code.tsx      | 265 ++++++++++++++++++
 .../examples/buttons-in-magnets/story.tsx     |  25 ++
 11 files changed, 953 insertions(+), 25 deletions(-)
 create mode 100644 packages/joint-react/src/components/paper/__tests__/paper-html-content-events.test.tsx
 create mode 100644 packages/joint-react/src/presets/__tests__/paper-button-interactions.test.tsx
 create mode 100644 packages/joint-react/stories/examples/buttons-in-magnets/code.tsx
 create mode 100644 packages/joint-react/stories/examples/buttons-in-magnets/story.tsx

diff --git a/packages/joint-core/src/dia/Paper.mjs b/packages/joint-core/src/dia/Paper.mjs
index 5ad5458448..0a4263199d 100644
--- a/packages/joint-core/src/dia/Paper.mjs
+++ b/packages/joint-core/src/dia/Paper.mjs
@@ -302,6 +302,19 @@ const backgroundPatterns = {
 
 const CELL_VIEW_PLACEHOLDER_MARKER = Symbol('joint.cellViewPlaceholderMarker');
 
+// Is `target`, or any of its ancestors up to and including `boundary`, one of `tagNames`?
+// The press target of `<button><span>Save</span></button>` is the SPAN, so testing the
+// target alone would tell us nothing about the control it belongs to.
+function hasTagNameInPath(target, tagNames, boundary) {
+    let node = target;
+    while (node) {
+        if (tagNames.includes(node.tagName)) return true;
+        if (node === boundary) return false;
+        node = node.parentElement;
+    }
+    return false;
+}
+
 export const Paper = View.extend({
     className: 'paper',
 
@@ -587,9 +600,19 @@ export const Paper = View.extend({
     _layers: null,
 
     UPDATE_DELAYING_BATCHES: ['translate'],
-    // If you interact with these elements,
-    // the default interaction such as `element move` is prevented.
-    FORM_CONTROL_TAG_NAMES: ['TEXTAREA', 'INPUT', 'BUTTON', 'SELECT', 'OPTION'] ,
+    // If you interact with these elements, the browser's own default action is kept
+    // (the paper does not call `preventDefault()`), so a text input can be focused and
+    // its text selected, a checkbox can be ticked, a button can be pressed. Matched
+    // against the whole path up to the cell view, so a press on markup inside a control
+    // counts as a press on the control - `<option>` through its `<select>`, a label
+    // `<span>` through its `<button>`.
+    FORM_CONTROL_TAG_NAMES: ['TEXTAREA', 'INPUT', 'BUTTON', 'SELECT'],
+    // If you interact with these elements, the default interaction such as `element move`
+    // or starting a link from a magnet is prevented, i.e. a press is only ever a click.
+    // The same members as above by default, but a separate decision: narrow this list to
+    // let a control both be clicked and start a drag - dropping `BUTTON`, say, makes a
+    // button inside a magnet draggable to create a link while it stays clickable.
+    PREVENT_INTERACTION_TAG_NAMES: ['TEXTAREA', 'INPUT', 'BUTTON', 'SELECT'],
     // If you interact with these elements, the events are not propagated to the paper
     // i.e. paper events such as `element:pointerdown` are not triggered.
     GUARDED_TAG_NAMES: [
@@ -3476,20 +3499,31 @@ export const Paper = View.extend({
         const view = this.findView(target);
         const isContextMenu = (button === 2);
 
-        if (view) {
+        if (!isContextMenu) {
+            // A press that did not hit a cell view is guarded too, so that DOM content
+            // inside `el` (an overlay, a popup, a toolbar) can opt out of opening a blank
+            // interaction. Only an explicit veto counts there: the full `guard()` also
+            // rejects anything off the paper's event surface, and such a press has always
+            // opened a blank interaction.
+            // `contextmenu` is exempt: `contextMenuTrigger()` runs its own guard.
+            const guarded = view
+                ? this.guard(evt, view)
+                : this.guardExplicit(evt, view);
 
-            if (!isContextMenu && this.guard(evt, view)) return;
+            if (guarded) return;
+        }
 
-            const isTargetFormNode = this.FORM_CONTROL_TAG_NAMES.includes(target.tagName);
+        if (view) {
 
-            if (this.options.preventDefaultViewAction && !isTargetFormNode) {
+            if (this.options.preventDefaultViewAction &&
+                !hasTagNameInPath(target, this.FORM_CONTROL_TAG_NAMES, view.el)) {
                 // If the target is a form element, we do not want to prevent the default action.
                 // For example, we want to be able to select text in a text input or
                 // to be able to click on a checkbox.
                 evt.preventDefault();
             }
 
-            if (isTargetFormNode) {
+            if (hasTagNameInPath(target, this.PREVENT_INTERACTION_TAG_NAMES, view.el)) {
                 // If the target is a form element, we do not want to start dragging the element.
                 // For example, we want to be able to select text by dragging the mouse.
                 view.preventDefaultInteraction(evt);
@@ -3889,17 +3923,9 @@ export const Paper = View.extend({
     // Otherwise, it returns `false`.
     guard: function(evt, view) {
 
-        if (evt.type === 'mousedown' && evt.button === 2) {
-            // handled as `contextmenu` type
-            return true;
-        }
-
-        if (this.options.guard && this.options.guard(evt, view)) {
-            return true;
-        }
-
-        if (evt.data && evt.data.guarded !== undefined) {
-            return evt.data.guarded;
+        const guarded = this.guardExplicit(evt, view);
+        if (guarded !== undefined) {
+            return guarded;
         }
 
         const { target } = evt;
@@ -3919,6 +3945,31 @@ export const Paper = View.extend({
         return true;    // Event guarded. Paper should not react on it in any way.
     },
 
+    // The part of `guard()` that reflects a decision made about this very event: the right
+    // mouse button, the `guard` option, an `evt.data.guarded` flag. Returns a boolean when
+    // one of them has decided and `undefined` when none has, leaving the answer to the
+    // caller - `guard()` then goes on to judge the target itself (its tag name, its view,
+    // whether it is on the paper's event surface). `undefined` is the only non-boolean it
+    // returns, so a caller can tell "explicitly allowed" from "no opinion".
+    guardExplicit: function(evt, view) {
+
+        if (evt.type === 'mousedown' && evt.button === 2) {
+            // handled as `contextmenu` type
+            return true;
+        }
+
+        if (this.options.guard && this.options.guard(evt, view)) {
+            return true;
+        }
+
+        if (evt.data && evt.data.guarded !== undefined) {
+            // Set by the caller, so it can be any value. Only `undefined` means undecided.
+            return !!evt.data.guarded;
+        }
+
+        return undefined;
+    },
+
     setGridSize: function(gridSize) {
         const { options } = this;
         options.gridSize = gridSize;
diff --git a/packages/joint-core/test/jointjs/paper.js b/packages/joint-core/test/jointjs/paper.js
index a7a12dabd0..f99bd9a832 100644
--- a/packages/joint-core/test/jointjs/paper.js
+++ b/packages/joint-core/test/jointjs/paper.js
@@ -1240,6 +1240,216 @@ QUnit.module('paper', function(hooks) {
         assert.ok(diffX < 5 && diffY < 5, 'element should not have been moved');
     });
 
+    QUnit.test('a press on DOM content inside the paper can be guarded', function(assert) {
+
+        // `guard()` rejects a target that is not on the event surface, so an HTML overlay,
+        // popup or toolbar inside `paper.el` gets no `blank:pointerclick` and no hover
+        // events. A press on one has always opened a blank interaction regardless, and
+        // still does - but `pointerdown` now consults the `guard` option there too, so an
+        // overlay can opt out of it.
+        const overlayEl = document.createElement('div');
+        this.paper.el.appendChild(overlayEl);
+
+        assert.equal(this.paper.guard({ type: 'mousedown', button: 0, target: overlayEl }), true,
+            'guard() rejects an HTML overlay target');
+
+        let blankPointerdownCount = 0;
+        this.paper.on('blank:pointerdown', function() {
+            blankPointerdownCount += 1;
+        });
+
+        simulate.mousedown({ el: overlayEl, clientX: 10, clientY: 10 });
+        simulate.mouseup({ el: overlayEl, clientX: 10, clientY: 10 });
+
+        assert.equal(blankPointerdownCount, 1,
+            'a press on HTML content inside the paper opens a blank interaction');
+
+        // The `guard` option vetoes it.
+        this.paper.options.guard = function(evt) {
+            return overlayEl.contains(evt.target);
+        };
+
+        simulate.mousedown({ el: overlayEl, clientX: 10, clientY: 10 });
+        simulate.mouseup({ el: overlayEl, clientX: 10, clientY: 10 });
+
+        assert.equal(blankPointerdownCount, 1, 'the guard option prevents it');
+
+        // A genuine blank press (on the SVG) is unaffected by that guard.
+        simulate.mousedown({ el: this.paper.svg, clientX: 10, clientY: 10 });
+        simulate.mouseup({ el: this.paper.svg, clientX: 10, clientY: 10 });
+
+        assert.equal(blankPointerdownCount, 2, 'blank:pointerdown still fires on the SVG');
+
+        // Only the `guard` option, `evt.data.guarded` and the right button speak for a
+        // press that hit no cell view. `GUARDED_TAG_NAMES` judges the target instead, and
+        // stays out of it: a <select> in an overlay opens a blank interaction like any
+        // other DOM content there, exactly as it always has.
+        this.paper.options.guard = null;
+        const selectEl = document.createElement('select');
+        overlayEl.appendChild(selectEl);
+
+        assert.equal(this.paper.guard({ type: 'mousedown', button: 0, target: selectEl }), true,
+            'guard() still rejects a <select>');
+
+        simulate.mousedown({ el: selectEl, clientX: 10, clientY: 10 });
+        simulate.mouseup({ el: selectEl, clientX: 10, clientY: 10 });
+
+        assert.equal(blankPointerdownCount, 3, 'a <select> in an overlay is not treated differently');
+
+        overlayEl.remove();
+    });
+
+    QUnit.test('a press on a form control does not drag the element', function(assert) {
+
+        // FORM_CONTROL_TAG_NAMES marks a press on a <button>/<input>/<select>/<textarea>/
+        // <option> as default-interaction-prevented, so neither an element move
+        // (`ElementView#dragStart`) nor a link drag (`ElementView#dragMagnetStart`) begins
+        // from one. That is what lets a clickable control live inside a draggable element.
+        const element = new joint.shapes.standard.Rectangle({
+            position: { x: 100, y: 100 },
+            size: { width: 100, height: 100 },
+            markup: joint.util.svg`
+                <foreignObject @selector="fo" width="100" height="100">
+                    <button @selector="button" type="button">click me</button>
+                </foreignObject>
+            `
+        });
+        this.graph.addCell(element);
+
+        const elementView = this.paper.findViewByModel(element);
+        const buttonEl = elementView.findNode('button');
+        assert.ok(buttonEl, 'the button is rendered');
+
+        const positionBefore = element.position();
+
+        simulate.mousedown({ el: buttonEl, clientX: 150, clientY: 150 });
+        simulate.mousemove({ el: buttonEl, clientX: 250, clientY: 250 });
+        simulate.mouseup({ el: buttonEl, clientX: 250, clientY: 250 });
+
+        assert.deepEqual(element.position(), positionBefore,
+            'the element did not move when dragging from a <button>');
+
+        // Control: the same gesture on the element body DOES move it, so the assertion
+        // above reflects the form-control gate and not an inert drag simulation.
+        simulate.mousedown({ el: elementView.el, clientX: 150, clientY: 150 });
+        simulate.mousemove({ el: elementView.el, clientX: 250, clientY: 250 });
+        simulate.mouseup({ el: elementView.el, clientX: 250, clientY: 250 });
+
+        assert.notDeepEqual(element.position(), positionBefore,
+            'the element moved when dragging from its body');
+    });
+
+    QUnit.test('a press inside a form control counts as a press on it', function(assert) {
+
+        // Both tag-name lists are matched against the whole path up to the cell view, not
+        // against `evt.target` alone: the press target of `<button><span>text</span></button>`
+        // is the SPAN, so a control with any markup inside it - an icon, a label span -
+        // would otherwise behave the opposite way round from a bare one.
+        const element = new joint.shapes.standard.Rectangle({
+            position: { x: 100, y: 100 },
+            size: { width: 100, height: 100 },
+            markup: joint.util.svg`
+                <foreignObject @selector="fo" width="100" height="100">
+                    <button @selector="button" type="button"><span @selector="inner">click me</span></button>
+                </foreignObject>
+            `
+        });
+        this.graph.addCell(element);
+
+        const elementView = this.paper.findViewByModel(element);
+        const innerEl = elementView.findNode('inner');
+        assert.equal(innerEl.tagName, 'SPAN', 'the press target is the <span>, not the <button>');
+
+        const positionBefore = element.position();
+        const mousedownEvt = simulate.mousedown({ el: innerEl, clientX: 150, clientY: 150 });
+        simulate.mousemove({ el: innerEl, clientX: 250, clientY: 250 });
+        simulate.mouseup({ el: innerEl, clientX: 250, clientY: 250 });
+
+        assert.deepEqual(element.position(), positionBefore,
+            'the element did not move when dragging from inside a <button>');
+        assert.notOk(mousedownEvt.defaultPrevented,
+            'the <button> keeps its default action, so it can still be focused');
+    });
+
+    QUnit.test('an <option> counts through its <select>', function(assert) {
+
+        // `OPTION` is not listed: it can only exist inside a `<select>`, which is, and the
+        // lists are matched against the whole path. A `<select multiple>` renders its
+        // options inline, so they do receive real presses.
+        assert.notOk(this.paper.FORM_CONTROL_TAG_NAMES.includes('OPTION'),
+            'OPTION is not in FORM_CONTROL_TAG_NAMES');
+        assert.notOk(this.paper.PREVENT_INTERACTION_TAG_NAMES.includes('OPTION'),
+            'OPTION is not in PREVENT_INTERACTION_TAG_NAMES');
+
+        const element = new joint.shapes.standard.Rectangle({
+            position: { x: 100, y: 100 },
+            size: { width: 100, height: 100 },
+            markup: joint.util.svg`
+                <foreignObject @selector="fo" width="100" height="100">
+                    <select @selector="select" multiple="multiple">
+                        <option @selector="option" value="a">a</option>
+                        <option value="b">b</option>
+                    </select>
+                </foreignObject>
+            `
+        });
+        this.graph.addCell(element);
+
+        const elementView = this.paper.findViewByModel(element);
+        const optionEl = elementView.findNode('option');
+        assert.equal(optionEl.tagName, 'OPTION', 'the press target is the <option>');
+
+        const positionBefore = element.position();
+        const mousedownEvt = simulate.mousedown({ el: optionEl, clientX: 150, clientY: 150 });
+        simulate.mousemove({ el: optionEl, clientX: 250, clientY: 250 });
+        simulate.mouseup({ el: optionEl, clientX: 250, clientY: 250 });
+
+        assert.deepEqual(element.position(), positionBefore,
+            'the element did not move when dragging from an <option>');
+        assert.notOk(mousedownEvt.defaultPrevented,
+            'the <select> keeps its default action');
+    });
+
+    QUnit.test('PREVENT_INTERACTION_TAG_NAMES is separate from FORM_CONTROL_TAG_NAMES', function(assert) {
+
+        // The two lists start out identical but answer different questions:
+        // FORM_CONTROL_TAG_NAMES keeps the browser's default action (no `preventDefault`),
+        // PREVENT_INTERACTION_TAG_NAMES blocks the paper's own interactions. Narrowing only
+        // the second one is what lets a <button> be clicked AND dragged - to move the
+        // element, or to start a link when it sits in a magnet.
+        assert.deepEqual(this.paper.PREVENT_INTERACTION_TAG_NAMES, this.paper.FORM_CONTROL_TAG_NAMES,
+            'the defaults match, so the split changes nothing on its own');
+        assert.notStrictEqual(this.paper.PREVENT_INTERACTION_TAG_NAMES, this.paper.FORM_CONTROL_TAG_NAMES,
+            'but they are distinct arrays, so overriding one leaves the other alone');
+
+        const element = new joint.shapes.standard.Rectangle({
+            position: { x: 100, y: 100 },
+            size: { width: 100, height: 100 },
+            markup: joint.util.svg`
+                <foreignObject @selector="fo" width="100" height="100">
+                    <button @selector="button" type="button">click me</button>
+                </foreignObject>
+            `
+        });
+        this.graph.addCell(element);
+
+        const elementView = this.paper.findViewByModel(element);
+        const buttonEl = elementView.findNode('button');
+
+        // Let a press on a <button> start an interaction, while it keeps its native default.
+        this.paper.PREVENT_INTERACTION_TAG_NAMES = ['TEXTAREA', 'INPUT', 'SELECT', 'OPTION'];
+
+        const positionBefore = element.position();
+        const mousedownEvt = simulate.mousedown({ el: buttonEl, clientX: 150, clientY: 150 });
+        simulate.mousemove({ el: buttonEl, clientX: 250, clientY: 250 });
+        simulate.mouseup({ el: buttonEl, clientX: 250, clientY: 250 });
+
+        assert.notDeepEqual(element.position(), positionBefore,
+            'the element now moves when dragging from a <button>');
+        assert.notOk(mousedownEvt.defaultPrevented,
+            'the button keeps its default action, so the native click and focus still work');
+    });
+
     QUnit.test('getContentArea()', function(assert) {
 
         assert.checkBboxApproximately(2/* +- */, this.paper.getContentArea(), {
diff --git a/packages/joint-core/test/ts/index.test.ts b/packages/joint-core/test/ts/index.test.ts
index 6d102e8797..84e867bb8b 100644
--- a/packages/joint-core/test/ts/index.test.ts
+++ b/packages/joint-core/test/ts/index.test.ts
@@ -160,6 +160,11 @@ const paper = new joint.dia.Paper({
 
 paper.fitToContent({ padding: { top: 10  }, allowNewOrigin: false });
 
+const eventOptions: joint.dia.Paper.Options[] = [
+    // `guard` is called without a view when the event did not hit a cell view.
+    { guard: (_evt, view) => view?.model.isElement() ?? false }
+];
+
 const cellView = graph.getCells()[0].findView(paper);
 cellView.vel.addClass('test-class');
 
diff --git a/packages/joint-core/types/dia.d.ts b/packages/joint-core/types/dia.d.ts
index a53bc8e25a..356555820a 100644
--- a/packages/joint-core/types/dia.d.ts
+++ b/packages/joint-core/types/dia.d.ts
@@ -1760,7 +1760,9 @@ export namespace Paper {
         linkPinning?: boolean;
         allowLink?: ((linkView: LinkView, paper: Paper) => boolean) | null;
         // events
-        guard?: (evt: Event, view: CellView) => boolean;
+        // `view` is undefined when the event did not hit a cell view (a blank area,
+        // or DOM content inside the paper element).
+        guard?: (evt: Event, view?: CellView) => boolean;
         preventContextMenu?: boolean;
         preventDefaultViewAction?: boolean;
         preventDefaultBlankAction?: boolean;
@@ -1991,6 +1993,7 @@ export class Paper extends mvc.View<Graph> {
 
     GUARDED_TAG_NAMES: string[];
     FORM_CONTROL_TAG_NAMES: string[];
+    PREVENT_INTERACTION_TAG_NAMES: string[];
 
     matrix(): SVGMatrix;
     matrix(ctm: SVGMatrix | Vectorizer.Matrix, data?: any): this;
@@ -2333,7 +2336,9 @@ export class Paper extends mvc.View<Graph> {
 
     protected onlabel(evt: Event): void;
 
-    protected guard(evt: Event, view: CellView): boolean;
+    protected guard(evt: Event, view?: CellView): boolean;
+
+    protected guardExplicit(evt: Event, view?: CellView): boolean | undefined;
 
     protected drawBackgroundImage(img: HTMLImageElement | null, opt?: { [key: string]: any }): void;
 
diff --git a/packages/joint-react/src/components/paper/__tests__/paper-html-content-events.test.tsx b/packages/joint-react/src/components/paper/__tests__/paper-html-content-events.test.tsx
new file mode 100644
index 0000000000..f0e13701bb
--- /dev/null
+++ b/packages/joint-react/src/components/paper/__tests__/paper-html-content-events.test.tsx
@@ -0,0 +1,127 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
+import { useCallback } from 'react';
+import { render, waitFor } from '@testing-library/react';
+import { GraphProvider, Paper } from '../../../components';
+import { usePaper } from '../../../hooks/use-paper';
+import type { PaperView } from '../../../mvc/paper';
+import { ELEMENT_MODEL_TYPE } from '../../../mvc/element-model';
+import type { CellRecord } from '../../../types/cell.types';
+
+// `<Paper>` children are portaled into `paper.el`, so an overlay, popup or toolbar
+// rendered there is a DOM sibling of the paper's SVG. Pressing one must not open a blank
+// interaction, and because it never has to be intercepted, React events on that content
+// keep working normally.
+//
+// Suppressing it from React alone is not possible. React attaches its delegated listeners
+// to the portal container, which here IS `paper.el` — the very node the paper delegates
+// on, and the paper got there first. So a React `onMouseDown` runs AFTER the paper has
+// already reacted, and `stopPropagation()` is too late. Native `mousedown` / `touchstart`
+// listeners would work but break React's own `onMouseDown` on the overlay content.
+//
+// joint-core leaves such a press alone for backwards compatibility (plain `dia.Paper`
+// users render their own content into `paper.el` and rely on the blank interaction).
+// The `guardExplicit` override in the paper preset is what makes it inert here.
+
+const initialCells: readonly CellRecord[] = [
+  {
+    id: 'cell-1',
+    type: ELEMENT_MODEL_TYPE,
+    position: { x: 0, y: 0 },
+    size: { width: 50, height: 50 },
+  } as CellRecord,
+];
+
+let capturedPaper: PaperView | null = null;
+let capturedButton: HTMLButtonElement | null = null;
+
+function Capture() {
+  capturedPaper = usePaper().paper;
+  return null;
+}
+
+interface OverlayProbeProps {
+  readonly onButtonMouseDown: () => void;
+}
+
+function OverlayProbe({ onButtonMouseDown }: Readonly<OverlayProbeProps>) {
+  const buttonRef = useCallback((node: HTMLButtonElement | null) => {
+    capturedButton = node;
+  }, []);
+  return (
+    <div>
+      <button type="button" ref={buttonRef} onMouseDown={onButtonMouseDown}>
+        overlay button
+      </button>
+    </div>
+  );
+}
+
+const renderElement = () => <rect width={50} height={50} />;
+
+const readPaper = (): PaperView | null => capturedPaper;
+const readButton = (): HTMLButtonElement | null => capturedButton;
+
+/**
+ * Mount a paper with overlay content portaled into `paper.el`.
+ * @param onButtonMouseDown - Spy for the overlay button's React `onMouseDown`.
+ * @returns The mounted paper view.
+ */
+async function renderPaperWithOverlay(onButtonMouseDown: () => void): Promise<PaperView> {
+  capturedPaper = null;
+  capturedButton = null;
+  render(
+    <GraphProvider initialCells={initialCells}>
+      <Paper style={{ width: 100, height: 100 }} id="html-content-paper" renderElement={renderElement}>
+        <OverlayProbe onButtonMouseDown={onButtonMouseDown} />
+        <Capture />
+      </Paper>
+    </GraphProvider>
+  );
+  await waitFor(() => {
+    expect(capturedPaper).not.toBeNull();
+    expect(capturedButton).not.toBeNull();
+  });
+  const paper = readPaper();
+  if (!paper) throw new Error('paper not mounted');
+  return paper;
+}
+
+describe('HTML content inside the paper container', () => {
+  it('does not start a blank interaction when pressed', async () => {
+    const paper = await renderPaperWithOverlay(() => {});
+    const blankPointerdown = jest.fn();
+    paper.on('blank:pointerdown', blankPointerdown);
+
+    readButton()?.dispatchEvent(
+      new MouseEvent('mousedown', { clientX: 10, clientY: 10, bubbles: true })
+    );
+
+    expect(blankPointerdown).not.toHaveBeenCalled();
+    document.dispatchEvent(new MouseEvent('mouseup', { bubbles: true }));
+  });
+
+  it('still lets React events on that content fire', async () => {
+    const onButtonMouseDown = jest.fn();
+    await renderPaperWithOverlay(onButtonMouseDown);
+
+    readButton()?.dispatchEvent(
+      new MouseEvent('mousedown', { clientX: 10, clientY: 10, bubbles: true })
+    );
+
+    expect(onButtonMouseDown).toHaveBeenCalledTimes(1);
+    document.dispatchEvent(new MouseEvent('mouseup', { bubbles: true }));
+  });
+
+  it('still starts a blank interaction when the SVG itself is pressed', async () => {
+    const paper = await renderPaperWithOverlay(() => {});
+    const blankPointerdown = jest.fn();
+    paper.on('blank:pointerdown', blankPointerdown);
+
+    paper.svg.dispatchEvent(
+      new MouseEvent('mousedown', { clientX: 10, clientY: 10, bubbles: true })
+    );
+
+    expect(blankPointerdown).toHaveBeenCalledTimes(1);
+    document.dispatchEvent(new MouseEvent('mouseup', { bubbles: true }));
+  });
+});
diff --git a/packages/joint-react/src/hooks/__tests__/use-markup.test.tsx b/packages/joint-react/src/hooks/__tests__/use-markup.test.tsx
index fddd66f2de..dfc378e39d 100644
--- a/packages/joint-react/src/hooks/__tests__/use-markup.test.tsx
+++ b/packages/joint-react/src/hooks/__tests__/use-markup.test.tsx
@@ -1,4 +1,5 @@
 /* eslint-disable react-perf/jsx-no-new-object-as-prop */
+/* eslint-disable react-perf/jsx-no-new-function-as-prop */
 import { useCallback, useEffect, useRef } from 'react';
 import { render, waitFor } from '@testing-library/react';
 import { GraphProvider, Paper } from '../../components';
@@ -161,7 +162,8 @@ describe('useMarkup', () => {
     cleanupUtilities = undefined;
     render(
       <GraphProvider initialCells={initialCells}>
-        <Paper style={{ width: 100, height: 100 }}
+        <Paper
+          style={{ width: 100, height: 100 }}
           id="markup-cleanup-paper"
           renderElement={renderCleanupProbe}
         />
@@ -177,7 +179,8 @@ describe('useMarkup', () => {
     reservedUtilities = undefined;
     render(
       <GraphProvider initialCells={initialCells}>
-        <Paper style={{ width: 100, height: 100 }}
+        <Paper
+          style={{ width: 100, height: 100 }}
           id="markup-reserved-paper"
           renderElement={renderReservedProbe}
         />
@@ -198,7 +201,8 @@ describe('useMarkup', () => {
     emptyCaptured = undefined;
     render(
       <GraphProvider initialCells={initialCells}>
-        <Paper style={{ width: 100, height: 100 }}
+        <Paper
+          style={{ width: 100, height: 100 }}
           id="markup-empty-paper"
           renderElement={renderEmptyMarkupProbe}
         />
diff --git a/packages/joint-react/src/hooks/use-markup.ts b/packages/joint-react/src/hooks/use-markup.ts
index 0bb41902e5..ada271e55c 100644
--- a/packages/joint-react/src/hooks/use-markup.ts
+++ b/packages/joint-react/src/hooks/use-markup.ts
@@ -48,6 +48,36 @@ export interface MarkupApi {
  * Register SVG sub-elements as JointJS selectors (and optionally magnets) on
  * the current element view, so links and tools can target named parts of a
  * React-rendered element. Must be used inside `renderElement`.
+ * Interactive controls inside a magnet work with plain React events.
+ *
+ * To keep a press from reaching the paper, so it starts no link drag and no element
+ * move, stop the React event. `onClick` is a separate native event and still fires:
+ *
+ * ```tsx
+ * <g ref={magnetRef('row-0')}>
+ *   <foreignObject width={80} height={24}>
+ *     <button onMouseDown={(event) => event.stopPropagation()} onClick={toggle}>NN</button>
+ *   </foreignObject>
+ * </g>
+ * ```
+ *
+ * Stop `onMouseDown` (and `onTouchStart` for touch) — those are the events the paper
+ * listens to. Stopping `onPointerDown` does NOT work on its own: `pointerdown` is a
+ * separate event, so the `mousedown` that drives the paper still gets through. If a
+ * handler already owns the pointer (`setPointerCapture`), calling `preventDefault()` on
+ * `pointerdown` also works, because canceling it suppresses the compatibility
+ * `mousedown` altogether.
+ *
+ * Keeping a control clickable while the rest of the element stays draggable usually
+ * needs no wiring at all. A form control (`<input>`, `<select>`, `<textarea>`) keeps its
+ * native default action, so a press selects text or opens the dropdown rather than moving
+ * the element or starting a link. A `<button>` does both: a press-and-release in place
+ * clicks it, while a drag moves the element (or, from a magnet, starts a link) and the
+ * preset withholds the trailing click so the gesture is not also counted as a click.
+ * For a non-form control that must both click and drag-to-connect, set
+ * `magnetThreshold="onleave"` on the `<Paper>`: the link forms only once the pointer
+ * leaves the magnet, so a drag releases away from the control and the browser fires no
+ * click on it, while a press-and-release in place still clicks.
  * @group Hooks
  * @returns The {@link MarkupApi}: a `selectorRef` factory that tags an SVG node
  * under a named selector so links and tools can target it, and a `magnetRef`
diff --git a/packages/joint-react/src/presets/__tests__/paper-button-interactions.test.tsx b/packages/joint-react/src/presets/__tests__/paper-button-interactions.test.tsx
new file mode 100644
index 0000000000..e0f7a2ca35
--- /dev/null
+++ b/packages/joint-react/src/presets/__tests__/paper-button-interactions.test.tsx
@@ -0,0 +1,135 @@
+import { useCallback } from 'react';
+import { render, waitFor } from '@testing-library/react';
+import { GraphProvider, Paper } from '../../components';
+import { usePaper } from '../../hooks/use-paper';
+import type { PaperView } from '../../mvc/paper';
+import { ELEMENT_MODEL_TYPE } from '../../mvc/element-model';
+import type { CellRecord } from '../../types/cell.types';
+
+// A button inside a node must be clickable AND draggable: dragging it moves the element
+// (or starts a link when it sits in a magnet), while a press-and-release in place is just
+// a click. joint-core blocks every form control from starting an interaction, so the
+// preset narrows `PREVENT_INTERACTION_TAG_NAMES` to leave `BUTTON` out — and `pointerup`
+// withholds the native click once the gesture has moved, since a node dragged by its own
+// button ends the gesture back on that button and would otherwise fire `onClick`.
+
+const ELEMENT_ID = 'cell-1';
+
+beforeAll(() => {
+  // jsdom has no layout, so it ships no `elementFromPoint`; joint-core reaches for it
+  // while a drag is in flight (`CellView#getEventTarget`). Nothing here depends on the
+  // node it would return.
+  document.elementFromPoint = () => null;
+});
+
+const initialCells: readonly CellRecord[] = [
+  {
+    id: ELEMENT_ID,
+    type: ELEMENT_MODEL_TYPE,
+    position: { x: 0, y: 0 },
+    size: { width: 80, height: 40 },
+  } as CellRecord,
+];
+
+let capturedPaper: PaperView | null = null;
+let capturedButton: HTMLButtonElement | null = null;
+
+function Capture() {
+  capturedPaper = usePaper().paper;
+  return null;
+}
+
+const PAPER_STYLE = { width: 200, height: 200 };
+
+/** Reassigned per test, read at render time by the button's `onClick`. */
+let onButtonClick: () => void = () => {};
+
+function NodeWithButton() {
+  const buttonRef = useCallback((node: HTMLButtonElement | null) => {
+    capturedButton = node;
+  }, []);
+  return (
+    <>
+      <rect width={80} height={40} fill="#1c2836" />
+      <foreignObject width={80} height={40}>
+        <button type="button" ref={buttonRef} onClick={onButtonClick}>
+          press
+        </button>
+      </foreignObject>
+    </>
+  );
+}
+
+const renderElement = () => <NodeWithButton />;
+
+/**
+ * Mount a paper holding one element whose markup contains a `<button>`.
+ * @param clickSpy - Spy for the button's React `onClick`.
+ * @returns The paper and the rendered `<button>`.
+ */
+async function renderNodeWithButton(
+  clickSpy: () => void
+): Promise<{ paper: PaperView; button: HTMLButtonElement }> {
+  capturedPaper = null;
+  capturedButton = null;
+  onButtonClick = clickSpy;
+  render(
+    <GraphProvider initialCells={initialCells}>
+      <Paper style={PAPER_STYLE} renderElement={renderElement}>
+        <Capture />
+      </Paper>
+    </GraphProvider>
+  );
+  await waitFor(() => {
+    expect(capturedPaper).not.toBeNull();
+    expect(capturedButton).not.toBeNull();
+  });
+  const paper = capturedPaper;
+  const button = capturedButton;
+  if (!paper || !button) throw new Error('paper or button not mounted');
+  return { paper, button };
+}
+
+function dispatchAt(node: EventTarget, type: string, clientX: number, clientY: number) {
+  node.dispatchEvent(new MouseEvent(type, { clientX, clientY, bubbles: true, cancelable: true }));
+}
+
+/** A real browser fires `click` on the pressed node after `mouseup` — jsdom does not. */
+function dispatchClick(node: EventTarget) {
+  dispatchAt(node, 'click', 0, 0);
+}
+
+describe('a button inside a node', () => {
+  it('moves the element when dragged, and does not click', async () => {
+    const clickSpy = jest.fn();
+    const { paper, button } = await renderNodeWithButton(clickSpy);
+    const element = paper.model.getCell(ELEMENT_ID);
+    const positionBefore = { ...element.get('position') };
+
+    dispatchAt(button, 'mousedown', 10, 10);
+    // `clickThreshold` counts move events, not pixels, so a drag has to be more than a
+    // single jump for joint-core to stop treating the gesture as a click.
+    for (let step = 1; step <= 8; step += 1) {
+      dispatchAt(document, 'pointermove', 10 + step * 10, 10 + step * 10);
+    }
+    dispatchAt(document, 'pointerup', 90, 90);
+    dispatchClick(button);
+
+    expect(element.get('position')).not.toEqual(positionBefore);
+    expect(clickSpy).not.toHaveBeenCalled();
+  });
+
+  it('clicks when pressed without moving, and does not move the element', async () => {
+    const clickSpy = jest.fn();
+    const { paper, button } = await renderNodeWithButton(clickSpy);
+    const element = paper.model.getCell(ELEMENT_ID);
+    const positionBefore = { ...element.get('position') };
+
+    dispatchAt(button, 'mousedown', 10, 10);
+    dispatchAt(document, 'pointerup', 10, 10);
+    dispatchClick(button);
+
+    expect(element.get('position')).toEqual(positionBefore);
+    expect(clickSpy).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/joint-react/src/presets/paper.ts b/packages/joint-react/src/presets/paper.ts
index 71a9c3c9e2..e8bc17e3cd 100644
--- a/packages/joint-react/src/presets/paper.ts
+++ b/packages/joint-react/src/presets/paper.ts
@@ -23,6 +23,7 @@ type ProtectedPaperPrototype = {
   readonly pointerup: (event: dia.Event) => void;
   readonly startListening: () => void;
   readonly guard: (event: dia.Event, view: dia.CellView) => boolean;
+  readonly guardExplicit: (event: dia.Event, view?: dia.CellView) => boolean | undefined;
 };
 
 const protectedProto = dia.Paper.prototype as unknown as ProtectedPaperPrototype;
@@ -41,6 +42,31 @@ function getPointerId(event: dia.Event): number | null {
   return typeof fromOriginal === 'number' ? fromOriginal : null;
 }
 
+/**
+ * Swallow the next native `click`, so a gesture that moved does not also click.
+ *
+ * joint-core already withholds its own `pointerclick` once the pointer travels past
+ * `clickThreshold`, but the browser still fires a DOM `click` whenever press and release
+ * share a target — which a drag does whenever the node follows the pointer, as when an
+ * element is moved by a button inside it. Without this, dragging a node by its button
+ * would run the button's `onClick` on release.
+ *
+ * Capture on `document` rather than `paper.el`: React attaches its listeners to the
+ * portal container, so a listener on `paper.el` could be ordered behind them.
+ */
+function swallowClick(event: Event): void {
+  event.stopPropagation();
+  event.preventDefault();
+}
+
+function swallowNextClick(): void {
+  document.addEventListener('click', swallowClick, { capture: true, once: true });
+  // A drag released off the pressed node fires no click at all; drop the listener so it
+  // cannot eat an unrelated one later. Re-adding the same function is a no-op, so
+  // overlapping gestures cannot stack listeners.
+  setTimeout(() => document.removeEventListener('click', swallowClick, true), 0);
+}
+
 const DEFAULT_CLICK_THRESHOLD = 5;
 const DEFAULT_GRID_SIZE = 10;
 const DEFAULT_SNAP_RADIUS = 15;
@@ -195,15 +221,60 @@ export const Paper = dia.Paper.extend(
       return protectedProto.guard.call(this, event, view) || wheelGuard(event);
     },
 
+    /**
+     * Treat React content portaled into `paper.el` as off the paper's event surface.
+     *
+     * `<Paper>` children — an overlay, a popup, a toolbar — render into `paper.el` but
+     * outside its SVG. A press there must not open a blank interaction, and React alone
+     * cannot prevent one: React attaches its delegated listeners to the portal container,
+     * which IS `paper.el`, and the paper delegates on that same node and got there first,
+     * so a React `onMouseDown` runs after the paper has already reacted.
+     *
+     * joint-core leaves such a press alone for backwards compatibility, deciding it only
+     * from `guardExplicit`. Rejecting it here — after the caller's own `options.guard` —
+     * is what lets overlay content use plain React events with no interception of its own.
+     * @param event - Event delivered to the paper's dispatch.
+     * @param view - View resolved from the event target, if any.
+     * @returns `true` to guard, `false` to allow, `undefined` to leave it undecided.
+     */
+    guardExplicit(this: dia.Paper, event: dia.Event, view?: dia.CellView) {
+      const guarded = protectedProto.guardExplicit.call(this, event, view);
+      if (guarded !== undefined) return guarded;
+      const { target } = event;
+      const isPortaledContent =
+        target instanceof Node && !this.svg.contains(target) && this.el.contains(target);
+      // Anything else stays undecided, so the paper goes on to judge the target itself.
+      return isPortaledContent ? true : undefined;
+    },
+
+    /**
+     * Let a press on a `<button>` start a paper interaction — an element move, or a link
+     * when the button sits inside a magnet. joint-core blocks every form control here,
+     * which makes a button click-only; buttons are the one control whose whole purpose is
+     * a press, so a drag from one is unambiguous. `FORM_CONTROL_TAG_NAMES` is left alone,
+     * so the button keeps its native default action and stays focusable.
+     *
+     * A drag that moves does not also click: `pointerup` swallows the native click.
+     */
+    PREVENT_INTERACTION_TAG_NAMES: ['TEXTAREA', 'INPUT', 'SELECT'],
+
     /**
      * Run the upstream pointerup handler, then release capture. Also runs on
      * `pointercancel` (mapped to the same method via the events hash) so
      * OS-stolen pointers don't leave listeners attached.
+     *
+     * Also withholds the next native `click` when the gesture moved, so a drag started
+     * from a button does not fire its `onClick` on release.
      * @param event - The pointerup or pointercancel event.
      */
     pointerup(this: dia.Paper, event: dia.Event) {
       const pointerId = getPointerId(event);
-      const captureTarget = this.eventData(event).captureTarget as Element | undefined;
+      const { captureTarget, mousemoved = 0 } = this.eventData(event) as {
+        captureTarget?: Element;
+        mousemoved?: number;
+      };
+      // Read before the super call: it ends the gesture and resets this state.
+      if (mousemoved > (this.options.clickThreshold ?? 0)) swallowNextClick();
       protectedProto.pointerup.call(this, event);
       if (!captureTarget || pointerId === null) return;
       this.el.classList.remove(DRAGGING_CLASS_NAME);
diff --git a/packages/joint-react/stories/examples/buttons-in-magnets/code.tsx b/packages/joint-react/stories/examples/buttons-in-magnets/code.tsx
new file mode 100644
index 0000000000..1dc47e3f2b
--- /dev/null
+++ b/packages/joint-react/stories/examples/buttons-in-magnets/code.tsx
@@ -0,0 +1,265 @@
+import { useCallback, useState } from 'react';
+import {
+  type CanConnectOptions,
+  type CellRecord,
+  GraphProvider,
+  HTMLBox,
+  Paper,
+  type RenderElement,
+  linkRoutingSmooth,
+  useMarkup,
+} from '@joint/react';
+
+const SMOOTH_LINKS = linkRoutingSmooth({ mode: 'horizontal', straightWhenDisconnected: false });
+// Links may land on an element body, so a port button can be connected to the other card.
+const VALIDATE_CONNECTION: CanConnectOptions = { allowRootConnection: true };
+
+// Colors — unified dark diagram palette. The card body and border come from the
+// shared `jj-node` class; only the chrome below is styled here.
+const HEADER_COLOR = '#243445';
+const MUTED_TEXT_COLOR = '#93A4B3';
+const BUTTON_COLOR = '#2F4459';
+const MAGNET_COUNT = 3;
+
+interface NodeData {
+  readonly kind: 'body' | 'magnets';
+  readonly name: string;
+}
+
+const initialCells: Array<CellRecord<NodeData>> = [
+  {
+    id: 'body',
+    type: 'element',
+    data: { kind: 'body', name: 'controls in the body' },
+    position: { x: 40, y: 40 },
+    size: { width: 235, height: 224 },
+  },
+  {
+    id: 'magnets',
+    type: 'element',
+    data: { kind: 'magnets', name: 'a control in each magnet' },
+    position: { x: 340, y: 34 },
+    size: { width: 250, height: 250 },
+  },
+];
+
+const cardStyle: React.CSSProperties = {
+  flexDirection: 'column',
+  alignItems: 'stretch',
+  justifyContent: 'flex-start',
+  textAlign: 'left',
+  padding: 0,
+  overflow: 'hidden',
+  fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
+};
+
+const headerStyle: React.CSSProperties = {
+  padding: '9px 12px',
+  fontWeight: 600,
+  fontSize: 12,
+  background: HEADER_COLOR,
+  borderBottom: '1px solid rgba(128, 128, 128, 0.2)',
+};
+
+const bodyStyle: React.CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 8,
+  padding: '12px',
+};
+
+const selectStyle: React.CSSProperties = {
+  font: 'inherit',
+  fontSize: 11,
+  color: 'inherit',
+  background: 'rgba(0, 0, 0, 0.25)',
+  border: '1px solid rgba(128, 128, 128, 0.35)',
+  borderRadius: 4,
+  padding: '3px 6px',
+  width: '100%',
+  boxSizing: 'border-box',
+};
+
+const rowSelectStyle: React.CSSProperties = { ...selectStyle, width: 108 };
+
+const rowLabelStyle: React.CSSProperties = { whiteSpace: 'nowrap' };
+
+const rowStyle: React.CSSProperties = {
+  display: 'flex',
+  justifyContent: 'space-between',
+  alignItems: 'center',
+  gap: 8,
+  padding: '8px 12px',
+  fontSize: 12,
+  cursor: 'crosshair',
+  userSelect: 'none',
+  borderBottom: '1px solid rgba(128, 128, 128, 0.15)',
+};
+
+const buttonStyle: React.CSSProperties = {
+  font: 'inherit',
+  fontSize: 11,
+  color: 'inherit',
+  background: BUTTON_COLOR,
+  border: '1px solid rgba(128, 128, 128, 0.35)',
+  borderRadius: 4,
+  padding: '3px 8px',
+  cursor: 'pointer',
+};
+
+const inputStyle: React.CSSProperties = {
+  font: 'inherit',
+  fontSize: 11,
+  color: 'inherit',
+  background: 'rgba(0, 0, 0, 0.25)',
+  border: '1px solid rgba(128, 128, 128, 0.35)',
+  borderRadius: 4,
+  padding: '3px 8px',
+  boxSizing: 'border-box',
+  minWidth: 0,
+};
+
+const bodyInputStyle: React.CSSProperties = { ...inputStyle, width: '100%' };
+
+const rowInputStyle: React.CSSProperties = { ...inputStyle, width: 108 };
+
+const hintStyle: React.CSSProperties = {
+  margin: 0,
+  fontSize: 10,
+  lineHeight: 1.45,
+  color: MUTED_TEXT_COLOR,
+};
+
+/**
+ * Button label that makes it obvious the native click still lands. The count sits in a
+ * `<span>`, so this also covers the case where the press target is inside the control
+ * rather than the control itself.
+ */
+function ClickCounter() {
+  const [count, setCount] = useState(0);
+  const handleClick = useCallback(() => setCount((value) => value + 1), []);
+  return (
+    <button type="button" style={buttonStyle} onClick={handleClick}>
+      <span>clicked {count}×</span>
+    </button>
+  );
+}
+
+const SELECT_OPTIONS = ['idle', 'running', 'done'];
+
+/** Dropdown: `SELECT` is in GUARDED_TAG_NAMES, so the paper ignores it outright. */
+function StatusSelect({ style }: Readonly<{ style: React.CSSProperties }>) {
+  const [value, setValue] = useState(SELECT_OPTIONS[0]);
+  const handleChange = useCallback(
+    (event: React.ChangeEvent<HTMLSelectElement>) => setValue(event.target.value),
+    []
+  );
+  return (
+    <select style={style} value={value} onChange={handleChange}>
+      {SELECT_OPTIONS.map((option) => (
+        <option key={option} value={option}>
+          {option}
+        </option>
+      ))}
+    </select>
+  );
+}
+
+interface TextFieldProps {
+  readonly style: React.CSSProperties;
+}
+
+/** Text field: typeable and selectable, and never a drag handle. */
+function TextField({ style }: Readonly<TextFieldProps>) {
+  const [value, setValue] = useState('type here');
+  const handleChange = useCallback(
+    (event: React.ChangeEvent<HTMLInputElement>) => setValue(event.target.value),
+    []
+  );
+  return <input style={style} value={value} onChange={handleChange} />;
+}
+
+/** Card whose body holds a plain button — no magnet involved. */
+function BodyButtonNode({ name }: Readonly<Partial<NodeData>>) {
+  return (
+    <HTMLBox className="jj-node" useModelGeometry style={cardStyle}>
+      <div style={headerStyle}>{name}</div>
+      <div style={bodyStyle}>
+        <ClickCounter />
+        <TextField style={bodyInputStyle} />
+        <StatusSelect style={selectStyle} />
+        <p style={hintStyle}>
+          Click the button to count; drag it to move the element without counting. The text
+          field selects text instead, and the paper ignores the dropdown outright.
+        </p>
+      </div>
+    </HTMLBox>
+  );
+}
+
+interface MagnetRowProps {
+  readonly index: number;
+}
+
+/** One magnet row, each holding a different kind of control. */
+function MagnetRow({ index }: Readonly<MagnetRowProps>) {
+  const { magnetRef } = useMarkup();
+  return (
+    <div ref={magnetRef(`port-${index}`)} style={rowStyle}>
+      <span style={rowLabelStyle}>port-{index}</span>
+      {index === 0 && <ClickCounter />}
+      {index === 1 && <TextField style={rowInputStyle} />}
+      {index === 2 && <StatusSelect style={rowSelectStyle} />}
+    </div>
+  );
+}
+
+/** Card with three magnet rows, each holding a different control: a button, a text field, a select. */
+function MagnetButtonsNode({ name }: Readonly<Partial<NodeData>>) {
+  return (
+    <HTMLBox className="jj-node" useModelGeometry style={cardStyle}>
+      <div style={headerStyle}>{name}</div>
+      {Array.from({ length: MAGNET_COUNT }, (_, index) => (
+        <MagnetRow key={`port-${index}`} index={index} />
+      ))}
+      <div style={bodyStyle}>
+        <p style={hintStyle}>
+          Drag off a row, or off its button, to start a link. The text field starts none, and
+          the dropdown never reaches the paper at all.
+        </p>
+      </div>
+    </HTMLBox>
+  );
+}
+
+function Main() {
+  const renderElement: RenderElement<NodeData> = useCallback((data) => {
+    return data.kind === 'body' ? (
+      <BodyButtonNode name={data.name} />
+    ) : (
+      <MagnetButtonsNode name={data.name} />
+    );
+  }, []);
+
+  return (
+    <Paper
+      className="size-full"
+      renderElement={renderElement}
+      // Without `onleave` a press on a magnet starts the link immediately, so a plain
+      // click on a magnet would already create one.
+      magnetThreshold="onleave"
+      linkPinning={false}
+      linkRouting={SMOOTH_LINKS}
+      validateConnection={VALIDATE_CONNECTION}
+      drawGrid={false}
+    />
+  );
+}
+
+export default function App() {
+  return (
+    <GraphProvider initialCells={initialCells}>
+      <Main />
+    </GraphProvider>
+  );
+}
diff --git a/packages/joint-react/stories/examples/buttons-in-magnets/story.tsx b/packages/joint-react/stories/examples/buttons-in-magnets/story.tsx
new file mode 100644
index 0000000000..7f78e48ab6
--- /dev/null
+++ b/packages/joint-react/stories/examples/buttons-in-magnets/story.tsx
@@ -0,0 +1,25 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { getAPILink } from '../../utils/get-api-documentation-link';
+import Code from './code';
+import codeRaw from './code?raw';
+
+const meta = {
+  title: 'Examples/Buttons In Magnets',
+  component: Code,
+  tags: ['example'],
+  parameters: {
+    showcase: {
+      description:
+        'Three kinds of control inside a node: a button that both clicks and drags (moving the element, or starting a link from its magnet), a text field that keeps every gesture so it can select text, and a dropdown the paper ignores outright. A gesture that moves never also clicks.',
+      apiUrl: getAPILink('useMarkup'),
+      canvasHeight: 300,
+      code: codeRaw,
+    },
+  },
+} satisfies Meta<typeof Code>;
+
+export default meta;
+
+export type Story = StoryObj<typeof Code>;
+
+export const Default: Story = {};

From 61efb8f3fa4a7584e92841cb11c928325cd33456 Mon Sep 17 00:00:00 2001
From: Roman Bruckner <bruckner.roman@gmail.com>
Date: Thu, 13 Aug 2026 12:53:59 +0200
Subject: [PATCH 2/2] docs(joint-react): move magnet-control interaction note
 to Paper preset

The "interactive controls inside magnets" explanation lived on useMarkup's
JSDoc, but the behavior it describes (mousedown/pointerdown surface,
swallowNextClick, PREVENT_INTERACTION_TAG_NAMES, magnetThreshold) is owned by
the Paper preset. Relocate the note next to those symbols and leave a one-line
pointer on useMarkup.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/joint-react/src/hooks/use-markup.ts | 32 ++-----------------
 packages/joint-react/src/presets/paper.ts    | 33 ++++++++++++++++++++
 2 files changed, 36 insertions(+), 29 deletions(-)

diff --git a/packages/joint-react/src/hooks/use-markup.ts b/packages/joint-react/src/hooks/use-markup.ts
index ada271e55c..0e98f09949 100644
--- a/packages/joint-react/src/hooks/use-markup.ts
+++ b/packages/joint-react/src/hooks/use-markup.ts
@@ -48,36 +48,10 @@ export interface MarkupApi {
  * Register SVG sub-elements as JointJS selectors (and optionally magnets) on
  * the current element view, so links and tools can target named parts of a
  * React-rendered element. Must be used inside `renderElement`.
- * Interactive controls inside a magnet work with plain React events.
  *
- * To keep a press from reaching the paper, so it starts no link drag and no element
- * move, stop the React event. `onClick` is a separate native event and still fires:
- *
- * ```tsx
- * <g ref={magnetRef('row-0')}>
- *   <foreignObject width={80} height={24}>
- *     <button onMouseDown={(event) => event.stopPropagation()} onClick={toggle}>NN</button>
- *   </foreignObject>
- * </g>
- * ```
- *
- * Stop `onMouseDown` (and `onTouchStart` for touch) — those are the events the paper
- * listens to. Stopping `onPointerDown` does NOT work on its own: `pointerdown` is a
- * separate event, so the `mousedown` that drives the paper still gets through. If a
- * handler already owns the pointer (`setPointerCapture`), calling `preventDefault()` on
- * `pointerdown` also works, because canceling it suppresses the compatibility
- * `mousedown` altogether.
- *
- * Keeping a control clickable while the rest of the element stays draggable usually
- * needs no wiring at all. A form control (`<input>`, `<select>`, `<textarea>`) keeps its
- * native default action, so a press selects text or opens the dropdown rather than moving
- * the element or starting a link. A `<button>` does both: a press-and-release in place
- * clicks it, while a drag moves the element (or, from a magnet, starts a link) and the
- * preset withholds the trailing click so the gesture is not also counted as a click.
- * For a non-form control that must both click and drag-to-connect, set
- * `magnetThreshold="onleave"` on the `<Paper>`: the link forms only once the pointer
- * leaves the magnet, so a drag releases away from the control and the browser fires no
- * click on it, while a press-and-release in place still clicks.
+ * For nesting an interactive control (button, input) inside a `magnetRef` node
+ * without the press starting a link drag or element move, see the "Interactive
+ * controls inside magnets" note in the `Paper` preset (`presets/paper.ts`).
  * @group Hooks
  * @returns The {@link MarkupApi}: a `selectorRef` factory that tags an SVG node
  * under a named selector so links and tools can target it, and a `magnetRef`
diff --git a/packages/joint-react/src/presets/paper.ts b/packages/joint-react/src/presets/paper.ts
index e8bc17e3cd..db7787ca6b 100644
--- a/packages/joint-react/src/presets/paper.ts
+++ b/packages/joint-react/src/presets/paper.ts
@@ -18,6 +18,39 @@ const POINTER_DOCUMENT_EVENTS: Record<string, string> = {
   pointercancel: 'pointerup',
 };
 
+// ---------------------------------------------------------------------------
+// Interactive controls inside magnets
+// ---------------------------------------------------------------------------
+// A control nested in a connectable magnet (e.g. `magnetRef('row-0')` from
+// `useMarkup`) works with plain React events. To keep a press from reaching the
+// paper — so it starts no link drag and no element move — stop the React event.
+// `onClick` is a separate native event and still fires:
+//
+//   <g ref={magnetRef('row-0')}>
+//     <foreignObject width={80} height={24}>
+//       <button onMouseDown={(event) => event.stopPropagation()} onClick={toggle}>NN</button>
+//     </foreignObject>
+//   </g>
+//
+// Stop `onMouseDown` (and `onTouchStart` for touch) — those are the events the
+// paper listens to. Stopping `onPointerDown` does NOT work on its own:
+// `pointerdown` is a separate event, so the `mousedown` that drives the paper
+// still gets through. If a handler already owns the pointer (`setPointerCapture`),
+// calling `preventDefault()` on `pointerdown` also works, because canceling it
+// suppresses the compatibility `mousedown` altogether.
+//
+// Keeping a control clickable while the rest of the element stays draggable
+// usually needs no wiring at all. A form control (`<input>`, `<select>`,
+// `<textarea>`) keeps its native default action (see `PREVENT_INTERACTION_TAG_NAMES`),
+// so a press selects text or opens the dropdown rather than moving the element or
+// starting a link. A `<button>` does both: a press-and-release in place clicks it,
+// while a drag moves the element (or, from a magnet, starts a link) and the preset
+// withholds the trailing click (see `swallowNextClick`) so the gesture is not also
+// counted as a click. For a non-form control that must both click and
+// drag-to-connect, set `magnetThreshold="onleave"` on the `<Paper>`: the link forms
+// only once the pointer leaves the magnet, so a drag releases away from the control
+// and the browser fires no click on it, while a press-and-release in place still clicks.
+
 type ProtectedPaperPrototype = {
   readonly pointermove: (event: dia.Event) => void;
   readonly pointerup: (event: dia.Event) => void;