From 5a75afc457bbefb1fa9630dfe623fd827c3616da Mon Sep 17 00:00:00 2001
From: samuelgja <samuel.gjabel@gmail.com>
Date: Sat, 30 May 2026 18:49:22 +0700
Subject: [PATCH 1/2] chore(joint-react): Refactor Paper component styles and
 event handling across various examples

- Updated Paper component style properties to use single quotes for consistency.
- Replaced usePaperEvents with direct event handlers for onLinkMouseEnter, onLinkMouseLeave, onElementMouseEnter, and onElementMouseLeave in multiple examples.
- Added eslint-disable comments for performance-related rules in several files.
- Cleaned up unused imports and improved code readability in various components.
---
 .../paper/__tests__/paper-events.test.tsx     | 376 ++++++++++++++++++
 .../src/components/paper/paper.types.ts       |  28 +-
 .../__tests__/paper-element-item.test.tsx     |   3 +-
 .../__tests__/paper-html-overlay.test.tsx     |   3 +-
 .../src/hooks/__tests__/use-cells.test.tsx    |   6 +-
 .../__tests__/use-create-features.test.tsx    |   3 +-
 .../use-create-portal-paper.test.tsx          |   1 +
 .../src/hooks/__tests__/use-markup.test.tsx   |   1 +
 .../hooks/__tests__/use-measure-node.test.tsx |   1 +
 .../use-nodes-measured-effect.test.tsx        |   2 +-
 .../hooks/__tests__/use-paper-events.test.tsx |   1 +
 .../src/hooks/__tests__/use-paper.test.tsx    |   1 +
 .../src/hooks/use-create-portal-paper.tsx     |  13 +-
 .../presets/__tests__/extra-coverage.test.ts  |   4 +-
 .../src/presets/__tests__/link-labels.test.ts |  35 +-
 .../joint-react/src/presets/paper-events.ts   | 242 ++++++++---
 .../src/state/__tests__/data-mapper.test.ts   |   2 +-
 .../src/store/__tests__/paper-store.test.ts   |   2 +-
 .../demos/automatic-layout-storage/code.tsx   |   2 +-
 .../src/stories/demos/collaboration/code.tsx  |  30 +-
 .../src/stories/demos/flowchart/code.tsx      |  73 ++--
 .../stories/demos/introduction-demo/code.tsx  |  18 +-
 .../demos/investment-calculator/code.tsx      |   2 +-
 .../src/stories/demos/link-arrows/code.tsx    |  26 +-
 .../src/stories/demos/pulsing-port/code.tsx   |  10 +-
 .../src/stories/demos/saasflow/code.tsx       |   2 +-
 .../examples/markup-selectors-html/code.tsx   |   2 +-
 .../examples/markup-selectors/code.tsx        |   2 +-
 .../src/stories/examples/stress/code.tsx      |   1 +
 .../examples/with-auto-layout/code.tsx        |   1 +
 .../examples/with-auto-size-origin/code.tsx   |   3 +-
 .../stories/examples/with-cell-json/code.tsx  |   1 +
 .../with-collapsible-container/code.tsx       |  24 +-
 .../examples/with-default-element/code.tsx    |   1 +
 .../examples/with-default-link/code.tsx       |   2 +-
 .../with-dynamic-interactivity/code.tsx       |  67 +---
 .../examples/with-element-controls/code.tsx   |   3 +-
 .../examples/with-element-defaults/code.tsx   |   1 +
 .../with-element-ports-groups/code.tsx        |   1 +
 .../with-fixed-connection-points/code.tsx     |  69 ++--
 .../examples/with-graph-neighbors/code.tsx    |  39 +-
 .../examples/with-highlighter/code.tsx        |  13 +-
 .../examples/with-link-labels/code.tsx        |   3 +-
 .../examples/with-link-markers-named/code.tsx |   3 +-
 .../examples/with-link-markers/code.tsx       |   1 +
 .../examples/with-link-routing/code.tsx       |   1 +
 .../stories/examples/with-link-tools/code.tsx |  10 +-
 .../stories/examples/with-list-node/code.tsx  |   1 +
 .../stories/examples/with-minimap/code.tsx    |   2 +-
 .../examples/with-native-ports/code.tsx       |   1 +
 .../examples/with-portal-selector/code.tsx    |  21 +-
 .../examples/with-shape-animations/code.tsx   |   2 +-
 .../examples/with-tailwind-theme/code.tsx     |   1 +
 .../examples/with-theme-editor/code.tsx       |  86 ++--
 .../code-controlled-mode-jotai.tsx            |   1 +
 .../code-controlled-mode-peerjs.tsx           |   1 +
 .../code-controlled-mode-redux.tsx            |   1 +
 .../code-controlled-mode-zustand.tsx          |   1 +
 .../step-by-step/code-html-renderer.tsx       |   1 +
 .../utils/joint-jsx/jsx-to-markup.stories.tsx |   2 +-
 .../joint-react/src/utils/test-wrappers.tsx   |   1 +
 61 files changed, 875 insertions(+), 382 deletions(-)
 create mode 100644 packages/joint-react/src/components/paper/__tests__/paper-events.test.tsx

diff --git a/packages/joint-react/src/components/paper/__tests__/paper-events.test.tsx b/packages/joint-react/src/components/paper/__tests__/paper-events.test.tsx
new file mode 100644
index 0000000000..9311d46302
--- /dev/null
+++ b/packages/joint-react/src/components/paper/__tests__/paper-events.test.tsx
@@ -0,0 +1,376 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
+/* eslint-disable react-perf/jsx-no-new-function-as-prop */
+import { useCallback, useState } from 'react';
+import { render, waitFor, act } from '@testing-library/react';
+import { mvc, type dia } from '@joint/core';
+import { Paper } from '../paper';
+import { GraphProvider } from '../../graph/graph-provider';
+import { ELEMENT_MODEL_TYPE } from '../../../models/element-model';
+import type { CellRecord } from '../../../types/cell.types';
+
+const CELLS: readonly CellRecord[] = [
+  {
+    id: '1',
+    type: ELEMENT_MODEL_TYPE,
+    position: { x: 0, y: 0 },
+    size: { width: 50, height: 50 },
+  } as CellRecord,
+];
+
+const renderRectElement = () => <rect />;
+const fakeEvent = {} as dia.Event;
+
+interface HarnessProps {
+  readonly setRef: (paper: dia.Paper | null) => void;
+}
+
+/**
+ * Mounts a paper and resolves once the `dia.Paper` instance is available.
+ * @param ui - Factory receiving a ref callback; returns the tree under test.
+ * @returns The created paper.
+ */
+async function mountPaper(
+  ui: (ref: (paper: dia.Paper | null) => void) => React.ReactElement
+): Promise<{ paper: dia.Paper }> {
+  let current: dia.Paper | null = null;
+  const setRef = (paper: dia.Paper | null) => {
+    if (paper) current = paper;
+  };
+  render(<GraphProvider initialCells={CELLS}>{ui(setRef)}</GraphProvider>);
+  await waitFor(() => {
+    expect(current).not.toBeNull();
+  });
+  return { paper: current as unknown as dia.Paper };
+}
+
+const clickTestId = (testId: string) =>
+  act(() => {
+    (document.querySelector(`[data-testid="${testId}"]`) as HTMLButtonElement).click();
+  });
+
+describe('Paper normalized event props', () => {
+  it('fires a normalized handler with a context object', async () => {
+    const onBlankContextMenu = jest.fn();
+    const { paper } = await mountPaper((ref) => (
+      <Paper
+        ref={ref}
+        style={{ width: 100, height: 100 }}
+        renderElement={renderRectElement}
+        onBlankContextMenu={onBlankContextMenu}
+      />
+    ));
+
+    act(() => {
+      paper.trigger('blank:contextmenu', fakeEvent, 10, 20);
+    });
+
+    expect(onBlankContextMenu).toHaveBeenCalledTimes(1);
+    expect(onBlankContextMenu).toHaveBeenCalledWith(
+      expect.objectContaining({ paper, graph: paper.model, event: fakeEvent, x: 10, y: 20 })
+    );
+  });
+
+  it('does NOT re-subscribe across unrelated re-renders when handlers are stable refs', async () => {
+    const listenToSpy = jest.spyOn(mvc.Listener.prototype, 'listenTo');
+    const bindCount = (eventName: string) =>
+      listenToSpy.mock.calls.filter((call) => String(call[1]) === eventName).length;
+
+    const handler = jest.fn();
+    function Harness({ setRef }: Readonly<HarnessProps>) {
+      const [, force] = useState(0);
+      // eslint-disable-next-line sonarjs/no-nested-functions
+      const rerender = () => force((n) => n + 1);
+      // Stable reference across renders — this is the documented contract.
+      const onBlankContextMenu = useCallback(handler, []);
+      return (
+        <>
+          <button type="button" data-testid="rerender" onClick={rerender} />
+          <Paper
+            ref={setRef}
+            style={{ width: 100, height: 100 }}
+            renderElement={renderRectElement}
+            onBlankContextMenu={onBlankContextMenu}
+          />
+        </>
+      );
+    }
+
+    const { paper } = await mountPaper((ref) => <Harness setRef={ref} />);
+    expect(bindCount('blank:contextmenu')).toBe(1);
+
+    for (let index = 0; index < 3; index++) clickTestId('rerender');
+
+    // Stable ref → no re-subscribe across unrelated re-renders.
+    expect(bindCount('blank:contextmenu')).toBe(1);
+
+    act(() => {
+      paper.trigger('blank:contextmenu', fakeEvent, 0, 0);
+    });
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    listenToSpy.mockRestore();
+  });
+
+  it('re-subscribes and invokes the new handler when its reference changes', async () => {
+    const first = jest.fn();
+    const second = jest.fn();
+
+    function Harness({ setRef }: Readonly<HarnessProps>) {
+      const [useSecond, setUseSecond] = useState(false);
+      const swap = () => setUseSecond(true);
+      // Two distinct stable references; swapping changes the dependency.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      const handler = useCallback(useSecond ? second : first, [useSecond]);
+      return (
+        <>
+          <button type="button" data-testid="swap" onClick={swap} />
+          <Paper
+            ref={setRef}
+            style={{ width: 100, height: 100 }}
+            renderElement={renderRectElement}
+            onBlankContextMenu={handler}
+          />
+        </>
+      );
+    }
+
+    const { paper } = await mountPaper((ref) => <Harness setRef={ref} />);
+
+    clickTestId('swap');
+    act(() => {
+      paper.trigger('blank:contextmenu', fakeEvent, 0, 0);
+    });
+
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  it('re-subscribes when a new handler key is added', async () => {
+    const listenToSpy = jest.spyOn(mvc.Listener.prototype, 'listenTo');
+    const bindCount = (eventName: string) =>
+      listenToSpy.mock.calls.filter((call) => String(call[1]) === eventName).length;
+
+    const ctxHandler = jest.fn();
+    const clickHandler = jest.fn();
+    function Harness({ setRef }: Readonly<HarnessProps>) {
+      const [withExtra, setWithExtra] = useState(false);
+      const addKey = () => setWithExtra(true);
+      const onBlankContextMenu = useCallback(ctxHandler, []);
+      const onBlankPointerClick = useCallback(clickHandler, []);
+      return (
+        <>
+          <button type="button" data-testid="add-key" onClick={addKey} />
+          <Paper
+            ref={setRef}
+            style={{ width: 100, height: 100 }}
+            renderElement={renderRectElement}
+            onBlankContextMenu={onBlankContextMenu}
+            onBlankPointerClick={withExtra ? onBlankPointerClick : undefined}
+          />
+        </>
+      );
+    }
+
+    await mountPaper((ref) => <Harness setRef={ref} />);
+    expect(bindCount('blank:pointerclick')).toBe(0);
+
+    clickTestId('add-key');
+
+    // The added key activates → the subscription re-runs and binds it.
+    expect(bindCount('blank:pointerclick')).toBe(1);
+    listenToSpy.mockRestore();
+  });
+
+  it('documents the contract: a new inline handler re-subscribes every render', async () => {
+    const listenToSpy = jest.spyOn(mvc.Listener.prototype, 'listenTo');
+    const bindCount = (eventName: string) =>
+      listenToSpy.mock.calls.filter((call) => String(call[1]) === eventName).length;
+
+    function Harness({ setRef }: Readonly<HarnessProps>) {
+      const [, force] = useState(0);
+      // eslint-disable-next-line sonarjs/no-nested-functions
+      const rerender = () => force((n) => n + 1);
+      return (
+        <>
+          <button type="button" data-testid="rerender" onClick={rerender} />
+          <Paper
+            ref={setRef}
+            style={{ width: 100, height: 100 }}
+            renderElement={renderRectElement}
+            // New reference every render → re-subscribes every render (by design).
+            onBlankContextMenu={() => {}}
+          />
+        </>
+      );
+    }
+
+    await mountPaper((ref) => <Harness setRef={ref} />);
+    const afterMount = bindCount('blank:contextmenu');
+
+    clickTestId('rerender');
+
+    // Inline handler changed identity → one more bind. Stable refs avoid this.
+    expect(bindCount('blank:contextmenu')).toBe(afterMount + 1);
+    listenToSpy.mockRestore();
+  });
+
+  it('does NOT re-subscribe when only a non-event prop changes', async () => {
+    const listenToSpy = jest.spyOn(mvc.Listener.prototype, 'listenTo');
+    const bindCount = (eventName: string) =>
+      listenToSpy.mock.calls.filter((call) => String(call[1]) === eventName).length;
+
+    const handler = jest.fn();
+    function Harness({ setRef }: Readonly<HarnessProps>) {
+      const [grid, setGrid] = useState(5);
+      // eslint-disable-next-line sonarjs/no-nested-functions
+      const bumpGrid = () => setGrid((g) => g + 1);
+      const onBlankContextMenu = useCallback(handler, []);
+      return (
+        <>
+          <button type="button" data-testid="bump" onClick={bumpGrid} />
+          <Paper
+            ref={setRef}
+            style={{ width: 100, height: 100 }}
+            renderElement={renderRectElement}
+            gridSize={grid}
+            onBlankContextMenu={onBlankContextMenu}
+          />
+        </>
+      );
+    }
+
+    await mountPaper((ref) => <Harness setRef={ref} />);
+    expect(bindCount('blank:contextmenu')).toBe(1);
+
+    clickTestId('bump');
+
+    // A non-event prop (gridSize) changed → events must not re-subscribe.
+    expect(bindCount('blank:contextmenu')).toBe(1);
+    listenToSpy.mockRestore();
+  });
+});
+
+/**
+ * Resolves the `dia.ElementView` for the seeded cell once it is rendered.
+ * @param paper - The paper instance.
+ * @returns The element view for cell `'1'`.
+ */
+const elementView = (paper: dia.Paper): dia.ElementView => {
+  const model = paper.model.getCell('1');
+  return paper.findViewByModel(model) as dia.ElementView;
+};
+
+describe('Paper event context shapes', () => {
+  it('delivers element pointer context (id, model, view, coords)', async () => {
+    const onElementPointerClick = jest.fn();
+    const { paper } = await mountPaper((ref) => (
+      <Paper
+        ref={ref}
+        style={{ width: 100, height: 100 }}
+        renderElement={renderRectElement}
+        onElementPointerClick={onElementPointerClick}
+      />
+    ));
+    const view = elementView(paper);
+
+    act(() => {
+      paper.trigger('element:pointerclick', view, fakeEvent, 5, 6);
+    });
+
+    expect(onElementPointerClick).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: '1',
+        model: view.model,
+        view,
+        paper,
+        graph: paper.model,
+        event: fakeEvent,
+        x: 5,
+        y: 6,
+      })
+    );
+  });
+
+  it('delivers cell-level pointer context for an element', async () => {
+    const onCellPointerClick = jest.fn();
+    const { paper } = await mountPaper((ref) => (
+      <Paper
+        ref={ref}
+        style={{ width: 100, height: 100 }}
+        renderElement={renderRectElement}
+        onCellPointerClick={onCellPointerClick}
+      />
+    ));
+    const view = elementView(paper);
+
+    act(() => {
+      paper.trigger('cell:pointerclick', view, fakeEvent, 1, 2);
+    });
+
+    expect(onCellPointerClick).toHaveBeenCalledWith(
+      expect.objectContaining({ id: '1', model: view.model, view, x: 1, y: 2 })
+    );
+  });
+
+  it('delivers hover context with event but no coords', async () => {
+    const onElementMouseEnter = jest.fn();
+    const { paper } = await mountPaper((ref) => (
+      <Paper
+        ref={ref}
+        style={{ width: 100, height: 100 }}
+        renderElement={renderRectElement}
+        onElementMouseEnter={onElementMouseEnter}
+      />
+    ));
+    const view = elementView(paper);
+
+    act(() => {
+      paper.trigger('element:mouseenter', view, fakeEvent);
+    });
+
+    const [[ctx]] = onElementMouseEnter.mock.calls;
+    expect(ctx).toMatchObject({ id: '1', view, event: fakeEvent });
+    expect(ctx).not.toHaveProperty('x');
+  });
+
+  it('delivers blank wheel context with delta', async () => {
+    const onBlankMouseWheel = jest.fn();
+    const { paper } = await mountPaper((ref) => (
+      <Paper
+        ref={ref}
+        style={{ width: 100, height: 100 }}
+        renderElement={renderRectElement}
+        onBlankMouseWheel={onBlankMouseWheel}
+      />
+    ));
+
+    act(() => {
+      paper.trigger('blank:mousewheel', fakeEvent, 1, 2, 3);
+    });
+
+    expect(onBlankMouseWheel).toHaveBeenCalledWith(
+      expect.objectContaining({ event: fakeEvent, x: 1, y: 2, delta: 3, paper, graph: paper.model })
+    );
+  });
+
+  it('delivers paper-level resize context from raw native args', async () => {
+    const onResize = jest.fn();
+    const options = { source: 'test' };
+    const { paper } = await mountPaper((ref) => (
+      <Paper
+        ref={ref}
+        style={{ width: 100, height: 100 }}
+        renderElement={renderRectElement}
+        onResize={onResize}
+      />
+    ));
+
+    act(() => {
+      paper.trigger('resize', 800, 600, options);
+    });
+
+    expect(onResize).toHaveBeenCalledWith(
+      expect.objectContaining({ width: 800, height: 600, options, paper, graph: paper.model })
+    );
+  });
+});
diff --git a/packages/joint-react/src/components/paper/paper.types.ts b/packages/joint-react/src/components/paper/paper.types.ts
index 91444de757..4363da1141 100644
--- a/packages/joint-react/src/components/paper/paper.types.ts
+++ b/packages/joint-react/src/components/paper/paper.types.ts
@@ -3,12 +3,20 @@ import type { LinkRecord } from '../../types/cell.types';
 import type { PortalSelector } from '../../models/react-paper.types';
 import type { ReactPaper } from '../../models/react-paper';
 import type { CSSProperties, PropsWithChildren, ReactNode } from 'react';
-import type { ConnectionEnd, CanConnectOptions, ValidateConnectionContext } from '../../presets/can-connect';
+import type {
+  ConnectionEnd,
+  CanConnectOptions,
+  ValidateConnectionContext,
+} from '../../presets/can-connect';
 import type { ValidateEmbeddingContext, ValidateUnembeddingContext } from '../../presets/can-embed';
-import type { ConnectionStrategyOptions, ConnectionStrategyContext } from '../../presets/connection-strategy';
+import type {
+  ConnectionStrategyOptions,
+  ConnectionStrategyContext,
+} from '../../presets/connection-strategy';
 import type { CellVisibility } from '../../presets/cell-visibility';
 import type { Interactive } from '../../presets/interactive';
 import type { LinkRouting } from '../../presets/link-routing';
+import type { NormalizedPaperHandlers } from '../../presets/paper-events';
 
 /**
  * Value accepted by the Paper `transform` prop. Strings are parsed via the
@@ -212,9 +220,23 @@ export type RenderLink<LinkData = unknown> = (data: LinkData) => ReactNode;
 /**
  * The props for the Paper component. Extend the `dia.Paper.Options` interface.
  * For more information, see the JointJS documentation.
+ *
+ * Normalized paper events are exposed directly as props
+ * (`onBlankContextMenu`, `onElementPointerClick`, `onLinkMouseEnter`, …) via
+ * {@link NormalizedPaperHandlers}. Each handler receives a single context
+ * object — e.g. `onBlankContextMenu={({ paper, event, x, y }) => …}`.
+ *
+ * Handlers participate in the event subscription's dependency list, exactly
+ * like a `useEffect` dependency: the subscription re-binds whenever a handler's
+ * **reference** changes. Pass **stable references** — `useCallback` or a
+ * module-level function — so the paper subscribes once. A new inline arrow on
+ * every render (`onBlankContextMenu={() => …}`) re-subscribes that paper's
+ * events on every render; correct, but wasteful. For raw native event names or
+ * events without a normalized form (`resize`, `transform`, `render:done`, …),
+ * use the `usePaperEvents` hook.
  * @see https://docs.jointjs.com/api/dia/Paper
  */
-export interface PaperProps extends PortalPaperOptions, PropsWithChildren {
+export interface PaperProps extends PortalPaperOptions, PropsWithChildren, NormalizedPaperHandlers {
   /**
    * A function that renders the element.
    *
diff --git a/packages/joint-react/src/components/paper/render-element/__tests__/paper-element-item.test.tsx b/packages/joint-react/src/components/paper/render-element/__tests__/paper-element-item.test.tsx
index 7a8c0612b8..f4d45a1159 100644
--- a/packages/joint-react/src/components/paper/render-element/__tests__/paper-element-item.test.tsx
+++ b/packages/joint-react/src/components/paper/render-element/__tests__/paper-element-item.test.tsx
@@ -1,5 +1,6 @@
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
- 
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
+
 import { render, waitFor } from '@testing-library/react';
 import { useContext, type ComponentType } from 'react';
 import { GraphProvider } from '../../../graph/graph-provider';
diff --git a/packages/joint-react/src/components/paper/render-element/__tests__/paper-html-overlay.test.tsx b/packages/joint-react/src/components/paper/render-element/__tests__/paper-html-overlay.test.tsx
index 5b00373ef0..8cf43a6b16 100644
--- a/packages/joint-react/src/components/paper/render-element/__tests__/paper-html-overlay.test.tsx
+++ b/packages/joint-react/src/components/paper/render-element/__tests__/paper-html-overlay.test.tsx
@@ -1,5 +1,6 @@
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
- 
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
+
 import { render, waitFor } from '@testing-library/react';
 import { GraphProvider } from '../../../graph/graph-provider';
 import { Paper } from '../../paper';
diff --git a/packages/joint-react/src/hooks/__tests__/use-cells.test.tsx b/packages/joint-react/src/hooks/__tests__/use-cells.test.tsx
index f2b14e93b8..68f725ad4f 100644
--- a/packages/joint-react/src/hooks/__tests__/use-cells.test.tsx
+++ b/packages/joint-react/src/hooks/__tests__/use-cells.test.tsx
@@ -166,11 +166,11 @@ describe('useCells', () => {
 
   it('no-arg form handles large cell counts without stack overflow', async () => {
     const largeCells: CellRecord[] = [];
-    for (let i = 0; i < 5000; i++) {
+    for (let index = 0; index < 5000; index++) {
       largeCells.push({
-        id: `el-${i}`,
+        id: `el-${index}`,
         type: ELEMENT_MODEL_TYPE,
-        position: { x: i, y: 0 },
+        position: { x: index, y: 0 },
         size: { width: 10, height: 10 },
       } as CellRecord);
     }
diff --git a/packages/joint-react/src/hooks/__tests__/use-create-features.test.tsx b/packages/joint-react/src/hooks/__tests__/use-create-features.test.tsx
index 71840c7289..76992f1c08 100644
--- a/packages/joint-react/src/hooks/__tests__/use-create-features.test.tsx
+++ b/packages/joint-react/src/hooks/__tests__/use-create-features.test.tsx
@@ -1,5 +1,4 @@
- 
- 
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { render, waitFor } from '@testing-library/react';
 import { GraphProvider, Paper } from '../../components';
 import { FeaturesProvider } from '../../components/features-provider/features-provider';
diff --git a/packages/joint-react/src/hooks/__tests__/use-create-portal-paper.test.tsx b/packages/joint-react/src/hooks/__tests__/use-create-portal-paper.test.tsx
index 4da8e87170..c6fd747de1 100644
--- a/packages/joint-react/src/hooks/__tests__/use-create-portal-paper.test.tsx
+++ b/packages/joint-react/src/hooks/__tests__/use-create-portal-paper.test.tsx
@@ -1,4 +1,5 @@
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 
 import { dia } from '@joint/core';
 import { useEffect, useRef } from 'react';
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 7be95224d0..4379d84be3 100644
--- a/packages/joint-react/src/hooks/__tests__/use-markup.test.tsx
+++ b/packages/joint-react/src/hooks/__tests__/use-markup.test.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { useCallback, useEffect, useRef } from 'react';
 import { render, waitFor } from '@testing-library/react';
 import { GraphProvider, Paper } from '../../components';
diff --git a/packages/joint-react/src/hooks/__tests__/use-measure-node.test.tsx b/packages/joint-react/src/hooks/__tests__/use-measure-node.test.tsx
index 038254bb35..04592d9baf 100644
--- a/packages/joint-react/src/hooks/__tests__/use-measure-node.test.tsx
+++ b/packages/joint-react/src/hooks/__tests__/use-measure-node.test.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { Component, useRef, type ReactNode } from 'react';
 
 class CatchErrorBoundary extends Component<
diff --git a/packages/joint-react/src/hooks/__tests__/use-nodes-measured-effect.test.tsx b/packages/joint-react/src/hooks/__tests__/use-nodes-measured-effect.test.tsx
index a76cc87c5c..9e2a49c1bc 100644
--- a/packages/joint-react/src/hooks/__tests__/use-nodes-measured-effect.test.tsx
+++ b/packages/joint-react/src/hooks/__tests__/use-nodes-measured-effect.test.tsx
@@ -6,7 +6,7 @@ import { ELEMENT_MODEL_TYPE } from '../../models/element-model';
 import { useGraphStore } from '../use-graph-store';
 import type { CellRecord } from '../../types/cell.types';
 import type { ElementsMeasuredEvent } from '../../types/event.types';
-import { dia } from '@joint/core';
+import type { dia } from '@joint/core';
 
 const flush = () => new Promise<void>((resolve) => queueMicrotask(resolve));
 
diff --git a/packages/joint-react/src/hooks/__tests__/use-paper-events.test.tsx b/packages/joint-react/src/hooks/__tests__/use-paper-events.test.tsx
index 107c55d8cd..a80dd853fc 100644
--- a/packages/joint-react/src/hooks/__tests__/use-paper-events.test.tsx
+++ b/packages/joint-react/src/hooks/__tests__/use-paper-events.test.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { mvc } from '@joint/core';
 import { renderHook, render, waitFor } from '@testing-library/react';
 import { GraphProvider, Paper } from '../../components';
diff --git a/packages/joint-react/src/hooks/__tests__/use-paper.test.tsx b/packages/joint-react/src/hooks/__tests__/use-paper.test.tsx
index 09dbb5a409..d798c6e273 100644
--- a/packages/joint-react/src/hooks/__tests__/use-paper.test.tsx
+++ b/packages/joint-react/src/hooks/__tests__/use-paper.test.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { render, renderHook, waitFor } from '@testing-library/react';
 import { useRef } from 'react';
 import type { dia } from '@joint/core';
diff --git a/packages/joint-react/src/hooks/use-create-portal-paper.tsx b/packages/joint-react/src/hooks/use-create-portal-paper.tsx
index 3fda85e4d1..2ee3f80074 100644
--- a/packages/joint-react/src/hooks/use-create-portal-paper.tsx
+++ b/packages/joint-react/src/hooks/use-create-portal-paper.tsx
@@ -45,8 +45,9 @@ import {
 } from '../components/paper/render-element/paper-element-item';
 import { createSelectPaperVersion } from '../selectors';
 import { useAreElementsMeasured } from './use-are-elements-measured';
-import { LINK_MODEL_TYPE } from '../internal';
+import { LINK_MODEL_TYPE, subscribeToPaperEvents } from '../internal';
 import type { CellId } from '../types/cell.types';
+import { extractEventsFromPaperProps } from '../presets/paper-events';
 
 type LinkModelConstructor = new (attributes?: dia.Link.Attributes) => dia.Link;
 
@@ -290,6 +291,16 @@ export function useCreatePortalPaper(
 
   const isReady = !!paper && (isExternalPaper || !elementRef || !!elementRef.current);
 
+  const { eventDependencies, eventHandlers } = useMemo(
+    () => extractEventsFromPaperProps(paperOptions),
+    [paperOptions]
+  );
+  useLayoutEffect(() => {
+    if (!paperStore) return;
+    return subscribeToPaperEvents(paperStore, eventHandlers);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [paperStore, ...eventDependencies]);
+
   useLayoutEffect(() => {
     const hostElementForCreation = elementRef?.current;
 
diff --git a/packages/joint-react/src/presets/__tests__/extra-coverage.test.ts b/packages/joint-react/src/presets/__tests__/extra-coverage.test.ts
index c6716e1c20..2a0cd63785 100644
--- a/packages/joint-react/src/presets/__tests__/extra-coverage.test.ts
+++ b/packages/joint-react/src/presets/__tests__/extra-coverage.test.ts
@@ -26,8 +26,8 @@ describe('presets / element-ports / elementPort — group-positioned', () => {
 
   it('marks port magnet as passive when configured', () => {
     const port = elementPort({ passive: true });
-    const attributes = port.attrs as { portBody: { magnet: string } };
-    expect(attributes.portBody.magnet).toBe('passive');
+    const attributes = port.attrs as { port: { magnet: string } };
+    expect(attributes.port.magnet).toBe('passive');
   });
 });
 
diff --git a/packages/joint-react/src/presets/__tests__/link-labels.test.ts b/packages/joint-react/src/presets/__tests__/link-labels.test.ts
index 5c93d4780e..59cda8b325 100644
--- a/packages/joint-react/src/presets/__tests__/link-labels.test.ts
+++ b/packages/joint-react/src/presets/__tests__/link-labels.test.ts
@@ -13,31 +13,35 @@ describe('presets / link-labels / linkLabel', () => {
     const label = linkLabel({ text: 'x', backgroundShape: 'ellipse' });
     const [body] = label.markup as Array<{ tagName: string }>;
     expect(body.tagName).toBe('ellipse');
-    const labelBodyAttributes = (label.attrs as { labelBody: Record<string, unknown> }).labelBody;
-    expect(labelBodyAttributes.cx).toBe('0');
-    expect(labelBodyAttributes.rx).toBeDefined();
+    const labelBackgroundAttributes = (label.attrs as { labelBackground: Record<string, unknown> })
+      .labelBackground;
+    expect(labelBackgroundAttributes.cx).toBe('0');
+    expect(labelBackgroundAttributes.rx).toBeDefined();
   });
 
   it('builds a path-shaped label using SVG path d', () => {
     const label = linkLabel({ text: 'x', backgroundShape: 'M 0 0 L 10 10' });
     const [body] = label.markup as Array<{ tagName: string }>;
     expect(body.tagName).toBe('path');
-    const labelBodyAttributes = (label.attrs as { labelBody: Record<string, unknown> }).labelBody;
-    expect(labelBodyAttributes.d).toBe('M 0 0 L 10 10');
+    const labelBackgroundAttributes = (label.attrs as { labelBackground: Record<string, unknown> })
+      .labelBackground;
+    expect(labelBackgroundAttributes.d).toBe('M 0 0 L 10 10');
   });
 
   it('uses calc-expression path with ref', () => {
     const label = linkLabel({ text: 'x', backgroundShape: 'M calc(w) 0 L 10 10' });
     const [body] = label.markup as Array<{ tagName: string }>;
     expect(body.tagName).toBe('path');
-    const labelBodyAttributes = (label.attrs as { labelBody: Record<string, unknown> }).labelBody;
-    expect(labelBodyAttributes.ref).toBe('labelText');
+    const labelBackgroundAttributes = (label.attrs as { labelBackground: Record<string, unknown> })
+      .labelBackground;
+    expect(labelBackgroundAttributes.ref).toBe('label');
   });
 
   it('applies opacity when provided', () => {
     const label = linkLabel({ text: 'x', backgroundOpacity: 0.5 });
-    const labelBodyAttributes = (label.attrs as { labelBody: Record<string, unknown> }).labelBody;
-    expect(labelBodyAttributes.opacity).toBe(0.5);
+    const labelBackgroundAttributes = (label.attrs as { labelBackground: Record<string, unknown> })
+      .labelBackground;
+    expect(labelBackgroundAttributes.opacity).toBe(0.5);
   });
 
   it('applies offset when provided', () => {
@@ -48,8 +52,9 @@ describe('presets / link-labels / linkLabel', () => {
 
   it('handles numeric backgroundPadding', () => {
     const label = linkLabel({ text: 'x', backgroundPadding: 5 });
-    const labelBodyAttributes = (label.attrs as { labelBody: Record<string, unknown> }).labelBody;
-    expect(labelBodyAttributes.x).toContain('5');
+    const labelBackgroundAttributes = (label.attrs as { labelBackground: Record<string, unknown> })
+      .labelBackground;
+    expect(labelBackgroundAttributes.x).toContain('5');
   });
 
   it('handles partial backgroundPadding object', () => {
@@ -85,8 +90,8 @@ describe('presets / link-labels / linkLabels', () => {
       { a: { text: 'A' } },
       { color: '#fff' }
     );
-    const attributes = out[0].attrs as { labelText: { style: { fill: string } } };
-    expect(attributes.labelText.style.fill).toBe('#fff');
+    const attributes = out[0].attrs as { label: { style: { fill: string } } };
+    expect(attributes.label.style.fill).toBe('#fff');
   });
 
   it('per-label fields override label style', () => {
@@ -94,7 +99,7 @@ describe('presets / link-labels / linkLabels', () => {
       { a: { text: 'A', color: '#000' } },
       { color: '#fff' }
     );
-    const attributes = out[0].attrs as { labelText: { style: { fill: string } } };
-    expect(attributes.labelText.style.fill).toBe('#000');
+    const attributes = out[0].attrs as { label: { style: { fill: string } } };
+    expect(attributes.label.style.fill).toBe('#000');
   });
 });
diff --git a/packages/joint-react/src/presets/paper-events.ts b/packages/joint-react/src/presets/paper-events.ts
index 9d18907d01..65a2c88b1e 100644
--- a/packages/joint-react/src/presets/paper-events.ts
+++ b/packages/joint-react/src/presets/paper-events.ts
@@ -228,7 +228,6 @@ const LINK_CONNECT_MAP = {
 //   onRenderIdle: 'render:idle',
 // } as const;
 
-
 const POINTER_BLANK_MAP = {
   onBlankPointerDown: 'blank:pointerdown',
   onBlankPointerMove: 'blank:pointermove',
@@ -278,7 +277,7 @@ const TRANSFORM_MAP = {
   onTransform: 'transform',
 } as const;
 
-const NORMALIZED_KEYS = new Set<string>([
+export const NORMALIZED_KEYS = new Set<string>([
   ...Object.keys(POINTER_CELL_MAP),
   ...Object.keys(HOVER_CELL_MAP),
   ...Object.keys(WHEEL_CELL_MAP),
@@ -308,7 +307,7 @@ const NORMALIZED_KEYS = new Set<string>([
  * `'cell:unhighlight'`, `'cell:highlight:invalid'`, `'link:snap:connect'`,
  * `'link:snap:disconnect'`.
  */
-interface NormalizedPaperHandlers {
+export interface NormalizedPaperHandlers {
   // pointer (cell — fires for any cell, element OR link)
   readonly onCellPointerDown?: (ctx: PointerCellEventContext) => void;
   readonly onCellPointerMove?: (ctx: PointerCellEventContext) => void;
@@ -461,34 +460,75 @@ function subscribeRaw(
  * @param handlers - Normalized + raw event handlers.
  * @returns Cleanup callback that calls `listener.stopListening()`.
  */
-export function addPaperEventListeners(
-  paper: dia.Paper,
-  handlers: PaperEventMap
-): () => void {
+export function addPaperEventListeners(paper: dia.Paper, handlers: PaperEventMap): () => void {
   const graph = paper.model;
   const controller = new mvc.Listener();
   const eventMap = handlers as EventHandlerMap;
   const baseContext: BaseContext = { paper, graph };
 
-  subscribeGroup(controller, paper, eventMap, POINTER_CELL_MAP,
-    (view: dia.CellView, event: dia.Event, x: number, y: number) =>
-      ({ ...baseContext, ...makeCellContext(view), event, x, y }));
-
-  subscribeGroup(controller, paper, eventMap, HOVER_CELL_MAP,
-    (view: dia.CellView, event: dia.Event) => ({ ...baseContext, ...makeCellContext(view), event }));
-
-  subscribeGroup(controller, paper, eventMap, WHEEL_CELL_MAP,
-    (view: dia.CellView, event: dia.Event, x: number, y: number, delta: number) =>
-      ({ ...baseContext, ...makeCellContext(view), event, x, y, delta }));
+  subscribeGroup(
+    controller,
+    paper,
+    eventMap,
+    POINTER_CELL_MAP,
+    (view: dia.CellView, event: dia.Event, x: number, y: number) => ({
+      ...baseContext,
+      ...makeCellContext(view),
+      event,
+      x,
+      y,
+    })
+  );
+
+  subscribeGroup(
+    controller,
+    paper,
+    eventMap,
+    HOVER_CELL_MAP,
+    (view: dia.CellView, event: dia.Event) => ({ ...baseContext, ...makeCellContext(view), event })
+  );
+
+  subscribeGroup(
+    controller,
+    paper,
+    eventMap,
+    WHEEL_CELL_MAP,
+    (view: dia.CellView, event: dia.Event, x: number, y: number, delta: number) => ({
+      ...baseContext,
+      ...makeCellContext(view),
+      event,
+      x,
+      y,
+      delta,
+    })
+  );
 
   // Native magnet arg order is (view, evt, magnet, x, y) — not (view, evt, x, y, magnet).
-  subscribeGroup(controller, paper, eventMap, MAGNET_MAP,
+  subscribeGroup(
+    controller,
+    paper,
+    eventMap,
+    MAGNET_MAP,
     (view: dia.ElementView, event: dia.Event, magnet: DOMElement, x: number, y: number) => {
       const end = toConnectionEnd(view, magnet);
-      return { ...baseContext, ...makeCellContext(view), event, x, y, magnet, port: end.port, selector: end.selector };
-    });
-
-  subscribeGroup(controller, paper, eventMap, LINK_CONNECT_MAP,
+      return {
+        ...baseContext,
+        ...makeCellContext(view),
+        event,
+        x,
+        y,
+        magnet,
+        port: end.port,
+        selector: end.selector,
+      };
+    }
+  );
+
+  subscribeGroup(
+    controller,
+    paper,
+    eventMap,
+    LINK_CONNECT_MAP,
     (
       linkView: dia.LinkView,
       event: dia.Event,
@@ -501,52 +541,150 @@ export function addPaperEventListeners(
       event,
       end,
       endCell: toConnectionEnd(endView, endMagnet),
-    }));
-
-  subscribeGroup(controller, paper, eventMap, POINTER_BLANK_MAP,
-    (event: dia.Event, x: number, y: number) => ({ ...baseContext, event, x, y }));
-
-  subscribeGroup(controller, paper, eventMap, HOVER_BLANK_MAP,
-    (event: dia.Event) => ({ ...baseContext, event }));
-
-  subscribeGroup(controller, paper, eventMap, WHEEL_BLANK_MAP,
-    (event: dia.Event, x: number, y: number, delta: number) =>
-      ({ ...baseContext, event, x, y, delta }));
+    })
+  );
+
+  subscribeGroup(
+    controller,
+    paper,
+    eventMap,
+    POINTER_BLANK_MAP,
+    (event: dia.Event, x: number, y: number) => ({ ...baseContext, event, x, y })
+  );
+
+  subscribeGroup(controller, paper, eventMap, HOVER_BLANK_MAP, (event: dia.Event) => ({
+    ...baseContext,
+    event,
+  }));
+
+  subscribeGroup(
+    controller,
+    paper,
+    eventMap,
+    WHEEL_BLANK_MAP,
+    (event: dia.Event, x: number, y: number, delta: number) => ({
+      ...baseContext,
+      event,
+      x,
+      y,
+      delta,
+    })
+  );
 
   // Paper-level hover (`paper:mouseenter` / `paper:mouseleave`) — native (evt).
-  subscribeGroup(controller, paper, eventMap, PAPER_HOVER_MAP,
-    (event: dia.Event) => ({ ...baseContext, event }));
+  subscribeGroup(controller, paper, eventMap, PAPER_HOVER_MAP, (event: dia.Event) => ({
+    ...baseContext,
+    event,
+  }));
 
   // Paper-level pan (`paper:pan`) — native (evt, deltaX, deltaY).
-  subscribeGroup(controller, paper, eventMap, PAPER_PAN_MAP,
-    (event: dia.Event, deltaX: number, deltaY: number) =>
-      ({ ...baseContext, event, deltaX, deltaY }));
+  subscribeGroup(
+    controller,
+    paper,
+    eventMap,
+    PAPER_PAN_MAP,
+    (event: dia.Event, deltaX: number, deltaY: number) => ({
+      ...baseContext,
+      event,
+      deltaX,
+      deltaY,
+    })
+  );
 
   // Paper-level pinch (`paper:pinch`) — native (evt, x, y, scale).
-  subscribeGroup(controller, paper, eventMap, PAPER_PINCH_MAP,
-    (event: dia.Event, x: number, y: number, scale: number) =>
-      ({ ...baseContext, event, x, y, scale }));
+  subscribeGroup(
+    controller,
+    paper,
+    eventMap,
+    PAPER_PINCH_MAP,
+    (event: dia.Event, x: number, y: number, scale: number) => ({
+      ...baseContext,
+      event,
+      x,
+      y,
+      scale,
+    })
+  );
 
   // `translate` — native (tx, ty, data).
-  subscribeGroup(controller, paper, eventMap, TRANSLATE_MAP,
-    (translateX: number, translateY: number, options: unknown) =>
-      ({ ...baseContext, translateX, translateY, options }));
+  subscribeGroup(
+    controller,
+    paper,
+    eventMap,
+    TRANSLATE_MAP,
+    (translateX: number, translateY: number, options: unknown) => ({
+      ...baseContext,
+      translateX,
+      translateY,
+      options,
+    })
+  );
 
   // `scale` — native (sx, sy, data).
-  subscribeGroup(controller, paper, eventMap, SCALE_MAP,
-    (scaleX: number, scaleY: number, options: unknown) =>
-      ({ ...baseContext, scaleX, scaleY, options }));
+  subscribeGroup(
+    controller,
+    paper,
+    eventMap,
+    SCALE_MAP,
+    (scaleX: number, scaleY: number, options: unknown) => ({
+      ...baseContext,
+      scaleX,
+      scaleY,
+      options,
+    })
+  );
 
   // `resize` — native (width, height, data).
-  subscribeGroup(controller, paper, eventMap, RESIZE_MAP,
-    (width: number, height: number, options: unknown) =>
-      ({ ...baseContext, width, height, options }));
+  subscribeGroup(
+    controller,
+    paper,
+    eventMap,
+    RESIZE_MAP,
+    (width: number, height: number, options: unknown) => ({
+      ...baseContext,
+      width,
+      height,
+      options,
+    })
+  );
 
   // `transform` — native (matrix, data).
-  subscribeGroup(controller, paper, eventMap, TRANSFORM_MAP,
-    (matrix: SVGMatrix, options: unknown) => ({ ...baseContext, matrix, options }));
+  subscribeGroup(
+    controller,
+    paper,
+    eventMap,
+    TRANSFORM_MAP,
+    (matrix: SVGMatrix, options: unknown) => ({ ...baseContext, matrix, options })
+  );
 
   subscribeRaw(controller, paper, eventMap);
 
   return () => controller.stopListening();
 }
+
+/**
+ * Picks the normalized paper-event handlers (`onBlankContextMenu`, …) out of a
+ * props object. Returns the handlers map (to subscribe) plus a parallel
+ * `eventDependencies` array of the handler values, in key order — spread it
+ * into a `useLayoutEffect` dependency list so the subscription re-runs only
+ * when a handler reference changes. Non-event props are ignored, so changing
+ * them never re-subscribes.
+ * @param props - Any object that may contain normalized handler keys.
+ * @returns `eventHandlers` (the matched `on*` entries) and `eventDependencies` (their values, in key order).
+ */
+export function extractEventsFromPaperProps(props: Partial<NormalizedPaperHandlers>) {
+  const eventHandlers: Partial<NormalizedPaperHandlers> = {};
+  const eventDependencies: unknown[] = [];
+  for (const property in props) {
+    const key = property as keyof NormalizedPaperHandlers;
+    if (NORMALIZED_KEYS.has(key)) {
+      // Variable-key write: cast past the readonly/union index to assign.
+      (eventHandlers as Record<string, unknown>)[key] = props[key];
+      eventDependencies.push(props[key]);
+    }
+  }
+  return {
+    eventHandlers,
+    eventDependencies,
+  };
+}
diff --git a/packages/joint-react/src/state/__tests__/data-mapper.test.ts b/packages/joint-react/src/state/__tests__/data-mapper.test.ts
index 476b307032..72a554ee64 100644
--- a/packages/joint-react/src/state/__tests__/data-mapper.test.ts
+++ b/packages/joint-react/src/state/__tests__/data-mapper.test.ts
@@ -151,7 +151,7 @@ describe('dataMapper', () => {
       const [port] = cellJson.ports!.items!;
       expect(port.label).toBeDefined();
       expect(port.label!.position!.name).toBe('outside');
-      expect(port.attrs?.text?.text).toBe('Port A');
+      expect(port.attrs?.label?.text).toBe('Port A');
     });
 
     it('should handle rect shape ports', () => {
diff --git a/packages/joint-react/src/store/__tests__/paper-store.test.ts b/packages/joint-react/src/store/__tests__/paper-store.test.ts
index c65208dc3b..459b0d2cef 100644
--- a/packages/joint-react/src/store/__tests__/paper-store.test.ts
+++ b/packages/joint-react/src/store/__tests__/paper-store.test.ts
@@ -81,7 +81,7 @@ describe('PaperStore', () => {
       expect((highlighting as Record<string, unknown>)?.magnetAvailability).toMatchObject({
         name: 'addClass',
         options: {
-          className: 'jj-is-available',
+          className: 'jj-is-magnet-available',
         },
       });
     });
diff --git a/packages/joint-react/src/stories/demos/automatic-layout-storage/code.tsx b/packages/joint-react/src/stories/demos/automatic-layout-storage/code.tsx
index c258fc9a2a..09eae4042d 100644
--- a/packages/joint-react/src/stories/demos/automatic-layout-storage/code.tsx
+++ b/packages/joint-react/src/stories/demos/automatic-layout-storage/code.tsx
@@ -485,7 +485,7 @@ function InnerShell({ onLoadFile }: Readonly<InnerShellProps>) {
 
       <div className="flex-1 flex min-h-0">
         <div className="flex-1 relative bg-[radial-gradient(rgba(28,36,52,0.12)_1px,transparent_1px)] bg-[length:20px_20px] [background-position:12px_12px]">
-          <Paper style={{ backgroundColor: 'transparent', width: "100%", height: "100%" }}
+          <Paper style={{ backgroundColor: 'transparent', width: '100%', height: '100%' }}
             linkRouting={linkRoutingOrthogonal({
               sourceOffset: 6,
               targetOffset: 6,
diff --git a/packages/joint-react/src/stories/demos/collaboration/code.tsx b/packages/joint-react/src/stories/demos/collaboration/code.tsx
index 125c68b2ea..7f671a00fb 100644
--- a/packages/joint-react/src/stories/demos/collaboration/code.tsx
+++ b/packages/joint-react/src/stories/demos/collaboration/code.tsx
@@ -15,7 +15,6 @@ import {
   type IncrementalCellsChange,
 } from '@joint/react';
 import { linkRoutingOrthogonal } from '@joint/react/presets';
-import { usePaperEvents } from '../../../hooks';
 import Peer, { type DataConnection } from 'peerjs';
 import {
   createContext,
@@ -785,23 +784,6 @@ function Toolbar() {
   );
 }
 
-// ── Drag Tracker (broadcasts local drags to peers) ─────────────────────────
-
-function DragTracker({ manager }: Readonly<{ manager: ReturnType<typeof createPeerManager> }>) {
-  const draggingRef = useRef<Set<string>>(new Set());
-  usePaperEvents({
-    onElementPointerDown: ({ id }) => {
-      draggingRef.current.add(String(id));
-      manager.sendDrag([...draggingRef.current]);
-    },
-    onElementPointerUp: ({ id }) => {
-      draggingRef.current.delete(String(id));
-      manager.sendDrag([...draggingRef.current]);
-    },
-  }, [manager]);
-  return null;
-}
-
 // ── Main ────────────────────────────────────────────────────────────────────
 
 function GraphWithRedux() {
@@ -821,6 +803,7 @@ function GraphWithRedux() {
     () => USER_COLORS[Math.floor(Math.random() * USER_COLORS.length)]
   );
   const [remoteDragging, setRemoteDragging] = useState<Set<string>>(() => new Set());
+  const draggingRef = useRef<Set<string>>(new Set());
 
   const [manager] = useState(() =>
     createPeerManager({
@@ -910,7 +893,7 @@ function GraphWithRedux() {
           initialCells={themedCells}
           onIncrementalCellsChange={handleIncrementalChange}
         >
-          <Paper style={{ backgroundColor: theme.canvas, width: "100%", height: "100%" }}
+          <Paper style={{ backgroundColor: theme.canvas, width: '100%', height: '100%' }}
             gridSize={1}
             overflow
             linkPinning={false}
@@ -921,6 +904,14 @@ function GraphWithRedux() {
             defaultLink={{ style: { color: theme.link, width: 1.5, targetMarker: 'none' } }}
             validateConnection={({ target }) => target.port === 'in'}
             renderElement={RenderAgentNode}
+            onElementPointerDown={({ id }) => {
+              draggingRef.current.add(String(id));
+              manager.sendDrag([...draggingRef.current]);
+            }}
+            onElementPointerUp={({ id }) => {
+              draggingRef.current.delete(String(id));
+              manager.sendDrag([...draggingRef.current]);
+            }}
           />
           <ConnectionPanel
             peerId={peerId}
@@ -929,7 +920,6 @@ function GraphWithRedux() {
             peerName={peerName}
             onConnect={handleConnect}
           />
-          <DragTracker manager={manager} />
           <Toolbar />
         </GraphProvider>
       </RemoteDragContext.Provider>
diff --git a/packages/joint-react/src/stories/demos/flowchart/code.tsx b/packages/joint-react/src/stories/demos/flowchart/code.tsx
index bd952a7a35..8c10a0d5e8 100644
--- a/packages/joint-react/src/stories/demos/flowchart/code.tsx
+++ b/packages/joint-react/src/stories/demos/flowchart/code.tsx
@@ -1,9 +1,10 @@
 /* eslint-disable unicorn/consistent-function-scoping */
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 
 import './index.css';
 import type { CellRecord, ElementRecord, LinkRecord, LinkLabel, TransformOptions } from '@joint/react';
-import { GraphProvider, Paper, useMarkup, useMeasureNode, useNodesMeasuredEffect, usePaperEvents } from '@joint/react';
+import { GraphProvider, Paper, useMarkup, useMeasureNode, useNodesMeasuredEffect } from '@joint/react';
 import { PAPER_CLASSNAME } from 'storybook-config/theme';
 import { dia, highlighters, linkTools } from '@joint/core';
 import { linkRoutingOrthogonal } from '@joint/react/presets';
@@ -410,9 +411,27 @@ function RenderFlowchartElement(data: Readonly<ElementData>) {
 function Main() {
   const paperRef = useRef<dia.Paper | null>(null);
 
-  usePaperEvents(
-    {
-      onLinkPointerClick: ({ view: linkView, paper }) => {
+  useNodesMeasuredEffect(({ isInitial, paper }) => {
+    if (!isInitial) return;
+    paper.transformToFitContent({
+      padding: 40,
+      useModelGeometry: true,
+      verticalAlign: 'middle',
+      horizontalAlign: 'middle',
+    });
+  });
+
+  return (
+    <Paper style={{ height: 600 }}
+      ref={paperRef}
+      gridSize={5}
+      overflow
+      snapLabels
+      className={`${PAPER_CLASSNAME} flowchart-paper w-[200px]`}
+      renderElement={RenderFlowchartElement}
+      drawGrid={false}
+      linkRouting={ORTHOGONAL_LINKS}
+      onLinkPointerClick={({ view: linkView, paper }) => {
         paper.removeTools();
         dia.HighlighterView.removeAll(paper);
         const snapAnchor: linkTools.AnchorCallback<dia.Point> = (
@@ -452,8 +471,8 @@ function Main() {
           nonScalingStroke: true,
         });
         strokeHighlighter.el.classList.add('jj-flow-selection');
-      },
-      onElementMouseEnter: ({ view }) => {
+      }}
+      onElementMouseEnter={({ view }) => {
         const hl = highlighters.mask.add(view, 'body', 'frame', {
           padding: unit * 1.5,
           attrs: {
@@ -462,11 +481,11 @@ function Main() {
           },
         });
         hl.el.classList.add('jj-frame');
-      },
-      onElementMouseLeave: ({ view }) => {
+      }}
+      onElementMouseLeave={({ view }) => {
         highlighters.mask.remove(view, 'frame');
-      },
-      onLinkMouseEnter: ({ view: linkView }) => {
+      }}
+      onLinkMouseEnter={({ view: linkView }) => {
         if (highlighters.stroke.get(linkView, 'selection')) return;
         const frame = highlighters.mask.add(
           linkView,
@@ -482,38 +501,14 @@ function Main() {
           }
         );
         frame.el.classList.add('jj-frame');
-      },
-      onLinkMouseLeave: ({ paper }) => {
+      }}
+      onLinkMouseLeave={({ paper }) => {
         highlighters.mask.removeAll(paper, 'frame');
-      },
-      onBlankPointerDown: ({ paper }) => {
+      }}
+      onBlankPointerDown={({ paper }) => {
         paper.removeTools();
         dia.HighlighterView.removeAll(paper);
-      },
-    },
-    []
-  );
-
-  useNodesMeasuredEffect(({ isInitial, paper }) => {
-    if (!isInitial) return;
-    paper.transformToFitContent({
-      padding: 40,
-      useModelGeometry: true,
-      verticalAlign: 'middle',
-      horizontalAlign: 'middle',
-    });
-  });
-
-  return (
-    <Paper style={{ height: 600 }}
-      ref={paperRef}
-      gridSize={5}
-      overflow
-      snapLabels
-      className={`${PAPER_CLASSNAME} flowchart-paper w-[200px]`}
-      renderElement={RenderFlowchartElement}
-      drawGrid={false}
-      linkRouting={ORTHOGONAL_LINKS}
+      }}
     />
   );
 }
diff --git a/packages/joint-react/src/stories/demos/introduction-demo/code.tsx b/packages/joint-react/src/stories/demos/introduction-demo/code.tsx
index ded48958f2..c9597f3610 100644
--- a/packages/joint-react/src/stories/demos/introduction-demo/code.tsx
+++ b/packages/joint-react/src/stories/demos/introduction-demo/code.tsx
@@ -22,7 +22,6 @@ import {
   type LinkRecord,
   type ElementPort,
   type PaperProps,
-  usePaperEvents,
   selectElementSize,
 } from '@joint/react';
 import { useCallback, useEffect, useId, useRef, useState } from 'react';
@@ -481,18 +480,6 @@ function Main() {
 
   const paperId = useId();
 
-  usePaperEvents(
-    paperId,
-    {
-      onLinkMouseEnter: ({ view }) => view.addTools(toolsView),
-      onLinkMouseLeave: ({ view }) => view.removeTools(),
-      onElementPointerClick: ({ id }) => setSelectedElementId(id as CellId),
-      onLinkPointerClick: () => setSelectedElementId(null),
-      onBlankPointerClick: () => setSelectedElementId(null),
-    },
-    [setSelectedElementId]
-  );
-
   return (
     <div className="flex flex-col relative">
       <div className="flex flex-col relative">
@@ -531,6 +518,11 @@ function Main() {
           }}
           renderElement={renderElement}
           className={`${PAPER_CLASSNAME} h-[600px] bg-gray-900 shadow-md`}
+          onLinkMouseEnter={({ view }) => view.addTools(toolsView)}
+          onLinkMouseLeave={({ view }) => view.removeTools()}
+          onElementPointerClick={({ id }) => setSelectedElementId(id as CellId)}
+          onLinkPointerClick={() => setSelectedElementId(null)}
+          onBlankPointerClick={() => setSelectedElementId(null)}
         />
 
         {isMinimapVisible && <MiniMap />}
diff --git a/packages/joint-react/src/stories/demos/investment-calculator/code.tsx b/packages/joint-react/src/stories/demos/investment-calculator/code.tsx
index 6774484d22..e58dc907d4 100644
--- a/packages/joint-react/src/stories/demos/investment-calculator/code.tsx
+++ b/packages/joint-react/src/stories/demos/investment-calculator/code.tsx
@@ -686,7 +686,7 @@ function Main() {
   }, [graph]);
 
   return (
-    <Paper style={{ backgroundColor: '#0f172a', width: "100%", height: 800 }}
+    <Paper style={{ backgroundColor: '#0f172a', width: '100%', height: 800 }}
       ref={paperRef}
       className={PAPER_CLASSNAME}
       renderElement={RenderElement}
diff --git a/packages/joint-react/src/stories/demos/link-arrows/code.tsx b/packages/joint-react/src/stories/demos/link-arrows/code.tsx
index eaf3f68139..07318c2254 100644
--- a/packages/joint-react/src/stories/demos/link-arrows/code.tsx
+++ b/packages/joint-react/src/stories/demos/link-arrows/code.tsx
@@ -1,9 +1,10 @@
 /* eslint-disable react-perf/jsx-no-new-object-as-prop */
+/* eslint-disable react-perf/jsx-no-new-function-as-prop */
 
 import { useEffect, useState } from 'react';
 import { dia, util } from '@joint/core';
 import type { CellRecord, LinkRecord, LinkMarker } from '@joint/react';
-import { GraphProvider, Paper, usePaperEvents, usePaper, jsx } from '@joint/react';
+import { GraphProvider, Paper, usePaper, jsx } from '@joint/react';
 import { PAPER_CLASSNAME, BG } from 'storybook-config/theme';
 
 const BG_COLOR = BG;
@@ -482,23 +483,20 @@ function Main() {
     }
   }, [zoom, paper]);
 
-  usePaperEvents({
-    onLinkPointerDown: ({ model: link }) => {
-      setZoom((previous) => {
-        if (previous.type === 'link' && previous.link === link) {
-          return { type: 'arrow', link };
-        }
-        return { type: 'link', link };
-      });
-    },
-    onBlankPointerDown: () => setZoom({ type: 'overview' }),
-  });
-
   return (
-    <Paper style={{ background: BG_COLOR, width: "100%" }}
+    <Paper style={{ background: BG_COLOR, width: '100%' }}
       className={`${PAPER_CLASSNAME} h-150`}
       interactive={false}
       drawGrid={false}
+      onLinkPointerDown={({ model: link }) => {
+        setZoom((previous) => {
+          if (previous.type === 'link' && previous.link === link) {
+            return { type: 'arrow', link };
+          }
+          return { type: 'link', link };
+        });
+      }}
+      onBlankPointerDown={() => setZoom({ type: 'overview' })}
     />
   );
 }
diff --git a/packages/joint-react/src/stories/demos/pulsing-port/code.tsx b/packages/joint-react/src/stories/demos/pulsing-port/code.tsx
index 8d056b89fc..dce17974f2 100644
--- a/packages/joint-react/src/stories/demos/pulsing-port/code.tsx
+++ b/packages/joint-react/src/stories/demos/pulsing-port/code.tsx
@@ -7,7 +7,6 @@ import {
   GraphProvider,
   jsx,
   Paper,
-  usePaperEvents,
   useCells,
   useCellId,
   HTMLBox,
@@ -117,13 +116,10 @@ const toolsView = new dia.ToolsView({
 });
 
 function Main() {
-  usePaperEvents({
-    onLinkMouseEnter: ({ view }) => view.addTools(toolsView),
-    onLinkMouseLeave: ({ view }) => view.removeTools(),
-  });
-
   return (
-    <Paper style={{ width: "100%" }}
+    <Paper style={{ width: '100%' }}
+      onLinkMouseEnter={({ view }) => view.addTools(toolsView)}
+      onLinkMouseLeave={({ view }) => view.removeTools()}
       defaultLink={{
         style: { color: PRIMARY, targetMarker: 'arrow' },
       }}
diff --git a/packages/joint-react/src/stories/demos/saasflow/code.tsx b/packages/joint-react/src/stories/demos/saasflow/code.tsx
index 0bbeb2fccf..c0ab5d48b4 100644
--- a/packages/joint-react/src/stories/demos/saasflow/code.tsx
+++ b/packages/joint-react/src/stories/demos/saasflow/code.tsx
@@ -488,7 +488,7 @@ function Main() {
 
   return (
     <GraphProvider initialCells={initialCells}>
-      <Paper style={{ backgroundColor: 'transparent', width: "100%", height: "100%" }}
+      <Paper style={{ backgroundColor: 'transparent', width: '100%', height: '100%' }}
         ref={paperRef}
         gridSize={5}
         drawGrid={false}
diff --git a/packages/joint-react/src/stories/examples/markup-selectors-html/code.tsx b/packages/joint-react/src/stories/examples/markup-selectors-html/code.tsx
index affcf0a6da..e42f641c02 100644
--- a/packages/joint-react/src/stories/examples/markup-selectors-html/code.tsx
+++ b/packages/joint-react/src/stories/examples/markup-selectors-html/code.tsx
@@ -141,7 +141,7 @@ function Main() {
   }, []);
 
   return (
-    <Paper style={{ width: "100%", height: 280 }}
+    <Paper style={{ width: '100%', height: 280 }}
       renderElement={renderElement}
       magnetThreshold="onleave"
       linkPinning={false}
diff --git a/packages/joint-react/src/stories/examples/markup-selectors/code.tsx b/packages/joint-react/src/stories/examples/markup-selectors/code.tsx
index ac5e19e0a6..8f07539832 100644
--- a/packages/joint-react/src/stories/examples/markup-selectors/code.tsx
+++ b/packages/joint-react/src/stories/examples/markup-selectors/code.tsx
@@ -159,7 +159,7 @@ function Main() {
   }, []);
 
   return (
-    <Paper style={{ ...PAPER_STYLE, width: "100%", height: 250 }}
+    <Paper style={{ ...PAPER_STYLE, width: '100%', height: 250 }}
       className={PAPER_CLASSNAME}
       renderElement={renderElement}
       magnetThreshold={'onleave'}
diff --git a/packages/joint-react/src/stories/examples/stress/code.tsx b/packages/joint-react/src/stories/examples/stress/code.tsx
index d156e57051..20ccf3ba7f 100644
--- a/packages/joint-react/src/stories/examples/stress/code.tsx
+++ b/packages/joint-react/src/stories/examples/stress/code.tsx
@@ -1,4 +1,5 @@
 /* eslint-disable sonarjs/pseudo-random */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { HTMLBox, GraphProvider, Paper, type CellRecord, type ElementRecord, type LinkRecord } from '@joint/react';
 import '../index.css';
 import React, { useCallback, useState, startTransition } from 'react';
diff --git a/packages/joint-react/src/stories/examples/with-auto-layout/code.tsx b/packages/joint-react/src/stories/examples/with-auto-layout/code.tsx
index 24c5572c6b..107748a888 100644
--- a/packages/joint-react/src/stories/examples/with-auto-layout/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-auto-layout/code.tsx
@@ -2,6 +2,7 @@
 /* eslint-disable no-shadow */
 /* eslint-disable sonarjs/pseudo-random */
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import '../index.css';
 import {
   GraphProvider,
diff --git a/packages/joint-react/src/stories/examples/with-auto-size-origin/code.tsx b/packages/joint-react/src/stories/examples/with-auto-size-origin/code.tsx
index 3ae6e9f7e1..787d242945 100644
--- a/packages/joint-react/src/stories/examples/with-auto-size-origin/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-auto-size-origin/code.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 {
   type AutoSizeOrigin,
   type CellRecord,
@@ -108,7 +109,7 @@ export default function App() {
         <select
           id="autoSizeOriginToggle"
           value={origin}
-          onChange={(e) => setOrigin(e.target.value as AutoSizeOrigin)}
+          onChange={(event) => setOrigin(event.target.value as AutoSizeOrigin)}
         >
           <option value="top-left">top-left</option>
           <option value="center">center</option>
diff --git a/packages/joint-react/src/stories/examples/with-cell-json/code.tsx b/packages/joint-react/src/stories/examples/with-cell-json/code.tsx
index a6d1556e77..253e3c74f2 100644
--- a/packages/joint-react/src/stories/examples/with-cell-json/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-cell-json/code.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { PAPER_CLASSNAME, PRIMARY } from 'storybook-config/theme';
 import { shapes, dia } from '@joint/core';
 import '../index.css';
diff --git a/packages/joint-react/src/stories/examples/with-collapsible-container/code.tsx b/packages/joint-react/src/stories/examples/with-collapsible-container/code.tsx
index 8ef4304049..60add81ea4 100644
--- a/packages/joint-react/src/stories/examples/with-collapsible-container/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-collapsible-container/code.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 } from 'react';
 import { dia, elementTools } from '@joint/core';
 import {
@@ -9,7 +10,6 @@ import {
   useCell,
   useCellId,
   useGraph,
-  usePaperEvents,
   SVGText,
   selectElementSize,
 } from '@joint/react';
@@ -407,9 +407,12 @@ function Main() {
     }
   }, [graph]);
 
-  usePaperEvents(
-    {
-      onElementMouseEnter: ({ view }) => {
+  return (
+    <Paper style={{ backgroundColor: '#F3F7F6', height: 500 }}
+      className={PAPER_CLASSNAME}
+      renderElement={renderElement}
+      cellVisibility={cellVisibility}
+      onElementMouseEnter={({ view }) => {
         view.removeTools();
         view.addTools(
           new dia.ToolsView({
@@ -422,17 +425,8 @@ function Main() {
             ],
           })
         );
-      },
-      onElementMouseLeave: ({ view }) => view.removeTools(),
-    },
-    []
-  );
-
-  return (
-    <Paper style={{ backgroundColor: '#F3F7F6', height: 500 }}
-      className={PAPER_CLASSNAME}
-      renderElement={renderElement}
-      cellVisibility={cellVisibility}
+      }}
+      onElementMouseLeave={({ view }) => view.removeTools()}
     />
   );
 }
diff --git a/packages/joint-react/src/stories/examples/with-default-element/code.tsx b/packages/joint-react/src/stories/examples/with-default-element/code.tsx
index 8c87167439..b04bcb5a8d 100644
--- a/packages/joint-react/src/stories/examples/with-default-element/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-default-element/code.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { useState, useCallback, useMemo, useRef, memo } from 'react';
 import { type CellRecord, GraphProvider, Paper, HTMLBox, type LinkMarkerName } from '@joint/react';
 import { PAPER_CLASSNAME } from 'storybook-config/theme';
diff --git a/packages/joint-react/src/stories/examples/with-default-link/code.tsx b/packages/joint-react/src/stories/examples/with-default-link/code.tsx
index a61b638773..b1ef4b3885 100644
--- a/packages/joint-react/src/stories/examples/with-default-link/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-default-link/code.tsx
@@ -1,4 +1,4 @@
-
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 
 import { PAPER_CLASSNAME } from 'storybook-config/theme';
 import '../index.css';
diff --git a/packages/joint-react/src/stories/examples/with-dynamic-interactivity/code.tsx b/packages/joint-react/src/stories/examples/with-dynamic-interactivity/code.tsx
index 76ad94d85d..798a88c552 100644
--- a/packages/joint-react/src/stories/examples/with-dynamic-interactivity/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-dynamic-interactivity/code.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react-perf/jsx-no-new-function-as-prop */
 import { useCallback, useState } from 'react';
 import {
   type CellRecord,
@@ -5,9 +6,7 @@ import {
   Paper,
   useCells,
   useGraph,
-  usePaperEvents,
 } from '@joint/react';
-import { type dia } from '@joint/core';
 import { BUTTON_CLASSNAME, PAPER_CLASSNAME } from 'storybook-config/theme';
 
 import '../index.css';
@@ -30,45 +29,6 @@ const initialCells: ReadonlyArray<CellRecord<NodeData>> = [
   { id: 'b→c', type: 'link', source: { id: 'b' }, target: { id: 'c' }, style: { targetMarker: 'arrow' } },
 ];
 
-// ============================================================================
-// Controllers — different event wiring per mode
-// ============================================================================
-
-interface EditControllerProps {
-  readonly onSelect: (id: string | null) => void;
-}
-
-function EditController({ onSelect }: Readonly<EditControllerProps>) {
-  usePaperEvents(
-    {
-      onElementPointerClick: ({ id }) => onSelect(String(id)),
-      onBlankPointerClick: () => onSelect(null),
-    },
-    [onSelect]
-  );
-  return null;
-}
-
-function ViewController() {
-  const [hovered, setHovered] = useState<string | null>(null);
-  usePaperEvents(
-    {
-      onElementMouseEnter: ({ id, model }) => {
-        const data = model.attributes.data as NodeData | undefined;
-        setHovered(data?.label ?? String(id));
-      },
-      onElementMouseLeave: () => setHovered(null),
-    },
-    []
-  );
-  if (!hovered) return null;
-  return (
-    <div className="absolute top-2 right-2 px-3 py-1 rounded-md bg-white border border-gray-200 shadow-md text-xs font-medium text-gray-700 pointer-events-none">
-      Hovering: {hovered}
-    </div>
-  );
-}
-
 // ============================================================================
 // Property Editor — visible only in edit mode
 // ============================================================================
@@ -127,6 +87,7 @@ function PropertyEditor({ selectedId }: Readonly<PropertyEditorProps>) {
 function Main() {
   const [editMode, setEditMode] = useState(true);
   const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [hovered, setHovered] = useState<string | null>(null);
 
   const toggleMode = useCallback(() => {
     setEditMode((previous) => {
@@ -149,11 +110,25 @@ function Main() {
 
       <div className="flex">
         <div className="flex-1 relative">
-          <Paper className={PAPER_CLASSNAME + ' h-[300px]'} interactive={editMode} />
-          {editMode ? (
-            <EditController onSelect={setSelectedId} />
-          ) : (
-            <ViewController />
+          <Paper
+            className={PAPER_CLASSNAME + ' h-[300px]'}
+            interactive={editMode}
+            onElementPointerClick={editMode ? ({ id }) => setSelectedId(String(id)) : undefined}
+            onBlankPointerClick={editMode ? () => setSelectedId(null) : undefined}
+            onElementMouseEnter={
+              editMode
+                ? undefined
+                : ({ id, model }) => {
+                    const data = model.attributes.data as NodeData | undefined;
+                    setHovered(data?.label ?? String(id));
+                  }
+            }
+            onElementMouseLeave={editMode ? undefined : () => setHovered(null)}
+          />
+          {!editMode && hovered && (
+            <div className="absolute top-2 right-2 px-3 py-1 rounded-md bg-white border border-gray-200 shadow-md text-xs font-medium text-gray-700 pointer-events-none">
+              Hovering: {hovered}
+            </div>
           )}
         </div>
         {editMode && (
diff --git a/packages/joint-react/src/stories/examples/with-element-controls/code.tsx b/packages/joint-react/src/stories/examples/with-element-controls/code.tsx
index 4caa2125d0..efc0a18719 100644
--- a/packages/joint-react/src/stories/examples/with-element-controls/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-element-controls/code.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { type CellRecord, GraphProvider, useCell, Paper, useNodesMeasuredEffect, type ElementRecord, selectElementSize } from '@joint/react';
 import '../index.css';
 import { PAPER_CLASSNAME, PAPER_STYLE, PRIMARY, LIGHT, TEXT } from 'storybook-config/theme';
@@ -743,7 +744,7 @@ function Main() {
   useNodesMeasuredEffect(handleElementsMeasured);
 
   return (
-    <Paper style={{ ...PAPER_STYLE, width: "100%", height: 600 }}
+    <Paper style={{ ...PAPER_STYLE, width: '100%', height: 600 }}
       className={PAPER_CLASSNAME}
       renderElement={renderElement}
       drawGrid={false}
diff --git a/packages/joint-react/src/stories/examples/with-element-defaults/code.tsx b/packages/joint-react/src/stories/examples/with-element-defaults/code.tsx
index 32a41ce300..d006a92df6 100644
--- a/packages/joint-react/src/stories/examples/with-element-defaults/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-element-defaults/code.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import type {
   ElementRecord,
   LinkRecord} from '@joint/react';
diff --git a/packages/joint-react/src/stories/examples/with-element-ports-groups/code.tsx b/packages/joint-react/src/stories/examples/with-element-ports-groups/code.tsx
index 08f6a209fd..ce1ae306d0 100644
--- a/packages/joint-react/src/stories/examples/with-element-ports-groups/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-element-ports-groups/code.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { type CellRecord, GraphProvider, Paper, HTMLBox } from '@joint/react';
 import { elementPort } from '@joint/react/presets';
 import { PAPER_CLASSNAME, PRIMARY, SECONDARY } from 'storybook-config/theme';
diff --git a/packages/joint-react/src/stories/examples/with-fixed-connection-points/code.tsx b/packages/joint-react/src/stories/examples/with-fixed-connection-points/code.tsx
index 248e27a286..f7f1506eec 100644
--- a/packages/joint-react/src/stories/examples/with-fixed-connection-points/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-fixed-connection-points/code.tsx
@@ -2,7 +2,7 @@
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
 import { useEffect, useRef } from 'react';
 import type { CellRecord, LinkStyle } from '@joint/react';
-import { GraphProvider, useCell, jsx, Paper, resolveLinkMarker, usePaperEvents, selectElementSize } from '@joint/react';
+import { GraphProvider, useCell, jsx, Paper, resolveLinkMarker, selectElementSize } from '@joint/react';
 import { PAPER_CLASSNAME, PAPER_STYLE, BG, PRIMARY, TEXT, LIGHT } from 'storybook-config/theme';
 import { dia, elementTools, linkTools, highlighters, g } from '@joint/core';
 import { linkRoutingOrthogonal } from '@joint/react/presets';
@@ -364,42 +364,39 @@ function Main() {
     };
   }, []);
 
-  usePaperEvents({
-    onCellMouseEnter: ({ model, view, paper }) => {
-      paper.removeTools();
-
-      if (timeoutIdRef.current) {
-        clearTimeout(timeoutIdRef.current);
-        timeoutIdRef.current = null;
-      }
-
-      const tools = model.isLink()
-        ? getLinkTools(view as dia.LinkView)
-        : getElementTools(view as dia.ElementView);
-
-      const toolsView = new dia.ToolsView({ tools });
-      view.addTools(toolsView);
-      currentToolsViewRef.current = toolsView;
-    },
-    onCellMouseLeave: () => {
-      timeoutIdRef.current = setTimeout(() => {
-        currentToolsViewRef.current?.remove();
-        currentToolsViewRef.current = null;
-        timeoutIdRef.current = null;
-      }, 1000);
-
-      currentToolsViewRef.current?.el.classList.add(
-        'opacity-0',
-        'transition-opacity',
-        'duration-300',
-        'delay-300'
-      );
-    },
-    onElementPointerMove: ({ view }) => view.removeTools(),
-  });
-
   return (
-    <Paper style={{ ...PAPER_STYLE, width: "100%", height: 650 }}
+    <Paper style={{ ...PAPER_STYLE, width: '100%', height: 650 }}
+      onCellMouseEnter={({ model, view, paper }) => {
+        paper.removeTools();
+
+        if (timeoutIdRef.current) {
+          clearTimeout(timeoutIdRef.current);
+          timeoutIdRef.current = null;
+        }
+
+        const tools = model.isLink()
+          ? getLinkTools(view as dia.LinkView)
+          : getElementTools(view as dia.ElementView);
+
+        const toolsView = new dia.ToolsView({ tools });
+        view.addTools(toolsView);
+        currentToolsViewRef.current = toolsView;
+      }}
+      onCellMouseLeave={() => {
+        timeoutIdRef.current = setTimeout(() => {
+          currentToolsViewRef.current?.remove();
+          currentToolsViewRef.current = null;
+          timeoutIdRef.current = null;
+        }, 1000);
+
+        currentToolsViewRef.current?.el.classList.add(
+          'opacity-0',
+          'transition-opacity',
+          'duration-300',
+          'delay-300'
+        );
+      }}
+      onElementPointerMove={({ view }) => view.removeTools()}
       className={PAPER_CLASSNAME}
       renderElement={RenderElement}
       gridSize={20}
diff --git a/packages/joint-react/src/stories/examples/with-graph-neighbors/code.tsx b/packages/joint-react/src/stories/examples/with-graph-neighbors/code.tsx
index 6dbf2ecbf3..2caddc1b6b 100644
--- a/packages/joint-react/src/stories/examples/with-graph-neighbors/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-graph-neighbors/code.tsx
@@ -1,7 +1,8 @@
-
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
+/* eslint-disable react-perf/jsx-no-new-function-as-prop */
 
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { type CellRecord, GraphProvider, useCell, Paper, SVGText, useGraph, useMarkup, usePaperEvents, selectElementSize } from '@joint/react';
+import { type CellRecord, GraphProvider, useCell, Paper, SVGText, useGraph, useMarkup, selectElementSize } from '@joint/react';
 import { highlighters, type dia } from '@joint/core';
 import { LIGHT, PAPER_CLASSNAME, PAPER_STYLE, PRIMARY, SECONDARY } from 'storybook-config/theme';
 
@@ -179,9 +180,18 @@ function Main() {
     }
   }, [highlightState]);
 
-  usePaperEvents(
-    {
-      onElementPointerClick: ({ id }) => {
+  const renderElement = useCallback(
+    (data: NodeData) => <RenderNode {...data} />,
+    []
+  );
+
+  return (
+    <Paper style={{ ...PAPER_STYLE, width: '100%', height: 500 }}
+      ref={paperRef}
+      className={PAPER_CLASSNAME}
+      renderElement={renderElement}
+      drawGrid={false}
+      onElementPointerClick={({ id }) => {
         const clickedId = String(id);
         setHighlightState((previous) => {
           if (previous.selectedId === clickedId) {
@@ -202,23 +212,8 @@ function Main() {
             connectedLinkIds: nextConnectedLinkIds,
           };
         });
-      },
-      onBlankPointerClick: () => setHighlightState(INITIAL_STATE),
-    },
-    [graph]
-  );
-
-  const renderElement = useCallback(
-    (data: NodeData) => <RenderNode {...data} />,
-    []
-  );
-
-  return (
-    <Paper style={{ ...PAPER_STYLE, width: "100%", height: 500 }}
-      ref={paperRef}
-      className={PAPER_CLASSNAME}
-      renderElement={renderElement}
-      drawGrid={false}
+      }}
+      onBlankPointerClick={() => setHighlightState(INITIAL_STATE)}
     />
   );
 }
diff --git a/packages/joint-react/src/stories/examples/with-highlighter/code.tsx b/packages/joint-react/src/stories/examples/with-highlighter/code.tsx
index 78024f127d..a837c3efb4 100644
--- a/packages/joint-react/src/stories/examples/with-highlighter/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-highlighter/code.tsx
@@ -1,5 +1,6 @@
 /* eslint-disable react-perf/jsx-no-new-object-as-prop */
-import { type CellRecord, GraphProvider, useCell, Paper, useMarkup, usePaperEvents, selectElementSize } from '@joint/react';
+/* eslint-disable react-perf/jsx-no-new-function-as-prop */
+import { type CellRecord, GraphProvider, useCell, Paper, useMarkup, selectElementSize } from '@joint/react';
 import { type dia, highlighters } from '@joint/core';
 import '../index.css';
 import { useRef } from 'react';
@@ -99,20 +100,14 @@ function removeHighlighter(variant: HighlighterVariant, elementView: dia.Element
 function Main({ variant }: Readonly<MainProps>) {
   const paperRef = useRef<dia.Paper | null>(null);
 
-  usePaperEvents(
-    {
-      onElementMouseEnter: ({ view }) => addHighlighter(variant, view),
-      onElementMouseLeave: ({ view }) => removeHighlighter(variant, view),
-    },
-    [variant]
-  );
-
   return (
     <div style={{ display: 'flex', flexDirection: 'row' }}>
       <Paper style={{ height: 280 }}
         ref={paperRef}
         className={PAPER_CLASSNAME}
         renderElement={RenderElement}
+        onElementMouseEnter={({ view }) => addHighlighter(variant, view)}
+        onElementMouseLeave={({ view }) => removeHighlighter(variant, view)}
       />
     </div>
   );
diff --git a/packages/joint-react/src/stories/examples/with-link-labels/code.tsx b/packages/joint-react/src/stories/examples/with-link-labels/code.tsx
index 56e456e80b..6142c44d03 100644
--- a/packages/joint-react/src/stories/examples/with-link-labels/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-link-labels/code.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { type CellRecord, GraphProvider, Paper } from '@joint/react';
 import { LIGHT, PAPER_CLASSNAME, PRIMARY, SECONDARY } from 'storybook-config/theme';
 import '../index.css';
@@ -79,7 +80,7 @@ const initialCells: ReadonlyArray<CellRecord<ShapeData>> = [
 
 function Main() {
   return (
-    <Paper style={{ width: "100%", height: 350 }}
+    <Paper style={{ width: '100%', height: 350 }}
       className={PAPER_CLASSNAME}
       interactive={INTERACTIVE_OPTIONS}
     />
diff --git a/packages/joint-react/src/stories/examples/with-link-markers-named/code.tsx b/packages/joint-react/src/stories/examples/with-link-markers-named/code.tsx
index c2cc3c9ccc..e426ba6731 100644
--- a/packages/joint-react/src/stories/examples/with-link-markers-named/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-link-markers-named/code.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import type { CellRecord, LinkRecord } from '@joint/react';
 import { GraphProvider, Paper } from '@joint/react';
 import { PAPER_CLASSNAME } from 'storybook-config/theme';
@@ -51,7 +52,7 @@ const initialCells = buildCells();
 export default function App() {
   return (
     <GraphProvider initialCells={initialCells}>
-      <Paper style={{ width: "100%" }}
+      <Paper style={{ width: '100%' }}
         transform={'scale(2)'}
         className={`${PAPER_CLASSNAME} h-[800px]`}
         interactive={false}
diff --git a/packages/joint-react/src/stories/examples/with-link-markers/code.tsx b/packages/joint-react/src/stories/examples/with-link-markers/code.tsx
index e7154692ae..86b905f260 100644
--- a/packages/joint-react/src/stories/examples/with-link-markers/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-link-markers/code.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { useCallback, useMemo, useState, type ChangeEvent } from 'react';
 import type { CellRecord, ElementPort, ElementRecord, LinkRecord } from '@joint/react';
 import { GraphProvider, Paper, HTMLBox } from '@joint/react';
diff --git a/packages/joint-react/src/stories/examples/with-link-routing/code.tsx b/packages/joint-react/src/stories/examples/with-link-routing/code.tsx
index 9b6bfc62ad..5be0ce83bb 100644
--- a/packages/joint-react/src/stories/examples/with-link-routing/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-link-routing/code.tsx
@@ -1,4 +1,5 @@
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { useEffect, useMemo, useState } from 'react';
 import { type CellRecord, GraphProvider, useCell, Paper, HTMLBox, useMarkup, type ElementPort, type LinkRecord, usePaper, selectElementSize } from '@joint/react';
 import { linkRoutingStraight, linkRoutingOrthogonal, linkRoutingSmooth, type LinkRoutingStraightOptions, type LinkRoutingOrthogonalOptions, type LinkRoutingSmoothOptions, type LinkMode } from '@joint/react/presets';
diff --git a/packages/joint-react/src/stories/examples/with-link-tools/code.tsx b/packages/joint-react/src/stories/examples/with-link-tools/code.tsx
index 3d4b683175..e8988d5417 100644
--- a/packages/joint-react/src/stories/examples/with-link-tools/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-link-tools/code.tsx
@@ -1,7 +1,8 @@
 /* eslint-disable react-perf/jsx-no-new-object-as-prop */
+/* eslint-disable react-perf/jsx-no-new-function-as-prop */
 import { dia, linkTools } from '@joint/core';
 import '../index.css';
-import { type CellRecord, GraphProvider, jsx, Paper, usePaperEvents } from '@joint/react';
+import { type CellRecord, GraphProvider, jsx, Paper } from '@joint/react';
 import { PRIMARY, SECONDARY, PAPER_CLASSNAME } from 'storybook-config/theme';
 import { linkRoutingOrthogonal } from '@joint/react/presets';
 
@@ -92,16 +93,13 @@ const toolsView = new dia.ToolsView({
 });
 
 function Main() {
-  usePaperEvents({
-    onLinkMouseEnter: ({ view }) => view.addTools(toolsView),
-    onLinkMouseLeave: ({ view }) => view.removeTools(),
-  });
-
   return (
     <div style={{ display: 'flex', flexDirection: 'row', position: 'relative' }}>
       <Paper style={{ height: 280 }}
         className={PAPER_CLASSNAME}
         linkRouting={ORTHOGONAL_LINKS}
+        onLinkMouseEnter={({ view }) => view.addTools(toolsView)}
+        onLinkMouseLeave={({ view }) => view.removeTools()}
       />
       <div
         style={{
diff --git a/packages/joint-react/src/stories/examples/with-list-node/code.tsx b/packages/joint-react/src/stories/examples/with-list-node/code.tsx
index 85d98b3b19..aaebaf8ec0 100644
--- a/packages/joint-react/src/stories/examples/with-list-node/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-list-node/code.tsx
@@ -1,5 +1,6 @@
 /* eslint-disable @eslint-react/no-array-index-key */
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 
 import '../index.css';
 import { useCallback, useRef, type PropsWithChildren } from 'react';
diff --git a/packages/joint-react/src/stories/examples/with-minimap/code.tsx b/packages/joint-react/src/stories/examples/with-minimap/code.tsx
index 49b651ebfa..c67b1afa58 100644
--- a/packages/joint-react/src/stories/examples/with-minimap/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-minimap/code.tsx
@@ -47,7 +47,7 @@ function MiniMap() {
 
   return (
     <div className="absolute bottom-4 right-6 w-[200px] h-[150px] border border-[#dde6ed] rounded-lg overflow-hidden">
-      <Paper style={{ height: "100%" }}
+      <Paper style={{ height: '100%' }}
         id="minimap"
         interactive={false}
         transform={'scale(0.4)'}
diff --git a/packages/joint-react/src/stories/examples/with-native-ports/code.tsx b/packages/joint-react/src/stories/examples/with-native-ports/code.tsx
index f51caa580d..5d18ea52dd 100644
--- a/packages/joint-react/src/stories/examples/with-native-ports/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-native-ports/code.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { PAPER_CLASSNAME, PAPER_STYLE } from 'storybook-config/theme';
 import type { dia } from '@joint/core';
 import '../index.css';
diff --git a/packages/joint-react/src/stories/examples/with-portal-selector/code.tsx b/packages/joint-react/src/stories/examples/with-portal-selector/code.tsx
index 722e5602d1..54dbd14902 100644
--- a/packages/joint-react/src/stories/examples/with-portal-selector/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-portal-selector/code.tsx
@@ -11,7 +11,6 @@ import {
   useGraph,
   useMeasureNode,
   usePaper,
-  usePaperEvents,
   ELEMENT_MODEL_TYPE,
   type CellId,
   type PaperProps,
@@ -191,7 +190,7 @@ function MiniMap({ paper }: Readonly<{ paper: dia.Paper }>) {
       className="absolute bg-black bottom-6 right-6 border border-[#dde6ed] rounded-lg overflow-hidden"
       style={{ width: MINIMAP_WIDTH, height: MINIMAP_HEIGHT }}
     >
-      <Paper style={{ backgroundColor: LIGHT, height: "100%" }}
+      <Paper style={{ backgroundColor: LIGHT, height: '100%' }}
         {...PAPER_PROPS}
         interactive={false}
         transform={`scale(${scale})`}
@@ -288,20 +287,9 @@ function Main() {
   // Subscribe to cells so the story reflects graph size in devtools if needed.
   useCells();
 
-  usePaperEvents(
-    {
-      onElementPointerClick: ({ id }) => setSelectedElement(id),
-      onElementPointerDblClick: ({ model, graph }) => {
-        model.clone().translate(10, 10).addTo(graph);
-      },
-      onBlankPointerClick: () => setSelectedElement(null),
-    },
-    [setSelectedElement]
-  );
-
   return (
     <div className="flex flex-col relative w-full h-full">
-      <Paper style={{ ...PAPER_STYLE, height: "calc(100vh - 100px)" }}
+      <Paper style={{ ...PAPER_STYLE, height: 'calc(100vh - 100px)' }}
         {...PAPER_PROPS}
         ref={setPaper}
         className={PAPER_CLASSNAME}
@@ -313,6 +301,11 @@ function Main() {
           // implicit: use the default selector for ElementModel cells
         }}
         drawGrid={false}
+        onElementPointerClick={({ id }) => setSelectedElement(id)}
+        onElementPointerDblClick={({ model, graph }) => {
+          model.clone().translate(10, 10).addTo(graph);
+        }}
+        onBlankPointerClick={() => setSelectedElement(null)}
       >
         <Selection selectedId={selectedElement} />
       </Paper>
diff --git a/packages/joint-react/src/stories/examples/with-shape-animations/code.tsx b/packages/joint-react/src/stories/examples/with-shape-animations/code.tsx
index bad413698e..22ff94098b 100644
--- a/packages/joint-react/src/stories/examples/with-shape-animations/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-shape-animations/code.tsx
@@ -420,7 +420,7 @@ function PowerControl() {
 function Main() {
   return (
     <div style={{ display: 'flex', flexDirection: 'column' }}>
-      <Paper style={{ width: "100%", height: 500 }}
+      <Paper style={{ width: '100%', height: 500 }}
         className={PAPER_CLASSNAME}
         renderElement={RenderShapeElement}
         transform={'scale(3)'}
diff --git a/packages/joint-react/src/stories/examples/with-tailwind-theme/code.tsx b/packages/joint-react/src/stories/examples/with-tailwind-theme/code.tsx
index 77f4f25091..3952769d82 100644
--- a/packages/joint-react/src/stories/examples/with-tailwind-theme/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-tailwind-theme/code.tsx
@@ -1,4 +1,5 @@
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 
 import { useState, useCallback, useRef } from 'react';
 import { type CellRecord, GraphProvider, Paper, selectElementSize, useCell } from '@joint/react';
diff --git a/packages/joint-react/src/stories/examples/with-theme-editor/code.tsx b/packages/joint-react/src/stories/examples/with-theme-editor/code.tsx
index 2ecdda3d3d..494f76387a 100644
--- a/packages/joint-react/src/stories/examples/with-theme-editor/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-theme-editor/code.tsx
@@ -9,7 +9,6 @@ import {
   Paper,
   HTMLBox,
   type LinkMarkerName,
-  usePaperEvents,
   useGraph,
 } from '@joint/react';
 import { PAPER_CLASSNAME } from 'storybook-config/theme';
@@ -464,50 +463,6 @@ interface DiagramProps {
 function Diagram({ zoom }: Readonly<DiagramProps>) {
   const { setCell } = useGraph<CellRecord<Data>>();
 
-  usePaperEvents({
-    'blank:pointerdblclick': (_event, x, y) => {
-      setCell({
-        id: `node-${Date.now()}`,
-        type: 'element',
-        data: { label: 'New Node' },
-        position: { x, y },
-        portMap: { in: PORT_IN, out: PORT_OUT },
-        z: 2,
-      });
-    },
-    'link:contextmenu': (linkView, event_, _x, _y) => {
-      const labelNode = (event_.target as Element | null)?.closest('[label-idx]');
-      if (!labelNode) return;
-      const labelIndex = Number.parseInt(labelNode.getAttribute('label-idx') ?? '', 10);
-      if (Number.isNaN(labelIndex)) return;
-      event_.preventDefault();
-      setCell(String(linkView.model.id), (previous) => {
-        const rawLabelMap = (previous as { labelMap?: Record<string, unknown> }).labelMap;
-        if (!rawLabelMap) return previous;
-        const keys = Object.keys(rawLabelMap);
-        if (labelIndex >= keys.length) return previous;
-        const labelKey = keys[labelIndex];
-        const labelMap = Object.fromEntries(
-          Object.entries(rawLabelMap).filter(([key]) => key !== labelKey)
-        );
-        return { ...previous, labelMap } as CellRecord<Data>;
-      });
-    },
-    'link:pointerdblclick': (linkView, _event, x, y) => {
-      const totalLength = linkView.getConnectionLength();
-      const closestLength = linkView.getClosestPointLength({ x, y });
-      const position = totalLength > 0 ? closestLength / totalLength : 0.5;
-      const labelKey = `label-${Date.now()}`;
-      setCell(String(linkView.model.id), (previous) => {
-        const linkRecord = previous as CellRecord<Data> & { labelMap?: Record<string, unknown> };
-        return {
-          ...linkRecord,
-          labelMap: { ...linkRecord.labelMap, [labelKey]: { position, text: 'New Label' } },
-        };
-      });
-    },
-  });
-
   return (
     <Paper
       className={PAPER_CLASSNAME}
@@ -518,6 +473,47 @@ function Diagram({ zoom }: Readonly<DiagramProps>) {
       embeddingMode
       validateEmbedding={validateEmbedding}
       transform={`scale(${zoom})`}
+      onBlankPointerDblClick={({ x, y }) => {
+        setCell({
+          id: `node-${Date.now()}`,
+          type: 'element',
+          data: { label: 'New Node' },
+          position: { x, y },
+          portMap: { in: PORT_IN, out: PORT_OUT },
+          z: 2,
+        });
+      }}
+      onLinkContextMenu={({ view, event }) => {
+        const labelNode = (event.target as Element | null)?.closest('[label-idx]');
+        if (!labelNode) return;
+        const labelIndex = Number.parseInt(labelNode.getAttribute('label-idx') ?? '', 10);
+        if (Number.isNaN(labelIndex)) return;
+        event.preventDefault();
+        setCell(String(view.model.id), (previous) => {
+          const rawLabelMap = (previous as { labelMap?: Record<string, unknown> }).labelMap;
+          if (!rawLabelMap) return previous;
+          const keys = Object.keys(rawLabelMap);
+          if (labelIndex >= keys.length) return previous;
+          const labelKey = keys[labelIndex];
+          const labelMap = Object.fromEntries(
+            Object.entries(rawLabelMap).filter(([key]) => key !== labelKey)
+          );
+          return { ...previous, labelMap } as CellRecord<Data>;
+        });
+      }}
+      onLinkPointerDblClick={({ view, x, y }) => {
+        const totalLength = view.getConnectionLength();
+        const closestLength = view.getClosestPointLength({ x, y });
+        const position = totalLength > 0 ? closestLength / totalLength : 0.5;
+        const labelKey = `label-${Date.now()}`;
+        setCell(String(view.model.id), (previous) => {
+          const linkRecord = previous as CellRecord<Data> & { labelMap?: Record<string, unknown> };
+          return {
+            ...linkRecord,
+            labelMap: { ...linkRecord.labelMap, [labelKey]: { position, text: 'New Label' } },
+          };
+        });
+      }}
     />
   );
 }
diff --git a/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode-jotai.tsx b/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode-jotai.tsx
index 7f7f6328b2..a0480047ea 100644
--- a/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode-jotai.tsx
+++ b/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode-jotai.tsx
@@ -1,5 +1,6 @@
 /* eslint-disable sonarjs/pseudo-random */
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 
 /**
  * ============================================================================
diff --git a/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode-peerjs.tsx b/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode-peerjs.tsx
index 4fc3d62979..752a4087fe 100644
--- a/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode-peerjs.tsx
+++ b/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode-peerjs.tsx
@@ -1,5 +1,6 @@
 /* eslint-disable sonarjs/pseudo-random */
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 
 /**
  * ============================================================================
diff --git a/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode-redux.tsx b/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode-redux.tsx
index 344bc107ae..865c5d61aa 100644
--- a/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode-redux.tsx
+++ b/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode-redux.tsx
@@ -1,6 +1,7 @@
 /* eslint-disable @eslint-react/hooks-extra/no-direct-set-state-in-use-effect */
 /* eslint-disable sonarjs/pseudo-random */
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 
 import {
   GraphProvider,
diff --git a/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode-zustand.tsx b/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode-zustand.tsx
index 43d3a2848a..6020ad9dc0 100644
--- a/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode-zustand.tsx
+++ b/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode-zustand.tsx
@@ -1,5 +1,6 @@
 /* eslint-disable sonarjs/pseudo-random */
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 
 /**
  * ============================================================================
diff --git a/packages/joint-react/src/stories/tutorials/step-by-step/code-html-renderer.tsx b/packages/joint-react/src/stories/tutorials/step-by-step/code-html-renderer.tsx
index 5fc780afa4..7c868a7753 100644
--- a/packages/joint-react/src/stories/tutorials/step-by-step/code-html-renderer.tsx
+++ b/packages/joint-react/src/stories/tutorials/step-by-step/code-html-renderer.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { useCallback, useRef, useState } from 'react';
 import {
   type CellRecord,
diff --git a/packages/joint-react/src/utils/joint-jsx/jsx-to-markup.stories.tsx b/packages/joint-react/src/utils/joint-jsx/jsx-to-markup.stories.tsx
index 129ad5c5b8..6c08432a7b 100644
--- a/packages/joint-react/src/utils/joint-jsx/jsx-to-markup.stories.tsx
+++ b/packages/joint-react/src/utils/joint-jsx/jsx-to-markup.stories.tsx
@@ -1,4 +1,4 @@
- 
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { useMemo } from 'react';
 import { dia } from '@joint/core';
 import '../../stories/examples/index.css';
diff --git a/packages/joint-react/src/utils/test-wrappers.tsx b/packages/joint-react/src/utils/test-wrappers.tsx
index 2ff83b10aa..d8d4fd446b 100644
--- a/packages/joint-react/src/utils/test-wrappers.tsx
+++ b/packages/joint-react/src/utils/test-wrappers.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { useCallback } from 'react';
 import { GraphProvider, Paper, type GraphProviderProps, type PaperProps } from '../components';
 import { dia } from '@joint/core';

From 9493a94cb5aa34017b49ee5bbb37b4e14a7b2575 Mon Sep 17 00:00:00 2001
From: samuelgja <samuel.gjabel@gmail.com>
Date: Tue, 2 Jun 2026 17:51:23 +0700
Subject: [PATCH 2/2] Refactor code structure for improved readability and
 maintainability; removed redundant code blocks and optimized function calls.

---
 package.json                                  |    5 +
 .../decorators/with-strict-mode.tsx           |   14 +-
 packages/joint-react/CHANGELOG.md             |    6 +
 packages/joint-react/__mocks__/jest-setup.ts  |    5 +
 packages/joint-react/examples/build.ts        |   25 +
 .../joint-react/examples/bun-environment.d.ts |   19 +
 packages/joint-react/jest.config.js           |    3 +
 packages/joint-react/package.json             |   28 +-
 packages/joint-react/rollup.config.ts         |   11 +-
 .../src/__tests__/ssr-client-handoff.test.tsx |   84 ++
 .../src/__tests__/ssr-paper-handoff.test.tsx  |   93 ++
 .../joint-react/src/__tests__/ssr.test.tsx    |   86 ++
 .../src/components/graph/graph-provider.tsx   |   40 +-
 .../paper/default-render-element.tsx          |   15 +
 .../src/components/paper/paper.tsx            |   25 +-
 .../src/components/paper/paper.types.ts       |    4 +-
 .../render-element/paper-html-container.tsx   |   11 +-
 .../src/hooks/use-are-elements-measured.ts    |    4 +-
 .../src/hooks/use-create-portal-paper.tsx     |   25 +-
 .../src/hooks/use-isomorphic-layout-effect.ts |   13 +
 .../src/hooks/use-server-paper-tree.ts        |   86 ++
 .../src/server/__tests__/react-ssr.test.tsx   |  214 ++++
 .../server/__tests__/ssr-elements.test.tsx    |  134 +++
 .../src/server/__tests__/ssr-links.test.tsx   |  145 +++
 .../src/server/__tests__/text-style.test.ts   |   86 ++
 packages/joint-react/src/server/index.ts      |   35 +
 .../src/server/render/build-paper-tree.tsx    |   31 +
 .../src/server/render/build-paper.tsx         |  212 ++++
 .../src/server/render/dom-to-react.tsx        |  187 +++
 packages/joint-react/src/server/text-style.ts |  161 +++
 .../__tests__/update-layout-state.test.ts     |    5 +-
 .../store/create-elements-size-observer.ts    |   22 +-
 .../src/stories/demos/flowchart/code.tsx      |   31 +-
 .../src/utils/__tests__/is.test.ts            |    2 +
 .../src/utils/server-paper-renderer.ts        |   91 ++
 packages/joint-react/src/utils/ssr.ts         |   25 +
 packages/joint-svg-shim/.gitignore            |   20 +
 packages/joint-svg-shim/LICENSE               |  376 ++++++
 packages/joint-svg-shim/README.md             |  166 +++
 packages/joint-svg-shim/eslint.config.mjs     |   14 +
 .../examples/core-static/.gitignore           |    3 +
 .../examples/core-static/README.md            |   39 +
 .../examples/core-static/package.json         |   23 +
 .../examples/core-static/src/diagram.ts       |  256 +++++
 .../examples/core-static/src/server.ts        |  161 +++
 .../examples/core-static/tsconfig.json        |   21 +
 .../examples/react-ssr/.gitignore             |    3 +
 .../examples/react-ssr/README.md              |   61 +
 .../examples/react-ssr/index.html             |   16 +
 .../examples/react-ssr/package.json           |   33 +
 .../examples/react-ssr/server.ts              |   81 ++
 .../examples/react-ssr/src/diagram.tsx        |  185 +++
 .../examples/react-ssr/src/entry-client.tsx   |   19 +
 .../examples/react-ssr/src/entry-server.tsx   |   18 +
 .../examples/react-ssr/src/page.tsx           |   53 +
 .../examples/react-ssr/src/styles.css         |   37 +
 .../examples/react-ssr/tsconfig.json          |   22 +
 .../examples/react-ssr/vite.config.ts         |   19 +
 packages/joint-svg-shim/jest.config.js        |   22 +
 packages/joint-svg-shim/package.json          |  105 ++
 packages/joint-svg-shim/rollup.config.ts      |    9 +
 .../scripts/create-rollup-config.ts           |   68 ++
 .../src/__tests__/happy-dom-provider.test.ts  |   44 +
 .../src/__tests__/install-dom-shim.test.ts    |  118 ++
 .../src/__tests__/svg-matrix.test.ts          |  150 +++
 .../src/__tests__/svg-polyfills.test.ts       |  191 ++++
 .../src/__tests__/text-metrics.test.ts        |   58 +
 packages/joint-svg-shim/src/dom-shim-flag.ts  |    8 +
 packages/joint-svg-shim/src/index.ts          |   35 +
 .../joint-svg-shim/src/install-dom-shim.ts    |  218 ++++
 packages/joint-svg-shim/src/install.ts        |   12 +
 packages/joint-svg-shim/src/node-require.ts   |   19 +
 .../joint-svg-shim/src/svg-element-proxies.ts |  178 +++
 packages/joint-svg-shim/src/svg-matrix.ts     |  226 ++++
 packages/joint-svg-shim/src/svg-polyfills.ts  |  134 +++
 packages/joint-svg-shim/src/svg-prototype.ts  |   32 +
 packages/joint-svg-shim/src/svg-text-bbox.ts  |  143 +++
 packages/joint-svg-shim/src/text-metrics.ts   |  116 ++
 .../joint-svg-shim/src/text-style-resolver.ts |   43 +
 packages/joint-svg-shim/tsconfig.json         |   23 +
 packages/joint-svg-shim/tsconfig.types.json   |   11 +
 yarn.lock                                     | 1011 +++++++++++++++--
 82 files changed, 6407 insertions(+), 176 deletions(-)
 create mode 100644 packages/joint-react/CHANGELOG.md
 create mode 100644 packages/joint-react/examples/build.ts
 create mode 100644 packages/joint-react/examples/bun-environment.d.ts
 create mode 100644 packages/joint-react/src/__tests__/ssr-client-handoff.test.tsx
 create mode 100644 packages/joint-react/src/__tests__/ssr-paper-handoff.test.tsx
 create mode 100644 packages/joint-react/src/__tests__/ssr.test.tsx
 create mode 100644 packages/joint-react/src/components/paper/default-render-element.tsx
 create mode 100644 packages/joint-react/src/hooks/use-isomorphic-layout-effect.ts
 create mode 100644 packages/joint-react/src/hooks/use-server-paper-tree.ts
 create mode 100644 packages/joint-react/src/server/__tests__/react-ssr.test.tsx
 create mode 100644 packages/joint-react/src/server/__tests__/ssr-elements.test.tsx
 create mode 100644 packages/joint-react/src/server/__tests__/ssr-links.test.tsx
 create mode 100644 packages/joint-react/src/server/__tests__/text-style.test.ts
 create mode 100644 packages/joint-react/src/server/index.ts
 create mode 100644 packages/joint-react/src/server/render/build-paper-tree.tsx
 create mode 100644 packages/joint-react/src/server/render/build-paper.tsx
 create mode 100644 packages/joint-react/src/server/render/dom-to-react.tsx
 create mode 100644 packages/joint-react/src/server/text-style.ts
 create mode 100644 packages/joint-react/src/utils/server-paper-renderer.ts
 create mode 100644 packages/joint-react/src/utils/ssr.ts
 create mode 100644 packages/joint-svg-shim/.gitignore
 create mode 100644 packages/joint-svg-shim/LICENSE
 create mode 100644 packages/joint-svg-shim/README.md
 create mode 100644 packages/joint-svg-shim/eslint.config.mjs
 create mode 100644 packages/joint-svg-shim/examples/core-static/.gitignore
 create mode 100644 packages/joint-svg-shim/examples/core-static/README.md
 create mode 100644 packages/joint-svg-shim/examples/core-static/package.json
 create mode 100644 packages/joint-svg-shim/examples/core-static/src/diagram.ts
 create mode 100644 packages/joint-svg-shim/examples/core-static/src/server.ts
 create mode 100644 packages/joint-svg-shim/examples/core-static/tsconfig.json
 create mode 100644 packages/joint-svg-shim/examples/react-ssr/.gitignore
 create mode 100644 packages/joint-svg-shim/examples/react-ssr/README.md
 create mode 100644 packages/joint-svg-shim/examples/react-ssr/index.html
 create mode 100644 packages/joint-svg-shim/examples/react-ssr/package.json
 create mode 100644 packages/joint-svg-shim/examples/react-ssr/server.ts
 create mode 100644 packages/joint-svg-shim/examples/react-ssr/src/diagram.tsx
 create mode 100644 packages/joint-svg-shim/examples/react-ssr/src/entry-client.tsx
 create mode 100644 packages/joint-svg-shim/examples/react-ssr/src/entry-server.tsx
 create mode 100644 packages/joint-svg-shim/examples/react-ssr/src/page.tsx
 create mode 100644 packages/joint-svg-shim/examples/react-ssr/src/styles.css
 create mode 100644 packages/joint-svg-shim/examples/react-ssr/tsconfig.json
 create mode 100644 packages/joint-svg-shim/examples/react-ssr/vite.config.ts
 create mode 100644 packages/joint-svg-shim/jest.config.js
 create mode 100644 packages/joint-svg-shim/package.json
 create mode 100644 packages/joint-svg-shim/rollup.config.ts
 create mode 100644 packages/joint-svg-shim/scripts/create-rollup-config.ts
 create mode 100644 packages/joint-svg-shim/src/__tests__/happy-dom-provider.test.ts
 create mode 100644 packages/joint-svg-shim/src/__tests__/install-dom-shim.test.ts
 create mode 100644 packages/joint-svg-shim/src/__tests__/svg-matrix.test.ts
 create mode 100644 packages/joint-svg-shim/src/__tests__/svg-polyfills.test.ts
 create mode 100644 packages/joint-svg-shim/src/__tests__/text-metrics.test.ts
 create mode 100644 packages/joint-svg-shim/src/dom-shim-flag.ts
 create mode 100644 packages/joint-svg-shim/src/index.ts
 create mode 100644 packages/joint-svg-shim/src/install-dom-shim.ts
 create mode 100644 packages/joint-svg-shim/src/install.ts
 create mode 100644 packages/joint-svg-shim/src/node-require.ts
 create mode 100644 packages/joint-svg-shim/src/svg-element-proxies.ts
 create mode 100644 packages/joint-svg-shim/src/svg-matrix.ts
 create mode 100644 packages/joint-svg-shim/src/svg-polyfills.ts
 create mode 100644 packages/joint-svg-shim/src/svg-prototype.ts
 create mode 100644 packages/joint-svg-shim/src/svg-text-bbox.ts
 create mode 100644 packages/joint-svg-shim/src/text-metrics.ts
 create mode 100644 packages/joint-svg-shim/src/text-style-resolver.ts
 create mode 100644 packages/joint-svg-shim/tsconfig.json
 create mode 100644 packages/joint-svg-shim/tsconfig.types.json

diff --git a/package.json b/package.json
index 714a6123fd..ceedeb7ecd 100644
--- a/package.json
+++ b/package.json
@@ -28,6 +28,7 @@
   },
   "workspaces": [
     "./packages/*",
+    "./packages/joint-svg-shim/examples/*",
     "./examples/*"
   ],
   "volta": {
@@ -35,5 +36,9 @@
     "npm": "11.2.0",
     "yarn": "4.7.0"
   },
+  "resolutions": {
+    "react": "19.2.5",
+    "react-dom": "19.2.5"
+  },
   "packageManager": "yarn@4.7.0"
 }
diff --git a/packages/joint-react/.storybook/decorators/with-strict-mode.tsx b/packages/joint-react/.storybook/decorators/with-strict-mode.tsx
index e3f4b719d1..6bdbde9704 100644
--- a/packages/joint-react/.storybook/decorators/with-strict-mode.tsx
+++ b/packages/joint-react/.storybook/decorators/with-strict-mode.tsx
@@ -1,4 +1,16 @@
+import { StrictMode } from 'react';
+
+/**
+ * Wraps a story in `React.StrictMode` so double-invoked renders / effects and
+ * cleanup regressions surface during development (especially on React 19).
+ * @param Story - The story component to render.
+ * @returns The story wrapped in `StrictMode`.
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function withStrictMode(Story: any) {
-  return <Story />;
+  return (
+    <StrictMode>
+      <Story />
+    </StrictMode>
+  );
 }
diff --git a/packages/joint-react/CHANGELOG.md b/packages/joint-react/CHANGELOG.md
new file mode 100644
index 0000000000..d6cfe59357
--- /dev/null
+++ b/packages/joint-react/CHANGELOG.md
@@ -0,0 +1,6 @@
+# Changelog
+
+All notable changes to `@joint/react` are documented here. The format is based
+on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
diff --git a/packages/joint-react/__mocks__/jest-setup.ts b/packages/joint-react/__mocks__/jest-setup.ts
index 29102e11ef..c19a939925 100644
--- a/packages/joint-react/__mocks__/jest-setup.ts
+++ b/packages/joint-react/__mocks__/jest-setup.ts
@@ -46,6 +46,11 @@ Object.defineProperty(globalThis, 'SVGAngle', {
 });
 
 beforeEach(() => {
+  // Node (SSR) test environments have no DOM — skip the browser API mocks so
+  // server-rendering tests (`@jest-environment node`) can run with this setup.
+  if (globalThis.SVGSVGElement === undefined) {
+    return;
+  }
   /**
    * @see https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver
    */
diff --git a/packages/joint-react/examples/build.ts b/packages/joint-react/examples/build.ts
new file mode 100644
index 0000000000..cbc583ec72
--- /dev/null
+++ b/packages/joint-react/examples/build.ts
@@ -0,0 +1,25 @@
+/* eslint-disable no-console -- build script logs bundle output to stdout */
+import tailwind from 'bun-plugin-tailwind';
+import { rm } from 'node:fs/promises';
+import path from 'node:path';
+
+const outdir = path.join(process.cwd(), 'dist');
+await rm(outdir, { recursive: true, force: true });
+
+const entrypoints = [...new Bun.Glob('src/**/*.html').scanSync()];
+
+const result = await Bun.build({
+  entrypoints,
+  outdir,
+  plugins: [tailwind],
+  minify: true,
+  target: 'browser',
+  sourcemap: 'linked',
+  define: {
+    'process.env.NODE_ENV': JSON.stringify('production'),
+  },
+});
+
+for (const output of result.outputs) {
+  console.log(` ${path.relative(process.cwd(), output.path)}  ${(output.size / 1024).toFixed(1)} KB`);
+}
diff --git a/packages/joint-react/examples/bun-environment.d.ts b/packages/joint-react/examples/bun-environment.d.ts
new file mode 100644
index 0000000000..94c9f93a62
--- /dev/null
+++ b/packages/joint-react/examples/bun-environment.d.ts
@@ -0,0 +1,19 @@
+// Generated by `bun init`
+
+declare module '*.svg' {
+  /**
+   * A path to the SVG file
+   */
+  const path: `${string}.svg`;
+  export = path;
+}
+
+declare module '*.css' {}
+
+declare module '*.module.css' {
+  /**
+   * A record of class names to their corresponding CSS module classes
+   */
+  const classes: { readonly [key: string]: string };
+  export = classes;
+}
diff --git a/packages/joint-react/jest.config.js b/packages/joint-react/jest.config.js
index 90a71fd35e..3434844eee 100644
--- a/packages/joint-react/jest.config.js
+++ b/packages/joint-react/jest.config.js
@@ -28,6 +28,9 @@ export default {
   ],
   moduleNameMapper: {
     '^.+\\.css$': '<rootDir>/__mocks__/style-mock.ts', // Mock CSS files
+    '^@joint/svg-shim/install$': '<rootDir>/../joint-svg-shim/src/install.ts',
+    '^@joint/svg-shim/flag$': '<rootDir>/../joint-svg-shim/src/dom-shim-flag.ts',
+    '^@joint/svg-shim$': '<rootDir>/../joint-svg-shim/src/index.ts',
     '^@joint/react$': '<rootDir>/src/index.ts',
     '^src/(.*)$': '<rootDir>/src/$1',
     '^storybook-config/(.*)$': '<rootDir>/.storybook/$1',
diff --git a/packages/joint-react/package.json b/packages/joint-react/package.json
index c79a5d6bb7..693c75f060 100644
--- a/packages/joint-react/package.json
+++ b/packages/joint-react/package.json
@@ -31,6 +31,11 @@
       "import": "./dist/esm/internal.js",
       "require": "./dist/cjs/internal.js"
     },
+    "./server": {
+      "types": "./dist/types/server/index.d.ts",
+      "import": "./dist/esm/server/index.js",
+      "require": "./dist/cjs/server/index.js"
+    },
     "./presets": {
       "types": "./dist/types/presets/index.d.ts",
       "import": "./dist/esm/presets/index.js",
@@ -45,12 +50,17 @@
     "./scripts/*": "./scripts/*.ts",
     "./styles.css": "./src/css/styles.css"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "**/*.css",
+    "./dist/esm/server/index.js",
+    "./dist/cjs/server/index.js"
+  ],
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
-    "src"
+    "src/css"
   ],
   "homepage": "https://jointjs.com",
   "author": {
@@ -62,7 +72,6 @@
     "Samuel <samuel@jointjs.com> (https://github.com/samuelgja)"
   ],
   "scripts": {
-    "prepublishOnly": "echo \"Publishing via NPM is not allowed!\" && exit 1",
     "prepack": "yarn test && yarn build",
     "build": "rollup -c rollup.config.ts --configPlugin esbuild && tsc --project tsconfig.types.json",
     "build-storybook": "storybook build",
@@ -80,6 +89,7 @@
     "@chromatic-com/storybook": "^5.0.0",
     "@joint/eslint-config": "workspace:*",
     "@joint/layout-directed-graph": "workspace:*",
+    "@joint/svg-shim": "workspace:*",
     "@reduxjs/toolkit": "^2.11.0",
     "@rollup/plugin-commonjs": "^28.0.6",
     "@rollup/plugin-node-resolve": "^16.0.1",
@@ -94,6 +104,7 @@
     "@testing-library/react": "^16.0.1",
     "@testing-library/react-hooks": "^8.0.1",
     "@types/jest": "30.0.0",
+    "@types/jsdom": "21.1.7",
     "@types/node": "^24.3.0",
     "@types/react": "19.1.12",
     "@types/react-dom": "19.1.9",
@@ -107,6 +118,7 @@
     "jest": "30.1.2",
     "jest-environment-jsdom": "30.1.2",
     "jotai": "^2.15.2",
+    "jsdom": "26.1.0",
     "knip": "5.63.0",
     "peerjs": "^1.5.5",
     "prettier": "3.3.3",
@@ -144,8 +156,14 @@
     "use-sync-external-store": "^1.6.0"
   },
   "peerDependencies": {
-    "react": ">=18",
-    "react-dom": ">=18"
+    "@joint/svg-shim": ">=0.0.1",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@joint/svg-shim": {
+      "optional": true
+    }
   },
   "volta": {
     "node": "22.14.0",
diff --git a/packages/joint-react/rollup.config.ts b/packages/joint-react/rollup.config.ts
index 28be647cda..c36a8d9ced 100644
--- a/packages/joint-react/rollup.config.ts
+++ b/packages/joint-react/rollup.config.ts
@@ -1,12 +1,21 @@
 import { createRollupConfig } from './scripts/create-rollup-config';
 
 export default createRollupConfig({
-  entries: ['src/index.ts', 'src/internal.ts', 'src/presets/index.ts', 'src/stories.ts'],
+  entries: [
+    'src/index.ts',
+    'src/internal.ts',
+    'src/presets/index.ts',
+    'src/stories.ts',
+    'src/server/index.ts',
+  ],
   external: [
     'react',
     'react-dom',
     'use-sync-external-store',
     '@joint/core',
     '@joint/layout-directed-graph',
+    'node:module',
+    'node:path',
+    'jsdom',
   ],
 });
diff --git a/packages/joint-react/src/__tests__/ssr-client-handoff.test.tsx b/packages/joint-react/src/__tests__/ssr-client-handoff.test.tsx
new file mode 100644
index 0000000000..95b7c07474
--- /dev/null
+++ b/packages/joint-react/src/__tests__/ssr-client-handoff.test.tsx
@@ -0,0 +1,84 @@
+/* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
+/**
+ * SSR → client handoff: a tree authored to be server-rendered is hydrated on
+ * the client, and we assert the full interactive surface works afterwards —
+ * Paper mounts its real canvas, JointJS events fire, the normalized event
+ * props invoke their handlers, and React state updates re-render.
+ *
+ * (jsdom = the client/browser side of the handoff. The server side — that
+ * `GraphProvider` renders to HTML at all — is covered by `ssr.test.tsx`.)
+ */
+import { useState } from 'react';
+import { act, waitFor } from '@testing-library/react';
+import { hydrateRoot } from 'react-dom/client';
+import type { dia } from '@joint/core';
+import { GraphProvider } from '../components/graph/graph-provider';
+import { Paper } from '../components/paper/paper';
+import { ELEMENT_MODEL_TYPE } from '../models/element-model';
+import type { CellRecord } from '../types/cell.types';
+
+const CELLS: readonly CellRecord[] = [
+  { id: '1', type: ELEMENT_MODEL_TYPE, position: { x: 0, y: 0 }, size: { width: 50, height: 50 } } as CellRecord,
+];
+const renderRect = () => <rect />;
+const fakeEvent = {} as dia.Event;
+
+it('hydrates a server tree and Paper is fully interactive on the client (events + state)', async () => {
+  let paper: dia.Paper | null = null;
+  const setPaper = (instance: dia.Paper | null) => {
+    if (instance) paper = instance;
+  };
+
+  function App() {
+    // React state driven by a JointJS paper event — proves the full loop.
+    const [clicks, setClicks] = useState(0);
+    return (
+      <GraphProvider initialCells={CELLS}>
+        <output data-testid="clicks">{clicks}</output>
+        <Paper
+          ref={setPaper}
+          style={{ width: 100, height: 100 }}
+          renderElement={renderRect}
+          onElementPointerClick={() => setClicks((value) => value + 1)}
+        />
+      </GraphProvider>
+    );
+  }
+
+  const container = document.createElement('div');
+  document.body.append(container);
+
+  // Hydrate on the client (as it would after SSR delivered the markup).
+  await act(async () => {
+    hydrateRoot(container, <App />);
+  });
+
+  // 1) Paper mounted its real canvas on the client.
+  await waitFor(() => {
+    expect(container.querySelector('svg')).toBeTruthy();
+    expect(paper).not.toBeNull();
+  });
+
+  const livePaper = paper as unknown as dia.Paper;
+
+  // 2) The element view exists (JointJS rendered the cell).
+  const view = livePaper.findViewByModel(livePaper.model.getCell('1'));
+  expect(view).toBeTruthy();
+
+  // 3) A paper event fires → normalized handler runs → React state updates → re-render.
+  act(() => {
+    livePaper.trigger('element:pointerclick', view, fakeEvent, 5, 5);
+  });
+  await waitFor(() => {
+    expect(container.querySelector('[data-testid="clicks"]')?.textContent).toBe('1');
+  });
+
+  // 4) It keeps working — second event, state advances again.
+  act(() => {
+    livePaper.trigger('element:pointerclick', view, fakeEvent, 6, 6);
+  });
+  await waitFor(() => {
+    expect(container.querySelector('[data-testid="clicks"]')?.textContent).toBe('2');
+  });
+});
diff --git a/packages/joint-react/src/__tests__/ssr-paper-handoff.test.tsx b/packages/joint-react/src/__tests__/ssr-paper-handoff.test.tsx
new file mode 100644
index 0000000000..4d7bd77d0d
--- /dev/null
+++ b/packages/joint-react/src/__tests__/ssr-paper-handoff.test.tsx
@@ -0,0 +1,93 @@
+/* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
+/**
+ * The SSR round-trip for the automatic `<Paper>` server render:
+ *  1. on the server the full diagram (nodes + `renderElement` content) is in the
+ *     HTML — first paint with no client JS, and
+ *  2. on the client the same tree hydrates and the live, interactive paper takes
+ *     over (events drive React state).
+ *
+ * `../server/register` registers the server renderer; the DOM-shim flag is
+ * toggled to reproduce the server→client boundary.
+ */
+import { useState } from 'react';
+import { act, waitFor } from '@testing-library/react';
+import { renderToString } from 'react-dom/server';
+import { hydrateRoot } from 'react-dom/client';
+import type { dia } from '@joint/core';
+import '../server';
+import { GraphProvider } from '../components/graph/graph-provider';
+import { Paper } from '../components/paper/paper';
+import { DOM_SHIM_FLAG } from '../utils/ssr';
+import type { CellRecord } from '../types/cell.types';
+
+const CELLS: readonly CellRecord[] = [
+  { id: '1', type: 'element', position: { x: 10, y: 10 }, size: { width: 60, height: 40 }, data: { label: 'A' } } as CellRecord,
+];
+const renderRect = () => <rect width={60} height={40} fill="#444" />;
+const fakeEvent = {} as dia.Event;
+
+function App({ onClick }: Readonly<{ onClick?: () => void }>) {
+  return (
+    <GraphProvider initialCells={CELLS}>
+      <Paper style={{ width: 100, height: 100 }} renderElement={renderRect} onElementPointerClick={onClick} />
+    </GraphProvider>
+  );
+}
+
+it('server-renders the full diagram (nodes + renderElement) as HTML', () => {
+  const globalScope = globalThis as Record<string, unknown>;
+  globalScope[DOM_SHIM_FLAG] = true;
+  let html = '';
+  try {
+    html = renderToString(<App />);
+  } finally {
+    Reflect.deleteProperty(globalScope, DOM_SHIM_FLAG);
+  }
+  expect(html).toContain('joint-cells');
+  expect(html).toContain('translate(10,10)'); // node position from the model
+  expect(html).toContain('<rect'); // renderElement content
+});
+
+it('hydrates to a live interactive paper on the client (events drive state)', async () => {
+  let paper: dia.Paper | null = null;
+  const setPaper = (instance: dia.Paper | null) => {
+    if (instance) paper = instance;
+  };
+
+  function ClientApp() {
+    const [clicks, setClicks] = useState(0);
+    return (
+      <GraphProvider initialCells={CELLS}>
+        <output data-testid="clicks">{clicks}</output>
+        <Paper
+          ref={setPaper}
+          style={{ width: 100, height: 100 }}
+          renderElement={renderRect}
+          onElementPointerClick={() => setClicks((value) => value + 1)}
+        />
+      </GraphProvider>
+    );
+  }
+
+  const container = document.createElement('div');
+  document.body.append(container);
+  await act(async () => {
+    hydrateRoot(container, <ClientApp />);
+  });
+
+  await waitFor(() => {
+    expect(paper).not.toBeNull();
+    expect(container.querySelector('.joint-cells')).toBeTruthy();
+  });
+
+  const livePaper = paper as unknown as dia.Paper;
+  const view = livePaper.findViewByModel(livePaper.model.getCell('1'));
+  expect(view).toBeTruthy();
+  act(() => {
+    livePaper.trigger('element:pointerclick', view, fakeEvent, 5, 5);
+  });
+  await waitFor(() => {
+    expect(container.querySelector('[data-testid="clicks"]')?.textContent).toBe('1');
+  });
+});
diff --git a/packages/joint-react/src/__tests__/ssr.test.tsx b/packages/joint-react/src/__tests__/ssr.test.tsx
new file mode 100644
index 0000000000..b5d3d4bcc8
--- /dev/null
+++ b/packages/joint-react/src/__tests__/ssr.test.tsx
@@ -0,0 +1,86 @@
+/**
+ * @jest-environment node
+ *
+ * Server-side rendering smoke tests, run in a real Node environment (no DOM).
+ * Contract:
+ * - `GraphProvider` (data + context) renders on the server, including children
+ *   and data read via hooks like `useCells`.
+ * - `Paper` (DOM rendering) degrades gracefully to its host element — it must
+ *   not crash the server render.
+ */
+import { renderToString } from 'react-dom/server';
+import { GraphProvider } from '../components/graph/graph-provider';
+import { Paper } from '../components/paper/paper';
+import { useCells } from '../hooks/use-cells';
+import { ELEMENT_MODEL_TYPE } from '../models/element-model';
+import type { CellRecord } from '../types/cell.types';
+
+const CELLS: readonly CellRecord[] = [
+  {
+    id: 'a',
+    type: ELEMENT_MODEL_TYPE,
+    position: { x: 0, y: 0 },
+    size: { width: 50, height: 50 },
+  } as CellRecord,
+  {
+    id: 'b',
+    type: ELEMENT_MODEL_TYPE,
+    position: { x: 0, y: 0 },
+    size: { width: 50, height: 50 },
+  } as CellRecord,
+];
+
+function CellIds() {
+  const cells = useCells();
+  return (
+    <ul>
+      {cells.map((cell) => (
+        <li key={cell.id}>{String(cell.id)}</li>
+      ))}
+    </ul>
+  );
+}
+
+describe('SSR: node environment, no DOM', () => {
+  it('is a real server environment (no DOM globals)', () => {
+    expect(globalThis.document).toBeUndefined();
+    expect(globalThis.window).toBeUndefined();
+    expect(globalThis.ResizeObserver).toBeUndefined();
+  });
+
+  it('GraphProvider renders its children on the server', () => {
+    let html = '';
+    expect(() => {
+      html = renderToString(
+        <GraphProvider initialCells={CELLS}>
+          <div>server-child</div>
+        </GraphProvider>
+      );
+    }).not.toThrow();
+    expect(html).toContain('server-child');
+  });
+
+  it('exposes graph data to hooks during SSR (useCells works on the server)', () => {
+    const html = renderToString(
+      <GraphProvider initialCells={CELLS}>
+        <CellIds />
+      </GraphProvider>
+    );
+    expect(html).toContain('<li>a</li>');
+    expect(html).toContain('<li>b</li>');
+  });
+
+  it('Paper degrades gracefully on the server (renders host element, no crash)', () => {
+    let html = '';
+    expect(() => {
+      html = renderToString(
+        <GraphProvider initialCells={CELLS}>
+          {/* eslint-disable-next-line react-perf/jsx-no-new-function-as-prop */}
+          <Paper renderElement={() => <rect />} />
+        </GraphProvider>
+      );
+    }).not.toThrow();
+    // The host container renders; the SVG/portal content is client-only.
+    expect(html).toContain('<div');
+  });
+});
diff --git a/packages/joint-react/src/components/graph/graph-provider.tsx b/packages/joint-react/src/components/graph/graph-provider.tsx
index 4df5e092e1..d119512f43 100644
--- a/packages/joint-react/src/components/graph/graph-provider.tsx
+++ b/packages/joint-react/src/components/graph/graph-provider.tsx
@@ -1,8 +1,10 @@
 import type { dia } from '@joint/core';
-import React, { useLayoutEffect } from 'react';
+import React from 'react';
 import { useImperativeApi } from '../../hooks/use-imperative-api';
+import { useIsomorphicLayoutEffect } from '../../hooks/use-isomorphic-layout-effect';
 import { GraphStoreContext } from '../../context';
 import { GraphStore } from '../../store';
+import { isServerEnvironment } from '../../utils/ssr';
 import type { AutoSizeOrigin } from '../../store/graph-store';
 import type { OnIncrementalCellsChange } from '../../store/graph-projection';
 import type { ElementJSONInit, LinkJSONInit } from '../../types/cell.types';
@@ -103,20 +105,25 @@ function GraphBase(props: GraphProviderBaseInternalProps) {
 
   const isControlled = !!cells;
 
+  const buildStore = (): GraphStore<ElementJSONInit, LinkJSONInit> =>
+    store ??
+    new GraphStore<ElementJSONInit, LinkJSONInit>({
+      graph,
+      cellNamespace,
+      cellModel,
+      initialCells: cells ?? initialCells ?? [],
+      autoSizeOrigin,
+    });
+
+  // Client: the store is owned by a layout-effect lifecycle (StrictMode-safe
+  // create/cleanup). `isReady` stays false on the server because layout effects
+  // never run there — that is handled by the SSR branch below.
   const { isReady, ref } = useImperativeApi<GraphStore<ElementJSONInit, LinkJSONInit>, dia.Graph>(
     {
       instanceSelector: (instance) => instance.graph,
       forwardedRef,
       onLoad() {
-        const graphStore =
-          store ??
-          new GraphStore<ElementJSONInit, LinkJSONInit>({
-            graph,
-            cellNamespace,
-            cellModel,
-            initialCells: cells ?? initialCells ?? [],
-            autoSizeOrigin,
-          });
+        const graphStore = buildStore();
         return {
           cleanup() {
             if (store) return;
@@ -129,7 +136,7 @@ function GraphBase(props: GraphProviderBaseInternalProps) {
     []
   );
 
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     if (!isReady) return;
     ref.current.setOnIncrementalCellsChange((changeSet) => {
       onIncrementalCellsChange?.(changeSet);
@@ -147,6 +154,17 @@ function GraphBase(props: GraphProviderBaseInternalProps) {
   }, [isReady, onIncrementalCellsChange, onCellsChange, ref, isControlled, cells]);
 
   if (!isReady) {
+    // Server render: provide a synchronous, per-request store so children and
+    // data hooks (`useCells`, ...) render to HTML. `GraphStore` is pure data
+    // (no DOM), so this is SSR-safe; `<Paper>` renders the diagram tree (or just
+    // its host element). On the client this branch is never reached once the
+    // layout effect runs. Evaluated at render time so it also fires when the
+    // server DOM shim has installed a headless `document`.
+    if (isServerEnvironment()) {
+      return (
+        <GraphStoreContext.Provider value={buildStore()}>{children}</GraphStoreContext.Provider>
+      );
+    }
     return null;
   }
 
diff --git a/packages/joint-react/src/components/paper/default-render-element.tsx b/packages/joint-react/src/components/paper/default-render-element.tsx
new file mode 100644
index 0000000000..a8e17049d4
--- /dev/null
+++ b/packages/joint-react/src/components/paper/default-render-element.tsx
@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+import { HTMLBox } from '../html-box';
+import type { RenderElement } from './paper.types';
+
+/**
+ * Default element renderer used by `<Paper>` when no `renderElement` is given:
+ * a themed `HTMLBox` showing `data.label`. Shared by the client portal renderer
+ * and the server tree builder so the first paint matches on both.
+ * @param data - the element's `data` slice.
+ * @returns the default element content.
+ */
+export const defaultRenderElement: RenderElement<Record<string, unknown>> = (data) => {
+  const label = (data as { label?: ReactNode } | undefined)?.label;
+  return <HTMLBox>{label}</HTMLBox>;
+};
diff --git a/packages/joint-react/src/components/paper/paper.tsx b/packages/joint-react/src/components/paper/paper.tsx
index 58b871d256..4c30929b49 100644
--- a/packages/joint-react/src/components/paper/paper.tsx
+++ b/packages/joint-react/src/components/paper/paper.tsx
@@ -1,8 +1,9 @@
 import type { dia } from '@joint/core';
-import { forwardRef, useImperativeHandle, useRef } from 'react';
+import { forwardRef, useImperativeHandle, useMemo, useRef, type CSSProperties } from 'react';
 import { createPortal } from 'react-dom';
 import { PaperStoreContext } from '../../context';
 import { useCreatePortalPaper } from '../../hooks/use-create-portal-paper';
+import { useServerPaperTree } from '../../hooks/use-server-paper-tree';
 import type { PaperProps } from './paper.types';
 import { DEFAULT_PAPER_ID } from '../../models/react-paper';
 
@@ -20,6 +21,18 @@ function PaperBase(
   const paperHTMLElementRef = useRef<HTMLDivElement | null>(null);
   const id = props.id ?? DEFAULT_PAPER_ID;
   const isExternalPaper = !!externalPaper;
+  // On the server (when `@joint/react/server` is loaded) build the full diagram
+  // as a React tree from the GraphProvider graph — so a plain
+  // `<GraphProvider><Paper renderElement={…} /></GraphProvider>` renders a
+  // complete diagram. `undefined` on the client (the live paper mounts there).
+  const serverTree = useServerPaperTree({ paperId: id, isExternalPaper, props });
+  // The server SVG is `position: absolute; inset: 0`, so the host needs
+  // `position: relative` to contain it — without JS the live paper isn't there
+  // to set it. (The live paper sets it itself on the client.)
+  const hostStyle = useMemo<CSSProperties | undefined>(
+    () => (serverTree == null ? style : { ...style, position: 'relative' }),
+    [serverTree, style]
+  );
   const { paperRef, paperStore, isReady, content } = useCreatePortalPaper({
     ...props,
     elementRef: isExternalPaper ? undefined : paperHTMLElementRef,
@@ -40,16 +53,20 @@ function PaperBase(
   if (isExternalPaper) {
     return (
       <PaperStoreContext.Provider value={paperStore ?? null}>
-        {isReady && content}
+        {isReady ? content : null}
         {portaledChildren}
       </PaperStoreContext.Provider>
     );
   }
 
+  // On the server the host renders the diagram tree (so `renderToString` emits
+  // the full SVG). On the client `serverTree` is `undefined`, so React reconciles
+  // it away and `useCreatePortalPaper` mounts the live paper into the host;
+  // portal content renders there.
   return (
     <PaperStoreContext.Provider value={paperStore ?? null}>
-      <div className={className} ref={paperHTMLElementRef} style={style}>
-        {isReady && content}
+      <div className={className} ref={paperHTMLElementRef} style={hostStyle}>
+        {serverTree ?? (isReady ? content : null)}
       </div>
       {portaledChildren}
     </PaperStoreContext.Provider>
diff --git a/packages/joint-react/src/components/paper/paper.types.ts b/packages/joint-react/src/components/paper/paper.types.ts
index 4363da1141..7f5d07e2d6 100644
--- a/packages/joint-react/src/components/paper/paper.types.ts
+++ b/packages/joint-react/src/components/paper/paper.types.ts
@@ -247,7 +247,7 @@ export interface PaperProps extends PortalPaperOptions, PropsWithChildren, Norma
    * @example
    * Example with `global component`:
    * ```tsx
-   * type BaseElementWithData = InferElement<typeof initialElements>
+   * type BaseElementWithData = { label: string }
    * function RenderElement({ label }: BaseElementWithData) {
    *  return <HTMLElement className="node">{label}</HTMLElement>
    * }
@@ -256,7 +256,7 @@ export interface PaperProps extends PortalPaperOptions, PropsWithChildren, Norma
    * Example with `local component`:
    * ```tsx
    *
-  type BaseElementWithData = InferElement<typeof initialElements>
+  type BaseElementWithData = { label: string }
   const renderElement: RenderElement<BaseElementWithData> = useCallback(
       (element) => <HTMLElement className="node">{element.label}</HTMLElement>,
       []
diff --git a/packages/joint-react/src/components/paper/render-element/paper-html-container.tsx b/packages/joint-react/src/components/paper/render-element/paper-html-container.tsx
index 59f0d7a31a..1934340472 100644
--- a/packages/joint-react/src/components/paper/render-element/paper-html-container.tsx
+++ b/packages/joint-react/src/components/paper/render-element/paper-html-container.tsx
@@ -1,4 +1,4 @@
-import { memo, useEffect, useMemo, useRef, type CSSProperties } from 'react';
+import { memo, useLayoutEffect, useMemo, useRef, type CSSProperties } from 'react';
 import { usePaper } from '../../../hooks';
 import { mvc, V } from '@joint/core';
 import { createPortal } from 'react-dom';
@@ -6,16 +6,16 @@ import { createPortal } from 'react-dom';
 interface Props {
   readonly onSetElement: (element: HTMLElement) => void;
 }
- 
+
 function Component({ onSetElement }: Readonly<Props>) {
   const { paper } = usePaper();
   const divRef = useRef<HTMLDivElement>(null);
 
-  useEffect(() => {
+  useLayoutEffect(() => {
     if (!paper || !divRef.current) {
       return;
     }
-     
+
     function transformElement() {
       if (!divRef.current) {
         return;
@@ -36,7 +36,8 @@ function Component({ onSetElement }: Readonly<Props>) {
     return () => {
       controller.stopListening();
     };
-  }, [divRef, onSetElement, paper]);
+    // `divRef` is a ref — stable identity, intentionally not a dependency.
+  }, [onSetElement, paper]);
 
   const style = useMemo(
     (): CSSProperties => ({
diff --git a/packages/joint-react/src/hooks/use-are-elements-measured.ts b/packages/joint-react/src/hooks/use-are-elements-measured.ts
index 998d68c011..7ff72109cc 100644
--- a/packages/joint-react/src/hooks/use-are-elements-measured.ts
+++ b/packages/joint-react/src/hooks/use-are-elements-measured.ts
@@ -16,6 +16,8 @@ export function useAreElementsMeasured() {
     },
     () => {
       return measureState.get() > 0;
-    }
+    },
+    // Server snapshot: nothing is measured without a DOM, so report unmeasured.
+    () => false
   );
 }
diff --git a/packages/joint-react/src/hooks/use-create-portal-paper.tsx b/packages/joint-react/src/hooks/use-create-portal-paper.tsx
index 2ee3f80074..5037fe488d 100644
--- a/packages/joint-react/src/hooks/use-create-portal-paper.tsx
+++ b/packages/joint-react/src/hooks/use-create-portal-paper.tsx
@@ -22,7 +22,7 @@ import type { LinkRecord } from '../types/cell.types';
 import type { PaperStore } from '../store';
 import { ReactPaper } from '../models/react-paper';
 import type { PaperProps, PortalPaperOptions, RenderLink } from '../components/paper/paper.types';
-import { HTMLBox } from '../components/html-box';
+import { defaultRenderElement } from '../components/paper/default-render-element';
 
 import { mapLinkToAttributes } from '../state/data-mapping';
 import type { CanConnectOptions } from '../presets/can-connect';
@@ -138,7 +138,7 @@ function createDefaultLinkCallback(defaultLink: PortalPaperOptions['defaultLink'
  */
 function LinkItem({
   portalElement,
-  renderLink,
+  renderLink: RenderLink,
 }: {
   readonly portalElement: SVGElement | HTMLElement;
   readonly renderLink: RenderLink;
@@ -159,21 +159,10 @@ function LinkItem({
   if (!portalElement || id === undefined) {
     return null;
   }
-  const linkContent = renderLink(data);
+  const linkContent = <RenderLink {...data} />;
   return createPortal(linkContent, portalElement);
 }
 
-/**
- * The default element if the user doesn't provide a renderElement function.
- * Renders `data.label` inside a DefaultHTMLHost.
- * @param data - the element's user data slice
- * @returns A JSX element rendering the label inside a DefaultHTMLHost with default styling.
- */
-const defaultRenderElement = (data: unknown) => {
-  const label = (data as { label?: string } | undefined)?.label;
-  return <HTMLBox>{label}</HTMLBox>;
-};
-
 /**
  * Creates and manages a React-backed JointJS paper instance lifecycle.
  * @param options - Hook options with paper settings and behavior overrides.
@@ -304,6 +293,14 @@ export function useCreatePortalPaper(
   useLayoutEffect(() => {
     const hostElementForCreation = elementRef?.current;
 
+    // Clear any server-rendered SSR markup from the host before the live paper
+    // mounts, so the JointJS-built SVG replaces it rather than stacking on top.
+    // React keeps the host's `dangerouslySetInnerHTML` value stable, so it does
+    // not re-insert the markup after this.
+    if (hostElementForCreation) {
+      hostElementForCreation.replaceChildren();
+    }
+
     const { paperStore, remove } = addPaper(id, {
       paperOptions: {
         ...paperOptions,
diff --git a/packages/joint-react/src/hooks/use-isomorphic-layout-effect.ts b/packages/joint-react/src/hooks/use-isomorphic-layout-effect.ts
new file mode 100644
index 0000000000..a50a992702
--- /dev/null
+++ b/packages/joint-react/src/hooks/use-isomorphic-layout-effect.ts
@@ -0,0 +1,13 @@
+import { useEffect, useLayoutEffect } from 'react';
+import { isServerEnvironment } from '../utils/ssr';
+
+/**
+ * `useLayoutEffect` in the browser, `useEffect` on the server.
+ *
+ * `useLayoutEffect` logs a warning during server rendering ("useLayoutEffect
+ * does nothing on the server") because layout effects never run there. This
+ * alias swaps to `useEffect` on the server (including when the DOM shim has
+ * installed a headless `document`), silencing the warning while preserving
+ * synchronous, pre-paint timing in the browser.
+ */
+export const useIsomorphicLayoutEffect = isServerEnvironment() ? useEffect : useLayoutEffect;
diff --git a/packages/joint-react/src/hooks/use-server-paper-tree.ts b/packages/joint-react/src/hooks/use-server-paper-tree.ts
new file mode 100644
index 0000000000..e234d54fd2
--- /dev/null
+++ b/packages/joint-react/src/hooks/use-server-paper-tree.ts
@@ -0,0 +1,86 @@
+import { useMemo, type CSSProperties, type ReactNode } from 'react';
+import type { dia } from '@joint/core';
+import { useGraphStore } from './use-graph-store';
+import { isServerEnvironment } from '../utils/ssr';
+import { getServerPaperRenderer } from '../utils/server-paper-renderer';
+import type { PaperProps } from '../components/paper/paper.types';
+
+/** Reads a CSS length as a number, or `undefined` when it is not a plain number. */
+function toNumber(value: CSSProperties['width']): number | undefined {
+  return typeof value === 'number' ? value : undefined;
+}
+
+/** Options for {@link useServerPaperTree}. */
+export interface ServerPaperTreeOptions {
+  /** Effective paper id. */
+  readonly paperId: string;
+  /** Whether the paper is externally managed (skip server generation). */
+  readonly isExternalPaper: boolean;
+  /** The Paper props (renderers, style, paper options). */
+  readonly props: Readonly<PaperProps>;
+}
+
+/**
+ * Builds the diagram React tree for `<Paper>` on the server.
+ *
+ * On the server — and only when `@joint/react/server` has registered
+ * the renderer — this builds the full diagram (positioned nodes, links, and
+ * `renderElement` content) from the `GraphProvider` graph, so a plain
+ * `<GraphProvider><Paper renderElement={…} /></GraphProvider>` renders a complete
+ * diagram with no extra wiring. The returned tree is rendered by the outer
+ * `renderToString`, so `renderElement` runs natively in the same pass.
+ *
+ * Returns `undefined` on the client, where the live paper mounts normally.
+ * @param options - paper id, external flag, and props.
+ * @returns the diagram React tree, or `undefined`.
+ */
+export function useServerPaperTree(options: ServerPaperTreeOptions): ReactNode {
+  const { paperId, isExternalPaper, props } = options;
+  const graphStore = useGraphStore();
+
+  return useMemo(() => {
+    if (isExternalPaper || !isServerEnvironment()) {
+      return;
+    }
+    const renderer = getServerPaperRenderer();
+    if (!renderer) {
+      return;
+    }
+
+    // `linkRouting` is a bundle of `dia.Paper.Options` (router/connector). Spread
+    // it like the client (`useCreatePortalPaper`) so links route identically on
+    // the server — otherwise the JS-disabled first paint would differ.
+    const paperOptions: Partial<dia.Paper.Options> = { ...props.options, ...props.linkRouting };
+    if (props.drawGrid !== undefined) {
+      paperOptions.drawGrid = props.drawGrid;
+    }
+    if (props.gridSize !== undefined) {
+      paperOptions.gridSize = props.gridSize;
+    }
+    if (props.background !== undefined) {
+      paperOptions.background = props.background;
+    }
+
+    try {
+      const { tree } = renderer({
+        graph: graphStore.graph,
+        graphStore,
+        renderElement: props.renderElement,
+        renderLink: props.renderLink,
+        portalSelector: props.portalSelector,
+        paperId,
+        width: toNumber(props.style?.width),
+        height: toNumber(props.style?.height),
+        paperOptions,
+      });
+      return tree;
+    } catch {
+      // SSR is best-effort: if building the server tree throws, degrade to a
+      // client-mounted paper (return `undefined`) instead of failing the whole
+      // `renderToString`. The client hydrates the live paper as usual.
+      return;
+    }
+    // Server rendering is one-shot — generate once per render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+}
diff --git a/packages/joint-react/src/server/__tests__/react-ssr.test.tsx b/packages/joint-react/src/server/__tests__/react-ssr.test.tsx
new file mode 100644
index 0000000000..c5e04f4fd6
--- /dev/null
+++ b/packages/joint-react/src/server/__tests__/react-ssr.test.tsx
@@ -0,0 +1,214 @@
+/* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
+/* eslint-disable react-perf/jsx-no-new-array-as-prop */
+/**
+ * @jest-environment node
+ *
+ * The headline SSR flow: a plain `<GraphProvider><Paper /></GraphProvider>`
+ * tree, rendered with `renderToString`, produces a COMPLETE diagram HTML on the
+ * server — positioned nodes, links, and `renderElement` content — with no
+ * `ssrMarkup` prop and no separate `renderPaperToStaticMarkup` call.
+ *
+ * `..` is imported first: it installs the DOM shim (before `@joint/core`
+ * is evaluated by the component imports) and registers the server paper renderer
+ * that `<Paper>` uses automatically.
+ */
+import '..';
+import { renderToString } from 'react-dom/server';
+import { GraphProvider } from '../../components/graph/graph-provider';
+import { Paper } from '../../components/paper/paper';
+import { useCell } from '../../hooks/use-cell';
+import { useCellId } from '../../hooks/use-cell-id';
+import { useCells } from '../../hooks/use-cells';
+import { linkRoutingOrthogonal } from '../../presets/link-routing';
+import type { CellRecord } from '../../types/cell.types';
+
+const LINK_LINE_TAG = /<path[^>]*jj-link-line[^>]*>/;
+const PATH_D_ATTRIBUTE = /\bd="([^"]*)"/;
+
+/** Extracts the `d` of the rendered link line (`jj-link-line`) from SSR HTML. */
+function linkLinePath(html: string): string {
+  const tag = LINK_LINE_TAG.exec(html)?.[0] ?? '';
+  return PATH_D_ATTRIBUTE.exec(tag)?.[1] ?? '';
+}
+
+/** Counts path segment commands (`L`/`C`) — more segments means more bends. */
+function segmentCount(pathData: string): number {
+  return (pathData.match(/[LC]/g) ?? []).length;
+}
+
+const CELLS: readonly CellRecord[] = [
+  {
+    id: 'a',
+    type: 'element',
+    position: { x: 40, y: 40 },
+    size: { width: 120, height: 60 },
+    data: { label: 'Node A' },
+  } as CellRecord,
+  {
+    id: 'b',
+    type: 'element',
+    position: { x: 300, y: 200 },
+    size: { width: 120, height: 60 },
+    data: { label: 'Node B' },
+  } as CellRecord,
+  { id: 'l', type: 'link', source: { id: 'a' }, target: { id: 'b' } } as CellRecord,
+];
+
+const renderRect = () => <rect width={120} height={60} fill="#3366ff" />;
+
+describe('SSR: <GraphProvider><Paper /> renders a full diagram on the server', () => {
+  it('renders positioned nodes, links and SVG renderElement content', () => {
+    const html = renderToString(
+      <GraphProvider initialCells={CELLS}>
+        <Paper renderElement={renderRect} style={{ width: 500, height: 320 }} />
+      </GraphProvider>
+    );
+
+    expect(html).toContain('<svg');
+    expect(html).toContain('<rect');
+    expect(html).toContain('<path'); // link
+    // Node positions come from the model.
+    expect(html).toContain('translate(40,40)');
+    expect(html).toContain('translate(300,200)');
+    // Links must be visible — not left hidden waiting for client measurement.
+    expect(html).not.toContain('visibility:hidden');
+    expect(html).not.toContain('visibility: hidden');
+  });
+
+  it('renders preset link style (custom arrowhead markup) on the server', () => {
+    const cells: readonly CellRecord[] = [
+      { id: 'a', type: 'element', position: { x: 40, y: 40 }, size: { width: 120, height: 60 }, data: {} } as CellRecord,
+      { id: 'b', type: 'element', position: { x: 300, y: 200 }, size: { width: 120, height: 60 }, data: {} } as CellRecord,
+      {
+        id: 'l',
+        type: 'link',
+        source: { id: 'a' },
+        target: { id: 'b' },
+        style: {
+          color: '#38bdf8',
+          width: 2,
+          targetMarker: { markup: [{ tagName: 'path', attributes: { d: 'M 0 0 L 8 4 L 8 -4 Z' } }] },
+        },
+      } as CellRecord,
+    ];
+
+    const html = renderToString(
+      <GraphProvider initialCells={cells}>
+        <Paper renderElement={renderRect} style={{ width: 500, height: 320 }} />
+      </GraphProvider>
+    );
+
+    expect(html).toContain('jj-link-line'); // preset line class applied
+    expect(html).toContain('M 0 0 L 8 4'); // custom arrowhead markup rendered
+    expect(html).toContain('#38bdf8'); // link color applied to the line
+  });
+
+  it('forwards linkRouting to the server so links route identically (no JS-off mismatch)', () => {
+    const cells: readonly CellRecord[] = [
+      { id: 'a', type: 'element', position: { x: 40, y: 40 }, size: { width: 120, height: 60 }, data: {} } as CellRecord,
+      { id: 'b', type: 'element', position: { x: 320, y: 240 }, size: { width: 120, height: 60 }, data: {} } as CellRecord,
+      { id: 'l', type: 'link', source: { id: 'a' }, target: { id: 'b' } } as CellRecord,
+    ];
+
+    const straightHtml = renderToString(
+      <GraphProvider initialCells={cells}>
+        <Paper renderElement={renderRect} style={{ width: 520, height: 360 }} />
+      </GraphProvider>
+    );
+    const orthogonalHtml = renderToString(
+      <GraphProvider initialCells={cells}>
+        <Paper
+          renderElement={renderRect}
+          style={{ width: 520, height: 360 }}
+          linkRouting={linkRoutingOrthogonal({ cornerType: 'line' })}
+        />
+      </GraphProvider>
+    );
+
+    const straightPath = linkLinePath(straightHtml);
+    const orthogonalPath = linkLinePath(orthogonalHtml);
+
+    expect(orthogonalPath).not.toBe('');
+    // Orthogonal routing bends the link (right-angle segments), so its path has
+    // strictly more segments than the straight diagonal default.
+    expect(orthogonalPath).not.toBe(straightPath);
+    expect(segmentCount(orthogonalPath)).toBeGreaterThan(segmentCount(straightPath));
+  });
+
+  it('renders rotated elements via a plain transform attribute', () => {
+    const cells: readonly CellRecord[] = [
+      {
+        id: 'rot',
+        type: 'element',
+        position: { x: 120, y: 120 },
+        size: { width: 80, height: 80 },
+        angle: 30,
+        data: { label: 'Rotated' },
+      } as CellRecord,
+    ];
+    let html = '';
+    expect(() => {
+      html = renderToString(
+        <GraphProvider initialCells={cells}>
+          <Paper renderElement={renderRect} style={{ width: 300, height: 300 }} />
+        </GraphProvider>
+      );
+    }).not.toThrow();
+    expect(html).toContain('model-id="rot"');
+    expect(html).toContain('rotate(30');
+  });
+
+  it('renders the default HTMLBox renderElement with labels', () => {
+    const html = renderToString(
+      <GraphProvider initialCells={CELLS}>
+        <Paper style={{ width: 500, height: 320 }} />
+      </GraphProvider>
+    );
+
+    expect(html).toContain('foreignObject');
+    expect(html).toContain('Node A');
+    expect(html).toContain('Node B');
+  });
+
+  it('runs useSyncExternalStore hooks (useCell/useCellId/useCells) inside renderElement on the server', () => {
+    function NodeWithHooks() {
+      const id = useCellId();
+      const width = useCell((cell) => cell.size?.width ?? 0);
+      const total = useCells((cells) => cells.length);
+      return (
+        <foreignObject width={120} height={60}>
+          <div className="hooked" data-id={String(id)} data-width={width} data-total={total} />
+        </foreignObject>
+      );
+    }
+
+    const html = renderToString(
+      <GraphProvider initialCells={CELLS}>
+        <Paper renderElement={NodeWithHooks} style={{ width: 500, height: 320 }} />
+      </GraphProvider>
+    );
+
+    expect(html).toContain('class="hooked"');
+    expect(html).toContain('data-id="a"');
+    expect(html).toContain('data-id="b"');
+    expect(html).toContain('data-width="120"'); // useCell selector resolved from the model
+    expect(html).toContain('data-total="3"'); // useCells counted all cells (2 elements + 1 link)
+  });
+
+  it('renders custom renderElement reading element data', () => {
+    const renderLabel = ({ label }: { label?: string }) => (
+      <foreignObject width={120} height={60}>
+        <div className="custom-node">{label}</div>
+      </foreignObject>
+    );
+    const html = renderToString(
+      <GraphProvider initialCells={CELLS}>
+        <Paper renderElement={renderLabel} style={{ width: 500, height: 320 }} />
+      </GraphProvider>
+    );
+
+    expect(html).toContain('custom-node');
+    expect(html).toContain('Node A');
+  });
+});
diff --git a/packages/joint-react/src/server/__tests__/ssr-elements.test.tsx b/packages/joint-react/src/server/__tests__/ssr-elements.test.tsx
new file mode 100644
index 0000000000..bf3960352e
--- /dev/null
+++ b/packages/joint-react/src/server/__tests__/ssr-elements.test.tsx
@@ -0,0 +1,134 @@
+/* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
+/**
+ * @jest-environment node
+ *
+ * Comprehensive SSR coverage for ELEMENTS: geometry (position, size, angle,
+ * z-order), embedding/containers, ports, and raw SVG correctness. Asserts the
+ * static `renderToString` output.
+ */
+import '..';
+import type { ReactNode } from 'react';
+import { renderToString } from 'react-dom/server';
+import { GraphProvider } from '../../components/graph/graph-provider';
+import { Paper } from '../../components/paper/paper';
+import type { CellRecord } from '../../types/cell.types';
+
+/**
+ * Renders a graph. With no `renderElement` the package default (an `HTMLBox` in
+ * a `<foreignObject>`) applies; pass one to render custom SVG instead.
+ */
+function render(cells: readonly CellRecord[], renderElement?: () => ReactNode): string {
+  return renderToString(
+    <GraphProvider initialCells={cells}>
+      <Paper renderElement={renderElement} style={{ width: 600, height: 420 }} />
+    </GraphProvider>
+  );
+}
+
+describe('SSR elements — geometry', () => {
+  it('positions elements via translate(x,y) from the model', () => {
+    const html = render([
+      { id: 'a', type: 'element', position: { x: 40, y: 40 }, size: { width: 80, height: 40 }, data: {} } as CellRecord,
+      { id: 'b', type: 'element', position: { x: 300, y: 200 }, size: { width: 80, height: 40 }, data: {} } as CellRecord,
+    ]);
+    expect(html).toContain('translate(40,40)');
+    expect(html).toContain('translate(300,200)');
+  });
+
+  it('rotates elements via a transform attribute', () => {
+    const html = render([
+      { id: 'r', type: 'element', position: { x: 120, y: 120 }, size: { width: 80, height: 80 }, angle: 45, data: {} } as CellRecord,
+    ]);
+    expect(html).toContain('rotate(45');
+  });
+
+  it('renders elements in ascending z-order', () => {
+    const html = render([
+      { id: 'high', type: 'element', position: { x: 80, y: 80 }, size: { width: 60, height: 60 }, z: 5, data: {} } as CellRecord,
+      { id: 'low', type: 'element', position: { x: 40, y: 40 }, size: { width: 60, height: 60 }, z: 1, data: {} } as CellRecord,
+    ]);
+    expect(html.indexOf('model-id="low"')).toBeLessThan(html.indexOf('model-id="high"'));
+  });
+});
+
+describe('SSR elements — embedding / containers', () => {
+  it('renders a parent container with its embedded children and an inner link, in order', () => {
+    const html = render([
+      { id: 'c', type: 'element', position: { x: 40, y: 40 }, size: { width: 320, height: 220 }, z: 1, data: {} } as CellRecord,
+      { id: 'k1', type: 'element', position: { x: 70, y: 90 }, size: { width: 80, height: 40 }, parent: 'c', z: 2, data: {} } as CellRecord,
+      { id: 'k2', type: 'element', position: { x: 240, y: 160 }, size: { width: 80, height: 40 }, parent: 'c', z: 2, data: {} } as CellRecord,
+      { id: 'l', type: 'link', source: { id: 'k1' }, target: { id: 'k2' }, parent: 'c', z: 2 } as CellRecord,
+    ]);
+
+    for (const id of ['c', 'k1', 'k2', 'l']) {
+      expect(html).toContain(`model-id="${id}"`);
+    }
+    // Parent before children before the inner link (z-order preserved).
+    const order = ['c', 'k1', 'k2', 'l'].map((id) => html.indexOf(`model-id="${id}"`));
+    expect(order).toEqual(order.toSorted((first, second) => first - second));
+  });
+});
+
+describe('SSR elements — ports', () => {
+  it('renders a port shape with fill, magnet and label', () => {
+    const html = render([
+      {
+        id: 'p',
+        type: 'element',
+        position: { x: 40, y: 40 },
+        size: { width: 120, height: 60 },
+        data: {},
+        portMap: { out: { cx: 120, cy: 30, color: '#00ff00', shape: 'ellipse', label: 'OUT' } },
+      } as CellRecord,
+    ]);
+
+    expect(html).toContain('jj-port');
+    expect(html).toMatch(/<ellipse[^>]*jj-port/);
+    expect(html).toContain('#00ff00');
+    expect(html).toContain('magnet="active"');
+    expect(html).toContain('OUT');
+  });
+
+  it('supports a rectangular port shape', () => {
+    const html = render([
+      {
+        id: 'p',
+        type: 'element',
+        position: { x: 40, y: 40 },
+        size: { width: 120, height: 60 },
+        data: {},
+        portMap: { r: { cx: 0, cy: 30, shape: 'rect', color: '#ff8800' } },
+      } as CellRecord,
+    ]);
+    expect(html).toMatch(/<rect[^>]*jj-port/);
+  });
+});
+
+describe('SSR elements — SVG correctness', () => {
+  it('emits a valid <svg> root', () => {
+    const html = render([
+      { id: 'a', type: 'element', position: { x: 10, y: 10 }, size: { width: 40, height: 40 }, data: {} } as CellRecord,
+    ]);
+    expect(html).toContain('<svg');
+    expect(html).toContain('xmlns:xlink="http://www.w3.org/1999/xlink"');
+  });
+
+  it('renders <foreignObject> with the correct camelCase casing', () => {
+    const html = render([
+      { id: 'a', type: 'element', position: { x: 10, y: 10 }, size: { width: 120, height: 60 }, data: { label: 'Hi' } } as CellRecord,
+    ]);
+    expect(html).toContain('foreignObject');
+    expect(html).not.toContain('foreignobject');
+    expect(html).toContain('Hi');
+  });
+
+  it('serializes SVG presentation attributes from a custom renderElement', () => {
+    const html = render(
+      [{ id: 'a', type: 'element', position: { x: 10, y: 10 }, size: { width: 80, height: 40 }, data: {} } as CellRecord],
+      () => <rect width={80} height={40} fill="red" strokeWidth={2} strokeLinejoin="round" />
+    );
+    expect(html).toContain('stroke-width="2"');
+    expect(html).toContain('stroke-linejoin="round"');
+  });
+});
diff --git a/packages/joint-react/src/server/__tests__/ssr-links.test.tsx b/packages/joint-react/src/server/__tests__/ssr-links.test.tsx
new file mode 100644
index 0000000000..16c646c7b8
--- /dev/null
+++ b/packages/joint-react/src/server/__tests__/ssr-links.test.tsx
@@ -0,0 +1,145 @@
+/* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
+/* eslint-disable react-perf/jsx-no-new-array-as-prop */
+/**
+ * @jest-environment node
+ *
+ * Comprehensive SSR coverage for LINKS: endpoints, vertices, presets (style,
+ * markers, routing) and labels. Each case asserts the STATIC `renderToString`
+ * output so the JS-disabled first paint matches the interactive client.
+ *
+ * `..` is imported first so the DOM shim + server renderer install before
+ * `@joint/core` is evaluated.
+ */
+import '..';
+import type { ReactNode } from 'react';
+import { renderToString } from 'react-dom/server';
+import { GraphProvider } from '../../components/graph/graph-provider';
+import { Paper } from '../../components/paper/paper';
+import { linkRoutingStraight, linkRoutingSmooth } from '../../presets/link-routing';
+import type { LinkStyle } from '../../presets/link-style';
+import type { CellRecord } from '../../types/cell.types';
+import type { LinkRouting } from '../../presets/link-routing';
+
+const noElement = (): ReactNode => null;
+
+/** Renders a two-element graph joined by one configurable link, returns the HTML. */
+function renderLinkGraph(link: Record<string, unknown>, linkRouting?: LinkRouting): string {
+  const cells: readonly CellRecord[] = [
+    { id: 'a', type: 'element', position: { x: 40, y: 40 }, size: { width: 80, height: 40 }, data: {} } as CellRecord,
+    { id: 'b', type: 'element', position: { x: 320, y: 240 }, size: { width: 80, height: 40 }, data: {} } as CellRecord,
+    { id: 'l', type: 'link', source: { id: 'a' }, target: { id: 'b' }, ...link } as CellRecord,
+  ];
+  return renderToString(
+    <GraphProvider initialCells={cells}>
+      <Paper renderElement={noElement} style={{ width: 520, height: 360 }} linkRouting={linkRouting} />
+    </GraphProvider>
+  );
+}
+
+const LINK_PATH_D = /d="(M[^"]*)"/;
+
+/** First link line `d` in the HTML. */
+function linkPath(html: string): string {
+  return LINK_PATH_D.exec(html)?.[1] ?? '';
+}
+
+describe('SSR links — endpoints & geometry', () => {
+  it('renders a link path between two elements', () => {
+    const html = renderLinkGraph({ style: { color: '#38bdf8', width: 2 } satisfies LinkStyle });
+    expect(html).toContain('jj-link-line');
+    expect(linkPath(html)).toMatch(/^M /);
+    expect(html).not.toContain('visibility:hidden');
+  });
+
+  it('routes through explicit vertices', () => {
+    const html = renderLinkGraph({ vertices: [{ x: 250, y: 60 }] });
+    // The path must pass through the vertex coordinate.
+    expect(linkPath(html)).toContain('250 60');
+  });
+
+  it('supports point endpoints (no connected element)', () => {
+    const cells: readonly CellRecord[] = [
+      { id: 'l', type: 'link', source: { x: 30, y: 30 }, target: { x: 200, y: 150 } } as CellRecord,
+    ];
+    const html = renderToString(
+      <GraphProvider initialCells={cells}>
+        <Paper renderElement={noElement} style={{ width: 300, height: 220 }} />
+      </GraphProvider>
+    );
+    expect(linkPath(html)).toBe('M 30 30 L 200 150');
+  });
+});
+
+describe('SSR links — preset style', () => {
+  it('applies color, width, dasharray and a custom class', () => {
+    const html = renderLinkGraph({
+      style: { color: '#abcdef', width: 3, dasharray: '5,5', className: 'my-link' } satisfies LinkStyle,
+    });
+    expect(html).toContain('jj-link-line');
+    expect(html).toContain('my-link');
+    expect(html).toContain('#abcdef');
+    expect(html).toMatch(/stroke-dasharray:\s*5,\s*5/);
+  });
+});
+
+describe('SSR links — markers / arrows', () => {
+  it.each(['arrow', 'arrow-open', 'arrow-sunken', 'circle', 'diamond'] as const)(
+    'renders the named "%s" target marker',
+    (markerName) => {
+      const html = renderLinkGraph({ style: { targetMarker: markerName } satisfies LinkStyle });
+      expect(html).toContain('<marker');
+    }
+  );
+
+  it('colors the marker with the link color', () => {
+    const html = renderLinkGraph({ style: { color: '#ff00ff', targetMarker: 'diamond' } satisfies LinkStyle });
+    expect(html).toMatch(/<marker[^>]*(?:stroke|fill)="#ff00ff"/);
+  });
+
+  it('renders both a source and a target marker', () => {
+    const html = renderLinkGraph({ style: { sourceMarker: 'circle', targetMarker: 'arrow' } satisfies LinkStyle });
+    expect((html.match(/<marker/g) ?? []).length).toBe(2);
+  });
+
+  it('renders a custom arrowhead markup', () => {
+    const html = renderLinkGraph({
+      style: {
+        targetMarker: { markup: [{ tagName: 'path', attributes: { d: 'M 0 0 L 8 4 L 8 -4 Z' } }] },
+      } satisfies LinkStyle,
+    });
+    expect(html).toContain('M 0 0 L 8 4');
+  });
+
+  it('renders no marker by default', () => {
+    const html = renderLinkGraph({ style: { color: '#38bdf8' } satisfies LinkStyle });
+    expect(html).not.toContain('<marker');
+  });
+});
+
+describe('SSR links — routing presets', () => {
+  it('smooth routing produces cubic bezier (C) segments', () => {
+    const html = renderLinkGraph({}, linkRoutingSmooth());
+    expect(linkPath(html)).toContain('C');
+  });
+
+  it('straight routing produces a single line segment (no curves)', () => {
+    const html = renderLinkGraph({}, linkRoutingStraight());
+    const path = linkPath(html);
+    expect(path).not.toContain('C');
+    expect((path.match(/L/g) ?? []).length).toBe(1);
+  });
+});
+
+describe('SSR links — labels', () => {
+  it('renders a labelMap label as text on the link', () => {
+    const html = renderLinkGraph({ labelMap: { main: { text: 'HELLO', backgroundColor: '#222' } } });
+    expect(html).toContain('HELLO');
+    expect(html).toContain('class="labels"');
+  });
+
+  // NOTE: label-background *sizing* depends on `getBBox`/`getComputedTextLength`,
+  // which the jest setup (mock-svg in `__mocks__/jest-setup.ts`) stubs to 0. The
+  // real text measurement that drives label size is covered deterministically by
+  // `text-metrics.test.ts` and `svg-polyfills.test.ts` instead.
+});
diff --git a/packages/joint-react/src/server/__tests__/text-style.test.ts b/packages/joint-react/src/server/__tests__/text-style.test.ts
new file mode 100644
index 0000000000..6d77c22bed
--- /dev/null
+++ b/packages/joint-react/src/server/__tests__/text-style.test.ts
@@ -0,0 +1,86 @@
+/**
+ * @jest-environment node
+ *
+ * Unit coverage for the theme-font CSS parser. The server measures SVG text at
+ * the font the theme applies via CSS classes, so this parsing drives link-label
+ * background sizing — it must resolve `var()`, ignore non-text rules, and reject
+ * anything that isn't a lone single-class rule.
+ *
+ * `getTextStyle` (which reads `@joint/react/styles.css` from disk) is exercised
+ * end-to-end by the SSR tests; here jest maps `*.css` to a stub, so this file
+ * tests the parser directly against synthetic stylesheets.
+ */
+import { parseTextStyles } from '../text-style';
+
+describe('parseTextStyles — single-class font rules', () => {
+  it('collects font properties from a lone single-class rule', () => {
+    const map = parseTextStyles('.label { font-size: 11px; font-family: Arial; font-weight: 700; }');
+    expect(map.get('label')).toEqual({ fontSize: '11px', fontFamily: 'Arial', fontWeight: '700' });
+  });
+
+  it('omits classes that declare no font properties', () => {
+    const map = parseTextStyles('.box { fill: red; stroke: blue; }');
+    expect(map.has('box')).toBe(false);
+  });
+
+  it('merges multiple rules for the same class, later declarations winning', () => {
+    const map = parseTextStyles('.label { font-size: 10px; font-family: Arial; } .label { font-size: 12px; }');
+    expect(map.get('label')).toEqual({ fontSize: '12px', fontFamily: 'Arial' });
+  });
+});
+
+describe('parseTextStyles — selector rejection', () => {
+  it.each([
+    ['descendant', '.a .label { font-size: 11px; }'],
+    ['tag-qualified', 'text.label { font-size: 11px; }'],
+    ['child combinator', '.a > .label { font-size: 11px; }'],
+    ['attribute selector', '.label[data-x] { font-size: 11px; }'],
+  ])('ignores a %s selector', (_name, css) => {
+    expect(parseTextStyles(css).has('label')).toBe(false);
+  });
+
+  it('ignores grouped selectors (only the lone-class member would be ambiguous)', () => {
+    const map = parseTextStyles('.a, .label { font-size: 11px; }');
+    expect(map.has('label')).toBe(false);
+    expect(map.has('a')).toBe(false);
+  });
+});
+
+describe('parseTextStyles — var() resolution', () => {
+  it('resolves a class font from a :root custom property', () => {
+    const css = ':root { --label-size: 11px; } .label { font-size: var(--label-size); }';
+    expect(parseTextStyles(css).get('label')).toEqual({ fontSize: '11px' });
+  });
+
+  it('uses the var() fallback when the property is undefined', () => {
+    const map = parseTextStyles('.label { font-size: var(--missing, 9px); }');
+    expect(map.get('label')).toEqual({ fontSize: '9px' });
+  });
+
+  it('captures the first var in a block and is not corrupted by a `:` in a value', () => {
+    const css =
+      ':root { --first: 11px; --image: url(http://example.com/x.png); }' +
+      ' .label { font-size: var(--first); }';
+    expect(parseTextStyles(css).get('label')).toEqual({ fontSize: '11px' });
+  });
+
+  it('chains var() references across passes', () => {
+    const css = ':root { --base: 11px; --label-size: var(--base); } .label { font-size: var(--label-size); }';
+    expect(parseTextStyles(css).get('label')).toEqual({ fontSize: '11px' });
+  });
+});
+
+describe('parseTextStyles — comments', () => {
+  it('strips a comment that would otherwise swallow a rule', () => {
+    const css = '.label { font-size: 11px; } /* .other { font-size: 99px; } */ .next { font-size: 12px; }';
+    const map = parseTextStyles(css);
+    expect(map.get('label')).toEqual({ fontSize: '11px' });
+    expect(map.get('next')).toEqual({ fontSize: '12px' });
+    expect(map.has('other')).toBe(false);
+  });
+
+  it('ignores a `:` inside a comment between declarations', () => {
+    const css = ':root { --a: 11px; /* note: keep */ --b: 12px; } .label { font-size: var(--b); }';
+    expect(parseTextStyles(css).get('label')).toEqual({ fontSize: '12px' });
+  });
+});
diff --git a/packages/joint-react/src/server/index.ts b/packages/joint-react/src/server/index.ts
new file mode 100644
index 0000000000..644d86ec5b
--- /dev/null
+++ b/packages/joint-react/src/server/index.ts
@@ -0,0 +1,35 @@
+// @joint/react/server — enable server-side rendering of `<Paper>`.
+//
+// Import this once, before anything that pulls in `@joint/core` (e.g. as the
+// first import of your SSR entry, or via Next.js `instrumentation.ts`):
+//
+//   import '@joint/react/server';
+//
+// It installs a headless DOM and registers the server paper renderer, so a plain
+// `<GraphProvider><Paper renderElement={…} /></GraphProvider>` rendered with
+// `renderToString` (from `react-dom/server`) emits the full diagram SVG — which
+// then hydrates into the live, interactive paper on the client.
+
+// Side effects, in order: `@joint/svg-shim/install` installs the shim, and must
+// run before `./render/build-paper-tree` (which evaluates `@joint/core`) — ES
+// modules evaluate imports in source order.
+import '@joint/svg-shim/install';
+import { setTextStyleResolver } from '@joint/svg-shim';
+import { getTextStyle } from './text-style';
+import { registerServerPaperRenderer } from '../utils/server-paper-renderer';
+import { buildPaperReactTree } from './render/build-paper-tree';
+
+// Teach the (framework-agnostic) shim how `@joint/react`'s theme sizes text, so
+// label/port backgrounds are measured at the size the browser renders.
+setTextStyleResolver(getTextStyle);
+registerServerPaperRenderer(buildPaperReactTree);
+
+// Advanced: choose a different DOM provider before the shim auto-installs.
+// `isDomShimInstalled` is a diagnostic companion (whether the shim has run).
+export { installDomShim, isDomShimInstalled } from '@joint/svg-shim';
+export type {
+  DomShimOptions,
+  DomProvider,
+  ShimWindow,
+  ShimWindowFactory,
+} from '@joint/svg-shim';
diff --git a/packages/joint-react/src/server/render/build-paper-tree.tsx b/packages/joint-react/src/server/render/build-paper-tree.tsx
new file mode 100644
index 0000000000..b4b64d20df
--- /dev/null
+++ b/packages/joint-react/src/server/render/build-paper-tree.tsx
@@ -0,0 +1,31 @@
+import { setupServerPaper, collectCellContents } from './build-paper';
+import { hostChildrenToReact } from './dom-to-react';
+import type {
+  ServerPaperRenderOptions,
+  ServerPaperRenderResult,
+} from '../../utils/server-paper-renderer';
+
+/**
+ * Builds a paper's diagram as a React node tree (not a string). This is the
+ * renderer `<Paper>` uses during SSR: the returned tree is rendered by the outer
+ * `renderToString`, so `renderElement` content renders natively in the same pass
+ * — no nested `renderToStaticMarkup`.
+ *
+ * The host DOM is detached, but the paper + store are intentionally left alive:
+ * the tree's spliced `renderElement` nodes reference them via context, so they
+ * must outlive this call. Both are short-lived and GC'd with the SSR response.
+ * @param options - graph, store, renderers, and paper options.
+ * @returns the diagram React tree and the host size used.
+ */
+export function buildPaperReactTree(options: ServerPaperRenderOptions): ServerPaperRenderResult {
+  const setup = setupServerPaper(options);
+  try {
+    const contents = collectCellContents(setup, options);
+    const tree = hostChildrenToReact(setup.host, contents);
+    return { tree, width: setup.width, height: setup.height };
+  } finally {
+    // Always detach the host, even if building throws — otherwise a failed build
+    // would leak a detached subtree into the shared headless DOM.
+    setup.host.remove();
+  }
+}
diff --git a/packages/joint-react/src/server/render/build-paper.tsx b/packages/joint-react/src/server/render/build-paper.tsx
new file mode 100644
index 0000000000..e3f1df1781
--- /dev/null
+++ b/packages/joint-react/src/server/render/build-paper.tsx
@@ -0,0 +1,212 @@
+import type { ReactNode } from 'react';
+import type { dia } from '@joint/core';
+import { PaperStore } from '../../store/paper-store';
+import { ReactPaper } from '../../models/react-paper';
+import { GraphStoreContext, PaperStoreContext, CellIdContext } from '../../context';
+import { defaultRenderElement } from '../../components/paper/default-render-element';
+import type { CellId, ElementRecord, LinkRecord } from '../../types/cell.types';
+import type {
+  ServerPaperRenderOptions,
+  AnyGraphStore,
+  AnyRenderer,
+} from '../../utils/server-paper-renderer';
+
+/** No-op that detaches the paper from graph-store view-sync after the build. */
+const NOOP_VIEW_MOUNT_CHANGE = (): void => {};
+
+interface ServerCellProvidersProps {
+  readonly graphStore: AnyGraphStore;
+  readonly paperStore: PaperStore;
+  readonly cellId: CellId;
+  readonly children: ReactNode;
+}
+
+/**
+ * Supplies the store + cell contexts a `renderElement` / `renderLink` may read
+ * via hooks (`useCell`, `useCellId`, `useGraphStore`, `usePaper`, `useMeasureNode`).
+ * @param props - the contexts and children to provide.
+ * @returns the children wrapped in the joint-react server contexts.
+ */
+function ServerCellProviders(props: Readonly<ServerCellProvidersProps>): ReactNode {
+  const { graphStore, paperStore, cellId, children } = props;
+  return (
+    <GraphStoreContext.Provider value={graphStore}>
+      <PaperStoreContext.Provider value={paperStore}>
+        <CellIdContext.Provider value={cellId}>{children}</CellIdContext.Provider>
+      </PaperStoreContext.Provider>
+    </GraphStoreContext.Provider>
+  );
+}
+
+/** Derives `[width, height]` from the graph content box when not explicitly set. */
+function resolveSize(
+  graph: dia.Graph,
+  width: number | undefined,
+  height: number | undefined
+): readonly [number, number] {
+  if (width !== undefined && height !== undefined) {
+    return [width, height];
+  }
+  const contentBox = graph.getBBox();
+  const derivedWidth = contentBox ? Math.ceil(contentBox.x + contentBox.width) : 0;
+  const derivedHeight = contentBox ? Math.ceil(contentBox.y + contentBox.height) : 0;
+  return [width ?? derivedWidth, height ?? derivedHeight];
+}
+
+/** A built-and-mounted server paper, ready to read views from. */
+export interface ServerPaperSetup {
+  readonly paper: ReactPaper;
+  readonly paperStore: PaperStore;
+  readonly host: HTMLElement;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * Builds a JointJS paper synchronously in the headless DOM with every view
+ * mounted, so its DOM can be converted to a React tree. Assumes the DOM shim is
+ * installed (the `@joint/react/server` entry guarantees this).
+ * @param options - graph, store, and paper options.
+ * @returns the mounted paper, its store, host element, and resolved size.
+ */
+export function setupServerPaper(options: ServerPaperRenderOptions): ServerPaperSetup {
+  const { graph, graphStore, portalSelector, paperId, width, height, paperOptions } = options;
+  const [resolvedWidth, resolvedHeight] = resolveSize(graph, width, height);
+
+  const host = document.createElement('div');
+  document.body.append(host);
+
+  const paper = new ReactPaper({
+    model: graph,
+    id: paperId,
+    portalSelector,
+    el: host,
+    ...paperOptions,
+    // joint-react-controlled options: forced for synchronous, fully-mounted
+    // server rendering. Must come after `paperOptions` so they cannot be undone.
+    width: resolvedWidth,
+    height: resolvedHeight,
+    async: false,
+    // Construct frozen so `super()` (dia.Paper) does NOT render cells before
+    // ReactPaper's class fields (`viewChanges`, ...) initialize — JS runs field
+    // initializers only after `super()` returns. We unfreeze right after.
+    frozen: true,
+    autoFreeze: false,
+    viewManagement: { disposeHidden: false, lazyInitialize: false },
+  });
+
+  // unfreeze starts rendering; updateViews flushes all scheduled updates
+  // synchronously (`async: false`, no viewport culling, eager view init).
+  paper.unfreeze();
+  paper.updateViews();
+
+  // Reveal every link. ReactPaper hides a link (visibility:hidden) until its
+  // endpoints' React content has mounted into the DOM — but during SSR that
+  // content is spliced into the React tree separately, so the portals are empty
+  // at build time. On the server every element renders, so all links are shown.
+  for (const linkCell of graph.getLinks()) {
+    const linkView = paper.getLinkView(linkCell.id as CellId);
+    if (linkView?.el) {
+      linkView.el.style.visibility = '';
+    }
+  }
+
+  // PaperStore backs `usePaper()` inside renderers. Neutralize its graph-store
+  // view-sync callback: the build is one-shot.
+  const paperStore = new PaperStore({ graphStore, id: paperId, paper, paperOptions: {} });
+  paper.onViewMountChange = NOOP_VIEW_MOUNT_CHANGE;
+
+  return { paper, paperStore, host, width: resolvedWidth, height: resolvedHeight };
+}
+
+/** Wraps a cell's renderer output in the server cell contexts. */
+function createCellContentNode(
+  renderer: AnyRenderer,
+  data: Record<string, unknown>,
+  graphStore: AnyGraphStore,
+  paperStore: PaperStore,
+  cellId: CellId
+): ReactNode {
+  const Renderer = renderer as (data: Record<string, unknown>) => ReactNode;
+  return (
+    <ServerCellProviders graphStore={graphStore} paperStore={paperStore} cellId={cellId}>
+      <Renderer {...data} />
+    </ServerCellProviders>
+  );
+}
+
+/** Reads a cell's `data` slice from the store projection. */
+function getCellData(graphStore: AnyGraphStore, cellId: CellId): Record<string, unknown> {
+  const record = graphStore.graphProjection.cells.get(cellId) as
+    | ElementRecord
+    | LinkRecord
+    | undefined;
+  return (record?.data as Record<string, unknown> | undefined) ?? {};
+}
+
+/** Resolves a cell's view from the paper (element or link). */
+type CellViewLookup = (cellId: CellId) => dia.CellView | undefined;
+
+/**
+ * Maps each cell's portal node to its React content node (renderer + contexts),
+ * for one cell kind (elements or links).
+ */
+function collectCellKindContents(
+  setup: ServerPaperSetup,
+  graphStore: AnyGraphStore,
+  cells: readonly dia.Cell[],
+  getView: CellViewLookup,
+  renderer: AnyRenderer,
+  contents: Map<Element, ReactNode>
+): void {
+  const { paper, paperStore } = setup;
+  for (const cell of cells) {
+    const cellId = cell.id as CellId;
+    const view = getView(cellId);
+    if (!view) continue;
+    const portalNode = paper.getCellViewPortalNode(view);
+    if (!portalNode) continue;
+    const data = getCellData(graphStore, cellId);
+    contents.set(portalNode, createCellContentNode(renderer, data, graphStore, paperStore, cellId));
+  }
+}
+
+/**
+ * Maps each cell's portal node to its React content node (renderer + contexts),
+ * for splicing into the converted React tree.
+ * @param setup - the mounted server paper.
+ * @param options - render options (graph, renderers, store).
+ * @returns a map of portal DOM node to React content.
+ */
+export function collectCellContents(
+  setup: ServerPaperSetup,
+  options: ServerPaperRenderOptions
+): Map<Element, ReactNode> {
+  const { paper } = setup;
+  const { graph, graphStore } = options;
+  const renderElement = options.renderElement ?? defaultRenderElement;
+  const { renderLink } = options;
+  const contents = new Map<Element, ReactNode>();
+
+  collectCellKindContents(
+    setup,
+    graphStore,
+    graph.getElements(),
+    (cellId) => paper.getElementView(cellId),
+    renderElement,
+    contents
+  );
+
+  if (renderLink) {
+    collectCellKindContents(
+      setup,
+      graphStore,
+      graph.getLinks(),
+      (cellId) => paper.getLinkView(cellId),
+      renderLink,
+      contents
+    );
+  }
+
+  return contents;
+}
diff --git a/packages/joint-react/src/server/render/dom-to-react.tsx b/packages/joint-react/src/server/render/dom-to-react.tsx
new file mode 100644
index 0000000000..583b74b0ce
--- /dev/null
+++ b/packages/joint-react/src/server/render/dom-to-react.tsx
@@ -0,0 +1,187 @@
+import { createElement, type ReactNode } from 'react';
+
+/**
+ * Converts a JointJS-built DOM subtree into React elements so the outer
+ * `renderToString` serializes it in a single pass — no nested
+ * `renderToStaticMarkup` (which would corrupt React's hooks dispatcher).
+ *
+ * Portal nodes are not converted recursively: their React content (a
+ * `renderElement` / `renderLink` node) is spliced in as children, so user hooks
+ * run in the outer render with the right contexts.
+ */
+
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+const STYLE_TAG = 'style';
+
+/**
+ * Standard SVG / namespaced attribute names that React expects in camelCase.
+ * Names not listed here (custom attributes like `joint-selector`, `model-id`,
+ * `data-*`, `aria-*`) are passed through unchanged.
+ */
+const SVG_ATTRIBUTE_NAME_MAP: Readonly<Record<string, string>> = {
+  'xmlns:xlink': 'xmlnsXlink',
+  'xlink:href': 'xlinkHref',
+  'xlink:show': 'xlinkShow',
+  'xlink:role': 'xlinkRole',
+  'xlink:title': 'xlinkTitle',
+  'xlink:actuate': 'xlinkActuate',
+  'xlink:arcrole': 'xlinkArcrole',
+  'xlink:type': 'xlinkType',
+  'xml:space': 'xmlSpace',
+  'xml:lang': 'xmlLang',
+  'xml:base': 'xmlBase',
+  'pointer-events': 'pointerEvents',
+  'stroke-width': 'strokeWidth',
+  'stroke-linecap': 'strokeLinecap',
+  'stroke-linejoin': 'strokeLinejoin',
+  'stroke-dasharray': 'strokeDasharray',
+  'stroke-dashoffset': 'strokeDashoffset',
+  'stroke-opacity': 'strokeOpacity',
+  'stroke-miterlimit': 'strokeMiterlimit',
+  'fill-opacity': 'fillOpacity',
+  'fill-rule': 'fillRule',
+  'clip-path': 'clipPath',
+  'clip-rule': 'clipRule',
+  'color-interpolation-filters': 'colorInterpolationFilters',
+  'vector-effect': 'vectorEffect',
+  'text-anchor': 'textAnchor',
+  'dominant-baseline': 'dominantBaseline',
+  'alignment-baseline': 'alignmentBaseline',
+  'baseline-shift': 'baselineShift',
+  'font-family': 'fontFamily',
+  'font-size': 'fontSize',
+  'font-weight': 'fontWeight',
+  'font-style': 'fontStyle',
+  'letter-spacing': 'letterSpacing',
+  'word-spacing': 'wordSpacing',
+  'paint-order': 'paintOrder',
+  'stop-color': 'stopColor',
+  'stop-opacity': 'stopOpacity',
+  'flood-color': 'floodColor',
+  'flood-opacity': 'floodOpacity',
+  'marker-start': 'markerStart',
+  'marker-mid': 'markerMid',
+  'marker-end': 'markerEnd',
+  'shape-rendering': 'shapeRendering',
+  'text-rendering': 'textRendering',
+  'image-rendering': 'imageRendering',
+  'color-interpolation': 'colorInterpolation',
+  'writing-mode': 'writingMode',
+  'unicode-bidi': 'unicodeBidi',
+};
+
+/** Maps a DOM attribute name to the React prop name React expects. */
+function mapAttributeName(name: string): string {
+  return SVG_ATTRIBUTE_NAME_MAP[name] ?? name;
+}
+
+/** Parses an inline `style` string into a React style object (camelCased keys). */
+function styleStringToObject(style: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const declaration of style.split(';')) {
+    const separator = declaration.indexOf(':');
+    if (separator === -1) {
+      continue;
+    }
+    const rawKey = declaration.slice(0, separator).trim();
+    const value = declaration.slice(separator + 1).trim();
+    if (rawKey === '' || value === '') {
+      continue;
+    }
+    // CSS custom properties keep their literal `--name`; other props are camelCased.
+    const key = rawKey.startsWith('--')
+      ? rawKey
+      : rawKey.replaceAll(/-([a-z])/g, (_, character: string) => character.toUpperCase());
+    result[key] = value;
+  }
+  return result;
+}
+
+/** Builds React props from a DOM element's attributes. */
+function attributesToProps(element: Element, key: string): Record<string, unknown> {
+  const props: Record<string, unknown> = { key };
+  for (const attribute of element.attributes) {
+    if (attribute.name === 'class') {
+      props.className = attribute.value;
+    } else if (attribute.name === 'style') {
+      props.style = styleStringToObject(attribute.value);
+    } else {
+      // Standard SVG attributes are camelCased for React; custom attributes
+      // (`joint-selector`, `model-id`, `data-*`, …) pass through unchanged.
+      props[mapAttributeName(attribute.name)] = attribute.value;
+    }
+  }
+  return props;
+}
+
+/** Mutable counter so sibling React elements get stable, unique keys. */
+interface KeyCounter {
+  value: number;
+}
+
+/**
+ * Recursively converts a DOM node to a React node.
+ * @param node - the DOM node to convert.
+ * @param portalContent - map of portal DOM nodes to the React content to splice in.
+ * @param counter - shared key counter.
+ * @returns the converted React node (or `null` to skip).
+ */
+export function domNodeToReact(
+  node: Node,
+  portalContent: ReadonlyMap<Element, ReactNode>,
+  counter: KeyCounter
+): ReactNode {
+  if (node.nodeType === TEXT_NODE) {
+    return node.textContent;
+  }
+  if (node.nodeType !== ELEMENT_NODE) {
+    return null;
+  }
+  const element = node as Element;
+  const props = attributesToProps(element, `n${counter.value++}`);
+
+  const spliced = portalContent.get(element);
+  if (spliced !== undefined) {
+    return createElement(element.localName, props, spliced);
+  }
+
+  // `<style>` holds CSS text — emit it via dangerouslySetInnerHTML so React
+  // doesn't escape it.
+  if (element.localName === STYLE_TAG) {
+    props.dangerouslySetInnerHTML = { __html: element.textContent ?? '' };
+    return createElement(element.localName, props);
+  }
+
+  const children = convertChildNodes(element.childNodes, portalContent, counter);
+  return createElement(element.localName, props, ...children);
+}
+
+/** Converts a node's children to React nodes, dropping empty/skipped ones. */
+function convertChildNodes(
+  childNodes: NodeListOf<ChildNode>,
+  portalContent: ReadonlyMap<Element, ReactNode>,
+  counter: KeyCounter
+): ReactNode[] {
+  const result: ReactNode[] = [];
+  for (const childNode of childNodes) {
+    const child = domNodeToReact(childNode, portalContent, counter);
+    if (child != null && child !== '') {
+      result.push(child);
+    }
+  }
+  return result;
+}
+
+/**
+ * Converts every child of a host element to React nodes.
+ * @param host - the paper host whose children to convert.
+ * @param portalContent - map of portal DOM nodes to React content to splice in.
+ * @returns the converted React nodes.
+ */
+export function hostChildrenToReact(
+  host: Element,
+  portalContent: ReadonlyMap<Element, ReactNode>
+): ReactNode[] {
+  return convertChildNodes(host.childNodes, portalContent, { value: 0 });
+}
diff --git a/packages/joint-react/src/server/text-style.ts b/packages/joint-react/src/server/text-style.ts
new file mode 100644
index 0000000000..94246d63a6
--- /dev/null
+++ b/packages/joint-react/src/server/text-style.ts
@@ -0,0 +1,161 @@
+import type fs from 'node:fs';
+import { getNodeRequire } from '@joint/svg-shim';
+import type { TextStyle } from '@joint/svg-shim';
+
+/**
+ * `@joint/react`'s theme-font resolver — wired into the shim by
+ * `@joint/react/server`. It resolves the font properties the theme applies to SVG
+ * text via CSS classes (e.g. `.jj-link-label { font-size: 11px }`), so the server
+ * measures text at the size/family the browser renders — most visibly link-label
+ * backgrounds.
+ *
+ * Parses the package's own stylesheet into a `class → font` map (resolving its
+ * `var()` references against its `:root` defaults) rather than relying on jsdom's
+ * `getComputedStyle`, which resolves stylesheet rules inconsistently across
+ * runtimes (notably Bun) and only for attached elements.
+ */
+
+const VARIABLE_REFERENCE = /var\((--[\w-]+)(?:,([^)]*))?\)/g;
+// Custom-property definitions, anchored after a `{`, `;`, or `}` boundary so the
+// FIRST declaration in a block is captured and a preceding selector/comment can't
+// glue onto it. The value stops at the next `;` or `}`, so a value containing `:`
+// (e.g. `url(http://x)`) does not corrupt the following declaration.
+const VARIABLE_DEFINITION = /[{;}]\s*(--[\w-]+)\s*:\s*([^;}]+)/g;
+// Lone single-class rules (`.name { ... }`) only. Compound, descendant, and
+// tag-qualified selectors (`.a .b`, `rect.bg`, `.a, .b`) are intentionally NOT
+// matched — the themed text classes (`.jj-link-label`, `.jj-port-label`) are
+// plain single-class rules. A lookbehind anchors the selector to a `{`/`}`/start
+// boundary (without consuming it, so adjacent rules are not skipped); the capture
+// runs to the rule's `{`, and a guard rejects anything that isn't a bare `.name`.
+const CLASS_RULE = /(?<=^|[{}])\s*(\.[\w-]+)\s*\{([^}]*)\}/g;
+// A bare single-class selector: a leading `.` then one class name, nothing else
+// (no combinator, second class, attribute selector, or tag qualifier).
+const SINGLE_CLASS_SELECTOR = /^\.([\w-]+)$/;
+const FONT_SIZE_DECLARATION = /font-size:\s*([^;]+)/;
+const FONT_FAMILY_DECLARATION = /font-family:\s*([^;]+)/;
+const FONT_WEIGHT_DECLARATION = /font-weight:\s*([^;]+)/;
+// CSS variables can reference other variables; a few passes resolve the chain.
+const MAX_RESOLUTION_PASSES = 5;
+
+let cachedFontMap: ReadonlyMap<string, TextStyle> | undefined;
+
+/**
+ * Collects `--name: value` custom-property definitions into a `name → value` map.
+ * Each definition is matched at a `{`/`;`/`}` boundary, so the first declaration of
+ * a block is captured and the value (which may itself contain `:`) cannot bleed
+ * into the next declaration.
+ */
+function collectVariableDefinitions(css: string): Map<string, string> {
+  const values = new Map<string, string>();
+  for (const [, name, value] of css.matchAll(VARIABLE_DEFINITION)) {
+    values.set(name, value.trim());
+  }
+  return values;
+}
+
+/** Strips CSS block comments, so they cannot corrupt declaration parsing. */
+function stripComments(css: string): string {
+  return css.replaceAll(/\/\*[\s\S]*?\*\//g, '');
+}
+
+/** Resolves `var(--x[, fallback])` against the stylesheet's own `:root` defaults. */
+function resolveCssVariables(css: string): string {
+  const values = collectVariableDefinitions(css);
+
+  let resolved = css;
+  for (let pass = 0; pass < MAX_RESOLUTION_PASSES; pass++) {
+    const next = resolved.replaceAll(
+      VARIABLE_REFERENCE,
+      (match, name: string, fallback?: string) => values.get(name) ?? fallback?.trim() ?? match
+    );
+    if (next === resolved) {
+      break;
+    }
+    resolved = next;
+  }
+  return resolved;
+}
+
+/** Extracts a declaration's value from a rule body, when present. */
+function declarationValue(body: string, pattern: RegExp): string | undefined {
+  return pattern.exec(body)?.[1]?.trim();
+}
+
+/** Builds the `class → font` map from resolved CSS. */
+function buildFontMap(css: string): Map<string, TextStyle> {
+  const map = new Map<string, TextStyle>();
+  for (const [, selector, body] of css.matchAll(CLASS_RULE)) {
+    const singleClass = SINGLE_CLASS_SELECTOR.exec(selector);
+    if (!singleClass) {
+      continue;
+    }
+    const [, className] = singleClass;
+    const font: TextStyle = {
+      fontSize: declarationValue(body, FONT_SIZE_DECLARATION),
+      fontFamily: declarationValue(body, FONT_FAMILY_DECLARATION),
+      fontWeight: declarationValue(body, FONT_WEIGHT_DECLARATION),
+    };
+    if (font.fontSize === undefined && font.fontFamily === undefined && font.fontWeight === undefined) {
+      continue;
+    }
+    map.set(className, { ...map.get(className), ...stripUndefined(font) });
+  }
+  return map;
+}
+
+/** Drops `undefined` entries so merges don't overwrite real values with gaps. */
+function stripUndefined(font: TextStyle): TextStyle {
+  const result: { fontSize?: string; fontFamily?: string; fontWeight?: string } = {};
+  if (font.fontSize !== undefined) result.fontSize = font.fontSize;
+  if (font.fontFamily !== undefined) result.fontFamily = font.fontFamily;
+  if (font.fontWeight !== undefined) result.fontWeight = font.fontWeight;
+  return result;
+}
+
+/**
+ * Parses a stylesheet into a `class → font` map: strips comments, resolves the
+ * sheet's own `var()` references, then collects lone single-class font rules.
+ * @param css - the raw stylesheet text.
+ * @returns the `class → font` map (empty when no themed text classes exist).
+ */
+export function parseTextStyles(css: string): ReadonlyMap<string, TextStyle> {
+  return buildFontMap(resolveCssVariables(stripComments(css)));
+}
+
+/** Loads + parses `@joint/react`'s stylesheet once, or an empty map if unavailable. */
+function getFontMap(): ReadonlyMap<string, TextStyle> {
+  if (cachedFontMap !== undefined) {
+    return cachedFontMap;
+  }
+  cachedFontMap = new Map();
+  try {
+    const nodeRequire = getNodeRequire();
+    const cssPath = nodeRequire.resolve('@joint/react/styles.css');
+    const { readFileSync } = nodeRequire('node:fs') as typeof fs;
+    cachedFontMap = parseTextStyles(readFileSync(cssPath, 'utf8'));
+  } catch {
+    cachedFontMap = new Map();
+  }
+  return cachedFontMap;
+}
+
+/**
+ * Resolves the theme font properties for a `class` attribute. Later classes win,
+ * mirroring same-specificity CSS ordering.
+ * @param classAttribute - the element's `class` attribute value.
+ * @returns the merged theme font for those classes (empty when none apply).
+ */
+export function getTextStyle(classAttribute: string): TextStyle {
+  const map = getFontMap();
+  if (map.size === 0 || classAttribute === '') {
+    return {};
+  }
+  let result: TextStyle = {};
+  for (const className of classAttribute.split(/\s+/)) {
+    const font = map.get(className);
+    if (font) {
+      result = { ...result, ...font };
+    }
+  }
+  return result;
+}
diff --git a/packages/joint-react/src/store/__tests__/update-layout-state.test.ts b/packages/joint-react/src/store/__tests__/update-layout-state.test.ts
index 1963f20e41..3ca982f522 100644
--- a/packages/joint-react/src/store/__tests__/update-layout-state.test.ts
+++ b/packages/joint-react/src/store/__tests__/update-layout-state.test.ts
@@ -13,7 +13,9 @@ type LooseElement = dia.Element & {
 describe('getElementLayoutFields', () => {
   it('returns null when the element has no size attribute', () => {
     const element = new dia.Element() as LooseElement;
-    // dia.Element has a default size; force it to undefined to exercise the early return
+    // dia.Element has a default size; force it to undefined to exercise the early return.
+    // `set(key, undefined)` is intentional and differs from omitting the value.
+    // eslint-disable-next-line sonarjs/no-undefined-argument
     element.set('size', undefined);
     expect(getElementLayoutFields(element)).toBeNull();
   });
@@ -35,6 +37,7 @@ describe('getElementLayoutFields', () => {
     const element = new dia.Element({
       size: { width: 100, height: 50 },
     }) as LooseElement;
+    // eslint-disable-next-line sonarjs/no-undefined-argument
     element.set('position', undefined);
     const result = getElementLayoutFields(element);
     expect(result?.position).toEqual({ x: 0, y: 0 });
diff --git a/packages/joint-react/src/store/create-elements-size-observer.ts b/packages/joint-react/src/store/create-elements-size-observer.ts
index d7a78f1ab4..4cb76c7369 100644
--- a/packages/joint-react/src/store/create-elements-size-observer.ts
+++ b/packages/joint-react/src/store/create-elements-size-observer.ts
@@ -16,6 +16,17 @@ import type { ElementLayout } from '../types/cell.types';
 import type { ElementJSONInit } from '../types/cell.types';
 
 const DEFAULT_OBSERVER_OPTIONS: ResizeObserverOptions = { box: 'border-box' };
+
+/**
+ * No-op stand-in used when `ResizeObserver` is unavailable (server-side
+ * rendering). There is nothing to measure without a DOM, so observe / unobserve
+ * / disconnect are inert — this keeps `GraphStore` construction SSR-safe.
+ */
+const NOOP_RESIZE_OBSERVER: ResizeObserver = {
+  observe() {},
+  unobserve() {},
+  disconnect() {},
+};
 // Epsilon value to avoid jitter due to sub-pixel rendering
 // especially on Safari
 const EPSILON = 0.5;
@@ -229,7 +240,7 @@ export function createElementsSizeObserver(options: Options): GraphStoreObserver
     activeObservedElementByDomNode.delete(observedElement.node);
   }
 
-  const observer = new ResizeObserver((entries) => {
+  const handleResize: ResizeObserverCallback = (entries) => {
     let hasAnySizeChange = false;
     const elements = getElements();
     const mutableLayouts: Record<CellId, ElementLayoutOptionalXY> = {};
@@ -277,7 +288,14 @@ export function createElementsSizeObserver(options: Options): GraphStoreObserver
     }
 
     onBatchUpdate(mutableLayouts);
-  });
+  };
+
+  // Guarded so `GraphStore` can be constructed during server rendering, where
+  // `ResizeObserver` does not exist. The no-op observer never fires.
+  const observer: ResizeObserver =
+    typeof ResizeObserver === 'undefined'
+      ? NOOP_RESIZE_OBSERVER
+      : new ResizeObserver(handleResize);
 
   return {
     add({ id, node, transform }: SetMeasuredNodeOptions) {
diff --git a/packages/joint-react/src/stories/demos/flowchart/code.tsx b/packages/joint-react/src/stories/demos/flowchart/code.tsx
index 8c10a0d5e8..51c0a44bb2 100644
--- a/packages/joint-react/src/stories/demos/flowchart/code.tsx
+++ b/packages/joint-react/src/stories/demos/flowchart/code.tsx
@@ -3,8 +3,20 @@
 /* eslint-disable react-perf/jsx-no-new-object-as-prop */
 
 import './index.css';
-import type { CellRecord, ElementRecord, LinkRecord, LinkLabel, TransformOptions } from '@joint/react';
-import { GraphProvider, Paper, useMarkup, useMeasureNode, useNodesMeasuredEffect } from '@joint/react';
+import type {
+  CellRecord,
+  ElementRecord,
+  LinkRecord,
+  LinkLabel,
+  TransformOptions,
+} from '@joint/react';
+import {
+  GraphProvider,
+  Paper,
+  useMarkup,
+  useMeasureNode,
+  useNodesMeasuredEffect,
+} from '@joint/react';
 import { PAPER_CLASSNAME } from 'storybook-config/theme';
 import { dia, highlighters, linkTools } from '@joint/core';
 import { linkRoutingOrthogonal } from '@joint/react/presets';
@@ -31,7 +43,12 @@ type ElementData = {
 // top-left coincides with center, and `autoSizeOrigin="center"` preserves
 // that center through the first DOM measurement.
 const flowchartElements: Array<ElementRecord<ElementData>> = [
-  { id: 'start', type: 'element', data: { label: 'Start', type: 'start' }, position: { x: 60, y: 40 } },
+  {
+    id: 'start',
+    type: 'element',
+    data: { label: 'Start', type: 'start' },
+    position: { x: 60, y: 40 },
+  },
   {
     id: 'addToCart',
     type: 'element',
@@ -254,7 +271,10 @@ const flowchartLinks: LinkRecord[] = [
   },
 ];
 
-const initialCells: ReadonlyArray<CellRecord<ElementData>> = [...flowchartElements, ...flowchartLinks];
+const initialCells: ReadonlyArray<CellRecord<ElementData>> = [
+  ...flowchartElements,
+  ...flowchartLinks,
+];
 
 interface PropsWithClick {
   readonly onMouseEnter?: () => void;
@@ -422,7 +442,8 @@ function Main() {
   });
 
   return (
-    <Paper style={{ height: 600 }}
+    <Paper
+      style={{ height: 600 }}
       ref={paperRef}
       gridSize={5}
       overflow
diff --git a/packages/joint-react/src/utils/__tests__/is.test.ts b/packages/joint-react/src/utils/__tests__/is.test.ts
index bf3b04ad83..3acb5d7b13 100644
--- a/packages/joint-react/src/utils/__tests__/is.test.ts
+++ b/packages/joint-react/src/utils/__tests__/is.test.ts
@@ -68,6 +68,8 @@ describe('is.ts utility functions', () => {
     });
 
     test('returns false when property is undefined', () => {
+      // Passing `undefined` explicitly is the case under test.
+      // eslint-disable-next-line sonarjs/no-undefined-argument
       expect(is.hasProperty({ foo: 1 }, undefined)).toBe(false);
     });
 
diff --git a/packages/joint-react/src/utils/server-paper-renderer.ts b/packages/joint-react/src/utils/server-paper-renderer.ts
new file mode 100644
index 0000000000..f607f24b76
--- /dev/null
+++ b/packages/joint-react/src/utils/server-paper-renderer.ts
@@ -0,0 +1,91 @@
+/**
+ * Client-safe registry for the server-side paper renderer.
+ *
+ * `<Paper>` calls the registered renderer during server rendering to build its
+ * diagram markup inline — so `renderToString(<GraphProvider><Paper/></GraphProvider>)`
+ * "just works". The renderer itself (which pulls `@joint/core` + `react-dom/server`)
+ * lives in `@joint/react/server` and is injected by importing
+ * `@joint/react/server`. Keeping it behind this registry means the
+ * browser bundle never imports the server renderer.
+ *
+ * All type imports here are erased at compile time, so this module stays free of
+ * runtime `@joint/core` / server dependencies.
+ */
+import type { ReactNode } from 'react';
+import type { dia } from '@joint/core';
+import type { GraphStore } from '../store/graph-store';
+import type { RenderElement, RenderLink } from '../components/paper/paper.types';
+import type { PortalSelector } from '../models/react-paper.types';
+
+/**
+ * A graph store with its element/link types erased. The server renderer is generic
+ * over any consumer's cell data, so the `any` type arguments are an intentional
+ * boundary the renderer treats opaquely.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyGraphStore = GraphStore<any, any>;
+
+/** An element or link renderer with its data type erased — see {@link AnyGraphStore}. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyRenderer = RenderElement<any> | RenderLink<any>;
+
+/** Input for the registered server paper renderer. */
+export interface ServerPaperRenderOptions {
+  /** The graph to render (from the `GraphProvider` store). */
+  readonly graph: dia.Graph;
+  /** The graph store, used to supply cell contexts to the renderers. */
+  readonly graphStore: AnyGraphStore;
+  /** Element renderer. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly renderElement?: RenderElement<any>;
+  /** Link renderer. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly renderLink?: RenderLink<any>;
+  /** Portal target override. */
+  readonly portalSelector?: PortalSelector;
+  /** Paper id. */
+  readonly paperId: string;
+  /** Host width, when known (else derived from content). */
+  readonly width?: number;
+  /** Host height, when known (else derived from content). */
+  readonly height?: number;
+  /** Extra `dia.Paper.Options` (grid, background, …). */
+  readonly paperOptions?: Partial<dia.Paper.Options>;
+}
+
+/** Output of the registered server paper renderer. */
+export interface ServerPaperRenderResult {
+  /**
+   * The diagram as a React node tree. Rendered by the outer `renderToString`, so
+   * `renderElement` content renders natively (no nested `renderToStaticMarkup`).
+   */
+  readonly tree: ReactNode;
+  /** Host width used. */
+  readonly width: number;
+  /** Host height used. */
+  readonly height: number;
+}
+
+/** Builds a paper's host markup synchronously on the server. */
+export type ServerPaperRenderer = (options: ServerPaperRenderOptions) => ServerPaperRenderResult;
+
+let registeredRenderer: ServerPaperRenderer | undefined;
+
+/**
+ * Registers the server paper renderer. Called once by `@joint/react/server` at
+ * import time.
+ * @param renderer - the renderer implementation.
+ */
+export function registerServerPaperRenderer(renderer: ServerPaperRenderer): void {
+  registeredRenderer = renderer;
+}
+
+/**
+ * The registered server paper renderer, or `undefined` when none is registered
+ * (i.e. the server entry was not preloaded — `<Paper>` then renders nothing on
+ * the server and mounts on the client as usual).
+ * @returns the registered renderer, if any.
+ */
+export function getServerPaperRenderer(): ServerPaperRenderer | undefined {
+  return registeredRenderer;
+}
diff --git a/packages/joint-react/src/utils/ssr.ts b/packages/joint-react/src/utils/ssr.ts
new file mode 100644
index 0000000000..595c210d38
--- /dev/null
+++ b/packages/joint-react/src/utils/ssr.ts
@@ -0,0 +1,25 @@
+/**
+ * Client-safe helpers for detecting a server render. Imports the shim's flag
+ * *constant* from the dedicated `@joint/svg-shim/flag` subpath — a single string
+ * with zero Node imports — so the browser bundle never pulls the Node-only shim
+ * barrel (jsdom, canvas, `node:module`).
+ */
+import { DOM_SHIM_FLAG } from '@joint/svg-shim/flag';
+
+export { DOM_SHIM_FLAG } from '@joint/svg-shim/flag';
+
+/**
+ * Whether the current render is happening on the server (no real browser DOM).
+ *
+ * True when there is no `document` at all, or when the server DOM shim is
+ * installed (a headless `document` exists but React effects still do not run).
+ * Evaluated at call time so it reflects the shim being installed after module
+ * load.
+ * @returns `true` during server-side rendering.
+ */
+export function isServerEnvironment(): boolean {
+  if (typeof document === 'undefined') {
+    return true;
+  }
+  return (globalThis as Record<string, unknown>)[DOM_SHIM_FLAG] === true;
+}
diff --git a/packages/joint-svg-shim/.gitignore b/packages/joint-svg-shim/.gitignore
new file mode 100644
index 0000000000..1fae91e954
--- /dev/null
+++ b/packages/joint-svg-shim/.gitignore
@@ -0,0 +1,20 @@
+# dependencies
+node_modules/
+
+# build output
+dist/
+
+# test coverage
+coverage/
+
+# logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# editor / OS
+.DS_Store
+.idea/
+.vscode/
+*.tsbuildinfo
diff --git a/packages/joint-svg-shim/LICENSE b/packages/joint-svg-shim/LICENSE
new file mode 100644
index 0000000000..04980886c3
--- /dev/null
+++ b/packages/joint-svg-shim/LICENSE
@@ -0,0 +1,376 @@
+Copyright 2013 client IO
+http://client.io
+
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in 
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.
\ No newline at end of file
diff --git a/packages/joint-svg-shim/README.md b/packages/joint-svg-shim/README.md
new file mode 100644
index 0000000000..19230c09d2
--- /dev/null
+++ b/packages/joint-svg-shim/README.md
@@ -0,0 +1,166 @@
+<p align="center">
+  <img src="https://cdn.prod.website-files.com/63061d4ee85b5a18644f221c/633045c1d726c7116dcbe582_JJS_logo.svg" alt="JointJS" height="56" />
+</p>
+
+<h1 align="center">@joint/svg-shim</h1>
+
+<p align="center">
+  <strong>Run JointJS SVG on the server.</strong> A headless DOM + SVG-geometry shim that lets
+  <a href="https://www.npmjs.com/package/@joint/core">@joint/core</a> and
+  <a href="https://www.npmjs.com/package/@joint/react">@joint/react</a> render real diagrams in Node — no browser.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@joint/svg-shim"><img src="https://img.shields.io/npm/v/@joint/svg-shim?style=flat-square&color=0EA5E9" alt="npm" /></a>
+  <a href="https://www.npmjs.com/package/@joint/svg-shim"><img src="https://img.shields.io/npm/types/@joint/svg-shim?style=flat-square&color=3178C6" alt="types" /></a>
+  <a href="https://bundlephobia.com/package/@joint/svg-shim"><img src="https://img.shields.io/bundlephobia/minzip/@joint/svg-shim?style=flat-square&color=8B5CF6" alt="bundle" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/@joint/svg-shim?style=flat-square&color=10B981" alt="license" /></a>
+</p>
+
+---
+
+## Why
+
+JointJS builds diagrams from **real SVG DOM** and measures geometry through it — `getBBox()`,
+`createSVGMatrix()`, text width. In Node there is no DOM, and even a headless DOM (jsdom, happy-dom)
+implements **no SVG layout**: `getBBox()` returns `0`, matrices and text metrics are missing. So a paper
+rendered server-side collapses — labels lose their size, links lose their geometry.
+
+`@joint/svg-shim` plugs exactly those holes:
+
+- Installs a headless DOM (jsdom by default) as Node globals.
+- Polyfills the missing **SVG geometry** — `getBBox`, `SVGMatrix`/`SVGPoint`/`SVGTransform`, transform lists, font-size coercion.
+- Measures **text** with a real font (via the bundled [`@napi-rs/canvas`](https://www.npmjs.com/package/@napi-rs/canvas)), so server-measured labels match the browser pixel-for-pixel.
+
+The result: `new dia.Paper(...)` works in Node, and `paper.svg.outerHTML` is a complete, correctly-sized SVG.
+
+## Install
+
+```bash
+yarn add @joint/svg-shim
+```
+
+`jsdom` (the DOM) and `@napi-rs/canvas` (pixel-exact text metrics) ship as dependencies — nothing else required.
+One **optional** add-on, only if you want the alternative DOM backend:
+
+```bash
+# use happy-dom instead of jsdom (lighter, faster startup)
+yarn add happy-dom
+```
+
+## Quick start — pure `@joint/core`
+
+Install the shim **before** anything that pulls in `@joint/core` (ES modules evaluate in source order):
+
+```ts
+import '@joint/svg-shim/install';          // 1. headless DOM + SVG geometry — must be first
+import { dia, shapes } from '@joint/core'; // 2. now safe to load
+
+const graph = new dia.Graph({}, { cellNamespace: shapes });
+const paper = new dia.Paper({
+  model: graph,
+  cellViewNamespace: shapes,
+  width: 400,
+  height: 200,
+});
+
+graph.addCell(
+  new shapes.standard.Rectangle({
+    position: { x: 40, y: 40 },
+    size: { width: 120, height: 60 },
+    attrs: { label: { text: 'Hello SSR' } },
+  })
+);
+
+const svg = paper.svg.outerHTML; // → static SVG string, send it as HTML
+```
+
+Prefer to control _when_ it installs? Skip the side-effect entry and call it yourself:
+
+```ts
+import { installDomShim } from '@joint/svg-shim';
+installDomShim();                          // idempotent
+import { dia } from '@joint/core';
+```
+
+## Quick start — `@joint/react`
+
+You don't use this package directly. `@joint/react/server` wires it for you — it installs the shim and
+teaches it how the React theme sizes text:
+
+```ts
+import '@joint/react/server';              // installs @joint/svg-shim + registers the SSR paper renderer
+import { renderToString } from 'react-dom/server';
+
+// <GraphProvider><Paper renderElement={…} /></GraphProvider>
+// → full diagram SVG inline, hydrates into the live paper on the client.
+```
+
+Just add `@joint/svg-shim` to the SSR app: `yarn add @joint/svg-shim`.
+
+## DOM providers
+
+The shim needs a DOM that creates **real `SVGElement` instances** (so their prototypes can be patched).
+
+| Provider | How | Notes |
+| --- | --- | --- |
+| **jsdom** _(default)_ | bundled | Spec-compliant SVG DOM. Zero config. |
+| **happy-dom** | `installDomShim({ provider: 'happy-dom' })` | Lighter & faster. Needs `yarn add happy-dom` (≥ 15; verified on 20.x). |
+| **custom** | `installDomShim({ provider: () => myWindow })` | Bring your own window — must yield real `SVGElement`s. |
+
+> Reusing an existing DOM (e.g. inside a jsdom test environment)? The shim detects it and only applies the
+> SVG-geometry polyfills — it won't create a second window.
+
+## Text measurement
+
+Text is measured with the real font via the bundled [`@napi-rs/canvas`](https://www.npmjs.com/package/@napi-rs/canvas)
+(Skia, prebuilt binaries — works in Node and Bun), matching the browser's `getBBox`. If canvas can't load for some
+reason, the shim falls back to an average-glyph estimate — fine for layout, not pixel-exact.
+
+If your text size comes from **CSS classes** (as `@joint/react`'s theme does), register a resolver so the shim
+measures at the themed size:
+
+```ts
+import { setTextStyleResolver } from '@joint/svg-shim';
+
+setTextStyleResolver((classAttribute) =>
+  classAttribute.includes('my-label') ? { fontSize: '11px', fontFamily: 'Arial' } : {}
+);
+```
+
+## API
+
+| Export | Description |
+| --- | --- |
+| `import '@joint/svg-shim/install'` | Side-effect entry — installs the shim on import (use it **first**). |
+| `installDomShim(options?)` | Installs the shim manually. Idempotent. Returns the `document`. |
+| `isDomShimInstalled()` | Whether the shim has been installed. |
+| `setTextStyleResolver(fn)` | Teach the shim how a `class` attribute maps to font size/family. |
+| `measureText(text, options)` | Measure a string's box (width + ascent/descent). |
+| `getNodeRequire()` | A CWD-anchored `require`, for resolving optional peers from the consumer. |
+| `import { DOM_SHIM_FLAG } from '@joint/svg-shim/flag'` | The server-detection flag — a lone string constant on a **client-safe** subpath (zero Node imports), so browser code can detect a shim render without pulling the Node-only barrel. |
+| `DomProvider` · `DomShimOptions` · `TextStyle` · `TextBox` … | Public types. |
+
+## Examples
+
+Runnable examples live in [`examples/`](./examples):
+
+- **[`examples/core-static`](./examples/core-static)** — pure `@joint/core`: render a diagram to SVG on the server and serve it as **static HTML** (no client JS).
+- **[`examples/react-ssr`](./examples/react-ssr)** — `@joint/react` + Vite: server-render an interactive diagram, ship it as SVG, then **hydrate** to the live paper. Works with JavaScript disabled.
+
+```bash
+# from the monorepo root
+yarn workspace @joint/svg-shim-example-core-static dev
+yarn workspace @joint/svg-shim-example-react-ssr dev
+```
+
+## Caveats
+
+- **Node only.** It shims a browser DOM — not for the browser, not for edge runtimes (jsdom needs Node APIs).
+- **Global DOM.** It sets `global.document` / `window`. Libraries that sniff `typeof document !== 'undefined'`
+  to detect a browser may mis-detect the server. Keep it on the Node server runtime.
+- **Element sizes come from the model** on the server — there's no layout engine to measure DOM boxes (only text is measured).
+
+## License
+
+[MPL-2.0](./LICENSE) © [client IO](https://client.io)
diff --git a/packages/joint-svg-shim/eslint.config.mjs b/packages/joint-svg-shim/eslint.config.mjs
new file mode 100644
index 0000000000..0e1f0c7aff
--- /dev/null
+++ b/packages/joint-svg-shim/eslint.config.mjs
@@ -0,0 +1,14 @@
+import { tsConfig, jsConfig, reactTsConfig } from '@joint/eslint-config';
+import { defineConfig } from 'eslint/config';
+
+// `reactTsConfig` is the monorepo's modern-TS profile (2-space, indent off); this
+// package has no React, but follows the same shared style as `@joint/react` it was
+// extracted from. No React-specific rules are triggered by its plain-TS sources.
+export default defineConfig([
+  {
+    files: ['src/**/*.ts'],
+  },
+  ...jsConfig,
+  ...tsConfig,
+  ...reactTsConfig,
+]);
diff --git a/packages/joint-svg-shim/examples/core-static/.gitignore b/packages/joint-svg-shim/examples/core-static/.gitignore
new file mode 100644
index 0000000000..d4d7e3f614
--- /dev/null
+++ b/packages/joint-svg-shim/examples/core-static/.gitignore
@@ -0,0 +1,3 @@
+node_modules
+dist
+*.log
diff --git a/packages/joint-svg-shim/examples/core-static/README.md b/packages/joint-svg-shim/examples/core-static/README.md
new file mode 100644
index 0000000000..8570a77c8e
--- /dev/null
+++ b/packages/joint-svg-shim/examples/core-static/README.md
@@ -0,0 +1,39 @@
+# @joint/core static-SVG example
+
+Runs **pure `@joint/core`** in Node — no browser, no React, no client JavaScript
+— and serves a diagram as **static HTML** with the SVG embedded inline.
+
+## What it shows
+
+- `@joint/svg-shim` makes JointJS's SVG DOM work in Node: `new dia.Paper(...)`
+  renders, and `paper.svg.outerHTML` is a complete, correctly-sized SVG.
+- A couple of `shapes.standard.Rectangle` nodes connected by a labeled
+  `shapes.standard.Link`. The link label's background is sized from the
+  **measured text** — measured server-side (the shim's whole point). With
+  `@napi-rs/canvas` installed, that measurement uses the real font.
+- The response is a full HTML page with no `<script>`: rendered entirely on the
+  server.
+
+## How it's wired
+
+`src/diagram.ts` imports `@joint/svg-shim/install` **first** (before
+`@joint/core`), then builds the graph and returns `paper.svg.outerHTML`.
+`src/server.ts` is a tiny Express server that wraps that SVG in an HTML shell.
+
+## Run
+
+From the monorepo root (after `yarn install` and building `@joint/svg-shim`):
+
+```bash
+yarn workspace @joint/svg-shim-example-core-static dev
+# → http://localhost:5174
+```
+
+```bash
+yarn workspace @joint/svg-shim-example-core-static typecheck
+yarn workspace @joint/svg-shim-example-core-static build
+```
+
+> The example consumes the **built** workspace packages (`@joint/core`,
+> `@joint/svg-shim`) via its own dependencies — no source aliases. Build the
+> shim first if needed: `yarn workspace @joint/svg-shim build`.
diff --git a/packages/joint-svg-shim/examples/core-static/package.json b/packages/joint-svg-shim/examples/core-static/package.json
new file mode 100644
index 0000000000..64f6987a90
--- /dev/null
+++ b/packages/joint-svg-shim/examples/core-static/package.json
@@ -0,0 +1,23 @@
+{
+  "name": "@joint/svg-shim-example-core-static",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "start": "tsx src/server.ts",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@joint/core": "workspace:*",
+    "@joint/svg-shim": "workspace:*",
+    "express": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^24.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.2"
+  }
+}
diff --git a/packages/joint-svg-shim/examples/core-static/src/diagram.ts b/packages/joint-svg-shim/examples/core-static/src/diagram.ts
new file mode 100644
index 0000000000..54d20953d6
--- /dev/null
+++ b/packages/joint-svg-shim/examples/core-static/src/diagram.ts
@@ -0,0 +1,256 @@
+/**
+ * Builds a JointJS diagram with pure `@joint/core` and serializes it to a static
+ * SVG string — entirely in Node, no browser. Styled after the JointJS homepage:
+ * dark cards, a dashed outline variant, a diamond decision node, simple line
+ * icons, dashed red orthogonal links, red pill labels and red ring ports.
+ *
+ * `@joint/svg-shim/install` is imported FIRST (ES modules evaluate in source
+ * order) so the headless DOM + SVG-geometry shim is installed before
+ * `@joint/core` is loaded. With `@napi-rs/canvas` present, label text is
+ * measured with the real font, so the serialized SVG is correctly sized.
+ */
+import '@joint/svg-shim/install';
+import { dia, shapes } from '@joint/core';
+
+const NODE_WIDTH = 216;
+const NODE_HEIGHT = 86;
+const DIAMOND_SIZE = 168;
+const FONT = '\'Helvetica Neue\', Helvetica, Arial, sans-serif';
+
+// JointJS brand: dark slate surfaces, a single red accent.
+const RED = '#ed2939';
+const RED_SOFT = '#f0453f';
+const NODE_FILL = '#161e2b';
+const DASH_WHITE = '#e8edf3';
+const TITLE_FILL = '#f3f5f8';
+const SUBTITLE_FILL = '#93a1b3';
+const ICON_FILL = '#cdd6e2';
+
+type Side = 'left' | 'right' | 'top' | 'bottom';
+
+// Simple 24×24 line-icon paths — proof that even icons render server-side.
+const ICONS = {
+  server: 'M3 4h18v6H3z M3 14h18v6H3z M7 7h0.5 M7 17h0.5',
+  cube: 'M12 2l9 5v10l-9 5-9-5V7z M12 2v20 M3 7l9 5 9-5',
+  layers: 'M12 3l9 5-9 5-9-5z M3 13l9 5 9-5 M3 17l9 5 9-5',
+  ruler: 'M3 7h18v10H3z M7 7v4 M11 7v6 M15 7v4 M19 7v6',
+  image: 'M3 4h18v16H3z M3 16l5-5 4 4 3-3 6 6 M8 9a1.5 1.5 0 1 0 0-0.01',
+  split: 'M7 3v8a4 4 0 0 0 4 4h6 M14 11l4 4-4 4 M7 15v6',
+} as const;
+
+/** A connection port: a red ring, echoing the JointJS homepage flow ports. */
+const portGroup = (position: Side): dia.Element.PortGroup => ({
+  position: { name: position },
+  markup: [{ tagName: 'circle', selector: 'port' }],
+  attrs: { port: { r: 7, fill: '#0d1117', stroke: RED, strokeWidth: 2, magnet: 'active' } },
+});
+
+const PORT_GROUPS = { left: portGroup('left'), right: portGroup('right'), top: portGroup('top'), bottom: portGroup('bottom') };
+
+/** A pipeline card: dark rounded rect, left line-icon, bold title, muted subtitle. */
+const CardNode = dia.Element.define(
+  'demo.CardNode',
+  {
+    attrs: {
+      body: { width: 'calc(w)', height: 'calc(h)', rx: 12, ry: 12, fill: NODE_FILL, stroke: 'none' },
+      icon: { fill: 'none', stroke: ICON_FILL, strokeWidth: 1.6, strokeLinejoin: 'round', strokeLinecap: 'round' },
+      title: { textAnchor: 'start', textVerticalAnchor: 'middle', x: 64, y: 'calc(0.4*h)', fontSize: 14, fontWeight: 'bold', fontFamily: FONT, fill: TITLE_FILL },
+      subtitle: { textAnchor: 'start', textVerticalAnchor: 'middle', x: 64, y: 'calc(0.66*h)', fontSize: 11, fontFamily: FONT, fill: SUBTITLE_FILL },
+    },
+    ports: { groups: PORT_GROUPS },
+  },
+  {
+    markup: [
+      { tagName: 'rect', selector: 'body' },
+      { tagName: 'path', selector: 'icon' },
+      { tagName: 'text', selector: 'title' },
+      { tagName: 'text', selector: 'subtitle' },
+    ],
+  }
+);
+
+/** A diamond decision node — transparent with a white outline (homepage style). */
+const DiamondNode = dia.Element.define(
+  'demo.DiamondNode',
+  {
+    attrs: {
+      body: { refPoints: '0,10 10,0 20,10 10,20', fill: 'transparent', stroke: DASH_WHITE, strokeWidth: 2, strokeDasharray: '6 5' },
+      title: { textAnchor: 'middle', textVerticalAnchor: 'middle', x: 'calc(w/2)', y: 'calc(0.5*h)', fontSize: 13, fontWeight: 'bold', fontFamily: FONT, fill: TITLE_FILL },
+    },
+    ports: { groups: PORT_GROUPS },
+  },
+  {
+    markup: [
+      { tagName: 'polygon', selector: 'body' },
+      { tagName: 'text', selector: 'title' },
+    ],
+  }
+);
+
+/** One node of the pipeline (linear: each node links to the next). */
+interface Node {
+  readonly id: string;
+  readonly title: string;
+  readonly subtitle: string;
+  readonly icon: keyof typeof ICONS;
+  readonly x: number;
+  readonly y: number;
+  readonly shape?: 'card' | 'diamond';
+  readonly dashed?: boolean;
+  /** Optional red pill on the link that LEAVES this node. */
+  readonly outLabel?: string;
+  /** Force the in/out port side (else it is derived from geometry). */
+  readonly inSide?: Side;
+  readonly outSide?: Side;
+}
+
+// Scattered, homepage-style layout. The pipeline runs in array order; ports are
+// derived from geometry below, so links always leave/enter the facing side.
+const NODES: readonly Node[] = [
+  { id: 'node', title: 'Node.js', subtitle: 'server runtime', icon: 'server', x: 64, y: 40 },
+  { id: 'core', title: '@joint/core', subtitle: 'dia.Paper builds the SVG', icon: 'cube', x: 64, y: 250, dashed: true, outLabel: 'measured on the server' },
+  { id: 'shim', title: '@joint/svg-shim', subtitle: 'headless DOM + geometry', icon: 'layers', x: 450, y: 40, inSide: 'bottom' },
+  { id: 'canvas', title: '@napi-rs/canvas', subtitle: 'measures the text', icon: 'ruler', x: 880, y: 250, dashed: true, inSide: 'top', outSide: 'bottom' },
+  { id: 'router', title: 'orthogonal router', subtitle: '', icon: 'split', x: 496, y: 350, shape: 'diamond', outLabel: 'static SVG' },
+  { id: 'svg', title: 'Static SVG', subtitle: 'paper.svg.outerHTML', icon: 'image', x: 80, y: 470 },
+];
+
+const PAPER_WIDTH = 1160;
+const PAPER_HEIGHT = 640;
+
+/** The node's centre point, accounting for its shape's size. */
+function centerOf(node: Node): { cx: number; cy: number } {
+  const w = node.shape === 'diamond' ? DIAMOND_SIZE : NODE_WIDTH;
+  const h = node.shape === 'diamond' ? DIAMOND_SIZE : NODE_HEIGHT;
+  return { cx: node.x + w / 2, cy: node.y + h / 2 };
+}
+
+/** Which side of `from` faces `to` — the dominant axis of the centre delta. */
+function sideFacing(from: Node, to: Node): Side {
+  const a = centerOf(from);
+  const b = centerOf(to);
+  const dx = b.cx - a.cx;
+  const dy = b.cy - a.cy;
+  if (Math.abs(dx) >= Math.abs(dy)) return dx >= 0 ? 'right' : 'left';
+  return dy >= 0 ? 'bottom' : 'top';
+}
+
+/** Builds a node (card or diamond) with its icon and the given in/out port sides. */
+function buildNode(node: Node, inSide: Side | undefined, outSide: Side | undefined): dia.Element {
+  const isDiamond = node.shape === 'diamond';
+  const Ctor = isDiamond ? DiamondNode : CardNode;
+  const size = isDiamond ? { width: DIAMOND_SIZE, height: DIAMOND_SIZE } : { width: NODE_WIDTH, height: NODE_HEIGHT };
+  const iconTransform = isDiamond
+    ? `translate(${DIAMOND_SIZE / 2 - 12}, ${DIAMOND_SIZE * 0.3}) scale(0.85)`
+    : `translate(22, ${NODE_HEIGHT / 2 - 12}) scale(0.85)`;
+  const attributes: dia.Element.Attributes['attrs'] = isDiamond
+    ? { title: { text: node.title } }
+    : {
+        body: node.dashed ? { fill: 'transparent', stroke: DASH_WHITE, strokeWidth: 2, strokeDasharray: '6 5' } : {},
+        icon: { d: ICONS[node.icon], transform: iconTransform },
+        title: { text: node.title },
+        subtitle: { text: node.subtitle },
+      };
+  const element = new Ctor({ id: node.id, position: { x: node.x, y: node.y }, size, attrs: attributes });
+  if (inSide) element.addPort({ id: 'in', group: inSide });
+  if (outSide) element.addPort({ id: 'out', group: outSide });
+  return element;
+}
+
+const unit = 4;
+
+
+/** A dashed-red orthogonal, rounded link from one node's out-port to another's in-port. */
+function pipeLink(source: string, target: string, label?: string): dia.Link {
+  const link = new shapes.standard.Link({
+    source: { id: source, port: 'out' },
+    target: { id: target, port: 'in' },
+    z: -1,
+    attrs: {
+      line: {
+        class: 'flow-link',
+        stroke: RED,
+        strokeWidth: 1.5,
+        strokeDasharray: '6 5',
+        targetMarker: { type: 'path', d: 'M 8 -4 0 0 8 4 Z', fill: RED, stroke: 'none' },
+      },
+    },
+  });
+  if (label !== undefined) {
+    link.labels([
+      {
+        position: 0.5,
+        attrs: {
+          // `ref: 'text'` sizes the red pill from the measured label, then `calc`
+          // adds padding around it — the shim measures the text in Node.
+          text: { text: label, fill: '#fff', fontSize: 11, fontFamily: FONT, fontWeight: 'bold' },
+          rect: { ref: 'text', x: 'calc(x - 11)', y: 'calc(y - 6)', width: 'calc(w + 22)', height: 'calc(h + 12)', fill: RED_SOFT, stroke: 'none', rx: 6, ry: 6 },
+        },
+      },
+    ]);
+  }
+  return link;
+}
+
+/**
+ * Build the diagram and return its serialized SVG markup.
+ *
+ * The labelled link's pill is sized from the measured text — the shim's whole
+ * point: that measurement happens server-side in Node.
+ */
+export function buildDiagramSvg(): string {
+  const graph = new dia.Graph({}, { cellNamespace: shapes });
+
+  const spacing= 6;
+  const paper = new dia.Paper({
+    model: graph,
+    cellViewNamespace: shapes,
+    width: PAPER_WIDTH,
+    height: PAPER_HEIGHT,
+    // Anchor links at the port centre using the MODEL geometry (the server has no
+    // layout, so a rendered bbox would be zero-height). The manhattan router then
+    // adds a perpendicular stub at each end, so links meet nodes at 90°.
+    defaultAnchor: { name: 'center', args: { useModelGeometry: true } },
+    gridSize: 5,
+    defaultConnectionPoint: {
+        name: 'boundary',
+        args: {
+            offset: spacing,
+            extrapolate: true
+        }
+    },
+    defaultRouter: { name: 'rightAngle', args: { margin: unit * 7 }},
+    defaultConnector: {
+        name: 'straight',
+        args: { cornerType: 'line', cornerPreserveAspectRatio: true }
+    } // bevelled path
+  });
+
+  // Derive each node's port sides from geometry: the out-port faces the next
+  // node, the in-port faces the previous one — so links never wrap around.
+  const cells: dia.Cell[] = NODES.map((node, index) => {
+    const previous = NODES[index - 1];
+    const next = NODES[index + 1];
+    const inSide = node.inSide ?? (previous ? sideFacing(node, previous) : undefined);
+    const outSide = node.outSide ?? (next ? sideFacing(node, next) : undefined);
+    return buildNode(node, inSide, outSide);
+  });
+  for (let index = 0; index < NODES.length - 1; index++) {
+    const from = NODES[index];
+    const to = NODES[index + 1];
+    if (from && to) cells.push(pipeLink(from.id, to.id, from.outLabel));
+  }
+  graph.addCells(cells);
+
+  // `paper.svg` fills its (DOM-less) paper container at `100%` — JointJS puts the
+  // pixel dimensions on the paper element, not the `<svg>`. Serialized on its own
+  // it would have no intrinsic size and collapse. Give it an explicit size +
+  // `viewBox`, then let it scale to the page frame (`width: 100%`).
+  const { svg } = paper;
+  svg.setAttribute('width', String(PAPER_WIDTH));
+  svg.setAttribute('height', String(PAPER_HEIGHT));
+  svg.setAttribute('viewBox', `0 0 ${PAPER_WIDTH} ${PAPER_HEIGHT}`);
+  svg.setAttribute('style', 'display: block; width: 100%; height: auto');
+
+  return svg.outerHTML;
+}
diff --git a/packages/joint-svg-shim/examples/core-static/src/server.ts b/packages/joint-svg-shim/examples/core-static/src/server.ts
new file mode 100644
index 0000000000..7cc0b358aa
--- /dev/null
+++ b/packages/joint-svg-shim/examples/core-static/src/server.ts
@@ -0,0 +1,161 @@
+/**
+ * Static-HTML server for pure `@joint/core`.
+ *
+ * Per request it builds a diagram in Node, serializes it to SVG, and returns a
+ * complete static HTML page embedding that SVG. There is NO React and NO client
+ * `<script>` — the page is fully rendered on the server, in the JointJS style.
+ */
+/* eslint-disable no-console -- dev server entry logs startup */
+import express from 'express';
+import { buildDiagramSvg } from './diagram';
+
+const port = Number(process.env.PORT ?? 5174);
+
+const LOGO =
+  'https://cdn.prod.website-files.com/63061d4ee85b5a18644f221c/633045c1d726c7116dcbe582_JJS_logo.svg';
+const BACKDROP =
+  'https://cdn.prod.website-files.com/63061d4ee85b5a18644f221c/69c684ee197b2040000acfa5_Homepage%20-%20React%20mobile.png';
+
+const PAGE_STYLE = `
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0;
+    min-height: 100vh;
+    color: #eef2f7;
+    font-family: 'Inter', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+    background: #0a0e14;
+  }
+  /* Faint JointJS homepage backdrop + a red brand wash, behind everything. */
+  body::before {
+    content: '';
+    position: fixed;
+    inset: 0;
+    background:
+      linear-gradient(180deg, rgba(10,14,20,0.82), rgba(10,14,20,0.95)),
+      radial-gradient(70rem 46rem at 78% -8%, rgba(237,41,57,0.20), transparent 60%),
+      url('${BACKDROP}') center top / cover no-repeat fixed;
+    z-index: -1;
+  }
+  main {
+    max-width: 1180px;
+    margin: 0 auto;
+    padding: clamp(1.5rem, 3vw, 2.5rem) clamp(1.25rem, 4vw, 3rem) 2.5rem;
+  }
+  .brand { display: flex; align-items: center; gap: 0.6rem; margin-bottom: clamp(1rem, 2.5vw, 1.5rem); }
+  .brand img { height: 30px; }
+  .brand b { font-weight: 800; letter-spacing: -0.01em; color: #fff; }
+  .brand span { color: #8a98ab; font-weight: 500; }
+  .badges { display: flex; flex-wrap: wrap; gap: 0.75rem; margin-bottom: 1rem; }
+  .badge {
+    display: inline-flex; align-items: center; gap: 0.5rem;
+    padding: 0.5rem 0.95rem;
+    font-size: 0.72rem; font-weight: 700; letter-spacing: 0.12em; text-transform: uppercase;
+    color: #ffd9d6;
+    border: 1px solid rgba(237,41,57,0.55);
+    background: rgba(237,41,57,0.07);
+    clip-path: polygon(11px 0, 100% 0, 100% calc(100% - 11px), calc(100% - 11px) 100%, 0 100%, 0 11px);
+  }
+  .badge svg { width: 15px; height: 15px; color: #ed2939; }
+  h1 {
+    margin: 0 0 0.7rem;
+    font-weight: 900;
+    font-size: clamp(1.4rem, 3vw, 2.4rem);
+    line-height: 1.04;
+    letter-spacing: -0.02em;
+    max-width: 18ch;
+  }
+  h1 .accent { color: #ed2939; }
+  .lede { margin: 0; max-width: 60ch; color: #aab6c6; font-size: clamp(0.95rem, 1.4vw, 1.18rem); line-height: 1.6; }
+  .lede code { color: #f0f4f8; background: rgba(255,255,255,0.08); padding: 0.06em 0.4em; border-radius: 5px; font-size: 0.92em; }
+  .note {
+    display: inline-flex; align-items: center; gap: 0.6rem;
+    margin-top: 1.6rem; padding: 0.6rem 1rem;
+    font-size: 0.9rem; color: #cbd5e1;
+    border: 1px solid rgba(255,255,255,0.1); border-radius: 999px; background: rgba(255,255,255,0.03);
+  }
+  .note .dot { width: 8px; height: 8px; border-radius: 50%; background: #ed2939; box-shadow: 0 0 0 4px rgba(237,41,57,0.18); }
+  .stage {
+    margin-top: clamp(1.25rem, 2.5vw, 2rem);
+    padding: clamp(1rem, 2.5vw, 1.75rem);
+    border: 1px solid rgba(255,255,255,0.08);
+    border-radius: 18px;
+    background: linear-gradient(180deg, rgba(18,24,33,0.66), rgba(11,15,21,0.66));
+    box-shadow: 0 30px 80px rgba(0,0,0,0.45);
+  }
+  .stage svg { width: 100%; height: auto; }
+  .caption { margin: 1rem 0 0; font-size: 0.84rem; color: #8492a6; text-align: center; }
+  .caption code { color: #cbd5e1; }
+  /* Marching-ants flow on the links — pure CSS, runs with JS disabled. */
+  @keyframes flow-march { to { stroke-dashoffset: -22; } }
+  .stage svg .flow-link { animation: flow-march 0.7s linear infinite; }
+`;
+
+/** Wrap the server-rendered SVG in the JointJS-styled static HTML document. */
+function htmlShell(svg: string): string {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>@joint/core — Diagrams rendered on the server</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800;900&display=swap" rel="stylesheet" />
+    <style>${PAGE_STYLE}</style>
+  </head>
+  <body>
+    <main>
+      <div class="brand">
+        <img src="${LOGO}" alt="JointJS" />
+        <b>svg-shim</b><span>· server-side rendering</span>
+      </div>
+
+      <div class="badges">
+        <span class="badge">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="4" width="18" height="7" rx="1"/><rect x="3" y="13" width="18" height="7" rx="1"/><path d="M7 7.5h.01M7 16.5h.01"/></svg>
+          Pure @joint/core
+        </span>
+        <span class="badge">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 4l16 16"/><path d="M9 4h11v11"/></svg>
+          No client JavaScript
+        </span>
+      </div>
+
+      <h1><span class="accent">Diagrams rendered</span><br />on the server.</h1>
+
+      <p class="lede">
+        This whole diagram is built in Node with pure <code>@joint/core</code> — no browser.
+        <code>@joint/svg-shim</code> supplies the headless DOM and SVG geometry,
+        <code>@napi-rs/canvas</code> measures the text, and <code>paper.svg.outerHTML</code>
+        is serialized to static SVG and shipped as HTML. Instant first paint, SEO-ready,
+        emailable.
+      </p>
+
+      <section class="stage">
+        ${svg}
+        <p class="caption">Built in Node · serialized with <code>paper.svg.outerHTML</code> · zero client runtime</p>
+      </section>
+
+      <div class="note"><span class="dot"></span> Static render — the diagram above was drawn entirely on the server, so it is <strong>not interactive</strong>.</div>
+    </main>
+  </body>
+</html>`;
+}
+
+// eslint-disable-next-line sonarjs/x-powered-by
+const app = express();
+
+app.get('/', (_request, response) => {
+  const svg = buildDiagramSvg();
+  response
+    .status(200)
+    .set({ 'Content-Type': 'text/html; charset=utf-8' })
+    .end(htmlShell(svg));
+});
+
+app.listen(port, () => {
+  console.log(
+    `🚀  @joint/core static example running at http://localhost:${port}`,
+  );
+});
diff --git a/packages/joint-svg-shim/examples/core-static/tsconfig.json b/packages/joint-svg-shim/examples/core-static/tsconfig.json
new file mode 100644
index 0000000000..aaa92691b8
--- /dev/null
+++ b/packages/joint-svg-shim/examples/core-static/tsconfig.json
@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "types": ["node"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "declaration": true
+  },
+  "include": ["src"],
+  "exclude": ["dist", "node_modules"]
+}
diff --git a/packages/joint-svg-shim/examples/react-ssr/.gitignore b/packages/joint-svg-shim/examples/react-ssr/.gitignore
new file mode 100644
index 0000000000..d4d7e3f614
--- /dev/null
+++ b/packages/joint-svg-shim/examples/react-ssr/.gitignore
@@ -0,0 +1,3 @@
+node_modules
+dist
+*.log
diff --git a/packages/joint-svg-shim/examples/react-ssr/README.md b/packages/joint-svg-shim/examples/react-ssr/README.md
new file mode 100644
index 0000000000..b455ab16e5
--- /dev/null
+++ b/packages/joint-svg-shim/examples/react-ssr/README.md
@@ -0,0 +1,61 @@
+# @joint/react SSR example
+
+Server-renders an interactive JointJS diagram with `@joint/react`, ships it to
+the browser as a **complete SVG inside the HTML**, then **hydrates** it into the
+live, draggable paper.
+
+## What it shows
+
+- The whole graph — nodes, links, ports, and each node's React content — is
+  produced by `renderToString` on the **server**.
+- Disable JavaScript and reload: the diagram is still there, because it shipped
+  as plain SVG in the HTML (great for first paint and SEO).
+- With JavaScript on, the client hydrates and the JointJS paper becomes fully
+  interactive (drag nodes, click, events).
+
+## How SSR is wired
+
+`src/entry-server.tsx` imports `@joint/react/server` **as its first import** —
+before `./page` (which pulls in `@joint/core`). That single import:
+
+1. installs the `@joint/svg-shim` headless DOM + SVG-geometry shim, and
+2. registers the `@joint/react` SSR paper renderer.
+
+So when `<Paper>` renders on the server, it emits real, correctly-sized SVG.
+`@napi-rs/canvas` is a dependency of `@joint/svg-shim` (so the example gets it
+transitively) — link/node label text is measured with the real font and matches
+the browser pixel-for-pixel.
+
+The server (`server.ts`) is Express:
+
+- **dev** — Vite in `middlewareMode`; `ssrLoadModule('/src/entry-server.tsx')`
+  renders the app, injected into `index.html` via `transformIndexHtml`.
+- **production** — serves the built `dist/client` and imports the built
+  `dist/server/entry-server.js`.
+
+## Run
+
+From the monorepo root (after `yarn install` and building the libs):
+
+```bash
+yarn workspace @joint/svg-shim-example-react-ssr dev
+# → http://localhost:5173
+```
+
+Build + preview the production bundles:
+
+```bash
+yarn workspace @joint/svg-shim-example-react-ssr build
+yarn workspace @joint/svg-shim-example-react-ssr preview
+```
+
+Typecheck:
+
+```bash
+yarn workspace @joint/svg-shim-example-react-ssr typecheck
+```
+
+> The example consumes the **built** workspace packages (`@joint/react`,
+> `@joint/svg-shim`, `@joint/core`) via its own dependencies — no source
+> aliases. If the dev server can't resolve them, build the libs first:
+> `yarn workspace @joint/svg-shim build && yarn workspace @joint/react build`.
diff --git a/packages/joint-svg-shim/examples/react-ssr/index.html b/packages/joint-svg-shim/examples/react-ssr/index.html
new file mode 100644
index 0000000000..8239a3e5e8
--- /dev/null
+++ b/packages/joint-svg-shim/examples/react-ssr/index.html
@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>@joint/react — Server-Side Rendering</title>
+    <!-- Real stylesheet link (not a JS import) so Tailwind + the JointJS theme
+         load even with JavaScript disabled — the server-rendered SVG is styled
+         on first paint. Vite serves it in dev and emits a hashed asset in build. -->
+    <link rel="stylesheet" href="/src/styles.css" />
+  </head>
+  <body>
+    <div id="root"><!--app-html--></div>
+    <script type="module" src="/src/entry-client.tsx"></script>
+  </body>
+</html>
diff --git a/packages/joint-svg-shim/examples/react-ssr/package.json b/packages/joint-svg-shim/examples/react-ssr/package.json
new file mode 100644
index 0000000000..5eb7e075a5
--- /dev/null
+++ b/packages/joint-svg-shim/examples/react-ssr/package.json
@@ -0,0 +1,33 @@
+{
+  "name": "@joint/svg-shim-example-react-ssr",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx server.ts",
+    "build": "vite build --outDir dist/client && vite build --ssr src/entry-server.tsx --outDir dist/server",
+    "preview": "cross-env NODE_ENV=production tsx server.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@joint/core": "workspace:*",
+    "@joint/react": "workspace:*",
+    "@joint/svg-shim": "workspace:*",
+    "express": "^5.0.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.2.2",
+    "@types/express": "^5.0.0",
+    "@types/node": "^24.3.0",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@vitejs/plugin-react": "^5.0.2",
+    "cross-env": "^7.0.3",
+    "tailwindcss": "^4.2.2",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.2",
+    "vite": "^7.0.0"
+  }
+}
diff --git a/packages/joint-svg-shim/examples/react-ssr/server.ts b/packages/joint-svg-shim/examples/react-ssr/server.ts
new file mode 100644
index 0000000000..8a3bdc3450
--- /dev/null
+++ b/packages/joint-svg-shim/examples/react-ssr/server.ts
@@ -0,0 +1,81 @@
+/**
+ * Express SSR server for the @joint/react example.
+ *
+ * Dev: Vite runs in middleware mode. Each request transforms `index.html`,
+ * loads the server entry via `ssrLoadModule`, renders the app to HTML, and
+ * injects it into the document. HMR works through Vite's middlewares.
+ *
+ * Production (NODE_ENV=production): serves the pre-built client assets from
+ * `dist/client` and imports the pre-built server bundle from `dist/server`.
+ */
+/* eslint-disable no-console -- dev server entry logs startup and request errors */
+import { fileURLToPath } from 'node:url';
+// eslint-disable-next-line unicorn/import-style
+import { dirname, resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import express from 'express';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const isProduction = process.env.NODE_ENV === 'production';
+const port = Number(process.env.PORT ?? 5173);
+
+const APP_HTML_PLACEHOLDER = '<!--app-html-->';
+
+/** Server entry contract: a `render()` that returns the app HTML string. */
+interface ServerEntry {
+  render: () => string;
+}
+
+async function createServer(): Promise<express.Express> {
+  const app = express();
+
+  if (!isProduction) {
+    const { createServer: createViteServer } = await import('vite');
+    const vite = await createViteServer({
+      root: __dirname,
+      server: { middlewareMode: true },
+      appType: 'custom',
+    });
+    app.use(vite.middlewares);
+
+    app.use(async (request, response, next) => {
+      try {
+        const url = request.originalUrl;
+        const templateRaw = await readFile(resolve(__dirname, 'index.html'), 'utf8');
+        const template = await vite.transformIndexHtml(url, templateRaw);
+        const entry = (await vite.ssrLoadModule('/src/entry-server.tsx')) as ServerEntry;
+        const appHtml = entry.render();
+        const html = template.replace(APP_HTML_PLACEHOLDER, appHtml);
+        response.status(200).set({ 'Content-Type': 'text/html' }).end(html);
+      } catch (error) {
+        if (error instanceof Error) vite.ssrFixStacktrace(error);
+        next(error);
+      }
+    });
+
+    app.listen(port, () => {
+      console.log(`🚀  @joint/react SSR example (dev) running at http://localhost:${port}`);
+    });
+    return app;
+  }
+
+  // eslint-disable-next-line unicorn/prevent-abbreviations
+  const clientDir = resolve(__dirname, 'dist/client');
+  const template = await readFile(resolve(clientDir, 'index.html'), 'utf8');
+  const serverEntryPath = resolve(__dirname, 'dist/server/entry-server.js');
+  const entry = (await import(serverEntryPath)) as ServerEntry;
+
+  app.use(express.static(clientDir, { index: false }));
+  app.use((_request, response) => {
+    const appHtml = entry.render();
+    const html = template.replace(APP_HTML_PLACEHOLDER, appHtml);
+    response.status(200).set({ 'Content-Type': 'text/html' }).end(html);
+  });
+
+  app.listen(port, () => {
+    console.log(`🚀  @joint/react SSR example (production) running at http://localhost:${port}`);
+  });
+  return app;
+}
+
+ await createServer();
diff --git a/packages/joint-svg-shim/examples/react-ssr/src/diagram.tsx b/packages/joint-svg-shim/examples/react-ssr/src/diagram.tsx
new file mode 100644
index 0000000000..4874fcc2a9
--- /dev/null
+++ b/packages/joint-svg-shim/examples/react-ssr/src/diagram.tsx
@@ -0,0 +1,185 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
+import {
+  GraphProvider,
+  Paper,
+  HTMLHost,
+  type RenderElement,
+  type CellRecord,
+  type ElementRecord,
+  type LinkRecord,
+} from '@joint/react';
+import {
+  linkRoutingOrthogonal,
+  type ElementPort,
+  type LinkLabel,
+  type LinkStyle,
+} from '@joint/react/presets';
+
+const unit = 4;
+const bevel = unit * 2;
+const ORTHOGONAL_LINKS = linkRoutingOrthogonal({
+  cornerType: 'line',
+  cornerRadius: bevel,
+  margin: unit * 7,
+});
+
+/** User data carried by each node. */
+interface NodeData {
+  readonly label: string;
+  readonly sub: string;
+  readonly tone: keyof typeof TONES;
+}
+
+/** Tailwind class sets per tone. Literal strings so Tailwind can see them. */
+const TONES = {
+  sky: 'from-sky-500/15 to-sky-500/5 border-sky-400/40 text-sky-200',
+  violet: 'from-violet-500/15 to-violet-500/5 border-violet-400/40 text-violet-200',
+  emerald: 'from-emerald-500/15 to-emerald-500/5 border-emerald-400/40 text-emerald-200',
+  amber: 'from-amber-500/15 to-amber-500/5 border-amber-400/40 text-amber-200',
+  rose: 'from-rose-500/15 to-rose-500/5 border-rose-400/40 text-rose-200',
+} as const;
+
+const NODE_WIDTH = 220;
+const NODE_HEIGHT = 76;
+
+/**
+ * Shared link look, built from the `@joint/react` preset — the same thin line +
+ * solid triangle arrowhead as the Flowchart demo story, themed for this page.
+ */
+const LINK_STYLE: LinkStyle = {
+  color: '#38bdf8',
+  width: 2,
+  // Marching-ants dashes via CSS animation (styles.css) — runs even with JS off.
+  className: 'jj-link-dashed',
+  wrapperColor: '#0f172a',
+  wrapperWidth: 5,
+  targetMarker: {
+    markup: [
+      {
+        tagName: 'path',
+        attributes: { d: `M 0 0 L ${2 * unit} ${unit} L ${2 * unit} -${unit} Z` },
+      },
+    ],
+  },
+};
+
+/** A sky-toned connection port, positioned at a node mid-side. */
+function port(cx: number, cy: number): ElementPort {
+  return { cx, cy, width: 12, height: 12, color: '#0ea5e9', outline: '#7dd3fc', outlineWidth: 2 };
+}
+
+const PORT_TOP = port(NODE_WIDTH / 2, 0);
+const PORT_BOTTOM = port(NODE_WIDTH / 2, NODE_HEIGHT);
+const PORT_LEFT = port(0, NODE_HEIGHT / 2);
+const PORT_RIGHT = port(NODE_WIDTH, NODE_HEIGHT / 2);
+
+// A real font both @napi-rs/canvas (server measurement) and the browser have, so the
+// measured label width matches the rendered one. The label SIZE (12px below) is
+// kept on the server too — the shim coerces the inline `font-size` jsdom would
+// otherwise drop. Without `canvas` the server uses a close metrics estimate.
+const LABEL_FONT = 'Verdana, sans-serif';
+
+/** A pill label sitting on a link. */
+function label(text: string): Record<string, LinkLabel> {
+  return {
+    main: {
+      text,
+      color: '#e0f2fe',
+      backgroundColor: '#0b1220',
+      backgroundOutline: '#0ea5e9',
+      backgroundOutlineWidth: 1,
+      backgroundBorderRadius: 6,
+      backgroundPadding: { horizontal: 8, vertical: 4 },
+      fontSize: 12,
+      fontFamily: LABEL_FONT,
+    },
+  };
+}
+
+const NODE_SIZE = { width: NODE_WIDTH, height: NODE_HEIGHT };
+
+/** The pipeline nodes, with a connection port on each mid-side a link uses. */
+const NODES: ReadonlyArray<ElementRecord<NodeData>> = [
+  {
+    id: 'server',
+    type: 'element',
+    position: { x: 60, y: 60 },
+    size: NODE_SIZE,
+    data: { label: 'Server', sub: 'Node / Bun runtime', tone: 'sky' },
+    portMap: { out: PORT_BOTTOM },
+  },
+  {
+    id: 'render',
+    type: 'element',
+    position: { x: 60, y: 230 },
+    size: NODE_SIZE,
+    data: { label: 'renderToString', sub: '@joint/react/server', tone: 'violet' },
+    portMap: { in: PORT_TOP, out: PORT_RIGHT },
+  },
+  {
+    id: 'html',
+    type: 'element',
+    position: { x: 350, y: 60 },
+    size: NODE_SIZE,
+    data: { label: 'Full SVG in HTML', sub: 'works with JS disabled', tone: 'emerald' },
+    portMap: { in: PORT_LEFT, out: PORT_RIGHT },
+  },
+  {
+    id: 'browser',
+    type: 'element',
+    position: { x: 740, y: 230 },
+    size: NODE_SIZE,
+    data: { label: 'Browser', sub: 'first paint · SEO', tone: 'amber' },
+    portMap: { in: PORT_LEFT, out: PORT_TOP },
+  },
+  {
+    id: 'interactive',
+    type: 'element',
+    position: { x: 740, y: 60 },
+    size: NODE_SIZE,
+    data: { label: 'Hydrate → Interactive', sub: 'drag · click · events', tone: 'rose' },
+    portMap: { in: PORT_BOTTOM },
+  },
+];
+
+/** The pipeline links: dashed + arrow-headed, port-to-port, some labeled. */
+const LINKS: readonly LinkRecord[] = [
+  { id: 'l1', type: 'link', source: { id: 'server', port: 'out' }, target: { id: 'render', port: 'in' }, style: LINK_STYLE },
+  { id: 'l2', type: 'link', source: { id: 'render', port: 'out' }, target: { id: 'html', port: 'in' }, style: LINK_STYLE, labelMap: label('renderToString') },
+  { id: 'l3', type: 'link', source: { id: 'html', port: 'out' }, target: { id: 'browser', port: 'in' }, style: LINK_STYLE, labelMap: label('ships SVG') },
+  { id: 'l4', type: 'link', source: { id: 'browser', port: 'out' }, target: { id: 'interactive', port: 'in' }, style: LINK_STYLE },
+];
+
+/** The diagram: an SSR pipeline rendered as a JointJS graph with ports + labels. */
+const CELLS: ReadonlyArray<CellRecord<NodeData>> = [...NODES, ...LINKS];
+
+/** Renders a node as a styled card inside the SVG (Tailwind via foreignObject). */
+const renderNode: RenderElement<NodeData> = ({ label, sub, tone }) => (
+  <HTMLHost
+    useModelGeometry
+    className={`flex h-full w-full flex-col justify-center gap-0.5 rounded-xl border bg-gradient-to-br px-4 shadow-lg backdrop-blur-sm ${TONES[tone]}`}
+  >
+    <span className="text-sm font-semibold tracking-tight text-white">{label}</span>
+    <span className="text-xs opacity-80">{sub}</span>
+  </HTMLHost>
+);
+
+/** The shared diagram, rendered identically on the server and the client. */
+export function Diagram() {
+  return (
+    <div className="rounded-2xl border border-white/10 bg-slate-950/40 p-3 shadow-2xl">
+      <GraphProvider initialCells={CELLS}>
+        <Paper
+          className="h-[360px] w-[1020px] overflow-hidden rounded-xl bg-slate-900/40"
+          drawGrid={false}
+          renderElement={renderNode}
+          style={{ width: 1020, height: 360 }}
+          linkRouting={ORTHOGONAL_LINKS}
+          defaultLink={{
+            style: LINK_STYLE,
+          }}
+        />
+      </GraphProvider>
+    </div>
+  );
+}
diff --git a/packages/joint-svg-shim/examples/react-ssr/src/entry-client.tsx b/packages/joint-svg-shim/examples/react-ssr/src/entry-client.tsx
new file mode 100644
index 0000000000..8469edf224
--- /dev/null
+++ b/packages/joint-svg-shim/examples/react-ssr/src/entry-client.tsx
@@ -0,0 +1,19 @@
+/**
+ * Client entry. Hydrates the server-rendered page so the JointJS paper becomes
+ * the live, interactive instance. With JavaScript disabled this file never runs
+ * — and the diagram is still visible (and styled, via the stylesheet `<link>` in
+ * `index.html`), because the server shipped it as SVG.
+ */
+import { StrictMode } from 'react';
+import { hydrateRoot } from 'react-dom/client';
+import { Page } from './page';
+
+const root = document.querySelector('#root');
+if (root) {
+  hydrateRoot(
+    root,
+    <StrictMode>
+      <Page />
+    </StrictMode>
+  );
+}
diff --git a/packages/joint-svg-shim/examples/react-ssr/src/entry-server.tsx b/packages/joint-svg-shim/examples/react-ssr/src/entry-server.tsx
new file mode 100644
index 0000000000..1d197e010a
--- /dev/null
+++ b/packages/joint-svg-shim/examples/react-ssr/src/entry-server.tsx
@@ -0,0 +1,18 @@
+/**
+ * Server entry for the React SSR example.
+ *
+ * `@joint/react/server` is imported FIRST — before anything that pulls in
+ * `@joint/core` (i.e. before `./page` → `./diagram`) — so the headless DOM shim
+ * (`@joint/svg-shim`) is installed and the server paper renderer is registered
+ * before joint-core is evaluated. Each `render()` then `renderToString`s the
+ * page and `<Paper>` emits the full diagram SVG inline.
+ */
+import '@joint/react/server';
+
+import { renderToString } from 'react-dom/server';
+import { Page } from './page';
+
+/** Render the full page to an HTML string for the SSR document shell. */
+export function render(): string {
+  return renderToString(<Page />);
+}
diff --git a/packages/joint-svg-shim/examples/react-ssr/src/page.tsx b/packages/joint-svg-shim/examples/react-ssr/src/page.tsx
new file mode 100644
index 0000000000..a8d354768a
--- /dev/null
+++ b/packages/joint-svg-shim/examples/react-ssr/src/page.tsx
@@ -0,0 +1,53 @@
+import { Diagram } from './diagram';
+
+const BADGES = [
+  'renderToString',
+  'full SVG in HTML',
+  'SEO-friendly',
+  'hydrates to interactive',
+];
+
+/** The full page, rendered identically on the server and hydrated on the client. */
+export function Page() {
+  return (
+    <main className="mx-auto flex min-h-screen max-w-5xl flex-col items-center justify-center gap-8 px-6 py-12">
+      <header className="flex flex-col items-center gap-4 text-center">
+        <span className="rounded-full border border-white/10 bg-white/5 px-3 py-1 text-xs font-medium uppercase tracking-widest text-slate-300">
+          @joint/react · server-side rendering
+        </span>
+        <h1 className="bg-gradient-to-r from-white to-slate-400 bg-clip-text text-4xl font-bold tracking-tight text-transparent sm:text-5xl">
+          The diagram is rendered on the server
+        </h1>
+        <p className="max-w-2xl text-balance text-slate-400">
+          This whole graph — nodes, links, and each node&apos;s React content — is produced by{' '}
+          <code className="rounded bg-white/10 px-1.5 py-0.5 font-mono text-slate-200">renderToString</code> on the
+          server. Disable JavaScript and reload: the diagram is still there, because it shipped as plain SVG in the HTML.
+        </p>
+        <ul className="flex flex-wrap justify-center gap-2">
+          {BADGES.map((badge) => (
+            <li
+              key={badge}
+              className="rounded-full border border-white/10 bg-white/5 px-3 py-1 text-xs text-slate-300"
+            >
+              {badge}
+            </li>
+          ))}
+        </ul>
+      </header>
+
+      <Diagram />
+
+      <footer className="flex flex-col items-center gap-2 text-center text-sm text-slate-500">
+        <p>
+          <span className="font-semibold text-emerald-400">JavaScript on:</span> the live JointJS paper hydrates — drag
+          nodes, it is fully interactive.
+        </p>
+        <noscript>
+          <p className="rounded-lg border border-amber-400/30 bg-amber-400/10 px-3 py-2 text-amber-200">
+            JavaScript is disabled — this diagram was rendered entirely on the server.
+          </p>
+        </noscript>
+      </footer>
+    </main>
+  );
+}
diff --git a/packages/joint-svg-shim/examples/react-ssr/src/styles.css b/packages/joint-svg-shim/examples/react-ssr/src/styles.css
new file mode 100644
index 0000000000..77383d90aa
--- /dev/null
+++ b/packages/joint-svg-shim/examples/react-ssr/src/styles.css
@@ -0,0 +1,37 @@
+@import 'tailwindcss';
+
+/* JointJS + @joint/react base styles (paper, cells, links), loaded into
+   Tailwind's components layer — the same import the Storybook setup uses.
+   Imported via the package export, not a relative path into another package. */
+@import '@joint/react/styles.css' layer(components);
+
+/* Tell Tailwind which source files to scan for class names. */
+@source './**/*.{ts,tsx}';
+
+:root {
+  color-scheme: dark;
+}
+
+/* Marching-ants link: a pure-CSS dash animation, so it runs even with JS
+   disabled (the server ships the class on the SVG line). */
+@keyframes jj-link-march {
+  to {
+    stroke-dashoffset: -12;
+  }
+}
+
+.jj-link-dashed {
+  stroke-dasharray: 6 6;
+  animation: jj-link-march 0.6s linear infinite;
+}
+
+body {
+  margin: 0;
+  background:
+    radial-gradient(60rem 60rem at 70% -10%, rgba(56, 189, 248, 0.12), transparent 60%),
+    radial-gradient(50rem 50rem at 10% 110%, rgba(168, 85, 247, 0.12), transparent 60%),
+    #020617;
+  color: #e2e8f0;
+  font-family:
+    ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+}
diff --git a/packages/joint-svg-shim/examples/react-ssr/tsconfig.json b/packages/joint-svg-shim/examples/react-ssr/tsconfig.json
new file mode 100644
index 0000000000..c6954b7259
--- /dev/null
+++ b/packages/joint-svg-shim/examples/react-ssr/tsconfig.json
@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "types": ["node"],
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src", "server.ts", "vite.config.ts"],
+  "exclude": ["dist", "node_modules"]
+}
diff --git a/packages/joint-svg-shim/examples/react-ssr/vite.config.ts b/packages/joint-svg-shim/examples/react-ssr/vite.config.ts
new file mode 100644
index 0000000000..493f468e14
--- /dev/null
+++ b/packages/joint-svg-shim/examples/react-ssr/vite.config.ts
@@ -0,0 +1,19 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  // Dedupe React so the server render and `@joint/react`'s hooks share ONE React
+  // instance. A single hoisted React copy is enforced via the monorepo root
+  // `resolutions` field; this keeps Vite's own graph deduped too.
+  resolve: {
+    dedupe: ['react', 'react-dom'],
+  },
+  // Transform the `@joint/*` packages through Vite (don't externalize them for
+  // SSR) so `<Paper>` renders with the shim installed by `@joint/react/server`.
+  // React stays externalized — Node loads its CJS natively.
+  ssr: {
+    noExternal: ['@joint/react', '@joint/core', '@joint/svg-shim'],
+  },
+  plugins: [react(), tailwindcss()],
+});
diff --git a/packages/joint-svg-shim/jest.config.js b/packages/joint-svg-shim/jest.config.js
new file mode 100644
index 0000000000..bd04c9d013
--- /dev/null
+++ b/packages/joint-svg-shim/jest.config.js
@@ -0,0 +1,22 @@
+export default {
+  testEnvironment: 'jsdom',
+  testPathIgnorePatterns: ['/node_modules/', '/dist/'],
+  transform: {
+    '^.+\\.(ts|tsx|js|jsx|mjs)$': [
+      '@swc/jest',
+      {
+        jsc: {
+          parser: {
+            syntax: 'typescript',
+            tsx: false,
+          },
+        },
+      },
+    ],
+  },
+  // happy-dom ships ESM; let SWC transform it so the optional-provider test can
+  // `require()` it through the shim's `createRequire` under Jest's module runtime.
+  transformIgnorePatterns: ['/node_modules/(?!(happy-dom)/)'],
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node', 'mjs'],
+  testMatch: ['<rootDir>/src/**/*.{test,spec}.ts?(x)'],
+};
diff --git a/packages/joint-svg-shim/package.json b/packages/joint-svg-shim/package.json
new file mode 100644
index 0000000000..d78f3b2b4e
--- /dev/null
+++ b/packages/joint-svg-shim/package.json
@@ -0,0 +1,105 @@
+{
+  "name": "@joint/svg-shim",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Headless DOM + SVG-geometry shim for running JointJS SVG/Vectorizer code in Node (server-side rendering).",
+  "license": "MPL-2.0",
+  "keywords": [
+    "jointjs",
+    "svg",
+    "ssr",
+    "server-side-rendering",
+    "jsdom",
+    "happy-dom",
+    "headless-dom"
+  ],
+  "main": "dist/esm/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "typescript": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./install": {
+      "types": "./dist/types/install.d.ts",
+      "import": "./dist/esm/install.js",
+      "require": "./dist/cjs/install.js"
+    },
+    "./flag": {
+      "types": "./dist/types/dom-shim-flag.d.ts",
+      "import": "./dist/esm/dom-shim-flag.js",
+      "require": "./dist/cjs/dom-shim-flag.js"
+    }
+  },
+  "sideEffects": [
+    "./dist/esm/install.js",
+    "./dist/cjs/install.js"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://jointjs.com",
+  "author": {
+    "name": "client IO",
+    "url": "https://client.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/clientIO/joint.git",
+    "directory": "packages/joint-svg-shim"
+  },
+  "bugs": {
+    "url": "https://github.com/clientIO/joint/issues"
+  },
+  "scripts": {
+    "prepack": "yarn test && yarn build",
+    "build": "rollup -c rollup.config.ts --configPlugin esbuild && tsc --project tsconfig.types.json",
+    "test": "yarn run typecheck && yarn run lint && yarn jest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint-fix": "yarn run lint --fix"
+  },
+  "dependencies": {
+    "@napi-rs/canvas": "^0.1.0",
+    "jsdom": "^26.1.0"
+  },
+  "peerDependencies": {
+    "happy-dom": ">=15.0.0"
+  },
+  "peerDependenciesMeta": {
+    "happy-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@joint/eslint-config": "workspace:*",
+    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@swc/core": "^1.15.11",
+    "@swc/jest": "^0.2.39",
+    "@types/jest": "30.0.0",
+    "@types/jsdom": "21.1.7",
+    "@types/node": "^24.3.0",
+    "esbuild": "^0.25.0",
+    "eslint": "9.39.2",
+    "happy-dom": "^20.0.0",
+    "jest": "30.1.2",
+    "jest-environment-jsdom": "30.1.2",
+    "rollup": "^4.50.0",
+    "rollup-plugin-esbuild": "^6.2.1",
+    "typescript": "^5.9.2"
+  },
+  "volta": {
+    "node": "22.14.0",
+    "npm": "11.2.0",
+    "yarn": "4.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
diff --git a/packages/joint-svg-shim/rollup.config.ts b/packages/joint-svg-shim/rollup.config.ts
new file mode 100644
index 0000000000..256c14b1c6
--- /dev/null
+++ b/packages/joint-svg-shim/rollup.config.ts
@@ -0,0 +1,9 @@
+import { createRollupConfig } from './scripts/create-rollup-config';
+
+export default createRollupConfig({
+  // `dom-shim-flag` is a standalone entry (a single string constant, zero Node
+  // imports) so client code can read the server-detection flag via the
+  // `@joint/svg-shim/flag` subpath without pulling the Node-only shim barrel.
+  entries: ['src/index.ts', 'src/install.ts', 'src/dom-shim-flag.ts'],
+  external: ['jsdom', 'happy-dom', '@napi-rs/canvas', 'node:module', 'node:path'],
+});
diff --git a/packages/joint-svg-shim/scripts/create-rollup-config.ts b/packages/joint-svg-shim/scripts/create-rollup-config.ts
new file mode 100644
index 0000000000..a9cc25e992
--- /dev/null
+++ b/packages/joint-svg-shim/scripts/create-rollup-config.ts
@@ -0,0 +1,68 @@
+import { defineConfig, type RollupOptions } from 'rollup';
+import esbuild from 'rollup-plugin-esbuild';
+
+interface CreateRollupConfigOptions {
+  /** Entry points to build (e.g. ['src/index.ts', 'src/internal.ts']) */
+  readonly entries: string[];
+  /** External dependencies to exclude from the bundle */
+  readonly external: string[];
+}
+
+/**
+ * Creates the default set of Rollup plugins for building the package.
+ * @returns Array of Rollup plugins configured with esbuild for TypeScript/JSX transpilation.
+ */
+function createPlugins() {
+  return [
+    esbuild({
+      include: /\.[jt]sx?$/,
+      target: 'es2020',
+      jsx: 'automatic',
+    }),
+  ];
+}
+
+/**
+ * Creates ESM and CJS Rollup configurations with preserved module structure.
+ * @param options - Build configuration including entry points and external dependencies.
+ * @returns Array of Rollup configurations for ESM and CJS output formats.
+ */
+export function createRollupConfig(options: CreateRollupConfigOptions): RollupOptions[] {
+  const { entries, external: externalList } = options;
+  const plugins = createPlugins();
+
+  const external = (id: string) =>
+    externalList.some((dep) => id === dep || id.startsWith(`${dep}/`));
+
+  return defineConfig([
+    // ESM build (preserve modules)
+    {
+      input: entries,
+      output: {
+        dir: 'dist/esm',
+        format: 'esm',
+        sourcemap: true,
+        preserveModules: true,
+        preserveModulesRoot: 'src',
+      },
+      context: 'globalThis',
+      external,
+      plugins,
+    },
+
+    // CJS build (preserve modules)
+    {
+      input: entries,
+      output: {
+        dir: 'dist/cjs',
+        format: 'cjs',
+        sourcemap: true,
+        preserveModules: true,
+        preserveModulesRoot: 'src',
+      },
+      context: 'globalThis',
+      external,
+      plugins,
+    },
+  ]);
+}
diff --git a/packages/joint-svg-shim/src/__tests__/happy-dom-provider.test.ts b/packages/joint-svg-shim/src/__tests__/happy-dom-provider.test.ts
new file mode 100644
index 0000000000..eedc2831a9
--- /dev/null
+++ b/packages/joint-svg-shim/src/__tests__/happy-dom-provider.test.ts
@@ -0,0 +1,44 @@
+/**
+ * @jest-environment node
+ *
+ * Runs in the `node` environment (no ambient `document`) so the shim exercises
+ * its real create-the-DOM path with the `happy-dom` provider.
+ */
+import { installDomShim, isDomShimInstalled } from '../install-dom-shim';
+import { DOM_SHIM_FLAG } from '../dom-shim-flag';
+
+const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+
+/** Clears the process-global shim state so each test installs from scratch. */
+function resetShim(): void {
+  const globalScope = globalThis as Record<string, unknown>;
+  Reflect.deleteProperty(globalScope, DOM_SHIM_FLAG);
+  Reflect.deleteProperty(globalScope, 'document');
+  Reflect.deleteProperty(globalScope, 'window');
+}
+
+beforeEach(resetShim);
+afterAll(resetShim);
+
+describe('installDomShim with the happy-dom provider', () => {
+  it('installs a working document and flips the installed flag', () => {
+    const document = installDomShim({ provider: 'happy-dom' });
+
+    expect(typeof document.createElementNS).toBe('function');
+    expect(isDomShimInstalled()).toBe(true);
+  });
+
+  it('measures non-empty text via the polyfilled getBBox (width > 0)', () => {
+    const document = installDomShim({ provider: 'happy-dom' });
+
+    const text = document.createElementNS(SVG_NAMESPACE, 'text') as unknown as {
+      textContent: string;
+      setAttribute: (name: string, value: string) => void;
+      getBBox: () => { width: number };
+    };
+    text.setAttribute('font-size', '16');
+    text.textContent = 'Hello';
+
+    expect(text.getBBox().width).toBeGreaterThan(0);
+  });
+});
diff --git a/packages/joint-svg-shim/src/__tests__/install-dom-shim.test.ts b/packages/joint-svg-shim/src/__tests__/install-dom-shim.test.ts
new file mode 100644
index 0000000000..be096fc3d7
--- /dev/null
+++ b/packages/joint-svg-shim/src/__tests__/install-dom-shim.test.ts
@@ -0,0 +1,118 @@
+/**
+ * @jest-environment node
+ *
+ * Runs in the `node` environment (no ambient `document`) so the shim exercises
+ * its real create-the-DOM path with the default `jsdom` provider.
+ */
+import { JSDOM } from 'jsdom';
+import { installDomShim, isDomShimInstalled, type ShimWindow } from '../install-dom-shim';
+import { DOM_SHIM_FLAG } from '../dom-shim-flag';
+
+const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+
+/** Clears the process-global shim state so each test installs from scratch. */
+function resetShim(): void {
+  const globalScope = globalThis as Record<string, unknown>;
+  Reflect.deleteProperty(globalScope, DOM_SHIM_FLAG);
+  Reflect.deleteProperty(globalScope, 'document');
+  Reflect.deleteProperty(globalScope, 'window');
+}
+
+beforeEach(resetShim);
+afterAll(resetShim);
+
+describe('installDomShim', () => {
+  it('reports not-installed before the first call', () => {
+    expect(isDomShimInstalled()).toBe(false);
+  });
+
+  it('installs a working document and flips the installed flag', () => {
+    const document = installDomShim();
+
+    expect(typeof document.createElementNS).toBe('function');
+    expect(isDomShimInstalled()).toBe(true);
+    expect((globalThis as Record<string, unknown>).document).toBe(document);
+  });
+
+  it('bridges the bare SVG globals, SVGAngle, and a no-op ResizeObserver', () => {
+    installDomShim();
+    const globalScope = globalThis as Record<string, unknown>;
+
+    // The bridge copies whatever SVG constructors the provider exposes; jsdom
+    // ships `SVGElement` / `SVGSVGElement` / `SVGGElement` (but not every leaf
+    // class such as `SVGPathElement`).
+    expect(globalScope.SVGElement).toBeDefined();
+    expect(globalScope.SVGSVGElement).toBeDefined();
+    expect(globalScope.SVGGElement).toBeDefined();
+    // The Vectorizer's `isSVGSupported` guard reads `window.SVGAngle`.
+    expect(globalScope.SVGAngle).toBeDefined();
+
+    expect(typeof globalScope.ResizeObserver).toBe('function');
+    const ResizeObserverClass = globalScope.ResizeObserver as new () => {
+      observe: () => void;
+      disconnect: () => void;
+    };
+    const observer = new ResizeObserverClass();
+    expect(() => {
+      observer.observe();
+      observer.disconnect();
+    }).not.toThrow();
+  });
+
+  it('applies the SVG geometry polyfills to the created window', () => {
+    const document = installDomShim();
+
+    const svg = document.createElementNS(SVG_NAMESPACE, 'svg') as unknown as {
+      createSVGMatrix: () => { a: number; d: number };
+    };
+    expect(svg.createSVGMatrix().a).toBe(1);
+    expect(svg.createSVGMatrix().d).toBe(1);
+
+    const group = document.createElementNS(SVG_NAMESPACE, 'g') as unknown as {
+      getBBox: () => { width: number; height: number };
+    };
+    expect(group.getBBox()).toEqual({ x: 0, y: 0, width: 0, height: 0 });
+  });
+
+  it('does not throw when global navigator is a read-only getter (modern Node 21+)', () => {
+    const globalScope = globalThis as Record<string, unknown>;
+    const originalDescriptor = Object.getOwnPropertyDescriptor(globalScope, 'navigator');
+    Object.defineProperty(globalScope, 'navigator', {
+      configurable: true,
+      get: () => ({ userAgent: 'read-only-navigator' }),
+    });
+
+    try {
+      expect(() => installDomShim()).not.toThrow();
+      expect(isDomShimInstalled()).toBe(true);
+    } finally {
+      if (originalDescriptor) {
+        Object.defineProperty(globalScope, 'navigator', originalDescriptor);
+      } else {
+        delete globalScope.navigator;
+      }
+    }
+  });
+
+  it('is idempotent — a second call returns the same document', () => {
+    const first = installDomShim();
+    const second = installDomShim();
+    expect(second).toBe(first);
+  });
+
+  it('honors a custom DOM provider factory', () => {
+    let factoryCalls = 0;
+    const provider = (): ShimWindow => {
+      factoryCalls += 1;
+      const { window } = new JSDOM('<!DOCTYPE html><html><body></body></html>', {
+        pretendToBeVisual: true,
+      });
+      return window as unknown as ShimWindow;
+    };
+
+    const document = installDomShim({ provider });
+
+    expect(factoryCalls).toBe(1);
+    expect((globalThis as Record<string, unknown>).document).toBe(document);
+  });
+});
diff --git a/packages/joint-svg-shim/src/__tests__/svg-matrix.test.ts b/packages/joint-svg-shim/src/__tests__/svg-matrix.test.ts
new file mode 100644
index 0000000000..3e04172338
--- /dev/null
+++ b/packages/joint-svg-shim/src/__tests__/svg-matrix.test.ts
@@ -0,0 +1,150 @@
+import {
+  createIdentityMatrix,
+  createMatrix,
+  createPoint,
+  createTransform,
+  matrixToTransformString,
+  parseTransformString,
+  type SvgMatrixLike,
+} from '../svg-matrix';
+
+const IDENTITY = { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 } as const;
+
+/** Asserts a matrix's six components match `expected` within float tolerance. */
+function expectMatrix(matrix: SvgMatrixLike, expected: Omit<SvgMatrixLike, 'multiply' | 'inverse' | 'translate' | 'scale' | 'scaleNonUniform' | 'rotate' | 'flipX' | 'flipY' | 'skewX' | 'skewY'>): void {
+  expect(matrix.a).toBeCloseTo(expected.a);
+  expect(matrix.b).toBeCloseTo(expected.b);
+  expect(matrix.c).toBeCloseTo(expected.c);
+  expect(matrix.d).toBeCloseTo(expected.d);
+  expect(matrix.e).toBeCloseTo(expected.e);
+  expect(matrix.f).toBeCloseTo(expected.f);
+}
+
+describe('createMatrix / createIdentityMatrix', () => {
+  it('stores the six affine components', () => {
+    expectMatrix(createMatrix(1, 2, 3, 4, 5, 6), { a: 1, b: 2, c: 3, d: 4, e: 5, f: 6 });
+  });
+
+  it('createIdentityMatrix is the identity', () => {
+    expectMatrix(createIdentityMatrix(), IDENTITY);
+  });
+
+  it('multiply by identity is a no-op (both sides)', () => {
+    const matrix = createMatrix(1, 2, 3, 4, 5, 6);
+    expectMatrix(matrix.multiply(createIdentityMatrix()), { a: 1, b: 2, c: 3, d: 4, e: 5, f: 6 });
+    expectMatrix(createIdentityMatrix().multiply(matrix), { a: 1, b: 2, c: 3, d: 4, e: 5, f: 6 });
+  });
+
+  it('multiply composes two transforms (translate then scale)', () => {
+    // translate(10,20) * scale(2): scales then offsets.
+    const result = createMatrix(1, 0, 0, 1, 10, 20).multiply(createMatrix(2, 0, 0, 2, 0, 0));
+    expectMatrix(result, { a: 2, b: 0, c: 0, d: 2, e: 10, f: 20 });
+  });
+
+  it('inverse undoes the matrix (M * M⁻¹ = identity)', () => {
+    const matrix = createMatrix(2, 0, 0, 2, 10, 20);
+    expectMatrix(matrix.multiply(matrix.inverse()), IDENTITY);
+  });
+
+  it('inverse throws on a singular matrix', () => {
+    expect(() => createMatrix(1, 2, 2, 4, 0, 0).inverse()).toThrow('Cannot invert a singular matrix.');
+  });
+});
+
+describe('matrix transform helpers', () => {
+  it('translate offsets e/f', () => {
+    expectMatrix(createIdentityMatrix().translate(7, 9), { ...IDENTITY, e: 7, f: 9 });
+  });
+
+  it('scale and scaleNonUniform set the diagonal', () => {
+    expectMatrix(createIdentityMatrix().scale(3), { ...IDENTITY, a: 3, d: 3 });
+    expectMatrix(createIdentityMatrix().scaleNonUniform(2, 5), { ...IDENTITY, a: 2, d: 5 });
+  });
+
+  it('rotate(90°) maps the x-axis onto the y-axis', () => {
+    expectMatrix(createIdentityMatrix().rotate(90), { a: 0, b: 1, c: -1, d: 0, e: 0, f: 0 });
+  });
+
+  it('flipX / flipY negate the matching axis', () => {
+    expectMatrix(createIdentityMatrix().flipX(), { ...IDENTITY, a: -1 });
+    expectMatrix(createIdentityMatrix().flipY(), { ...IDENTITY, d: -1 });
+  });
+
+  it('skewX / skewY apply tan(angle) to the off-diagonal', () => {
+    expectMatrix(createIdentityMatrix().skewX(45), { ...IDENTITY, c: 1 });
+    expectMatrix(createIdentityMatrix().skewY(45), { ...IDENTITY, b: 1 });
+  });
+});
+
+describe('createPoint', () => {
+  it('matrixTransform applies the affine transform', () => {
+    const point = createPoint(3, 4).matrixTransform(createMatrix(1, 0, 0, 1, 5, 6));
+    expect(point.x).toBeCloseTo(8);
+    expect(point.y).toBeCloseTo(10);
+  });
+
+  it('rotate(90°) sends (1,0) to (0,1)', () => {
+    const point = createPoint(1, 0).matrixTransform(createIdentityMatrix().rotate(90));
+    expect(point.x).toBeCloseTo(0);
+    expect(point.y).toBeCloseTo(1);
+  });
+});
+
+describe('createTransform', () => {
+  it('defaults to an identity matrix', () => {
+    const transform = createTransform();
+    expectMatrix(transform.matrix, IDENTITY);
+    expect(transform.angle).toBe(0);
+  });
+
+  it('setMatrix and setTranslate update the matrix', () => {
+    const transform = createTransform();
+    transform.setMatrix(createMatrix(2, 0, 0, 2, 0, 0));
+    expectMatrix(transform.matrix, { ...IDENTITY, a: 2, d: 2 });
+    transform.setTranslate(3, 4);
+    expectMatrix(transform.matrix, { ...IDENTITY, e: 3, f: 4 });
+  });
+});
+
+describe('matrixToTransformString', () => {
+  it('serializes to an SVG matrix() value', () => {
+    expect(matrixToTransformString(createMatrix(1, 2, 3, 4, 5, 6))).toBe('matrix(1,2,3,4,5,6)');
+  });
+});
+
+describe('parseTransformString', () => {
+  it('empty / unrecognized input yields the identity', () => {
+    expectMatrix(parseTransformString(''), IDENTITY);
+    expectMatrix(parseTransformString('unknown(5)'), IDENTITY);
+  });
+
+  it('parses translate (with comma or whitespace separators)', () => {
+    expectMatrix(parseTransformString('translate(10,20)'), { ...IDENTITY, e: 10, f: 20 });
+    expectMatrix(parseTransformString('translate( 10  20 )'), { ...IDENTITY, e: 10, f: 20 });
+  });
+
+  it('parses scale (uniform and non-uniform)', () => {
+    expectMatrix(parseTransformString('scale(2)'), { ...IDENTITY, a: 2, d: 2 });
+    expectMatrix(parseTransformString('scale(2 3)'), { ...IDENTITY, a: 2, d: 3 });
+  });
+
+  it('parses rotate', () => {
+    expectMatrix(parseTransformString('rotate(90)'), { a: 0, b: 1, c: -1, d: 0, e: 0, f: 0 });
+  });
+
+  it('parses an explicit matrix()', () => {
+    expectMatrix(parseTransformString('matrix(1,2,3,4,5,6)'), { a: 1, b: 2, c: 3, d: 4, e: 5, f: 6 });
+  });
+
+  it('composes a chain preserving JointJS translate-then-rotate origin', () => {
+    // translate(x,y) rotate(a): translation stays in e/f, rotation in a–d.
+    expectMatrix(parseTransformString('translate(10,20) rotate(90)'), {
+      a: 0,
+      b: 1,
+      c: -1,
+      d: 0,
+      e: 10,
+      f: 20,
+    });
+  });
+});
diff --git a/packages/joint-svg-shim/src/__tests__/svg-polyfills.test.ts b/packages/joint-svg-shim/src/__tests__/svg-polyfills.test.ts
new file mode 100644
index 0000000000..afa1cd4d31
--- /dev/null
+++ b/packages/joint-svg-shim/src/__tests__/svg-polyfills.test.ts
@@ -0,0 +1,191 @@
+import { applySvgGeometryPolyfills, type PolyfillWindow } from '../svg-polyfills';
+import { createMatrix } from '../svg-matrix';
+
+type Prototype = Record<string, unknown>;
+
+/** A node backed by an in-memory attribute map (the `AttributeHost` surface). */
+function createAttributeHost(): Record<string, unknown> {
+  const attributes = new Map<string, string>();
+  return {
+    getAttribute: (name: string): string | null => attributes.get(name) ?? null,
+    setAttribute: (name: string, value: string): void => {
+      attributes.set(name, value);
+    },
+  };
+}
+
+/**
+ * A minimal non-jsdom window whose SVG prototypes are empty and whose probe
+ * element is intentionally non-compliant (string `className`, no `transform`),
+ * so every polyfill branch runs. This isolates the polyfill from any DOM
+ * implementation, keeping the assertions deterministic.
+ */
+function createFakeWindow(): PolyfillWindow {
+  const probe = { className: '', ...createAttributeHost() };
+  return {
+    SVGSVGElement: { prototype: {} as Prototype },
+    SVGElement: { prototype: {} as Prototype },
+    Element: { prototype: {} as Prototype },
+    document: { createElementNS: () => probe } as unknown as Document,
+  } as unknown as PolyfillWindow;
+}
+
+/** Reads a constructor's prototype off the fake window. */
+function prototypeOf(window: PolyfillWindow, constructorName: string): Prototype {
+  return (window[constructorName] as { prototype: Prototype }).prototype;
+}
+
+/** An SVG node whose prototype carries the polyfilled accessors. */
+function createNodeWith(prototype: Prototype): Record<string, unknown> {
+  return Object.assign(Object.create(prototype) as object, createAttributeHost());
+}
+
+/** A constant fill-if-missing method used to assert provider methods are preserved. */
+const alwaysVisible = (): boolean => true;
+
+/** A text node carrying the polyfilled accessors, with attributes set. */
+function createTextNode(
+  window: PolyfillWindow,
+  text: string,
+  attributes: Readonly<Record<string, string>> = {}
+): Record<string, unknown> {
+  const node = createNodeWith(prototypeOf(window, 'SVGElement')) as Record<string, unknown> & {
+    setAttribute: (name: string, value: string) => void;
+  };
+  node.localName = 'text';
+  node.textContent = text;
+  for (const [name, value] of Object.entries(attributes)) {
+    node.setAttribute(name, value);
+  }
+  return node;
+}
+
+describe('applySvgGeometryPolyfills — factory methods', () => {
+  it('adds createSVGMatrix / Point / Transform returning identity primitives', () => {
+    const window = createFakeWindow();
+    applySvgGeometryPolyfills(window);
+    const svgSvg = prototypeOf(window, 'SVGSVGElement') as Record<string, () => { a?: number; x?: number }>;
+
+    expect(typeof svgSvg.createSVGMatrix).toBe('function');
+    expect(svgSvg.createSVGMatrix().a).toBe(1);
+    expect(svgSvg.createSVGPoint().x).toBe(0);
+    expect(typeof svgSvg.createSVGTransform).toBe('function');
+  });
+
+  it('createSVGTransformFromMatrix carries the supplied matrix', () => {
+    const window = createFakeWindow();
+    applySvgGeometryPolyfills(window);
+    const svgSvg = prototypeOf(window, 'SVGSVGElement') as Record<
+      string,
+      (matrix: ReturnType<typeof createMatrix>) => { matrix: { a: number; e: number } }
+    >;
+
+    const transform = svgSvg.createSVGTransformFromMatrix(createMatrix(2, 0, 0, 2, 5, 6));
+    expect(transform.matrix.a).toBe(2);
+    expect(transform.matrix.e).toBe(5);
+  });
+});
+
+describe('applySvgGeometryPolyfills — measurement + visibility', () => {
+  it('getBBox / getComputedTextLength / getCTM return geometry-free defaults', () => {
+    const window = createFakeWindow();
+    applySvgGeometryPolyfills(window);
+    const svg = prototypeOf(window, 'SVGElement') as Record<string, () => unknown>;
+
+    expect(svg.getBBox()).toEqual({ x: 0, y: 0, width: 0, height: 0 });
+    expect(svg.getComputedTextLength()).toBe(0);
+    expect((svg.getScreenCTM() as { a: number }).a).toBe(1);
+    expect((svg.getCTM() as { a: number }).a).toBe(1);
+  });
+
+  it('checkVisibility reports true (no layout culling on the server)', () => {
+    const window = createFakeWindow();
+    applySvgGeometryPolyfills(window);
+    const element = prototypeOf(window, 'Element') as Record<string, () => boolean>;
+    expect(element.checkVisibility()).toBe(true);
+  });
+
+  it('keeps a provider-supplied fill-if-missing method (checkVisibility)', () => {
+    const window = createFakeWindow();
+    prototypeOf(window, 'Element').checkVisibility = alwaysVisible;
+    applySvgGeometryPolyfills(window);
+    expect(prototypeOf(window, 'Element').checkVisibility).toBe(alwaysVisible);
+  });
+});
+
+describe('applySvgGeometryPolyfills — text measurement', () => {
+  it('getBBox measures text width and stays empty for non-text nodes', () => {
+    const window = createFakeWindow();
+    applySvgGeometryPolyfills(window);
+
+    const text = createTextNode(window, 'Hello', { 'font-size': '16' }) as { getBBox: () => { width: number } };
+    expect(text.getBBox().width).toBeGreaterThan(0);
+
+    const rect = createNodeWith(prototypeOf(window, 'SVGElement')) as Record<string, unknown> & {
+      getBBox: () => unknown;
+    };
+    rect.localName = 'rect';
+    expect(rect.getBBox()).toEqual({ x: 0, y: 0, width: 0, height: 0 });
+  });
+
+  it('honors text-anchor=middle by centering the bbox (x = -width / 2)', () => {
+    const window = createFakeWindow();
+    applySvgGeometryPolyfills(window);
+    const text = createTextNode(window, 'Centered', { 'font-size': '16', 'text-anchor': 'middle' }) as {
+      getBBox: () => { x: number; width: number };
+    };
+    const bbox = text.getBBox();
+    expect(bbox.x).toBeCloseTo(-bbox.width / 2);
+  });
+
+  it('getComputedTextLength returns the measured text width', () => {
+    const window = createFakeWindow();
+    applySvgGeometryPolyfills(window);
+    const text = createTextNode(window, 'Hello', { 'font-size': '16' }) as { getComputedTextLength: () => number };
+    expect(text.getComputedTextLength()).toBeGreaterThan(0);
+  });
+});
+
+describe('applySvgGeometryPolyfills — className accessor', () => {
+  it('exposes an SVGAnimatedString-like className backed by the class attribute', () => {
+    const window = createFakeWindow();
+    applySvgGeometryPolyfills(window);
+    const node = createNodeWith(prototypeOf(window, 'SVGElement')) as {
+      className: { baseVal: string; animVal: string };
+      getAttribute: (name: string) => string | null;
+    };
+
+    node.className.baseVal = 'shape selected';
+    expect(node.getAttribute('class')).toBe('shape selected');
+    expect(node.className.baseVal).toBe('shape selected');
+    expect(node.className.animVal).toBe('shape selected');
+  });
+});
+
+describe('applySvgGeometryPolyfills — transform list', () => {
+  it('reports no items and a null consolidate when there is no transform', () => {
+    const window = createFakeWindow();
+    applySvgGeometryPolyfills(window);
+    const node = createNodeWith(prototypeOf(window, 'SVGElement')) as {
+      transform: { baseVal: { numberOfItems: number; consolidate: () => unknown } };
+    };
+
+    expect(node.transform.baseVal.numberOfItems).toBe(0);
+    expect(node.transform.baseVal.consolidate()).toBeNull();
+  });
+
+  it('consolidate parses the transform attribute into a real matrix', () => {
+    const window = createFakeWindow();
+    applySvgGeometryPolyfills(window);
+    const node = createNodeWith(prototypeOf(window, 'SVGElement')) as {
+      transform: { baseVal: { numberOfItems: number; consolidate: () => { matrix: { e: number; f: number } } } };
+      setAttribute: (name: string, value: string) => void;
+    };
+
+    node.setAttribute('transform', 'translate(10,20)');
+    expect(node.transform.baseVal.numberOfItems).toBe(1);
+    const consolidated = node.transform.baseVal.consolidate();
+    expect(consolidated.matrix.e).toBe(10);
+    expect(consolidated.matrix.f).toBe(20);
+  });
+});
diff --git a/packages/joint-svg-shim/src/__tests__/text-metrics.test.ts b/packages/joint-svg-shim/src/__tests__/text-metrics.test.ts
new file mode 100644
index 0000000000..832eb4f454
--- /dev/null
+++ b/packages/joint-svg-shim/src/__tests__/text-metrics.test.ts
@@ -0,0 +1,58 @@
+/**
+ * @jest-environment node
+ *
+ * Runs in the `node` environment (no `document`). With `@napi-rs/canvas` installed
+ * (the package's dev/test setup) widths are exact, font-matched metrics; without
+ * it they fall back to a coarse average-glyph estimate. The scaling and ordering
+ * properties asserted here hold for both backends — exact-canvas widths are
+ * subject to per-glyph kerning, so only font-size scaling is asserted to be
+ * strictly linear, not character count.
+ */
+import { measureText } from '../text-metrics';
+
+describe('measureText', () => {
+  it('returns zero width for empty text', () => {
+    expect(measureText('', { fontSize: 16 }).width).toBe(0);
+  });
+
+  it('produces a positive width and vertical metrics for non-empty text', () => {
+    const box = measureText('renderToString', { fontSize: 16 });
+    expect(box.width).toBeGreaterThan(0);
+    expect(box.ascent).toBeGreaterThan(0);
+    expect(box.descent).toBeGreaterThan(0);
+  });
+
+  it('scales width linearly with font size', () => {
+    const at16 = measureText('renderToString', { fontSize: 16 }).width;
+    const at32 = measureText('renderToString', { fontSize: 32 }).width;
+    expect(at32).toBeCloseTo(at16 * 2);
+  });
+
+  it('scales the vertical box with font size', () => {
+    const small = measureText('X', { fontSize: 16 });
+    const large = measureText('X', { fontSize: 32 });
+    expect(large.ascent + large.descent).toBeCloseTo((small.ascent + small.descent) * 2);
+  });
+
+  it('width grows roughly with the character count', () => {
+    // Exact canvas metrics include per-glyph kerning, so repeating a glyph is not
+    // perfectly N× a single glyph; assert monotonic growth within a loose band.
+    const one = measureText('a', { fontSize: 16 }).width;
+    const five = measureText('aaaaa', { fontSize: 16 }).width;
+    expect(five).toBeGreaterThan(one);
+    expect(five).toBeLessThanOrEqual(one * 5 + 1);
+    expect(five).toBeGreaterThanOrEqual(one * 4);
+  });
+
+  it('width grows with text length', () => {
+    const short = measureText('Hi', { fontSize: 16 }).width;
+    const long = measureText('a considerably longer label', { fontSize: 16 }).width;
+    expect(long).toBeGreaterThan(short);
+  });
+
+  it('bold text is at least as wide as regular', () => {
+    const regular = measureText('Bold?', { fontSize: 16 }).width;
+    const bold = measureText('Bold?', { fontSize: 16, bold: true }).width;
+    expect(bold).toBeGreaterThanOrEqual(regular);
+  });
+});
diff --git a/packages/joint-svg-shim/src/dom-shim-flag.ts b/packages/joint-svg-shim/src/dom-shim-flag.ts
new file mode 100644
index 0000000000..2a5a95354f
--- /dev/null
+++ b/packages/joint-svg-shim/src/dom-shim-flag.ts
@@ -0,0 +1,8 @@
+/**
+ * Global flag the DOM shim sets on `globalThis` once installed. It lets a server
+ * render be detected even when a headless `document` exists — so
+ * `typeof document === 'undefined'` alone is not enough. Shared by the shim
+ * (which sets it) and any server-detection check (which reads it), so they agree
+ * on the key.
+ */
+export const DOM_SHIM_FLAG = '__JOINTJS_SVG_SHIM__';
diff --git a/packages/joint-svg-shim/src/index.ts b/packages/joint-svg-shim/src/index.ts
new file mode 100644
index 0000000000..9c23bb3538
--- /dev/null
+++ b/packages/joint-svg-shim/src/index.ts
@@ -0,0 +1,35 @@
+/**
+ * `@joint/svg-shim` — a headless DOM + SVG-geometry shim that lets JointJS's
+ * SVG/Vectorizer code run in Node (server-side rendering).
+ *
+ * Two ways to use it:
+ * - Side-effect entry: `import '@joint/svg-shim/install';` installs the shim
+ *   (jsdom by default) before anything that pulls in `@joint/core`.
+ * - Programmatic: call {@link installDomShim} with a {@link DomProvider} (jsdom,
+ *   happy-dom, or a custom factory), and register a {@link TextStyleResolver} via
+ *   {@link setTextStyleResolver} so themed text is measured at the right size.
+ */
+export {
+  installDomShim,
+  isDomShimInstalled,
+  DEFAULT_DOM_PROVIDER,
+} from './install-dom-shim';
+export type {
+  DomShimOptions,
+  DomProvider,
+  ShimWindow,
+  ShimWindowFactory,
+} from './install-dom-shim';
+
+export { setTextStyleResolver, resolveTextStyle } from './text-style-resolver';
+export type { TextStyle, TextStyleResolver } from './text-style-resolver';
+
+export { measureText } from './text-metrics';
+export type { TextBox, TextMeasureOptions } from './text-metrics';
+
+export { getNodeRequire } from './node-require';
+
+export { DOM_SHIM_FLAG } from './dom-shim-flag';
+
+export { applySvgGeometryPolyfills } from './svg-polyfills';
+export type { PolyfillWindow } from './svg-polyfills';
diff --git a/packages/joint-svg-shim/src/install-dom-shim.ts b/packages/joint-svg-shim/src/install-dom-shim.ts
new file mode 100644
index 0000000000..9394683413
--- /dev/null
+++ b/packages/joint-svg-shim/src/install-dom-shim.ts
@@ -0,0 +1,218 @@
+/**
+ * Headless DOM environment for server-side rendering of a JointJS paper.
+ *
+ * `@joint/core`'s `dia.Paper` builds real SVG DOM via `document.createElementNS`
+ * and the Vectorizer. In Node there is no `document`, and even a fake DOM (jsdom)
+ * implements no SVG **layout** — so `createSVGMatrix`, `getBBox`, `transform`,
+ * etc. are missing. This module installs a DOM window as the process globals and
+ * applies the SVG-geometry polyfills (see `./svg-polyfills`), so a paper can be
+ * constructed and serialized.
+ *
+ * **Ordering contract:** this must run *before* `@joint/core` is first evaluated
+ * (the Vectorizer captures `window.SVGAngle` at module-eval time). Import the
+ * `@joint/svg-shim/install` side-effect entry before anything that pulls in
+ * `@joint/core`.
+ *
+ * The install is idempotent and reuses a single window for the lifetime of the
+ * process — per-render work allocates only a host element + paper.
+ */
+import { DOM_SHIM_FLAG } from './dom-shim-flag';
+import { getNodeRequire } from './node-require';
+import { applySvgGeometryPolyfills, type PolyfillWindow } from './svg-polyfills';
+
+/**
+ * Structural shape of the DOM window the shim needs. jsdom's `window` satisfies
+ * it, so a custom provider factory can return a different implementation.
+ */
+export interface ShimWindow extends PolyfillWindow {
+  navigator: Navigator;
+}
+
+/** A factory returning the DOM window to install. */
+export type ShimWindowFactory = () => ShimWindow;
+
+/**
+ * DOM provider for the shim:
+ * - `'jsdom'` (default) — the bundled provider. jsdom creates real `SVGElement`s
+ *   with a spec-compliant `className`, both of which the Vectorizer requires.
+ * - `'happy-dom'` — a lighter optional backend (install the `happy-dom` peer).
+ *   happy-dom also creates real `SVGElement`s (with `SVGSVGElement` /
+ *   `SVGTextElement` and the `SVGElement` prototype chain), so the same global
+ *   bridge + polyfill flow applies; the polyfills override its stub
+ *   `getBBox`/`createSVGMatrix` with real geometry.
+ * - a custom factory — bring your own window (e.g. a pooled instance). It must
+ *   yield real `SVGElement`s, since the Vectorizer reads SVG-specific surfaces.
+ */
+export type DomProvider = 'jsdom' | 'happy-dom' | ShimWindowFactory;
+
+/** Options for {@link installDomShim}. */
+export interface DomShimOptions {
+  /** DOM provider. Defaults to `'jsdom'`. */
+  readonly provider?: DomProvider;
+}
+
+/** The provider used when none is specified. */
+export const DEFAULT_DOM_PROVIDER = 'jsdom';
+
+/** Bare DOM constructors / helpers JointJS references as globals (not via `window.`). */
+const GLOBAL_BRIDGE_KEYS = [
+  'SVGElement',
+  'SVGSVGElement',
+  'SVGGraphicsElement',
+  'SVGPathElement',
+  'SVGGElement',
+  'SVGTextElement',
+  'SVGTextContentElement',
+  'Element',
+  'Node',
+  'HTMLElement',
+  // `dia.Paper.drawBackground` checks `img instanceof HTMLImageElement` even with
+  // no background image — without the bridge that `instanceof` throws a
+  // ReferenceError. `Image` is the matching constructor consumers may use.
+  'HTMLImageElement',
+  'Image',
+  'DocumentFragment',
+  'Event',
+  'CustomEvent',
+  'MutationObserver',
+  'DOMParser',
+  'XMLSerializer',
+  'NodeFilter',
+  'getComputedStyle',
+  'requestAnimationFrame',
+  'cancelAnimationFrame',
+] as const;
+
+/** Loads an optional peer DOM library, with an actionable error when missing. */
+function loadOptionalModule<T>(moduleName: string): T {
+  try {
+    return getNodeRequire()(moduleName) as T;
+  } catch {
+    throw new Error(
+      `The headless SVG shim requires the "${moduleName}" package for server-side ` +
+        `rendering but it is not installed. Install it with \`yarn add ${moduleName}\`, ` +
+        'or pass a custom DOM provider factory.'
+    );
+  }
+}
+
+/** Minimal surface of the jsdom module the shim uses (optional peer dependency). */
+interface JsdomModule {
+  JSDOM: new (
+    html: string,
+    options?: { pretendToBeVisual?: boolean }
+  ) => { window: ShimWindow };
+}
+
+/** Creates a jsdom window (the bundled default provider). */
+function createJsdomWindow(): ShimWindow {
+  const { JSDOM } = loadOptionalModule<JsdomModule>('jsdom');
+  const { window } = new JSDOM('<!DOCTYPE html><html><body></body></html>', {
+    pretendToBeVisual: true,
+  });
+  return window;
+}
+
+/** Minimal surface of the happy-dom module the shim uses (optional peer dependency). */
+interface HappyDomModule {
+  Window: new () => ShimWindow;
+}
+
+/** Creates a happy-dom window (the lighter optional provider). */
+function createHappyDomWindow(): ShimWindow {
+  const { Window } = loadOptionalModule<HappyDomModule>('happy-dom');
+  return new Window() as unknown as ShimWindow;
+}
+
+/** Resolves a {@link DomProvider} to a window factory. */
+function resolveWindowFactory(provider: DomProvider): ShimWindowFactory {
+  if (typeof provider === 'function') {
+    return provider;
+  }
+  if (provider === 'happy-dom') {
+    return createHappyDomWindow;
+  }
+  return createJsdomWindow;
+}
+
+/**
+ * Bridges bare globals, ensures the Vectorizer's `SVGAngle` guard passes, applies
+ * the SVG-geometry polyfills, and marks the shim installed.
+ * @param window - the DOM window now backing the globals.
+ * @param globalScope - the global object to attach bridges and the flag to.
+ */
+function finalizeShim(window: ShimWindow, globalScope: ShimWindow & Record<string, unknown>): void {
+  // Vectorizer's `isSVGSupported` guard is `typeof window === 'object' && !!window.SVGAngle`.
+  if (window.SVGAngle === undefined) {
+    window.SVGAngle = function SVGAngle() {};
+  }
+  if (globalScope.SVGAngle === undefined) {
+    globalScope.SVGAngle = window.SVGAngle;
+  }
+  for (const key of GLOBAL_BRIDGE_KEYS) {
+    const value = window[key];
+    if (value !== undefined && globalScope[key] === undefined) {
+      globalScope[key] = value;
+    }
+  }
+  // A no-op ResizeObserver so code that constructs one doesn't crash. It never
+  // fires: jsdom has no layout, so a real one would report 0×0 and overwrite the
+  // model-provided element sizes — element sizes must come from the model on the
+  // server.
+  if (globalScope.ResizeObserver === undefined) {
+    globalScope.ResizeObserver = class ResizeObserver {
+      observe(): void {}
+      unobserve(): void {}
+      disconnect(): void {}
+    };
+  }
+  applySvgGeometryPolyfills(window);
+  globalScope[DOM_SHIM_FLAG] = true;
+}
+
+/**
+ * Installs the headless DOM globals required to render a JointJS paper in Node.
+ *
+ * Idempotent: the first call creates the window (jsdom by default) or reuses an
+ * existing DOM, bridges the bare-global constructors, and applies the SVG
+ * polyfills. Subsequent calls are no-ops.
+ * @param options - optional DOM provider override.
+ * @returns the installed `document`.
+ */
+export function installDomShim(options: DomShimOptions = {}): Document {
+  const globalScope = globalThis as ShimWindow & Record<string, unknown>;
+  // `globalThis.document` is `Document` in the lib types but genuinely absent in Node.
+  const existingDocument = globalScope.document as Document | undefined;
+  if (globalScope[DOM_SHIM_FLAG] === true && existingDocument !== undefined) {
+    return existingDocument;
+  }
+
+  // Reuse an existing DOM (e.g. a jsdom test environment) instead of creating a
+  // second window that would clobber it — only the SVG polyfills are applied.
+  if (existingDocument !== undefined) {
+    const existingWindow = (globalScope.window ?? globalScope) as ShimWindow;
+    finalizeShim(existingWindow, globalScope);
+    return existingWindow.document;
+  }
+
+  const window = resolveWindowFactory(options.provider ?? DEFAULT_DOM_PROVIDER)();
+  globalScope.window = window;
+  globalScope.document = window.document;
+  // Modern Node (21+) exposes a read-only global `navigator` getter — assigning
+  // to it throws. Only set ours when the runtime has none (older Node, where the
+  // jsdom navigator is needed). Cast: the lib types say `navigator` is always
+  // defined, but at runtime it genuinely can be absent.
+  if ((globalScope as { navigator?: unknown }).navigator === undefined) {
+    globalScope.navigator = window.navigator;
+  }
+  finalizeShim(window, globalScope);
+  return window.document;
+}
+
+/**
+ * Whether the headless DOM shim has been installed in the current process.
+ * @returns `true` when {@link installDomShim} has run.
+ */
+export function isDomShimInstalled(): boolean {
+  return (globalThis as Record<string, unknown>)[DOM_SHIM_FLAG] === true;
+}
diff --git a/packages/joint-svg-shim/src/install.ts b/packages/joint-svg-shim/src/install.ts
new file mode 100644
index 0000000000..2133ec98dd
--- /dev/null
+++ b/packages/joint-svg-shim/src/install.ts
@@ -0,0 +1,12 @@
+/**
+ * Side-effect entry (`@joint/svg-shim/install`) that installs the headless DOM
+ * shim on import.
+ *
+ * Import this *first* — before anything that pulls in `@joint/core` — so the shim
+ * is in place before the Vectorizer captures its DOM globals at module-eval time.
+ * ES modules evaluate dependencies in source order, so a bare
+ * `import '@joint/svg-shim/install';` at the top of an SSR entry is enough.
+ */
+import { installDomShim } from './install-dom-shim';
+
+installDomShim();
diff --git a/packages/joint-svg-shim/src/node-require.ts b/packages/joint-svg-shim/src/node-require.ts
new file mode 100644
index 0000000000..15f78a507d
--- /dev/null
+++ b/packages/joint-svg-shim/src/node-require.ts
@@ -0,0 +1,19 @@
+import { createRequire } from 'node:module';
+// eslint-disable-next-line unicorn/import-style
+import { join } from 'node:path';
+
+/**
+ * Resolves a synchronous `require` for loading optional Node-only peers
+ * (`jsdom`, `@napi-rs/canvas`) and package assets (the theme stylesheet).
+ *
+ * Anchored at the working directory (not this module): optional peers and the
+ * consumer's assets live in the CONSUMING project's `node_modules`, which a
+ * module-anchored `require` may miss in a monorepo / symlinked checkout (where
+ * this package resolves to a different `node_modules` subtree than the app's).
+ * Works in both CommonJS (Jest) and native ESM (e.g. Bun). `import.meta` is
+ * avoided because it cannot appear in a file also transpiled to CommonJS.
+ * @returns a `require` able to resolve installed packages and assets.
+ */
+export function getNodeRequire(): ReturnType<typeof createRequire> {
+  return createRequire(join(process.cwd(), 'noop.js'));
+}
diff --git a/packages/joint-svg-shim/src/svg-element-proxies.ts b/packages/joint-svg-shim/src/svg-element-proxies.ts
new file mode 100644
index 0000000000..bb669f37df
--- /dev/null
+++ b/packages/joint-svg-shim/src/svg-element-proxies.ts
@@ -0,0 +1,178 @@
+/**
+ * Element-level SVG polyfills the Vectorizer needs but fake DOMs (jsdom) may not
+ * supply: a spec-compliant `className` (`SVGAnimatedString`), a working
+ * `transform.baseVal` transform list backed by the `transform` attribute, and a
+ * bare-number `style.font-size` → `px` coercion. Each is a no-op when the provider
+ * is already compliant.
+ */
+import {
+  createTransform,
+  createTransformFromMatrix,
+  matrixToTransformString,
+  parseTransformString,
+  type SvgMatrixLike,
+  type SvgTransformLike,
+} from './svg-matrix';
+import { getPrototype, SVG_NAMESPACE, type PolyfillWindow } from './svg-prototype';
+
+const BARE_NUMBER = /^-?(?:\d+(?:\.\d+)?|\.\d+)$/;
+
+/** Minimal element surface the `className` / `transform` accessors need. */
+export interface AttributeHost {
+  getAttribute: (name: string) => string | null;
+  setAttribute: (name: string, value: string) => void;
+}
+
+/** Builds an `SVGAnimatedString`-like accessor backed by a node's `class` attribute. */
+export function createClassNameProxy(node: AttributeHost) {
+  return {
+    get baseVal(): string {
+      return node.getAttribute('class') ?? '';
+    },
+    set baseVal(value: string) {
+      node.setAttribute('class', value);
+    },
+    get animVal(): string {
+      return node.getAttribute('class') ?? '';
+    },
+  };
+}
+
+/**
+ * Ensures SVG elements expose `className` as a spec-compliant `SVGAnimatedString`
+ * (with `baseVal`), which the Vectorizer requires. jsdom already does; some
+ * providers return a plain string. No-op when already compliant.
+ * @param window - the DOM window to probe.
+ * @param svgPrototype - `SVGElement.prototype`, when present.
+ */
+export function applyClassNamePolyfill(
+  window: PolyfillWindow,
+  svgPrototype: Record<string, unknown> | undefined
+): void {
+  if (!svgPrototype) return;
+  let current: unknown;
+  try {
+    const probe = window.document.createElementNS(SVG_NAMESPACE, 'g') as unknown as { className: unknown };
+    current = probe.className;
+  } catch {
+    return;
+  }
+  const isCompliant = current !== null && typeof current === 'object' && 'baseVal' in (current as object);
+  if (isCompliant) return;
+
+  try {
+    Object.defineProperty(svgPrototype, 'className', {
+      configurable: true,
+      get(this: AttributeHost) {
+        return createClassNameProxy(this);
+      },
+    });
+  } catch {
+    // Provider's `className` is non-configurable — leave it as-is.
+  }
+}
+
+/** A minimal `SVGTransformList` backed by a node's `transform` attribute. */
+export function createTransformList(node: AttributeHost) {
+  return {
+    get numberOfItems(): number {
+      return node.getAttribute('transform') ? 1 : 0;
+    },
+    consolidate(): SvgTransformLike | null {
+      const value = node.getAttribute('transform');
+      if (!value) return null;
+      const transform = createTransform();
+      transform.setMatrix(parseTransformString(value));
+      return transform;
+    },
+    getItem(): SvgTransformLike {
+      const transform = createTransform();
+      transform.setMatrix(parseTransformString(node.getAttribute('transform') ?? ''));
+      return transform;
+    },
+    appendItem(item: SvgTransformLike): SvgTransformLike {
+      const current = parseTransformString(node.getAttribute('transform') ?? '');
+      node.setAttribute('transform', matrixToTransformString(current.multiply(item.matrix)));
+      return item;
+    },
+    initialize(item: SvgTransformLike): SvgTransformLike {
+      node.setAttribute('transform', matrixToTransformString(item.matrix));
+      return item;
+    },
+    clear(): void {
+      node.setAttribute('transform', '');
+    },
+    createSVGTransformFromMatrix(matrix: SvgMatrixLike): SvgTransformLike {
+      return createTransformFromMatrix(matrix);
+    },
+  };
+}
+
+/**
+ * Adds `SVGElement.prototype.transform` (with a working `baseVal` transform list)
+ * when the provider lacks it — the Vectorizer reads
+ * `node.transform.baseVal.consolidate()` for some geometry. Returns the real
+ * matrix parsed from the `transform` attribute. No-op when already implemented.
+ * @param window - the DOM window to probe.
+ * @param svgPrototype - `SVGElement.prototype`, when present.
+ */
+export function applyTransformPolyfill(
+  window: PolyfillWindow,
+  svgPrototype: Record<string, unknown> | undefined
+): void {
+  if (!svgPrototype) return;
+  let hasTransformList = false;
+  try {
+    const probe = window.document.createElementNS(SVG_NAMESPACE, 'g') as unknown as {
+      transform?: { baseVal?: { consolidate?: unknown } };
+    };
+    hasTransformList = typeof probe.transform?.baseVal?.consolidate === 'function';
+  } catch {
+    return;
+  }
+  if (hasTransformList) return;
+
+  try {
+    Object.defineProperty(svgPrototype, 'transform', {
+      configurable: true,
+      get(this: AttributeHost) {
+        return { baseVal: createTransformList(this) };
+      },
+    });
+  } catch {
+    // Provider's `transform` is non-configurable — leave it as-is.
+  }
+}
+
+/**
+ * Coerces a bare numeric `style.font-size` (e.g. `12`) to `px`, like the browser
+ * and React do. JointJS sets numeric font sizes via `element.style.fontSize`;
+ * jsdom otherwise rejects them as invalid CSS and drops the value — so the server
+ * would lose the inline size the browser actually applies (and over-size text to
+ * the theme class instead).
+ * @param window - the DOM window whose `CSSStyleDeclaration` is patched.
+ */
+export function applyFontSizeCoercion(window: PolyfillWindow): void {
+  const stylePrototype = getPrototype(window, 'CSSStyleDeclaration');
+  const descriptor = stylePrototype && Object.getOwnPropertyDescriptor(stylePrototype, 'fontSize');
+  if (!descriptor || typeof descriptor.get !== 'function' || typeof descriptor.set !== 'function') {
+    return;
+  }
+  const originalSet = descriptor.set;
+  try {
+    Object.defineProperty(stylePrototype, 'fontSize', {
+      configurable: true,
+      enumerable: descriptor.enumerable,
+      get: descriptor.get,
+      set(value: unknown) {
+        if (typeof value === 'number' || (typeof value === 'string' && BARE_NUMBER.test(value.trim()))) {
+          originalSet.call(this, `${value}px`);
+          return;
+        }
+        originalSet.call(this, value);
+      },
+    });
+  } catch {
+    // Provider's `fontSize` is non-configurable — leave it as-is.
+  }
+}
diff --git a/packages/joint-svg-shim/src/svg-matrix.ts b/packages/joint-svg-shim/src/svg-matrix.ts
new file mode 100644
index 0000000000..5c5d00f3e9
--- /dev/null
+++ b/packages/joint-svg-shim/src/svg-matrix.ts
@@ -0,0 +1,226 @@
+/* eslint-disable unicorn/prevent-abbreviations */
+/**
+ * Pure SVG geometry primitives — affine matrix, point, transform, and a
+ * `transform` attribute parser. No DOM access; used by the SVG polyfills to give
+ * `@joint/core`'s Vectorizer real geometry on a headless DOM (jsdom has none).
+ */
+
+/** Minimal affine 2D matrix matching the `SVGMatrix` surface JointJS uses. */
+export interface SvgMatrixLike {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  e: number;
+  f: number;
+  multiply: (other: SvgMatrixLike) => SvgMatrixLike;
+  inverse: () => SvgMatrixLike;
+  translate: (x: number, y: number) => SvgMatrixLike;
+  scale: (factor: number) => SvgMatrixLike;
+  scaleNonUniform: (scaleX: number, scaleY: number) => SvgMatrixLike;
+  rotate: (degrees: number) => SvgMatrixLike;
+  flipX: () => SvgMatrixLike;
+  flipY: () => SvgMatrixLike;
+  skewX: (degrees: number) => SvgMatrixLike;
+  skewY: (degrees: number) => SvgMatrixLike;
+}
+
+/** Minimal `SVGPoint` surface (`matrixTransform` only). */
+export interface SvgPointLike {
+  x: number;
+  y: number;
+  matrixTransform: (matrix: SvgMatrixLike) => SvgPointLike;
+}
+
+/** Minimal `SVGTransform` surface (`matrix` + setters). */
+export interface SvgTransformLike {
+  matrix: SvgMatrixLike;
+  angle: number;
+  type: number;
+  setMatrix: (matrix: SvgMatrixLike) => void;
+  setTranslate: (x: number, y: number) => void;
+}
+
+const DEGREES_TO_RADIANS = Math.PI / 180;
+
+/**
+ * Creates an affine 2D matrix `[a c e; b d f; 0 0 1]` with `SVGMatrix` methods.
+ * `a`–`f` are the universal SVGMatrix component names.
+ */
+export function createMatrix(
+  a: number,
+  b: number,
+  c: number,
+  d: number,
+  e: number,
+  f: number
+): SvgMatrixLike {
+  return {
+    a,
+    b,
+    c,
+    d,
+    e,
+    f,
+    multiply(other) {
+      return createMatrix(
+        this.a * other.a + this.c * other.b,
+        this.b * other.a + this.d * other.b,
+        this.a * other.c + this.c * other.d,
+        this.b * other.c + this.d * other.d,
+        this.a * other.e + this.c * other.f + this.e,
+        this.b * other.e + this.d * other.f + this.f
+      );
+    },
+    inverse() {
+      const determinant = this.a * this.d - this.b * this.c;
+      if (determinant === 0) {
+        throw new Error('Cannot invert a singular matrix.');
+      }
+      const inverseA = this.d / determinant;
+      const inverseB = -this.b / determinant;
+      const inverseC = -this.c / determinant;
+      const inverseD = this.a / determinant;
+      return createMatrix(
+        inverseA,
+        inverseB,
+        inverseC,
+        inverseD,
+        -(inverseA * this.e + inverseC * this.f),
+        -(inverseB * this.e + inverseD * this.f)
+      );
+    },
+    translate(x, y) {
+      return this.multiply(createMatrix(1, 0, 0, 1, x, y));
+    },
+    scale(factor) {
+      return this.multiply(createMatrix(factor, 0, 0, factor, 0, 0));
+    },
+    scaleNonUniform(scaleX, scaleY) {
+      return this.multiply(createMatrix(scaleX, 0, 0, scaleY, 0, 0));
+    },
+    rotate(degrees) {
+      const radians = degrees * DEGREES_TO_RADIANS;
+      const cos = Math.cos(radians);
+      const sin = Math.sin(radians);
+      return this.multiply(createMatrix(cos, sin, -sin, cos, 0, 0));
+    },
+    flipX() {
+      return this.multiply(createMatrix(-1, 0, 0, 1, 0, 0));
+    },
+    flipY() {
+      return this.multiply(createMatrix(1, 0, 0, -1, 0, 0));
+    },
+    skewX(degrees) {
+      return this.multiply(createMatrix(1, 0, Math.tan(degrees * DEGREES_TO_RADIANS), 1, 0, 0));
+    },
+    skewY(degrees) {
+      return this.multiply(createMatrix(1, Math.tan(degrees * DEGREES_TO_RADIANS), 0, 1, 0, 0));
+    },
+  };
+}
+
+/** The identity matrix. */
+export function createIdentityMatrix(): SvgMatrixLike {
+  return createMatrix(1, 0, 0, 1, 0, 0);
+}
+
+/** Creates an `SVGPoint`-like object. */
+export function createPoint(x: number, y: number): SvgPointLike {
+  return {
+    x,
+    y,
+    matrixTransform(matrix) {
+      return createPoint(
+        matrix.a * this.x + matrix.c * this.y + matrix.e,
+        matrix.b * this.x + matrix.d * this.y + matrix.f
+      );
+    },
+  };
+}
+
+/** Creates an `SVGTransform`-like object (identity matrix by default). */
+export function createTransform(): SvgTransformLike {
+  return {
+    matrix: createIdentityMatrix(),
+    angle: 0,
+    type: 0,
+    setMatrix(matrix) {
+      this.matrix = matrix;
+    },
+    setTranslate(x, y) {
+      this.matrix = createMatrix(1, 0, 0, 1, x, y);
+    },
+  };
+}
+
+/**
+ * Creates an `SVGTransform`-like object preset to a matrix — the
+ * `createSVGTransformFromMatrix` factory shape.
+ * @param matrix - the matrix to seed the transform with.
+ * @returns a transform whose `matrix` is the supplied matrix.
+ */
+export function createTransformFromMatrix(matrix: SvgMatrixLike): SvgTransformLike {
+  const transform = createTransform();
+  transform.setMatrix(matrix);
+  return transform;
+}
+
+/** Serializes a matrix to an SVG `transform="matrix(...)"` value. */
+export function matrixToTransformString(matrix: SvgMatrixLike): string {
+  return `matrix(${matrix.a},${matrix.b},${matrix.c},${matrix.d},${matrix.e},${matrix.f})`;
+}
+
+// eslint-disable-next-line sonarjs/slow-regex
+const TRANSFORM_FUNCTION = /([a-z]+)\(([^()]*)\)/gi;
+
+/**
+ * Parses an SVG `transform` attribute string into a single matrix — the real
+ * geometry JointJS expects from `transform.baseVal.consolidate()`. `rotate` and
+ * `scale` use the element's local origin, matching JointJS's
+ * `translate(x,y) rotate(a)` output.
+ * @param value - the `transform` attribute string.
+ * @returns the combined transformation matrix.
+ */
+export function parseTransformString(value: string): SvgMatrixLike {
+  let matrix = createIdentityMatrix();
+  for (const [, name, rawArguments] of value.matchAll(TRANSFORM_FUNCTION)) {
+    const values = rawArguments
+      .trim()
+      .split(/[\s,]+/)
+      .filter((part) => part !== '')
+      .map(Number)
+      .filter((part) => !Number.isNaN(part));
+    switch (name) {
+      case 'matrix': {
+        const [a = 1, b = 0, c = 0, d = 1, e = 0, f = 0] = values;
+        matrix = matrix.multiply(createMatrix(a, b, c, d, e, f));
+        break;
+      }
+      case 'translate': {
+        matrix = matrix.translate(values[0] ?? 0, values[1] ?? 0);
+        break;
+      }
+      case 'scale': {
+        matrix = matrix.scaleNonUniform(values[0] ?? 1, values[1] ?? values[0] ?? 1);
+        break;
+      }
+      case 'rotate': {
+        matrix = matrix.rotate(values[0] ?? 0);
+        break;
+      }
+      case 'skewX': {
+        matrix = matrix.skewX(values[0] ?? 0);
+        break;
+      }
+      case 'skewY': {
+        matrix = matrix.skewY(values[0] ?? 0);
+        break;
+      }
+      default: {
+        break;
+      }
+    }
+  }
+  return matrix;
+}
diff --git a/packages/joint-svg-shim/src/svg-polyfills.ts b/packages/joint-svg-shim/src/svg-polyfills.ts
new file mode 100644
index 0000000000..f34bdcb9ba
--- /dev/null
+++ b/packages/joint-svg-shim/src/svg-polyfills.ts
@@ -0,0 +1,134 @@
+/**
+ * Patches the SVG-geometry surface that fake DOMs (jsdom) do not implement but
+ * `@joint/core`'s Vectorizer requires. This is the single "plug the missing SVG
+ * pieces" point; every method here is something joint-core calls that jsdom
+ * lacks. Exported so a custom DOM provider can apply the same polyfills.
+ *
+ * `getBBox`/`getComputedTextLength` measure text via `./svg-text-bbox` (exact with
+ * `@napi-rs/canvas`, else estimated) so text-sized geometry — link-label backgrounds
+ * especially — is correct; for non-text nodes they return an empty box, since
+ * element/link positions come from the JointJS model (the `measureNode` preset).
+ * `getScreenCTM`/`getCTM` return identity. `transform.baseVal` returns the real
+ * matrix parsed from the `transform` attribute.
+ *
+ * The element-level proxies (`className`, `transform`, font-size coercion) live in
+ * `./svg-element-proxies`; text measurement in `./svg-text-bbox`.
+ */
+import {
+  createIdentityMatrix,
+  createPoint,
+  createTransform,
+  createTransformFromMatrix,
+  type SvgMatrixLike,
+} from './svg-matrix';
+import { getPrototype, SVG_NAMESPACE, type PolyfillWindow } from './svg-prototype';
+import { estimateBBox, measureNodeText, type TextMetricsNode } from './svg-text-bbox';
+import {
+  applyClassNamePolyfill,
+  applyFontSizeCoercion,
+  applyTransformPolyfill,
+} from './svg-element-proxies';
+
+// Re-exported so `install-dom-shim.ts` can keep importing `PolyfillWindow` from
+// here, the public polyfill entry point.
+export type { PolyfillWindow } from './svg-prototype';
+
+/** Fills the missing `createSVG*` factory methods on `SVGSVGElement.prototype`. */
+function applyFactoryPolyfills(svgSvgPrototype: Record<string, unknown> | undefined): void {
+  if (!svgSvgPrototype) return;
+  if (typeof svgSvgPrototype.createSVGMatrix !== 'function') {
+    svgSvgPrototype.createSVGMatrix = () => createIdentityMatrix();
+  }
+  if (typeof svgSvgPrototype.createSVGPoint !== 'function') {
+    svgSvgPrototype.createSVGPoint = () => createPoint(0, 0);
+  }
+  if (typeof svgSvgPrototype.createSVGTransform !== 'function') {
+    svgSvgPrototype.createSVGTransform = () => createTransform();
+  }
+  if (typeof svgSvgPrototype.createSVGTransformFromMatrix !== 'function') {
+    svgSvgPrototype.createSVGTransformFromMatrix = (matrix: SvgMatrixLike) =>
+      createTransformFromMatrix(matrix);
+  }
+}
+
+/** Whether the provider already returns real text metrics (e.g. svgdom) — then we leave it alone. */
+function providerMeasuresText(window: PolyfillWindow): boolean {
+  try {
+    const probe = window.document.createElementNS(SVG_NAMESPACE, 'text') as unknown as {
+      textContent: string;
+      getBBox?: () => { width?: number };
+    };
+    probe.textContent = 'measure';
+    const width = probe.getBBox?.().width;
+    return typeof width === 'number' && width > 0;
+  } catch {
+    return false;
+  }
+}
+
+// jsdom creates SVG elements it doesn't fully implement (e.g. `<text>`) as plain
+// `SVGElement`s, and defines `getBBox` only on `SVGGraphicsElement` — which those
+// elements don't inherit from. So a single target is unreliable: we install on
+// every SVG prototype the window exposes, so text elements get ours whatever
+// their concrete class, and overrides on a subclass can't shadow a base one.
+const MEASUREMENT_PROTOTYPE_NAMES = [
+  'SVGElement',
+  'SVGGraphicsElement',
+  'SVGTextPositioningElement',
+  'SVGTextContentElement',
+  'SVGTextElement',
+] as const;
+
+/**
+ * Installs text-aware `getBBox` + `getComputedTextLength` (and identity CTMs) on
+ * every SVG prototype, replacing jsdom's zero-returning stubs. Skipped for the
+ * measuring methods when the provider already returns real text metrics.
+ */
+function applyMeasurementPolyfills(window: PolyfillWindow): void {
+  const prototypes = MEASUREMENT_PROTOTYPE_NAMES.map((name) => getPrototype(window, name)).filter(
+    (prototype): prototype is Record<string, unknown> => prototype !== undefined
+  );
+
+  for (const prototype of prototypes) {
+    if (typeof prototype.getScreenCTM !== 'function') {
+      prototype.getScreenCTM = () => createIdentityMatrix();
+    }
+    if (typeof prototype.getCTM !== 'function') {
+      prototype.getCTM = () => createIdentityMatrix();
+    }
+  }
+
+  if (providerMeasuresText(window)) {
+    return;
+  }
+
+  for (const prototype of prototypes) {
+    prototype.getBBox = function getBBox(this: TextMetricsNode) {
+      return estimateBBox(this);
+    };
+    prototype.getComputedTextLength = function getComputedTextLength(this: TextMetricsNode) {
+      return measureNodeText(this).width;
+    };
+  }
+}
+
+/**
+ * Applies every SVG-geometry polyfill to a DOM window's prototypes. Only fills
+ * genuinely-missing methods, so a provider that ships real implementations wins.
+ * @param window - the DOM window to patch.
+ */
+export function applySvgGeometryPolyfills(window: PolyfillWindow): void {
+  applyFactoryPolyfills(getPrototype(window, 'SVGSVGElement'));
+  applyFontSizeCoercion(window);
+
+  const elementPrototype = getPrototype(window, 'Element');
+  if (elementPrototype && typeof elementPrototype.checkVisibility !== 'function') {
+    elementPrototype.checkVisibility = () => true;
+  }
+
+  applyMeasurementPolyfills(window);
+
+  const svgPrototype = getPrototype(window, 'SVGElement');
+  applyClassNamePolyfill(window, svgPrototype);
+  applyTransformPolyfill(window, svgPrototype);
+}
diff --git a/packages/joint-svg-shim/src/svg-prototype.ts b/packages/joint-svg-shim/src/svg-prototype.ts
new file mode 100644
index 0000000000..283c903c73
--- /dev/null
+++ b/packages/joint-svg-shim/src/svg-prototype.ts
@@ -0,0 +1,32 @@
+/**
+ * Shared primitives for the SVG-geometry polyfills: the structural window shape,
+ * the SVG namespace constant, and a typed prototype reader. Split out so the
+ * polyfill modules (`svg-text-bbox`, `svg-element-proxies`, `svg-polyfills`) share
+ * one definition without a circular dependency.
+ */
+
+/** Structural shape of the DOM window the polyfills patch. */
+export interface PolyfillWindow {
+  document: Document;
+  [key: string]: unknown;
+}
+
+export const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+
+interface PrototypeHolder {
+  prototype: Record<string, unknown>;
+}
+
+/**
+ * Reads a constructor's prototype from a window without `any`.
+ * @param window - the DOM window to read the constructor from.
+ * @param constructorName - the global constructor name (e.g. `'SVGElement'`).
+ * @returns the constructor's prototype, or `undefined` when absent.
+ */
+export function getPrototype(
+  window: PolyfillWindow,
+  constructorName: string
+): Record<string, unknown> | undefined {
+  const constructor = window[constructorName] as PrototypeHolder | undefined;
+  return constructor?.prototype;
+}
diff --git a/packages/joint-svg-shim/src/svg-text-bbox.ts b/packages/joint-svg-shim/src/svg-text-bbox.ts
new file mode 100644
index 0000000000..0d6d92c3c9
--- /dev/null
+++ b/packages/joint-svg-shim/src/svg-text-bbox.ts
@@ -0,0 +1,143 @@
+/**
+ * Server-side text bounding-box estimation for the SVG shim.
+ *
+ * `getBBox`/`getComputedTextLength` measure text via `./text-metrics` (exact with
+ * `@napi-rs/canvas`, else estimated), honoring the consumer theme's class fonts
+ * (`./text-style-resolver`), so text-sized geometry — link-label backgrounds
+ * especially — matches the browser. Non-text nodes get an empty box, since
+ * element/link positions come from the JointJS model.
+ */
+import { measureText } from './text-metrics';
+import { resolveTextStyle } from './text-style-resolver';
+
+const DEFAULT_FONT_SIZE = 16;
+const BOLD_WEIGHT_THRESHOLD = 600;
+const TEXT_TAGS = new Set(['text', 'tspan', 'textPath']);
+// cspell:ignore bbox svgdom
+const ZERO_BOX = { x: 0, y: 0, width: 0, height: 0 };
+// Trailing CSS unit of a `dy` value (e.g. `px`, `ex`, `%`), after the number.
+const DY_UNIT = /[\d.]\s*([a-z%]+)\s*$/i;
+
+/** The subset of a text element the metric reader needs. */
+export interface TextMetricsNode {
+  readonly localName?: string;
+  readonly textContent?: string | null;
+  readonly getAttribute?: (name: string) => string | null;
+  readonly style?: { fontSize?: string; fontFamily?: string; textAnchor?: string; fontWeight?: string };
+  /** First child element — the `<tspan>` whose `dy` shifts the baseline. */
+  readonly firstElementChild?: { getAttribute?: (name: string) => string | null } | null;
+}
+
+/** Reads an inline-style font value as a string, or `''` when absent. */
+function inlineStyle(node: TextMetricsNode, property: 'fontSize' | 'fontFamily' | 'fontWeight'): string {
+  const value = node.style?.[property];
+  return typeof value === 'string' ? value : '';
+}
+
+// Effective value precedence mirrors CSS: inline style beats a theme class, which
+// beats the element's presentation attribute.
+
+/** Resolves the effective font size (px): inline → theme class → attribute → default. */
+function resolveFontSize(node: TextMetricsNode, themeValue: string | undefined): number {
+  const attribute = node.getAttribute?.('font-size') ?? '';
+  const parsed = Number.parseFloat(inlineStyle(node, 'fontSize') || (themeValue ?? '') || attribute);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_FONT_SIZE;
+}
+
+/** Resolves the effective font family: inline → theme class → attribute, or `undefined`. */
+function resolveFontFamily(node: TextMetricsNode, themeValue: string | undefined): string | undefined {
+  const family = (inlineStyle(node, 'fontFamily') || (themeValue ?? '') || node.getAttribute?.('font-family') || '').trim();
+  return family || undefined;
+}
+
+/** Resolves whether the effective weight is bold: inline → theme class → attribute. */
+function resolveBold(node: TextMetricsNode, themeValue: string | undefined): boolean {
+  const weight = inlineStyle(node, 'fontWeight') || (themeValue ?? '') || node.getAttribute?.('font-weight') || '';
+  if (weight === 'bold' || weight === 'bolder') {
+    return true;
+  }
+  const numeric = Number.parseInt(weight, 10);
+  return Number.isFinite(numeric) && numeric >= BOLD_WEIGHT_THRESHOLD;
+}
+
+/** Resolves the element's text anchor (`start` | `middle` | `end`) from style/attribute. */
+function readTextAnchor(node: TextMetricsNode): string {
+  const fromStyle = typeof node.style?.textAnchor === 'string' ? node.style.textAnchor : '';
+  return fromStyle || node.getAttribute?.('text-anchor') || 'start';
+}
+
+/** Horizontal bbox offset for a text anchor — the glyph box grows from the anchor. */
+function anchorOffset(anchor: string, width: number): number {
+  if (anchor === 'middle') {
+    return -width / 2;
+  }
+  if (anchor === 'end') {
+    return -width;
+  }
+  return 0;
+}
+
+/**
+ * Reads the baseline shift (px) from the text's `<tspan dy>` (joint centers via
+ * `dy`). A bare number is taken as px and `em` is scaled by the font size; any
+ * other unit (`ex`, `%`, …) is not supported and yields no shift, so it cannot
+ * mis-position the box.
+ */
+function readBaselineShift(node: TextMetricsNode, fontSize: number): number {
+  const dy = (node.firstElementChild?.getAttribute?.('dy') ?? '').trim();
+  if (dy === '') {
+    return 0;
+  }
+  const value = Number.parseFloat(dy);
+  if (!Number.isFinite(value)) {
+    return 0;
+  }
+  if (dy.endsWith('em')) {
+    return value * fontSize;
+  }
+  // Bare numbers (and explicit `px`) are px; any other unit (`ex`, `%`, …) is
+  // unsupported and yields no shift, so it cannot mis-position the box.
+  const unit = DY_UNIT.exec(dy)?.[1] ?? '';
+  if (unit !== '' && unit !== 'px') {
+    return 0;
+  }
+  return value;
+}
+
+/** Measures a text node's box (width + baseline-relative extent), honoring theme CSS. */
+export function measureNodeText(node: TextMetricsNode): {
+  width: number;
+  ascent: number;
+  descent: number;
+  fontSize: number;
+} {
+  const theme = resolveTextStyle(node.getAttribute?.('class') ?? '');
+  const fontSize = resolveFontSize(node, theme.fontSize);
+  const box = measureText(node.textContent ?? '', {
+    fontSize,
+    bold: resolveBold(node, theme.fontWeight),
+    fontFamily: resolveFontFamily(node, theme.fontFamily),
+  });
+  return { ...box, fontSize };
+}
+
+/**
+ * A node's bounding box — measured metrics for text, an empty box otherwise.
+ * @param node - the SVG node to size.
+ * @returns the bounding box (`{ x, y, width, height }`).
+ */
+export function estimateBBox(node: TextMetricsNode): { x: number; y: number; width: number; height: number } {
+  if (node.localName !== undefined && TEXT_TAGS.has(node.localName)) {
+    const { width, ascent, descent, fontSize } = measureNodeText(node);
+    // The browser positions text from the baseline (y = 0), shifted by the
+    // `<tspan dy>`; the box runs from `dy - ascent` to `dy + descent`.
+    const baseline = readBaselineShift(node, fontSize);
+    return {
+      x: anchorOffset(readTextAnchor(node), width),
+      y: baseline - ascent,
+      width,
+      height: ascent + descent,
+    };
+  }
+  return { ...ZERO_BOX };
+}
diff --git a/packages/joint-svg-shim/src/text-metrics.ts b/packages/joint-svg-shim/src/text-metrics.ts
new file mode 100644
index 0000000000..d16368114f
--- /dev/null
+++ b/packages/joint-svg-shim/src/text-metrics.ts
@@ -0,0 +1,116 @@
+/**
+ * Server-side text measurement for the SVG shim.
+ *
+ * jsdom implements no text layout, so `getBBox`/`getComputedTextLength` report 0
+ * — which collapses everything sized from text (most visibly link-label
+ * backgrounds). We measure with a real Canvas 2D context from **`@napi-rs/canvas`**
+ * (Skia, prebuilt binaries — no native compilation, works in Node and Bun),
+ * giving exact, font-matched widths that scale with font size and match the
+ * browser's rendering.
+ *
+ * `@napi-rs/canvas` ships as a dependency, so metrics are pixel-exact by default.
+ * The coarse average-glyph fallback below only runs in the unlikely case it can't
+ * be loaded (e.g. an unsupported platform), purely so labels are not broken.
+ */
+// cspell:ignore napi
+import { getNodeRequire } from './node-require';
+
+/** Average glyph advance as a fraction of font size — used only without canvas. */
+const AVERAGE_GLYPH_WIDTH_RATIO = 0.6;
+// Vertical fallback metrics (fractions of font size) when canvas is unavailable —
+// a typical sans-serif font box (ascent + descent ≈ 1.2em).
+const FALLBACK_ASCENT_RATIO = 0.92;
+const FALLBACK_DESCENT_RATIO = 0.28;
+const DEFAULT_FONT_FAMILY = 'sans-serif';
+
+/** Canvas `TextMetrics`, narrowed to the fields we read. */
+interface CanvasTextMetrics {
+  width: number;
+  fontBoundingBoxAscent?: number;
+  fontBoundingBoxDescent?: number;
+}
+
+/** A Canvas 2D context, narrowed to the text-measuring surface we use. */
+interface MeasuringContext {
+  font: string;
+  measureText: (text: string) => CanvasTextMetrics;
+}
+
+/** Minimal `@napi-rs/canvas` surface we use (avoids a hard type dependency). */
+interface CanvasModule {
+  createCanvas: (width: number, height: number) => { getContext: (id: '2d') => MeasuringContext | null };
+}
+
+// `undefined` = not probed; `null` = probed, no canvas package available.
+let measuringContext: MeasuringContext | null | undefined;
+
+/** Lazily resolves a real Canvas 2D measuring context, or `null` when unavailable. */
+function getMeasuringContext(): MeasuringContext | null {
+  if (measuringContext !== undefined) {
+    return measuringContext;
+  }
+  measuringContext = null;
+  try {
+    const canvas = getNodeRequire()('@napi-rs/canvas') as CanvasModule;
+    const context = canvas.createCanvas(1, 1).getContext('2d');
+    if (context && typeof context.measureText === 'function') {
+      measuringContext = context;
+    }
+  } catch {
+    measuringContext = null;
+  }
+  return measuringContext;
+}
+
+/** Options for {@link measureText}. */
+export interface TextMeasureOptions {
+  /** Font size in px. */
+  readonly fontSize: number;
+  /** Whether the text is bold (font-weight ≥ 600). @default false */
+  readonly bold?: boolean;
+  /** The text's CSS font-family — measured against the same font the browser uses. */
+  readonly fontFamily?: string;
+}
+
+/** A text run's box: width plus the font ascent/descent above/below the baseline. */
+export interface TextBox {
+  /** Rendered width in px. */
+  readonly width: number;
+  /** Distance from the baseline to the box top (px). */
+  readonly ascent: number;
+  /** Distance from the baseline to the box bottom (px). */
+  readonly descent: number;
+}
+
+/**
+ * Measures a string's rendered box (width + vertical extent). Exact (font-matched)
+ * via `@napi-rs/canvas` when installed; otherwise a coarse estimate. The vertical
+ * metrics let `getBBox` match the browser, which positions text from the baseline
+ * (not a symmetric box).
+ * @param text - the string to measure.
+ * @param options - font size, weight, and family.
+ * @returns the text box (zero width for empty text).
+ */
+export function measureText(text: string, options: TextMeasureOptions): TextBox {
+  const { fontSize, bold = false, fontFamily = DEFAULT_FONT_FAMILY } = options;
+  const fallbackAscent = fontSize * FALLBACK_ASCENT_RATIO;
+  const fallbackDescent = fontSize * FALLBACK_DESCENT_RATIO;
+  if (text.length === 0) {
+    // Empty text occupies no box at all — no width and no vertical extent.
+    return { width: 0, ascent: 0, descent: 0 };
+  }
+  const context = getMeasuringContext();
+  if (context) {
+    context.font = `${bold ? 'bold ' : ''}${fontSize}px ${fontFamily}`;
+    const metrics = context.measureText(text);
+    if (metrics.width > 0) {
+      return {
+        width: metrics.width,
+        ascent: metrics.fontBoundingBoxAscent ?? fallbackAscent,
+        descent: metrics.fontBoundingBoxDescent ?? fallbackDescent,
+      };
+    }
+  }
+  return { width: text.length * fontSize * AVERAGE_GLYPH_WIDTH_RATIO, ascent: fallbackAscent, descent: fallbackDescent };
+}
+
diff --git a/packages/joint-svg-shim/src/text-style-resolver.ts b/packages/joint-svg-shim/src/text-style-resolver.ts
new file mode 100644
index 0000000000..db7318fe90
--- /dev/null
+++ b/packages/joint-svg-shim/src/text-style-resolver.ts
@@ -0,0 +1,43 @@
+/**
+ * Injectable resolver for the font properties a consumer's theme applies to SVG
+ * text through CSS classes (e.g. a label class that sets `font-size`).
+ *
+ * The shim measures text at the size/family the browser would render, but the
+ * mapping from class names to fonts is consumer-specific. So it is injected
+ * rather than hardcoded — keeping the shim free of any one framework's
+ * stylesheet (`@joint/react` registers its theme; joint-core could register its
+ * own, or none).
+ */
+
+/** Font properties a theme class can apply to text. */
+export interface TextStyle {
+  readonly fontSize?: string;
+  readonly fontFamily?: string;
+  readonly fontWeight?: string;
+}
+
+/** Resolves the theme font for an element's `class` attribute. */
+export type TextStyleResolver = (classAttribute: string) => TextStyle;
+
+const EMPTY_TEXT_STYLE: TextStyle = {};
+const registry: { resolve: TextStyleResolver } = { resolve: () => EMPTY_TEXT_STYLE };
+
+/**
+ * Registers how themed text classes map to font properties. A consumer with a
+ * CSS theme calls this so the shim measures themed text at the size the browser
+ * applies. With no resolver registered, text is measured from its own
+ * inline/attribute font only.
+ * @param resolver - maps a `class` attribute to its theme font.
+ */
+export function setTextStyleResolver(resolver: TextStyleResolver): void {
+  registry.resolve = resolver;
+}
+
+/**
+ * Resolves the theme font for a `class` attribute (empty when none registered).
+ * @param classAttribute - the element's `class` attribute value.
+ * @returns the resolved theme font.
+ */
+export function resolveTextStyle(classAttribute: string): TextStyle {
+  return registry.resolve(classAttribute);
+}
diff --git a/packages/joint-svg-shim/tsconfig.json b/packages/joint-svg-shim/tsconfig.json
new file mode 100644
index 0000000000..fa01b8a114
--- /dev/null
+++ b/packages/joint-svg-shim/tsconfig.json
@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": false,
+    "outDir": "lib",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "isolatedModules": true,
+    "strict": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "types": ["jest", "node"]
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "lib"]
+}
diff --git a/packages/joint-svg-shim/tsconfig.types.json b/packages/joint-svg-shim/tsconfig.types.json
new file mode 100644
index 0000000000..5318a6f1a5
--- /dev/null
+++ b/packages/joint-svg-shim/tsconfig.types.json
@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist/types",
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "**/*.test.ts"]
+}
diff --git a/yarn.lock b/yarn.lock
index e479c58a82..98b094993b 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2239,6 +2239,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/aix-ppc64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/aix-ppc64@npm:0.28.0"
+  conditions: os=aix & cpu=ppc64
+  languageName: node
+  linkType: hard
+
 "@esbuild/android-arm64@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/android-arm64@npm:0.18.20"
@@ -2288,6 +2295,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/android-arm64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/android-arm64@npm:0.28.0"
+  conditions: os=android & cpu=arm64
+  languageName: node
+  linkType: hard
+
 "@esbuild/android-arm@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/android-arm@npm:0.18.20"
@@ -2337,6 +2351,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/android-arm@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/android-arm@npm:0.28.0"
+  conditions: os=android & cpu=arm
+  languageName: node
+  linkType: hard
+
 "@esbuild/android-x64@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/android-x64@npm:0.18.20"
@@ -2386,6 +2407,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/android-x64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/android-x64@npm:0.28.0"
+  conditions: os=android & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@esbuild/darwin-arm64@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/darwin-arm64@npm:0.18.20"
@@ -2435,6 +2463,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/darwin-arm64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/darwin-arm64@npm:0.28.0"
+  conditions: os=darwin & cpu=arm64
+  languageName: node
+  linkType: hard
+
 "@esbuild/darwin-x64@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/darwin-x64@npm:0.18.20"
@@ -2484,6 +2519,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/darwin-x64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/darwin-x64@npm:0.28.0"
+  conditions: os=darwin & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@esbuild/freebsd-arm64@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/freebsd-arm64@npm:0.18.20"
@@ -2533,6 +2575,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/freebsd-arm64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/freebsd-arm64@npm:0.28.0"
+  conditions: os=freebsd & cpu=arm64
+  languageName: node
+  linkType: hard
+
 "@esbuild/freebsd-x64@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/freebsd-x64@npm:0.18.20"
@@ -2582,6 +2631,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/freebsd-x64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/freebsd-x64@npm:0.28.0"
+  conditions: os=freebsd & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-arm64@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/linux-arm64@npm:0.18.20"
@@ -2631,6 +2687,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-arm64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/linux-arm64@npm:0.28.0"
+  conditions: os=linux & cpu=arm64
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-arm@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/linux-arm@npm:0.18.20"
@@ -2680,6 +2743,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-arm@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/linux-arm@npm:0.28.0"
+  conditions: os=linux & cpu=arm
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-ia32@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/linux-ia32@npm:0.18.20"
@@ -2729,6 +2799,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-ia32@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/linux-ia32@npm:0.28.0"
+  conditions: os=linux & cpu=ia32
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-loong64@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/linux-loong64@npm:0.18.20"
@@ -2778,6 +2855,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-loong64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/linux-loong64@npm:0.28.0"
+  conditions: os=linux & cpu=loong64
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-mips64el@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/linux-mips64el@npm:0.18.20"
@@ -2827,6 +2911,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-mips64el@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/linux-mips64el@npm:0.28.0"
+  conditions: os=linux & cpu=mips64el
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-ppc64@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/linux-ppc64@npm:0.18.20"
@@ -2876,6 +2967,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-ppc64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/linux-ppc64@npm:0.28.0"
+  conditions: os=linux & cpu=ppc64
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-riscv64@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/linux-riscv64@npm:0.18.20"
@@ -2925,6 +3023,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-riscv64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/linux-riscv64@npm:0.28.0"
+  conditions: os=linux & cpu=riscv64
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-s390x@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/linux-s390x@npm:0.18.20"
@@ -2974,6 +3079,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-s390x@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/linux-s390x@npm:0.28.0"
+  conditions: os=linux & cpu=s390x
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-x64@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/linux-x64@npm:0.18.20"
@@ -3023,6 +3135,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-x64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/linux-x64@npm:0.28.0"
+  conditions: os=linux & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@esbuild/netbsd-arm64@npm:0.25.12":
   version: 0.25.12
   resolution: "@esbuild/netbsd-arm64@npm:0.25.12"
@@ -3058,6 +3177,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/netbsd-arm64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/netbsd-arm64@npm:0.28.0"
+  conditions: os=netbsd & cpu=arm64
+  languageName: node
+  linkType: hard
+
 "@esbuild/netbsd-x64@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/netbsd-x64@npm:0.18.20"
@@ -3107,6 +3233,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/netbsd-x64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/netbsd-x64@npm:0.28.0"
+  conditions: os=netbsd & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@esbuild/openbsd-arm64@npm:0.25.12":
   version: 0.25.12
   resolution: "@esbuild/openbsd-arm64@npm:0.25.12"
@@ -3142,6 +3275,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/openbsd-arm64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/openbsd-arm64@npm:0.28.0"
+  conditions: os=openbsd & cpu=arm64
+  languageName: node
+  linkType: hard
+
 "@esbuild/openbsd-x64@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/openbsd-x64@npm:0.18.20"
@@ -3191,6 +3331,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/openbsd-x64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/openbsd-x64@npm:0.28.0"
+  conditions: os=openbsd & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@esbuild/openharmony-arm64@npm:0.25.12":
   version: 0.25.12
   resolution: "@esbuild/openharmony-arm64@npm:0.25.12"
@@ -3219,6 +3366,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/openharmony-arm64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/openharmony-arm64@npm:0.28.0"
+  conditions: os=openharmony & cpu=arm64
+  languageName: node
+  linkType: hard
+
 "@esbuild/sunos-x64@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/sunos-x64@npm:0.18.20"
@@ -3268,6 +3422,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/sunos-x64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/sunos-x64@npm:0.28.0"
+  conditions: os=sunos & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@esbuild/win32-arm64@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/win32-arm64@npm:0.18.20"
@@ -3317,6 +3478,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/win32-arm64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/win32-arm64@npm:0.28.0"
+  conditions: os=win32 & cpu=arm64
+  languageName: node
+  linkType: hard
+
 "@esbuild/win32-ia32@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/win32-ia32@npm:0.18.20"
@@ -3366,6 +3534,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/win32-ia32@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/win32-ia32@npm:0.28.0"
+  conditions: os=win32 & cpu=ia32
+  languageName: node
+  linkType: hard
+
 "@esbuild/win32-x64@npm:0.18.20":
   version: 0.18.20
   resolution: "@esbuild/win32-x64@npm:0.18.20"
@@ -3415,6 +3590,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/win32-x64@npm:0.28.0":
+  version: 0.28.0
+  resolution: "@esbuild/win32-x64@npm:0.28.0"
+  conditions: os=win32 & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@eslint-community/eslint-utils@npm:^4.8.0, @eslint-community/eslint-utils@npm:^4.9.0, @eslint-community/eslint-utils@npm:^4.9.1":
   version: 4.9.1
   resolution: "@eslint-community/eslint-utils@npm:4.9.1"
@@ -5273,7 +5455,7 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@joint/react@workspace:^, @joint/react@workspace:packages/joint-react":
+"@joint/react@workspace:*, @joint/react@workspace:^, @joint/react@workspace:packages/joint-react":
   version: 0.0.0-use.local
   resolution: "@joint/react@workspace:packages/joint-react"
   dependencies:
@@ -5282,6 +5464,7 @@ __metadata:
     "@joint/core": "workspace:*"
     "@joint/eslint-config": "workspace:*"
     "@joint/layout-directed-graph": "workspace:*"
+    "@joint/svg-shim": "workspace:*"
     "@reduxjs/toolkit": "npm:^2.11.0"
     "@rollup/plugin-commonjs": "npm:^28.0.6"
     "@rollup/plugin-node-resolve": "npm:^16.0.1"
@@ -5296,6 +5479,7 @@ __metadata:
     "@testing-library/react": "npm:^16.0.1"
     "@testing-library/react-hooks": "npm:^8.0.1"
     "@types/jest": "npm:30.0.0"
+    "@types/jsdom": "npm:21.1.7"
     "@types/node": "npm:^24.3.0"
     "@types/react": "npm:19.1.12"
     "@types/react-dom": "npm:19.1.9"
@@ -5309,6 +5493,7 @@ __metadata:
     jest: "npm:30.1.2"
     jest-environment-jsdom: "npm:30.1.2"
     jotai: "npm:^2.15.2"
+    jsdom: "npm:26.1.0"
     knip: "npm:5.63.0"
     peerjs: "npm:^1.5.5"
     prettier: "npm:3.3.3"
@@ -5342,8 +5527,12 @@ __metadata:
     vitest: "npm:^3.0.4"
     zustand: "npm:^5.0.9"
   peerDependencies:
-    react: ">=18"
-    react-dom: ">=18"
+    "@joint/svg-shim": ">=0.0.1"
+    react: ^18.0.0 || ^19.0.0
+    react-dom: ^18.0.0 || ^19.0.0
+  peerDependenciesMeta:
+    "@joint/svg-shim":
+      optional: true
   languageName: unknown
   linkType: soft
 
@@ -5372,6 +5561,74 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@joint/svg-shim-example-core-static@workspace:packages/joint-svg-shim/examples/core-static":
+  version: 0.0.0-use.local
+  resolution: "@joint/svg-shim-example-core-static@workspace:packages/joint-svg-shim/examples/core-static"
+  dependencies:
+    "@joint/core": "workspace:*"
+    "@joint/svg-shim": "workspace:*"
+    "@types/express": "npm:^5.0.0"
+    "@types/node": "npm:^24.3.0"
+    express: "npm:^5.0.0"
+    tsx: "npm:^4.19.0"
+    typescript: "npm:^5.9.2"
+  languageName: unknown
+  linkType: soft
+
+"@joint/svg-shim-example-react-ssr@workspace:packages/joint-svg-shim/examples/react-ssr":
+  version: 0.0.0-use.local
+  resolution: "@joint/svg-shim-example-react-ssr@workspace:packages/joint-svg-shim/examples/react-ssr"
+  dependencies:
+    "@joint/core": "workspace:*"
+    "@joint/react": "workspace:*"
+    "@joint/svg-shim": "workspace:*"
+    "@tailwindcss/vite": "npm:^4.2.2"
+    "@types/express": "npm:^5.0.0"
+    "@types/node": "npm:^24.3.0"
+    "@types/react": "npm:^19"
+    "@types/react-dom": "npm:^19"
+    "@vitejs/plugin-react": "npm:^5.0.2"
+    cross-env: "npm:^7.0.3"
+    express: "npm:^5.0.0"
+    react: "npm:^19.1.1"
+    react-dom: "npm:^19.1.1"
+    tailwindcss: "npm:^4.2.2"
+    tsx: "npm:^4.19.0"
+    typescript: "npm:^5.9.2"
+    vite: "npm:^7.0.0"
+  languageName: unknown
+  linkType: soft
+
+"@joint/svg-shim@workspace:*, @joint/svg-shim@workspace:packages/joint-svg-shim":
+  version: 0.0.0-use.local
+  resolution: "@joint/svg-shim@workspace:packages/joint-svg-shim"
+  dependencies:
+    "@joint/eslint-config": "workspace:*"
+    "@napi-rs/canvas": "npm:^0.1.0"
+    "@rollup/plugin-commonjs": "npm:^28.0.6"
+    "@rollup/plugin-node-resolve": "npm:^16.0.1"
+    "@swc/core": "npm:^1.15.11"
+    "@swc/jest": "npm:^0.2.39"
+    "@types/jest": "npm:30.0.0"
+    "@types/jsdom": "npm:21.1.7"
+    "@types/node": "npm:^24.3.0"
+    esbuild: "npm:^0.25.0"
+    eslint: "npm:9.39.2"
+    happy-dom: "npm:^20.0.0"
+    jest: "npm:30.1.2"
+    jest-environment-jsdom: "npm:30.1.2"
+    jsdom: "npm:^26.1.0"
+    rollup: "npm:^4.50.0"
+    rollup-plugin-esbuild: "npm:^6.2.1"
+    typescript: "npm:^5.9.2"
+  peerDependencies:
+    happy-dom: ">=15.0.0"
+  peerDependenciesMeta:
+    happy-dom:
+      optional: true
+  languageName: unknown
+  linkType: soft
+
 "@joint/vitest-plugin-mock-svg@workspace:packages/joint-vitest-plugin-mock-svg, @joint/vitest-plugin-mock-svg@workspace:~":
   version: 0.0.0-use.local
   resolution: "@joint/vitest-plugin-mock-svg@workspace:packages/joint-vitest-plugin-mock-svg"
@@ -5867,6 +6124,129 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@napi-rs/canvas-android-arm64@npm:0.1.100":
+  version: 0.1.100
+  resolution: "@napi-rs/canvas-android-arm64@npm:0.1.100"
+  conditions: os=android & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@napi-rs/canvas-darwin-arm64@npm:0.1.100":
+  version: 0.1.100
+  resolution: "@napi-rs/canvas-darwin-arm64@npm:0.1.100"
+  conditions: os=darwin & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@napi-rs/canvas-darwin-x64@npm:0.1.100":
+  version: 0.1.100
+  resolution: "@napi-rs/canvas-darwin-x64@npm:0.1.100"
+  conditions: os=darwin & cpu=x64
+  languageName: node
+  linkType: hard
+
+"@napi-rs/canvas-linux-arm-gnueabihf@npm:0.1.100":
+  version: 0.1.100
+  resolution: "@napi-rs/canvas-linux-arm-gnueabihf@npm:0.1.100"
+  conditions: os=linux & cpu=arm
+  languageName: node
+  linkType: hard
+
+"@napi-rs/canvas-linux-arm64-gnu@npm:0.1.100":
+  version: 0.1.100
+  resolution: "@napi-rs/canvas-linux-arm64-gnu@npm:0.1.100"
+  conditions: os=linux & cpu=arm64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@napi-rs/canvas-linux-arm64-musl@npm:0.1.100":
+  version: 0.1.100
+  resolution: "@napi-rs/canvas-linux-arm64-musl@npm:0.1.100"
+  conditions: os=linux & cpu=arm64 & libc=musl
+  languageName: node
+  linkType: hard
+
+"@napi-rs/canvas-linux-riscv64-gnu@npm:0.1.100":
+  version: 0.1.100
+  resolution: "@napi-rs/canvas-linux-riscv64-gnu@npm:0.1.100"
+  conditions: os=linux & cpu=riscv64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@napi-rs/canvas-linux-x64-gnu@npm:0.1.100":
+  version: 0.1.100
+  resolution: "@napi-rs/canvas-linux-x64-gnu@npm:0.1.100"
+  conditions: os=linux & cpu=x64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@napi-rs/canvas-linux-x64-musl@npm:0.1.100":
+  version: 0.1.100
+  resolution: "@napi-rs/canvas-linux-x64-musl@npm:0.1.100"
+  conditions: os=linux & cpu=x64 & libc=musl
+  languageName: node
+  linkType: hard
+
+"@napi-rs/canvas-win32-arm64-msvc@npm:0.1.100":
+  version: 0.1.100
+  resolution: "@napi-rs/canvas-win32-arm64-msvc@npm:0.1.100"
+  conditions: os=win32 & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@napi-rs/canvas-win32-x64-msvc@npm:0.1.100":
+  version: 0.1.100
+  resolution: "@napi-rs/canvas-win32-x64-msvc@npm:0.1.100"
+  conditions: os=win32 & cpu=x64
+  languageName: node
+  linkType: hard
+
+"@napi-rs/canvas@npm:^0.1.0":
+  version: 0.1.100
+  resolution: "@napi-rs/canvas@npm:0.1.100"
+  dependencies:
+    "@napi-rs/canvas-android-arm64": "npm:0.1.100"
+    "@napi-rs/canvas-darwin-arm64": "npm:0.1.100"
+    "@napi-rs/canvas-darwin-x64": "npm:0.1.100"
+    "@napi-rs/canvas-linux-arm-gnueabihf": "npm:0.1.100"
+    "@napi-rs/canvas-linux-arm64-gnu": "npm:0.1.100"
+    "@napi-rs/canvas-linux-arm64-musl": "npm:0.1.100"
+    "@napi-rs/canvas-linux-riscv64-gnu": "npm:0.1.100"
+    "@napi-rs/canvas-linux-x64-gnu": "npm:0.1.100"
+    "@napi-rs/canvas-linux-x64-musl": "npm:0.1.100"
+    "@napi-rs/canvas-win32-arm64-msvc": "npm:0.1.100"
+    "@napi-rs/canvas-win32-x64-msvc": "npm:0.1.100"
+  dependenciesMeta:
+    "@napi-rs/canvas-android-arm64":
+      optional: true
+    "@napi-rs/canvas-darwin-arm64":
+      optional: true
+    "@napi-rs/canvas-darwin-x64":
+      optional: true
+    "@napi-rs/canvas-linux-arm-gnueabihf":
+      optional: true
+    "@napi-rs/canvas-linux-arm64-gnu":
+      optional: true
+    "@napi-rs/canvas-linux-arm64-musl":
+      optional: true
+    "@napi-rs/canvas-linux-riscv64-gnu":
+      optional: true
+    "@napi-rs/canvas-linux-x64-gnu":
+      optional: true
+    "@napi-rs/canvas-linux-x64-musl":
+      optional: true
+    "@napi-rs/canvas-win32-arm64-msvc":
+      optional: true
+    "@napi-rs/canvas-win32-x64-msvc":
+      optional: true
+    canvas:
+      built: true
+    skia-canvas:
+      built: true
+  checksum: 10/27fb6d96162d990eb05b108711532ef3000028310d81f9a108db2f9f7a7162c488bcb86986801617d7f598cc13921f59b5393f602b430a6221301db3e0b6024a
+  languageName: node
+  linkType: hard
+
 "@napi-rs/nice-android-arm-eabi@npm:1.1.1":
   version: 1.1.1
   resolution: "@napi-rs/nice-android-arm-eabi@npm:1.1.1"
@@ -8647,7 +9027,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/express@npm:*":
+"@types/express@npm:*, @types/express@npm:^5.0.0":
   version: 5.0.6
   resolution: "@types/express@npm:5.0.6"
   dependencies:
@@ -8737,7 +9117,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/jsdom@npm:^21.1.7":
+"@types/jsdom@npm:21.1.7, @types/jsdom@npm:^21.1.7":
   version: 21.1.7
   resolution: "@types/jsdom@npm:21.1.7"
   dependencies:
@@ -8834,6 +9214,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/node@npm:>=20.0.0":
+  version: 25.9.1
+  resolution: "@types/node@npm:25.9.1"
+  dependencies:
+    undici-types: "npm:>=7.24.0 <7.24.7"
+  checksum: 10/8a1ccf60f0c0ca856d3324a690ee35776f26dfc1d51c3763aecdf246a3246a7971a0156bf6eb3239aa22dfa940eb361d048212f5c3204264d31ef4c41d17416a
+  languageName: node
+  linkType: hard
+
 "@types/node@npm:^20.1.0, @types/node@npm:^20.11.30":
   version: 20.19.31
   resolution: "@types/node@npm:20.19.31"
@@ -8902,7 +9291,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/react-dom@npm:^19.1.2":
+"@types/react-dom@npm:^19, @types/react-dom@npm:^19.1.2":
   version: 19.2.3
   resolution: "@types/react-dom@npm:19.2.3"
   peerDependencies:
@@ -8947,6 +9336,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/react@npm:^19":
+  version: 19.2.16
+  resolution: "@types/react@npm:19.2.16"
+  dependencies:
+    csstype: "npm:^3.2.2"
+  checksum: 10/b88e77eec8c99757b74539d3495ecd5426e423191fe8c3cdb311f48760046598d9e7c9f876fa6232ee850202205e3165613791ff679e4007d2a92f1512e3b60a
+  languageName: node
+  linkType: hard
+
 "@types/resolve@npm:0.0.8":
   version: 0.0.8
   resolution: "@types/resolve@npm:0.0.8"
@@ -9100,6 +9498,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/whatwg-mimetype@npm:^3.0.2":
+  version: 3.0.2
+  resolution: "@types/whatwg-mimetype@npm:3.0.2"
+  checksum: 10/609607beeaa8b50b9e00541d8f571880d651b26b6b006103370099aba00784037de54433627c9fe775a5558e3d1fc09c2a48f54c8af91988e9bebeaf6a698eeb
+  languageName: node
+  linkType: hard
+
 "@types/which@npm:^2.0.1":
   version: 2.0.2
   resolution: "@types/which@npm:2.0.2"
@@ -9107,7 +9512,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/ws@npm:^8.5.10, @types/ws@npm:^8.5.3, @types/ws@npm:^8.5.5":
+"@types/ws@npm:^8.18.1, @types/ws@npm:^8.5.10, @types/ws@npm:^8.5.3, @types/ws@npm:^8.5.5":
   version: 8.18.1
   resolution: "@types/ws@npm:8.18.1"
   dependencies:
@@ -10280,6 +10685,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"accepts@npm:^2.0.0":
+  version: 2.0.0
+  resolution: "accepts@npm:2.0.0"
+  dependencies:
+    mime-types: "npm:^3.0.0"
+    negotiator: "npm:^1.0.0"
+  checksum: 10/ea1343992b40b2bfb3a3113fa9c3c2f918ba0f9197ae565c48d3f84d44b174f6b1d5cd9989decd7655963eb03a272abc36968cc439c2907f999bd5ef8653d5a7
+  languageName: node
+  linkType: hard
+
 "accepts@npm:~1.3.4, accepts@npm:~1.3.8":
   version: 1.3.8
   resolution: "accepts@npm:1.3.8"
@@ -11521,6 +11936,23 @@ __metadata:
   languageName: node
   linkType: hard
 
+"body-parser@npm:^2.2.1":
+  version: 2.2.2
+  resolution: "body-parser@npm:2.2.2"
+  dependencies:
+    bytes: "npm:^3.1.2"
+    content-type: "npm:^1.0.5"
+    debug: "npm:^4.4.3"
+    http-errors: "npm:^2.0.0"
+    iconv-lite: "npm:^0.7.0"
+    on-finished: "npm:^2.4.1"
+    qs: "npm:^6.14.1"
+    raw-body: "npm:^3.0.1"
+    type-is: "npm:^2.0.1"
+  checksum: 10/69671f67d4d5ae5974593901a92d639757231da1725ed6de4d35e86cde9ce7650afdf1cd28df9b6f7892ea7f9eb03ccb30c70fe27d679275ae4cb4aae5ce1b21
+  languageName: node
+  linkType: hard
+
 "body@npm:^5.1.0":
   version: 5.1.0
   resolution: "body@npm:5.1.0"
@@ -11950,7 +12382,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"bytes@npm:3.1.2, bytes@npm:~3.1.2":
+"bytes@npm:3.1.2, bytes@npm:^3.1.2, bytes@npm:~3.1.2":
   version: 3.1.2
   resolution: "bytes@npm:3.1.2"
   checksum: 10/a10abf2ba70c784471d6b4f58778c0beeb2b5d405148e66affa91f23a9f13d07603d0a0354667310ae1d6dc141474ffd44e2a074be0f6e2254edb8fc21445388
@@ -12904,13 +13336,27 @@ __metadata:
   languageName: node
   linkType: hard
 
-"content-type@npm:~1.0.4, content-type@npm:~1.0.5":
+"content-disposition@npm:^1.0.0":
+  version: 1.1.0
+  resolution: "content-disposition@npm:1.1.0"
+  checksum: 10/c4f65e3c001a4a8eb87d0d24c0f112abb139836fb13b8ea67276715e7dce09570ef666ba7848ee8b660d467e6588d030c8ed7e8d0128db6ca78a0800dcd8c7a8
+  languageName: node
+  linkType: hard
+
+"content-type@npm:^1.0.5, content-type@npm:~1.0.4, content-type@npm:~1.0.5":
   version: 1.0.5
   resolution: "content-type@npm:1.0.5"
   checksum: 10/585847d98dc7fb8035c02ae2cb76c7a9bd7b25f84c447e5ed55c45c2175e83617c8813871b4ee22f368126af6b2b167df655829007b21aa10302873ea9c62662
   languageName: node
   linkType: hard
 
+"content-type@npm:^2.0.0":
+  version: 2.0.0
+  resolution: "content-type@npm:2.0.0"
+  checksum: 10/0bbb276b790ba7e86c479c7d69fae1861b2e908ff3ce2cb01975b516f93eede2216d242902ed6c5b15cd554014611ce9dfdcf51cd35b16569e45a979e50d0cef
+  languageName: node
+  linkType: hard
+
 "continuable-cache@npm:^0.3.1":
   version: 0.3.1
   resolution: "continuable-cache@npm:0.3.1"
@@ -12946,6 +13392,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"cookie-signature@npm:^1.2.1":
+  version: 1.2.2
+  resolution: "cookie-signature@npm:1.2.2"
+  checksum: 10/be44a3c9a56f3771aea3a8bd8ad8f0a8e2679bcb967478267f41a510b4eb5ec55085386ba79c706c4ac21605ca76f4251973444b90283e0eb3eeafe8a92c7708
+  languageName: node
+  linkType: hard
+
 "cookie-signature@npm:~1.0.6":
   version: 1.0.7
   resolution: "cookie-signature@npm:1.0.7"
@@ -12960,7 +13413,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"cookie@npm:~0.7.1, cookie@npm:~0.7.2":
+"cookie@npm:^0.7.1, cookie@npm:~0.7.1, cookie@npm:~0.7.2":
   version: 0.7.2
   resolution: "cookie@npm:0.7.2"
   checksum: 10/24b286c556420d4ba4e9bc09120c9d3db7d28ace2bd0f8ccee82422ce42322f73c8312441271e5eefafbead725980e5996cc02766dbb89a90ac7f5636ede608f
@@ -13174,6 +13627,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"cross-env@npm:^7.0.3":
+  version: 7.0.3
+  resolution: "cross-env@npm:7.0.3"
+  dependencies:
+    cross-spawn: "npm:^7.0.1"
+  bin:
+    cross-env: src/bin/cross-env.js
+    cross-env-shell: src/bin/cross-env-shell.js
+  checksum: 10/e99911f0d31c20e990fd92d6fd001f4b01668a303221227cc5cb42ed155f086351b1b3bd2699b200e527ab13011b032801f8ce638e6f09f854bdf744095e604c
+  languageName: node
+  linkType: hard
+
 "cross-fetch@npm:3.1.5":
   version: 3.1.5
   resolution: "cross-fetch@npm:3.1.5"
@@ -13183,7 +13648,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"cross-spawn@npm:^7.0.0, cross-spawn@npm:^7.0.3, cross-spawn@npm:^7.0.6":
+"cross-spawn@npm:^7.0.0, cross-spawn@npm:^7.0.1, cross-spawn@npm:^7.0.3, cross-spawn@npm:^7.0.6":
   version: 7.0.6
   resolution: "cross-spawn@npm:7.0.6"
   dependencies:
@@ -13796,7 +14261,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"depd@npm:2.0.0, depd@npm:~2.0.0":
+"depd@npm:2.0.0, depd@npm:^2.0.0, depd@npm:~2.0.0":
   version: 2.0.0
   resolution: "depd@npm:2.0.0"
   checksum: 10/c0c8ff36079ce5ada64f46cc9d6fd47ebcf38241105b6e0c98f412e8ad91f084bcf906ff644cc3a4bd876ca27a62accb8b0fff72ea6ed1a414b89d8506f4a5ca
@@ -14278,6 +14743,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"encodeurl@npm:^2.0.0, encodeurl@npm:~2.0.0":
+  version: 2.0.0
+  resolution: "encodeurl@npm:2.0.0"
+  checksum: 10/abf5cd51b78082cf8af7be6785813c33b6df2068ce5191a40ca8b1afe6a86f9230af9a9ce694a5ce4665955e5c1120871826df9c128a642e09c58d592e2807fe
+  languageName: node
+  linkType: hard
+
 "encodeurl@npm:~1.0.2":
   version: 1.0.2
   resolution: "encodeurl@npm:1.0.2"
@@ -14285,13 +14757,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"encodeurl@npm:~2.0.0":
-  version: 2.0.0
-  resolution: "encodeurl@npm:2.0.0"
-  checksum: 10/abf5cd51b78082cf8af7be6785813c33b6df2068ce5191a40ca8b1afe6a86f9230af9a9ce694a5ce4665955e5c1120871826df9c128a642e09c58d592e2807fe
-  languageName: node
-  linkType: hard
-
 "encoding-sniffer@npm:^0.2.1":
   version: 0.2.1
   resolution: "encoding-sniffer@npm:0.2.1"
@@ -15144,40 +15609,129 @@ __metadata:
       optional: true
   bin:
     esbuild: bin/esbuild
-  checksum: 10/7f1229328b0efc63c4184a61a7eb303df1e99818cc1d9e309fb92600703008e69821e8e984e9e9f54a627da14e0960d561db3a93029482ef96dc82dd267a60c2
+  checksum: 10/7f1229328b0efc63c4184a61a7eb303df1e99818cc1d9e309fb92600703008e69821e8e984e9e9f54a627da14e0960d561db3a93029482ef96dc82dd267a60c2
+  languageName: node
+  linkType: hard
+
+"esbuild@npm:~0.27.0":
+  version: 0.27.3
+  resolution: "esbuild@npm:0.27.3"
+  dependencies:
+    "@esbuild/aix-ppc64": "npm:0.27.3"
+    "@esbuild/android-arm": "npm:0.27.3"
+    "@esbuild/android-arm64": "npm:0.27.3"
+    "@esbuild/android-x64": "npm:0.27.3"
+    "@esbuild/darwin-arm64": "npm:0.27.3"
+    "@esbuild/darwin-x64": "npm:0.27.3"
+    "@esbuild/freebsd-arm64": "npm:0.27.3"
+    "@esbuild/freebsd-x64": "npm:0.27.3"
+    "@esbuild/linux-arm": "npm:0.27.3"
+    "@esbuild/linux-arm64": "npm:0.27.3"
+    "@esbuild/linux-ia32": "npm:0.27.3"
+    "@esbuild/linux-loong64": "npm:0.27.3"
+    "@esbuild/linux-mips64el": "npm:0.27.3"
+    "@esbuild/linux-ppc64": "npm:0.27.3"
+    "@esbuild/linux-riscv64": "npm:0.27.3"
+    "@esbuild/linux-s390x": "npm:0.27.3"
+    "@esbuild/linux-x64": "npm:0.27.3"
+    "@esbuild/netbsd-arm64": "npm:0.27.3"
+    "@esbuild/netbsd-x64": "npm:0.27.3"
+    "@esbuild/openbsd-arm64": "npm:0.27.3"
+    "@esbuild/openbsd-x64": "npm:0.27.3"
+    "@esbuild/openharmony-arm64": "npm:0.27.3"
+    "@esbuild/sunos-x64": "npm:0.27.3"
+    "@esbuild/win32-arm64": "npm:0.27.3"
+    "@esbuild/win32-ia32": "npm:0.27.3"
+    "@esbuild/win32-x64": "npm:0.27.3"
+  dependenciesMeta:
+    "@esbuild/aix-ppc64":
+      optional: true
+    "@esbuild/android-arm":
+      optional: true
+    "@esbuild/android-arm64":
+      optional: true
+    "@esbuild/android-x64":
+      optional: true
+    "@esbuild/darwin-arm64":
+      optional: true
+    "@esbuild/darwin-x64":
+      optional: true
+    "@esbuild/freebsd-arm64":
+      optional: true
+    "@esbuild/freebsd-x64":
+      optional: true
+    "@esbuild/linux-arm":
+      optional: true
+    "@esbuild/linux-arm64":
+      optional: true
+    "@esbuild/linux-ia32":
+      optional: true
+    "@esbuild/linux-loong64":
+      optional: true
+    "@esbuild/linux-mips64el":
+      optional: true
+    "@esbuild/linux-ppc64":
+      optional: true
+    "@esbuild/linux-riscv64":
+      optional: true
+    "@esbuild/linux-s390x":
+      optional: true
+    "@esbuild/linux-x64":
+      optional: true
+    "@esbuild/netbsd-arm64":
+      optional: true
+    "@esbuild/netbsd-x64":
+      optional: true
+    "@esbuild/openbsd-arm64":
+      optional: true
+    "@esbuild/openbsd-x64":
+      optional: true
+    "@esbuild/openharmony-arm64":
+      optional: true
+    "@esbuild/sunos-x64":
+      optional: true
+    "@esbuild/win32-arm64":
+      optional: true
+    "@esbuild/win32-ia32":
+      optional: true
+    "@esbuild/win32-x64":
+      optional: true
+  bin:
+    esbuild: bin/esbuild
+  checksum: 10/aa74b8d8a3ed8e2eea4d8421737b322f4d21215244e8fa2156c6402d49b5bda01343c220196f1e3f830a7ce92b54ef653c6c723a8cc2e912bb4d17b7398b51ae
   languageName: node
   linkType: hard
 
-"esbuild@npm:~0.27.0":
-  version: 0.27.3
-  resolution: "esbuild@npm:0.27.3"
-  dependencies:
-    "@esbuild/aix-ppc64": "npm:0.27.3"
-    "@esbuild/android-arm": "npm:0.27.3"
-    "@esbuild/android-arm64": "npm:0.27.3"
-    "@esbuild/android-x64": "npm:0.27.3"
-    "@esbuild/darwin-arm64": "npm:0.27.3"
-    "@esbuild/darwin-x64": "npm:0.27.3"
-    "@esbuild/freebsd-arm64": "npm:0.27.3"
-    "@esbuild/freebsd-x64": "npm:0.27.3"
-    "@esbuild/linux-arm": "npm:0.27.3"
-    "@esbuild/linux-arm64": "npm:0.27.3"
-    "@esbuild/linux-ia32": "npm:0.27.3"
-    "@esbuild/linux-loong64": "npm:0.27.3"
-    "@esbuild/linux-mips64el": "npm:0.27.3"
-    "@esbuild/linux-ppc64": "npm:0.27.3"
-    "@esbuild/linux-riscv64": "npm:0.27.3"
-    "@esbuild/linux-s390x": "npm:0.27.3"
-    "@esbuild/linux-x64": "npm:0.27.3"
-    "@esbuild/netbsd-arm64": "npm:0.27.3"
-    "@esbuild/netbsd-x64": "npm:0.27.3"
-    "@esbuild/openbsd-arm64": "npm:0.27.3"
-    "@esbuild/openbsd-x64": "npm:0.27.3"
-    "@esbuild/openharmony-arm64": "npm:0.27.3"
-    "@esbuild/sunos-x64": "npm:0.27.3"
-    "@esbuild/win32-arm64": "npm:0.27.3"
-    "@esbuild/win32-ia32": "npm:0.27.3"
-    "@esbuild/win32-x64": "npm:0.27.3"
+"esbuild@npm:~0.28.0":
+  version: 0.28.0
+  resolution: "esbuild@npm:0.28.0"
+  dependencies:
+    "@esbuild/aix-ppc64": "npm:0.28.0"
+    "@esbuild/android-arm": "npm:0.28.0"
+    "@esbuild/android-arm64": "npm:0.28.0"
+    "@esbuild/android-x64": "npm:0.28.0"
+    "@esbuild/darwin-arm64": "npm:0.28.0"
+    "@esbuild/darwin-x64": "npm:0.28.0"
+    "@esbuild/freebsd-arm64": "npm:0.28.0"
+    "@esbuild/freebsd-x64": "npm:0.28.0"
+    "@esbuild/linux-arm": "npm:0.28.0"
+    "@esbuild/linux-arm64": "npm:0.28.0"
+    "@esbuild/linux-ia32": "npm:0.28.0"
+    "@esbuild/linux-loong64": "npm:0.28.0"
+    "@esbuild/linux-mips64el": "npm:0.28.0"
+    "@esbuild/linux-ppc64": "npm:0.28.0"
+    "@esbuild/linux-riscv64": "npm:0.28.0"
+    "@esbuild/linux-s390x": "npm:0.28.0"
+    "@esbuild/linux-x64": "npm:0.28.0"
+    "@esbuild/netbsd-arm64": "npm:0.28.0"
+    "@esbuild/netbsd-x64": "npm:0.28.0"
+    "@esbuild/openbsd-arm64": "npm:0.28.0"
+    "@esbuild/openbsd-x64": "npm:0.28.0"
+    "@esbuild/openharmony-arm64": "npm:0.28.0"
+    "@esbuild/sunos-x64": "npm:0.28.0"
+    "@esbuild/win32-arm64": "npm:0.28.0"
+    "@esbuild/win32-ia32": "npm:0.28.0"
+    "@esbuild/win32-x64": "npm:0.28.0"
   dependenciesMeta:
     "@esbuild/aix-ppc64":
       optional: true
@@ -15233,7 +15787,7 @@ __metadata:
       optional: true
   bin:
     esbuild: bin/esbuild
-  checksum: 10/aa74b8d8a3ed8e2eea4d8421737b322f4d21215244e8fa2156c6402d49b5bda01343c220196f1e3f830a7ce92b54ef653c6c723a8cc2e912bb4d17b7398b51ae
+  checksum: 10/49eafc8906cc4a760a1704556bd3b301f808fcdcf2725190383f151741226bf2a2898a03da75a06a896d6217dadc4f3f3168983557ee31bae602e2e37779a83a
   languageName: node
   linkType: hard
 
@@ -15244,7 +15798,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"escape-html@npm:~1.0.3":
+"escape-html@npm:^1.0.3, escape-html@npm:~1.0.3":
   version: 1.0.3
   resolution: "escape-html@npm:1.0.3"
   checksum: 10/6213ca9ae00d0ab8bccb6d8d4e0a98e76237b2410302cf7df70aaa6591d509a2a37ce8998008cbecae8fc8ffaadf3fb0229535e6a145f3ce0b211d060decbb24
@@ -15861,7 +16415,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"etag@npm:~1.8.1":
+"etag@npm:^1.8.1, etag@npm:~1.8.1":
   version: 1.8.1
   resolution: "etag@npm:1.8.1"
   checksum: 10/571aeb3dbe0f2bbd4e4fadbdb44f325fc75335cd5f6f6b6a091e6a06a9f25ed5392f0863c5442acb0646787446e816f13cbfc6edce5b07658541dff573cab1ff
@@ -16137,6 +16691,42 @@ __metadata:
   languageName: node
   linkType: hard
 
+"express@npm:^5.0.0":
+  version: 5.2.1
+  resolution: "express@npm:5.2.1"
+  dependencies:
+    accepts: "npm:^2.0.0"
+    body-parser: "npm:^2.2.1"
+    content-disposition: "npm:^1.0.0"
+    content-type: "npm:^1.0.5"
+    cookie: "npm:^0.7.1"
+    cookie-signature: "npm:^1.2.1"
+    debug: "npm:^4.4.0"
+    depd: "npm:^2.0.0"
+    encodeurl: "npm:^2.0.0"
+    escape-html: "npm:^1.0.3"
+    etag: "npm:^1.8.1"
+    finalhandler: "npm:^2.1.0"
+    fresh: "npm:^2.0.0"
+    http-errors: "npm:^2.0.0"
+    merge-descriptors: "npm:^2.0.0"
+    mime-types: "npm:^3.0.0"
+    on-finished: "npm:^2.4.1"
+    once: "npm:^1.4.0"
+    parseurl: "npm:^1.3.3"
+    proxy-addr: "npm:^2.0.7"
+    qs: "npm:^6.14.0"
+    range-parser: "npm:^1.2.1"
+    router: "npm:^2.2.0"
+    send: "npm:^1.1.0"
+    serve-static: "npm:^2.2.0"
+    statuses: "npm:^2.0.1"
+    type-is: "npm:^2.0.1"
+    vary: "npm:^1.1.2"
+  checksum: 10/4aa545d89702ac83f645c77abda1b57bcabe288f0b380fb5580fac4e323ea0eb533005c8e666b4e19152fb16d4abf11ba87b22aa9a10857a0485cd86b94639bd
+  languageName: node
+  linkType: hard
+
 "extend-shallow@npm:^2.0.1":
   version: 2.0.1
   resolution: "extend-shallow@npm:2.0.1"
@@ -16472,6 +17062,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"finalhandler@npm:^2.1.0":
+  version: 2.1.1
+  resolution: "finalhandler@npm:2.1.1"
+  dependencies:
+    debug: "npm:^4.4.0"
+    encodeurl: "npm:^2.0.0"
+    escape-html: "npm:^1.0.3"
+    on-finished: "npm:^2.4.1"
+    parseurl: "npm:^1.3.3"
+    statuses: "npm:^2.0.1"
+  checksum: 10/f4ba75c23408d8f9d393c3e875b9452e84d68c925411a6e67b7efa678b0bed5075ef33def4bb65ed8e0dd37c92a3ea354bcbde07303cd4dc2550e12b95885067
+  languageName: node
+  linkType: hard
+
 "finalhandler@npm:~1.3.1":
   version: 1.3.2
   resolution: "finalhandler@npm:1.3.2"
@@ -16786,6 +17390,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"fresh@npm:^2.0.0":
+  version: 2.0.0
+  resolution: "fresh@npm:2.0.0"
+  checksum: 10/44e1468488363074641991c1340d2a10c5a6f6d7c353d89fd161c49d120c58ebf9890720f7584f509058385836e3ce50ddb60e9f017315a4ba8c6c3461813bfc
+  languageName: node
+  linkType: hard
+
 "from2@npm:^2.1.0":
   version: 2.3.0
   resolution: "from2@npm:2.3.0"
@@ -17727,6 +18338,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"happy-dom@npm:^20.0.0":
+  version: 20.9.0
+  resolution: "happy-dom@npm:20.9.0"
+  dependencies:
+    "@types/node": "npm:>=20.0.0"
+    "@types/whatwg-mimetype": "npm:^3.0.2"
+    "@types/ws": "npm:^8.18.1"
+    entities: "npm:^7.0.1"
+    whatwg-mimetype: "npm:^3.0.0"
+    ws: "npm:^8.18.3"
+  checksum: 10/5b54d641b467a8826de995a4541e55d79f58e3513e78209c5ff7ef8aa598c201550a8c2975aad465d5605bcf2788314164402f350eaa9014c0d6d6f896cc30c7
+  languageName: node
+  linkType: hard
+
 "happy-dom@npm:^8.1.0":
   version: 8.9.0
   resolution: "happy-dom@npm:8.9.0"
@@ -18051,6 +18676,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"http-errors@npm:^2.0.0, http-errors@npm:^2.0.1, http-errors@npm:~2.0.0, http-errors@npm:~2.0.1":
+  version: 2.0.1
+  resolution: "http-errors@npm:2.0.1"
+  dependencies:
+    depd: "npm:~2.0.0"
+    inherits: "npm:~2.0.4"
+    setprototypeof: "npm:~1.2.0"
+    statuses: "npm:~2.0.2"
+    toidentifier: "npm:~1.0.1"
+  checksum: 10/9fe31bc0edf36566c87048aed1d3d0cbe03552564adc3541626a0613f542d753fbcb13bdfcec0a3a530dbe1714bb566c89d46244616b66bddd26ac413b06a207
+  languageName: node
+  linkType: hard
+
 "http-errors@npm:~1.6.2":
   version: 1.6.3
   resolution: "http-errors@npm:1.6.3"
@@ -18076,19 +18714,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"http-errors@npm:~2.0.0, http-errors@npm:~2.0.1":
-  version: 2.0.1
-  resolution: "http-errors@npm:2.0.1"
-  dependencies:
-    depd: "npm:~2.0.0"
-    inherits: "npm:~2.0.4"
-    setprototypeof: "npm:~1.2.0"
-    statuses: "npm:~2.0.2"
-    toidentifier: "npm:~1.0.1"
-  checksum: 10/9fe31bc0edf36566c87048aed1d3d0cbe03552564adc3541626a0613f542d753fbcb13bdfcec0a3a530dbe1714bb566c89d46244616b66bddd26ac413b06a207
-  languageName: node
-  linkType: hard
-
 "http-parser-js@npm:>=0.5.1":
   version: 0.5.10
   resolution: "http-parser-js@npm:0.5.10"
@@ -18235,7 +18860,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"iconv-lite@npm:^0.7.0":
+"iconv-lite@npm:^0.7.0, iconv-lite@npm:~0.7.0":
   version: 0.7.2
   resolution: "iconv-lite@npm:0.7.2"
   dependencies:
@@ -18982,6 +19607,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"is-promise@npm:^4.0.0":
+  version: 4.0.0
+  resolution: "is-promise@npm:4.0.0"
+  checksum: 10/0b46517ad47b00b6358fd6553c83ec1f6ba9acd7ffb3d30a0bf519c5c69e7147c132430452351b8a9fc198f8dd6c4f76f8e6f5a7f100f8c77d57d9e0f4261a8a
+  languageName: node
+  linkType: hard
+
 "is-reference@npm:1.2.1, is-reference@npm:^1.1.2":
   version: 1.2.1
   resolution: "is-reference@npm:1.2.1"
@@ -20005,7 +20637,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"jsdom@npm:^26.0.0, jsdom@npm:^26.1.0":
+"jsdom@npm:26.1.0, jsdom@npm:^26.0.0, jsdom@npm:^26.1.0":
   version: 26.1.0
   resolution: "jsdom@npm:26.1.0"
   dependencies:
@@ -21291,6 +21923,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"media-typer@npm:^1.1.0":
+  version: 1.1.0
+  resolution: "media-typer@npm:1.1.0"
+  checksum: 10/a58dd60804df73c672942a7253ccc06815612326dc1c0827984b1a21704466d7cde351394f47649e56cf7415e6ee2e26e000e81b51b3eebb5a93540e8bf93cbd
+  languageName: node
+  linkType: hard
+
 "memfs@npm:^3.4.3":
   version: 3.5.3
   resolution: "memfs@npm:3.5.3"
@@ -21331,6 +21970,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"merge-descriptors@npm:^2.0.0":
+  version: 2.0.0
+  resolution: "merge-descriptors@npm:2.0.0"
+  checksum: 10/e383332e700a94682d0125a36c8be761142a1320fc9feeb18e6e36647c9edf064271645f5669b2c21cf352116e561914fd8aa831b651f34db15ef4038c86696a
+  languageName: node
+  linkType: hard
+
 "merge-stream@npm:^2.0.0":
   version: 2.0.0
   resolution: "merge-stream@npm:2.0.0"
@@ -21418,7 +22064,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"mime-types@npm:^3.0.1":
+"mime-types@npm:^3.0.0, mime-types@npm:^3.0.1, mime-types@npm:^3.0.2":
   version: 3.0.2
   resolution: "mime-types@npm:3.0.2"
   dependencies:
@@ -23280,7 +23926,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"parseurl@npm:~1.3.2, parseurl@npm:~1.3.3":
+"parseurl@npm:^1.3.3, parseurl@npm:~1.3.2, parseurl@npm:~1.3.3":
   version: 1.3.3
   resolution: "parseurl@npm:1.3.3"
   checksum: 10/407cee8e0a3a4c5cd472559bca8b6a45b82c124e9a4703302326e9ab60fc1081442ada4e02628efef1eb16197ddc7f8822f5a91fd7d7c86b51f530aedb17dfa2
@@ -23433,6 +24079,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"path-to-regexp@npm:^8.0.0":
+  version: 8.4.2
+  resolution: "path-to-regexp@npm:8.4.2"
+  checksum: 10/70fd2cbce0b962cbcf4d312af07818bfce2bae11c09cf3bd86be99c0e30168238a1a7b02b18b452e73f075897df04597d30d63e56da7be41eecfc37998693389
+  languageName: node
+  linkType: hard
+
 "path-type@npm:^3.0.0":
   version: 3.0.0
   resolution: "path-type@npm:3.0.0"
@@ -24138,7 +24791,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"proxy-addr@npm:~2.0.7":
+"proxy-addr@npm:^2.0.7, proxy-addr@npm:~2.0.7":
   version: 2.0.7
   resolution: "proxy-addr@npm:2.0.7"
   dependencies:
@@ -24359,6 +25012,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"qs@npm:^6.14.0, qs@npm:^6.14.1":
+  version: 6.15.2
+  resolution: "qs@npm:6.15.2"
+  dependencies:
+    side-channel: "npm:^1.1.0"
+  checksum: 10/7a934b2dba40654cf9878dab7c1e7ad56c6186265509727fbece67dadc38fd5d67715b61b6ef938e5a0475faeee701d18ec0a7ce420ad64367caad7f1bdb66e2
+  languageName: node
+  linkType: hard
+
 "query-selector-shadow-dom@npm:^1.0.1":
   version: 1.0.1
   resolution: "query-selector-shadow-dom@npm:1.0.1"
@@ -24460,6 +25122,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"raw-body@npm:^3.0.1":
+  version: 3.0.2
+  resolution: "raw-body@npm:3.0.2"
+  dependencies:
+    bytes: "npm:~3.1.2"
+    http-errors: "npm:~2.0.1"
+    iconv-lite: "npm:~0.7.0"
+    unpipe: "npm:~1.0.0"
+  checksum: 10/4168c82157bd69175d5bd960e59b74e253e237b358213694946a427a6f750a18b8e150f036fed3421b3e83294b071a4e2bb01037a79ccacdac05360c63d3ebba
+  languageName: node
+  linkType: hard
+
 "raw-body@npm:~1.1.0":
   version: 1.1.7
   resolution: "raw-body@npm:1.1.7"
@@ -24552,29 +25226,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"react-dom@npm:19.1.1":
-  version: 19.1.1
-  resolution: "react-dom@npm:19.1.1"
-  dependencies:
-    scheduler: "npm:^0.26.0"
-  peerDependencies:
-    react: ^19.1.1
-  checksum: 10/9005415d2175b1f1eb4a544ad04afb29691bb7b6dd43bbdaa09932146b310b73bd4552bc772ad78fa481f409eada1560cf887606c83c1a53a922c1e30f1b3a34
-  languageName: node
-  linkType: hard
-
-"react-dom@npm:^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0, react-dom@npm:^19.1.0":
-  version: 19.2.4
-  resolution: "react-dom@npm:19.2.4"
-  dependencies:
-    scheduler: "npm:^0.27.0"
-  peerDependencies:
-    react: ^19.2.4
-  checksum: 10/ec17721a8cb131bc33480a9f738bc5bbfe4bd11b11cf69f3f473605346578a329ad26ceef6ef0761ea67a4b455803407dd7ed4ba3d8a5abd2cee8c32d221e498
-  languageName: node
-  linkType: hard
-
-"react-dom@npm:^19.1.1":
+"react-dom@npm:19.2.5":
   version: 19.2.5
   resolution: "react-dom@npm:19.2.5"
   dependencies:
@@ -24716,21 +25368,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"react@npm:19.1.1":
-  version: 19.1.1
-  resolution: "react@npm:19.1.1"
-  checksum: 10/9801530fdc939e1a7a499422e930515b2400809cb39c2872984e99f832d233f61659a693871183dac3155c2f9b2c9dcf4440a56bd18983277ae92860e38c3a61
-  languageName: node
-  linkType: hard
-
-"react@npm:^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0, react@npm:^19.1.0":
-  version: 19.2.4
-  resolution: "react@npm:19.2.4"
-  checksum: 10/18179fe217f67eb2d0bc61cd04e7ad3c282ea09a1dface7eacd71816f62609f4bbf566c447c704335284deb8397b00bca084e0cd60e6f437279a7498e2d0bfe0
-  languageName: node
-  linkType: hard
-
-"react@npm:^19.1.1":
+"react@npm:19.2.5":
   version: 19.2.5
   resolution: "react@npm:19.2.5"
   checksum: 10/1c3c7ffecb90b7f89a5c3ef635e6811f3a84600097f203b918150cb7e6b0a52915e858e5b4c82317a520dffccfa46ee4819ccf92c59c5b2d6c25cffe258dd20c
@@ -25891,6 +26529,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"router@npm:^2.2.0":
+  version: 2.2.0
+  resolution: "router@npm:2.2.0"
+  dependencies:
+    debug: "npm:^4.4.0"
+    depd: "npm:^2.0.0"
+    is-promise: "npm:^4.0.0"
+    parseurl: "npm:^1.3.3"
+    path-to-regexp: "npm:^8.0.0"
+  checksum: 10/8949bd1d3da5403cc024e2989fee58d7fda0f3ffe9f2dc5b8a192f295f400b3cde307b0b554f7d44851077640f36962ca469a766b3d57410d7d96245a7ba6c91
+  languageName: node
+  linkType: hard
+
 "rrweb-cssom@npm:^0.8.0":
   version: 0.8.0
   resolution: "rrweb-cssom@npm:0.8.0"
@@ -26158,13 +26809,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"scheduler@npm:^0.26.0":
-  version: 0.26.0
-  resolution: "scheduler@npm:0.26.0"
-  checksum: 10/1ecf2e5d7de1a7a132796834afe14a2d589ba7e437615bd8c06f3e0786a3ac3434655e67aac8755d9b14e05754c177e49c064261de2673aaa3c926bc98caa002
-  languageName: node
-  linkType: hard
-
 "scheduler@npm:^0.27.0":
   version: 0.27.0
   resolution: "scheduler@npm:0.27.0"
@@ -26378,6 +27022,25 @@ __metadata:
   languageName: node
   linkType: hard
 
+"send@npm:^1.1.0, send@npm:^1.2.0":
+  version: 1.2.1
+  resolution: "send@npm:1.2.1"
+  dependencies:
+    debug: "npm:^4.4.3"
+    encodeurl: "npm:^2.0.0"
+    escape-html: "npm:^1.0.3"
+    etag: "npm:^1.8.1"
+    fresh: "npm:^2.0.0"
+    http-errors: "npm:^2.0.1"
+    mime-types: "npm:^3.0.2"
+    ms: "npm:^2.1.3"
+    on-finished: "npm:^2.4.1"
+    range-parser: "npm:^1.2.1"
+    statuses: "npm:^2.0.2"
+  checksum: 10/274f842d69ccfa49d4940a85598c6825da58dee6cb8ea33b08d5bd3988e6a82267c4d7c32b23d0e4706aad076ee95b1edfa13f859877db9b589829019397e355
+  languageName: node
+  linkType: hard
+
 "send@npm:~0.19.0, send@npm:~0.19.1":
   version: 0.19.2
   resolution: "send@npm:0.19.2"
@@ -26463,6 +27126,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"serve-static@npm:^2.2.0":
+  version: 2.2.1
+  resolution: "serve-static@npm:2.2.1"
+  dependencies:
+    encodeurl: "npm:^2.0.0"
+    escape-html: "npm:^1.0.3"
+    parseurl: "npm:^1.3.3"
+    send: "npm:^1.2.0"
+  checksum: 10/71500fe80cc7163fec04e4297de7591ad1cb682d137fc030e7a53e57040fda5187e8082a9c1b2ef37f1d3f9c27c9a94d4ba61806ebc28938ba4a7c8947c9f71e
+  languageName: node
+  linkType: hard
+
 "serve-static@npm:~1.16.2":
   version: 1.16.3
   resolution: "serve-static@npm:1.16.3"
@@ -27264,6 +27939,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"statuses@npm:^2.0.1, statuses@npm:^2.0.2, statuses@npm:~2.0.1, statuses@npm:~2.0.2":
+  version: 2.0.2
+  resolution: "statuses@npm:2.0.2"
+  checksum: 10/6927feb50c2a75b2a4caab2c565491f7a93ad3d8dbad7b1398d52359e9243a20e2ebe35e33726dee945125ef7a515e9097d8a1b910ba2bbd818265a2f6c39879
+  languageName: node
+  linkType: hard
+
 "statuses@npm:~1.4.0":
   version: 1.4.0
   resolution: "statuses@npm:1.4.0"
@@ -27271,13 +27953,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"statuses@npm:~2.0.1, statuses@npm:~2.0.2":
-  version: 2.0.2
-  resolution: "statuses@npm:2.0.2"
-  checksum: 10/6927feb50c2a75b2a4caab2c565491f7a93ad3d8dbad7b1398d52359e9243a20e2ebe35e33726dee945125ef7a515e9097d8a1b910ba2bbd818265a2f6c39879
-  languageName: node
-  linkType: hard
-
 "std-env@npm:^3.9.0":
   version: 3.10.0
   resolution: "std-env@npm:3.10.0"
@@ -28497,6 +29172,21 @@ __metadata:
   languageName: node
   linkType: hard
 
+"tsx@npm:^4.19.0":
+  version: 4.22.4
+  resolution: "tsx@npm:4.22.4"
+  dependencies:
+    esbuild: "npm:~0.28.0"
+    fsevents: "npm:~2.3.3"
+  dependenciesMeta:
+    fsevents:
+      optional: true
+  bin:
+    tsx: dist/cli.mjs
+  checksum: 10/9d6e7e9d1158eb84327d822720a2053bcfd972f8988e4789041bac5a767fc394ef302b1ff7e1d3dfbee391a0b03bd3dbb02cd302387729baf1dc7b9dce93b3ba
+  languageName: node
+  linkType: hard
+
 "tsx@npm:^4.19.3, tsx@npm:^4.21.0":
   version: 4.21.0
   resolution: "tsx@npm:4.21.0"
@@ -28584,6 +29274,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"type-is@npm:^2.0.1":
+  version: 2.1.0
+  resolution: "type-is@npm:2.1.0"
+  dependencies:
+    content-type: "npm:^2.0.0"
+    media-typer: "npm:^1.1.0"
+    mime-types: "npm:^3.0.0"
+  checksum: 10/f011885fefb6c6882f36fab89cc596596b96eab1d208a3774628537cad7ce1f91232a6d758115e1a6ed03f0f8c21e9654bb6d280a5c6827ff72a35f6df0fa182
+  languageName: node
+  linkType: hard
+
 "type-is@npm:~1.6.18":
   version: 1.6.18
   resolution: "type-is@npm:1.6.18"
@@ -28948,6 +29649,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"undici-types@npm:>=7.24.0 <7.24.7":
+  version: 7.24.6
+  resolution: "undici-types@npm:7.24.6"
+  checksum: 10/defc9538b952e3c15b8526596c591f7c1f0c7605ad27a2b7feddbea7ef2e3003f3eda2cdb051a3cb1a2185e3893100fd9cb925c799db99d48131ea63b5233d10
+  languageName: node
+  linkType: hard
+
 "undici-types@npm:~6.21.0":
   version: 6.21.0
   resolution: "undici-types@npm:6.21.0"
@@ -29392,7 +30100,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"vary@npm:^1, vary@npm:~1.1.2":
+"vary@npm:^1, vary@npm:^1.1.2, vary@npm:~1.1.2":
   version: 1.1.2
   resolution: "vary@npm:1.1.2"
   checksum: 10/31389debef15a480849b8331b220782230b9815a8e0dbb7b9a8369559aed2e9a7800cd904d4371ea74f4c3527db456dc8e7ac5befce5f0d289014dbdf47b2242
@@ -29669,6 +30377,61 @@ __metadata:
   languageName: node
   linkType: hard
 
+"vite@npm:^7.0.0":
+  version: 7.3.5
+  resolution: "vite@npm:7.3.5"
+  dependencies:
+    esbuild: "npm:^0.27.0"
+    fdir: "npm:^6.5.0"
+    fsevents: "npm:~2.3.3"
+    picomatch: "npm:^4.0.3"
+    postcss: "npm:^8.5.6"
+    rollup: "npm:^4.43.0"
+    tinyglobby: "npm:^0.2.15"
+  peerDependencies:
+    "@types/node": ^20.19.0 || >=22.12.0
+    jiti: ">=1.21.0"
+    less: ^4.0.0
+    lightningcss: ^1.21.0
+    sass: ^1.70.0
+    sass-embedded: ^1.70.0
+    stylus: ">=0.54.8"
+    sugarss: ^5.0.0
+    terser: ^5.16.0
+    tsx: ^4.8.1
+    yaml: ^2.4.2
+  dependenciesMeta:
+    fsevents:
+      optional: true
+  peerDependenciesMeta:
+    "@types/node":
+      optional: true
+    jiti:
+      optional: true
+    less:
+      optional: true
+    lightningcss:
+      optional: true
+    sass:
+      optional: true
+    sass-embedded:
+      optional: true
+    stylus:
+      optional: true
+    sugarss:
+      optional: true
+    terser:
+      optional: true
+    tsx:
+      optional: true
+    yaml:
+      optional: true
+  bin:
+    vite: bin/vite.js
+  checksum: 10/2e1337510d6b81948b035f8b096c9be22daf1101fc52ad3d06cad9e090057ba1c1396e5e12cbaac2485f9c6cdcc854f978fe862280bdfe1a9a4149c60734c125
+  languageName: node
+  linkType: hard
+
 "vite@npm:^8.0.3":
   version: 8.0.8
   resolution: "vite@npm:8.0.8"