From 873ec0c68bdc59c8fdcee74d55f2ee7efc8fc334 Mon Sep 17 00:00:00 2001
From: samuelgja <samuel.gjabel@gmail.com>
Date: Thu, 29 Jan 2026 17:18:46 +0700
Subject: [PATCH 1/5] feat(joint-react): refactor scheduler to improve batching
 and add new interface

---
 packages/joint-react/src/store/graph-store.ts |   2 +-
 .../joint-react/src/utils/scheduler-old.ts    |  57 ++++++++
 packages/joint-react/src/utils/scheduler.ts   | 125 ++++++++++++------
 3 files changed, 140 insertions(+), 44 deletions(-)
 create mode 100644 packages/joint-react/src/utils/scheduler-old.ts

diff --git a/packages/joint-react/src/store/graph-store.ts b/packages/joint-react/src/store/graph-store.ts
index f95607442..86201525b 100644
--- a/packages/joint-react/src/store/graph-store.ts
+++ b/packages/joint-react/src/store/graph-store.ts
@@ -24,7 +24,7 @@ import {
   createDefaultLinkMapper,
 } from '../state/graph-state-selectors';
 import type { OnChangeOptions } from '../utils/cell/listen-to-cell-change';
-import { createScheduler } from '../utils/scheduler';
+import { createScheduler } from '../utils/scheduler-old';
 
 export const DEFAULT_CELL_NAMESPACE: Record<string, unknown> = {
   ...shapes,
diff --git a/packages/joint-react/src/utils/scheduler-old.ts b/packages/joint-react/src/utils/scheduler-old.ts
new file mode 100644
index 000000000..5ec990378
--- /dev/null
+++ b/packages/joint-react/src/utils/scheduler-old.ts
@@ -0,0 +1,57 @@
+// eslint-disable-next-line camelcase
+import { unstable_getCurrentPriorityLevel, unstable_scheduleCallback } from 'scheduler';
+/**
+ * Creates a debounced function that uses React's internal scheduler for timing.
+ * Multiple calls within the same synchronous execution cycle are batched into a single
+ * execution in the next available event loop tick. All callbacks stored by id will be
+ * executed when the scheduled work flushes.
+ * @param userCallback The function to be debounced and scheduled.
+ * @param priorityLevel The priority level to run the task at.
+ * @returns A function you call to schedule your work with an optional callback and id.
+ */
+export function createScheduler(userCallback: () => void, priorityLevel?: number) {
+  let callbackId: unknown | null = null;
+  const callbacks = new Map<string, (id: string) => void>();
+
+  const effectivePriority =
+    priorityLevel === undefined ? unstable_getCurrentPriorityLevel() : priorityLevel;
+
+  /**
+   * The actual function that processes the batched callbacks.
+   * This runs asynchronously via the scheduler.
+   */
+  const flushScheduledWork = () => {
+    callbackId = null;
+
+    // Collect all ids before clearing
+
+    // Execute all stored callbacks with their respective ids
+    for (const [id, callback] of callbacks) {
+      callback(id);
+    }
+
+    // Execute the main callback for each id after stored callbacks
+    userCallback();
+
+    // Clear all stored callbacks after execution
+    callbacks.clear();
+  };
+
+  /**
+   * This is the function the user calls to schedule a task.
+   * It stores the callback with its id and ensures the flush function is scheduled once.
+   * @param id Optional id string to pass to the callback.
+   * @param callback Optional callback function that receives an id parameter.
+   */
+  return (id?: string, callback?: (id: string) => void) => {
+    if (id !== undefined && callback !== undefined) {
+      // Store callback in map with id as key
+      callbacks.set(id, callback);
+    }
+
+    if (callbackId === null) {
+      // Schedule the flush function if it hasn't been scheduled already
+      callbackId = unstable_scheduleCallback(effectivePriority, flushScheduledWork);
+    }
+  };
+}
diff --git a/packages/joint-react/src/utils/scheduler.ts b/packages/joint-react/src/utils/scheduler.ts
index 5ec990378..5156ff45d 100644
--- a/packages/joint-react/src/utils/scheduler.ts
+++ b/packages/joint-react/src/utils/scheduler.ts
@@ -1,57 +1,96 @@
-// eslint-disable-next-line camelcase
-import { unstable_getCurrentPriorityLevel, unstable_scheduleCallback } from 'scheduler';
+import {
+  unstable_getCurrentPriorityLevel as getCurrentPriorityLevel,
+  unstable_scheduleCallback as scheduleCallback,
+} from "scheduler";
+
 /**
- * Creates a debounced function that uses React's internal scheduler for timing.
- * Multiple calls within the same synchronous execution cycle are batched into a single
- * execution in the next available event loop tick. All callbacks stored by id will be
- * executed when the scheduled work flushes.
- * @param userCallback The function to be debounced and scheduled.
- * @param priorityLevel The priority level to run the task at.
- * @returns A function you call to schedule your work with an optional callback and id.
+ * Options for creating a graph updates scheduler.
  */
-export function createScheduler(userCallback: () => void, priorityLevel?: number) {
-  let callbackId: unknown | null = null;
-  const callbacks = new Map<string, (id: string) => void>();
-
-  const effectivePriority =
-    priorityLevel === undefined ? unstable_getCurrentPriorityLevel() : priorityLevel;
-
+export interface GraphUpdatesSchedulerOptions<Data extends object> {
   /**
-   * The actual function that processes the batched callbacks.
-   * This runs asynchronously via the scheduler.
+   * Callback invoked when scheduled updates are flushed.
+   * Receives all accumulated data since the last flush.
    */
-  const flushScheduledWork = () => {
-    callbackId = null;
+  readonly onFlush: (data: Data) => void;
 
-    // Collect all ids before clearing
-
-    // Execute all stored callbacks with their respective ids
-    for (const [id, callback] of callbacks) {
-      callback(id);
-    }
+  /**
+   * Optional React scheduler priority level.
+   * If not specified, uses the current priority level.
+   */
+  readonly priorityLevel?: number;
+}
 
-    // Execute the main callback for each id after stored callbacks
-    userCallback();
+/**
+ * Scheduler that batches data updates and flushes them together.
+ * Uses React's internal scheduler for timing, batching multiple calls
+ * within the same synchronous execution cycle into a single flush.
+ * Data starts as empty object `{}` and resets after each flush.
+ * @example
+ * ```ts
+ * interface MyData {
+ *   elements?: string[];
+ *   links?: string[];
+ * }
+ *
+ * const scheduler = new GraphUpdatesScheduler<MyData>({
+ *   onFlush: (data) => {
+ *     console.log(data.elements, data.links);
+ *   },
+ * });
+ *
+ * // Multiple calls are batched
+ * scheduler.scheduleData((prev) => ({ ...prev, elements: ['el1'] }));
+ * scheduler.scheduleData((prev) => ({ ...prev, links: ['link1'] }));
+ * // onFlush called once with combined result: { elements: ['el1'], links: ['link1'] }
+ * ```
+ */
+export class Scheduler<Data extends object> {
+  private readonly onFlush: (data: Data) => void;
+  private readonly effectivePriority: number;
+  private callbackId: unknown | null = null;
+  private currentData: Data = {} as Data;
 
-    // Clear all stored callbacks after execution
-    callbacks.clear();
-  };
+  constructor(options: GraphUpdatesSchedulerOptions<Data>) {
+    const { onFlush, priorityLevel } = options;
+    this.onFlush = onFlush;
+    this.effectivePriority =
+      priorityLevel === undefined ? getCurrentPriorityLevel() : priorityLevel;
+  }
 
   /**
-   * This is the function the user calls to schedule a task.
-   * It stores the callback with its id and ensures the flush function is scheduled once.
-   * @param id Optional id string to pass to the callback.
-   * @param callback Optional callback function that receives an id parameter.
+   * Schedule a data update using an updater function.
+   * Multiple calls are batched and flushed together.
+   * @param updater Function that receives previous data and returns updated data.
    */
-  return (id?: string, callback?: (id: string) => void) => {
-    if (id !== undefined && callback !== undefined) {
-      // Store callback in map with id as key
-      callbacks.set(id, callback);
-    }
+  scheduleData = (updater: (previousData: Data) => Data): void => {
+    this.currentData = updater(this.currentData);
 
-    if (callbackId === null) {
-      // Schedule the flush function if it hasn't been scheduled already
-      callbackId = unstable_scheduleCallback(effectivePriority, flushScheduledWork);
+    if (this.callbackId === null) {
+      this.callbackId = scheduleCallback(
+        this.effectivePriority,
+        this.flushScheduledWork,
+      );
     }
   };
+
+  private flushScheduledWork = (): void => {
+    this.callbackId = null;
+
+    const dataToFlush = this.currentData;
+    this.currentData = {} as Data;
+
+    this.onFlush(dataToFlush);
+  };
+}
+
+/**
+ * Creates a simple scheduler function that batches multiple calls into a single flush.
+ * @param callback The callback to invoke on flush
+ * @returns A function to schedule updates
+ */
+export function createScheduler(callback: () => void): () => void {
+  const scheduler = new Scheduler<Record<string, never>>({
+    onFlush: callback,
+  });
+  return () => scheduler.scheduleData((previous) => previous);
 }

From 5696642f1f1b7c1b496281969221ef48c47ad200 Mon Sep 17 00:00:00 2001
From: samuelgja <samuel.gjabel@gmail.com>
Date: Fri, 30 Jan 2026 02:40:09 +0700
Subject: [PATCH 2/5] chore(joint-react): implement batch caching and state
 flushing for JointJS elements and links

- Add BatchCache class for managing batched updates for links, ports, and clear views.
- Introduce ClearViewCacheEntry and related functions for managing clear view updates.
- Create PortUpdateCacheEntry and functions for merging port updates and groups.
- Implement state flushing functions to handle element and link updates in a React-friendly manner.
- Develop example story demonstrating cell actions with dynamic node and link management.
- Define GraphSchedulerData type for unified scheduling of updates across elements, links, and ports.
---
 .../decorators/with-simple-data.tsx           |   26 +-
 packages/joint-react/README.md                |   48 +-
 packages/joint-react/jest.config.js           |   17 +-
 packages/joint-react/package.json             |    3 +-
 .../graph/graph-provider.stories.tsx          |   20 +-
 .../src/components/graph/graph-provider.tsx   |   41 +-
 .../__tests__/highlighter-cleanup.test.tsx    |    6 +-
 .../highlighters/__tests__/stroke.test.tsx    |    6 +-
 .../link/__tests__/base-link.test.tsx         |  224 ---
 .../link/__tests__/link-label.test.tsx        |  511 -----
 .../src/components/link/base-link.stories.tsx |  326 ----
 .../src/components/link/base-link.tsx         |  169 --
 .../src/components/link/base-link.types.ts    |   20 -
 .../joint-react/src/components/link/index.ts  |   62 +-
 .../components/link/link-label.stories.tsx    |  101 -
 .../src/components/link/link-label.tsx        |  181 --
 .../src/components/link/link-label.types.ts   |   53 -
 .../graph-provider-controlled-mode.test.tsx   |  352 ++--
 .../graph-provider-coverage.test.tsx          |   46 +-
 .../paper/__tests__/graph-provider.test.tsx   |  227 ++-
 .../paper-html-overlay-links.test.tsx         |  162 +-
 .../components/paper/__tests__/paper.test.tsx |   69 +-
 .../src/components/paper/paper.stories.tsx    |   33 +-
 .../src/components/paper/paper.tsx            |   68 +-
 .../src/components/paper/paper.types.ts       |   13 +-
 .../render-element/paper-element-item.tsx     |   26 +-
 .../port/__tests__/port-group.test.tsx        |    6 +-
 .../port/__tests__/port-item.test.tsx         |    6 +-
 .../components/port/__tests__/port.test.tsx   |  209 ++-
 .../components/port/port-group.stories.tsx    |   26 +-
 .../src/components/port/port-item.stories.tsx |   25 +-
 .../hooks/__tests__/use-cell-actions.test.tsx |  344 +++-
 .../src/hooks/__tests__/use-cell-id.test.tsx  |    6 +-
 .../src/hooks/__tests__/use-element.test.tsx  |    6 +-
 .../src/hooks/__tests__/use-elements.test.ts  |   26 +-
 .../src/hooks/__tests__/use-graph.test.ts     |    6 +-
 .../hooks/__tests__/use-link-layout.test.tsx  |   84 +
 .../src/hooks/__tests__/use-links.test.ts     |   20 +-
 .../__tests__/use-paper-context.test.tsx      |    6 +-
 packages/joint-react/src/hooks/index.ts       |    1 +
 .../src/hooks/use-cell-actions.stories.tsx    |    5 +-
 .../joint-react/src/hooks/use-cell-actions.ts |  121 +-
 packages/joint-react/src/hooks/use-element.ts |    9 +-
 .../src/hooks/use-elements.stories.tsx        |   44 +-
 .../joint-react/src/hooks/use-elements.ts     |   28 +-
 .../src/hooks/use-graph-store-selector.ts     |   15 -
 .../joint-react/src/hooks/use-link-layout.ts  |   63 +
 .../src/hooks/use-links.stories.tsx           |   26 +-
 packages/joint-react/src/hooks/use-links.ts   |   44 +-
 .../joint-react/src/hooks/use-node-layout.ts  |    2 +-
 .../src/hooks/use-state-to-external-store.ts  |   16 +-
 packages/joint-react/src/index.ts             |    7 +-
 .../__tests__/react-element-view.test.ts      |    8 -
 .../models/__tests__/react-element.test.ts    |    7 +
 .../models/__tests__/react-link-view.test.ts  |    8 -
 .../src/models/__tests__/react-link.test.ts   |   63 +
 .../src/models/__tests__/react-paper.test.ts  |  294 +++
 .../models/__tests__/view-extension.test.ts   |   39 -
 .../src/models/react-element-view.ts          |   68 -
 .../joint-react/src/models/react-element.tsx  |    5 +
 .../joint-react/src/models/react-link-view.ts |  121 --
 packages/joint-react/src/models/react-link.ts |   23 +-
 .../joint-react/src/models/react-paper.ts     |  127 ++
 .../src/models/react-paper.types.ts           |   28 +
 .../__tests__/graph-state-selectors.test.ts   |  396 ++--
 .../src/state/__tests__/state-sync.test.ts    | 1637 ++++++++---------
 .../src/state/graph-state-selectors.ts        |   62 +-
 packages/joint-react/src/state/state-sync.ts  |  887 +++------
 .../joint-react/src/state/update-graph.ts     |  179 ++
 .../src/store/__tests__/graph-store.test.ts   |  158 +-
 packages/joint-react/src/store/batch-cache.ts |  125 ++
 packages/joint-react/src/store/clear-view.ts  |  130 ++
 .../store/create-elements-size-observer.ts    |   24 +-
 packages/joint-react/src/store/graph-store.ts | 1261 +++----------
 packages/joint-react/src/store/paper-store.ts |   83 +-
 packages/joint-react/src/store/port-cache.ts  |  149 ++
 packages/joint-react/src/store/state-flush.ts |  193 ++
 .../src/stories/demos/flowchart/code.tsx      |   79 +-
 .../stories/demos/introduction-demo/code.tsx  |   28 +-
 .../src/stories/demos/pulsing-port/code.tsx   |   29 +-
 .../src/stories/demos/user-flow/code.tsx      |   30 +-
 .../src/stories/examples/stress/code.tsx      |   89 +-
 .../examples/with-auto-layout/code.tsx        |   30 +-
 .../examples/with-build-in-shapes/code.tsx    |   68 +-
 .../src/stories/examples/with-card/code.tsx   |   17 +-
 .../examples/with-cell-actions/code.tsx       |  533 ++++++
 .../examples/with-cell-actions/story.tsx      |   20 +
 .../code-with-create-links-classname.tsx      |   17 +-
 .../code-with-create-links.tsx                |   17 +-
 .../with-custom-link/code-with-dia-links.tsx  |   17 +-
 .../examples/with-highlighter/code.tsx        |   21 +-
 .../examples/with-intersection/code.tsx       |   21 +-
 .../stories/examples/with-link-tools/code.tsx |   17 +-
 .../stories/examples/with-list-node/code.tsx  |   22 +-
 .../stories/examples/with-minimap/code.tsx    |   17 +-
 .../with-node-update/code-add-remove-node.tsx |   29 +-
 .../with-node-update/code-with-color.tsx      |   16 +-
 .../with-node-update/code-with-svg.tsx        |   27 +-
 .../examples/with-node-update/code.tsx        |   18 +-
 .../examples/with-proximity-link/code.tsx     |   19 +-
 .../examples/with-render-link/code.tsx        |   66 +-
 .../examples/with-resizable-node/code.tsx     |   21 +-
 .../examples/with-rotable-node/code.tsx       |   18 +-
 .../stories/examples/with-svg-node/code.tsx   |   17 +-
 .../joint-react/src/stories/introduction.mdx  |   14 +-
 .../code-controlled-mode-jotai.tsx            |   55 +-
 .../code-controlled-mode-peerjs.tsx           |  217 ++-
 .../code-controlled-mode-redux.tsx            |   61 +-
 .../code-controlled-mode-zustand.tsx          |   64 +-
 .../step-by-step/code-controlled-mode.tsx     |   74 +-
 .../step-by-step/code-html-renderer.tsx       |   20 +-
 .../tutorials/step-by-step/code-html.tsx      |   19 +-
 .../tutorials/step-by-step/code-svg.tsx       |   19 +-
 .../stories/tutorials/step-by-step/docs.mdx   |   32 +-
 packages/joint-react/src/types/cell.types.ts  |    4 -
 .../joint-react/src/types/element-types.ts    |    4 -
 packages/joint-react/src/types/link-types.ts  |    4 -
 .../joint-react/src/types/scheduler.types.ts  |   40 +
 .../src/utils/__tests__/get-cell.test.ts      |   25 +-
 .../src/utils/cell/cell-utilities.ts          |  100 -
 .../src/utils/cell/listen-to-cell-change.ts   |   35 +-
 packages/joint-react/src/utils/clear-view.ts  |    9 +-
 packages/joint-react/src/utils/is.ts          |    7 +-
 .../utils/joint-jsx/jsx-to-markup.stories.tsx |   15 +-
 .../joint-react/src/utils/scheduler-old.ts    |   57 -
 packages/joint-react/src/utils/scheduler.ts   |   23 +-
 .../joint-react/src/utils/test-wrappers.tsx   |   12 +-
 yarn.lock                                     |  258 ++-
 128 files changed, 5861 insertions(+), 6646 deletions(-)
 delete mode 100644 packages/joint-react/src/components/link/__tests__/base-link.test.tsx
 delete mode 100644 packages/joint-react/src/components/link/__tests__/link-label.test.tsx
 delete mode 100644 packages/joint-react/src/components/link/base-link.stories.tsx
 delete mode 100644 packages/joint-react/src/components/link/base-link.tsx
 delete mode 100644 packages/joint-react/src/components/link/base-link.types.ts
 delete mode 100644 packages/joint-react/src/components/link/link-label.stories.tsx
 delete mode 100644 packages/joint-react/src/components/link/link-label.tsx
 delete mode 100644 packages/joint-react/src/components/link/link-label.types.ts
 create mode 100644 packages/joint-react/src/hooks/__tests__/use-link-layout.test.tsx
 create mode 100644 packages/joint-react/src/hooks/use-link-layout.ts
 delete mode 100644 packages/joint-react/src/models/__tests__/react-element-view.test.ts
 delete mode 100644 packages/joint-react/src/models/__tests__/react-link-view.test.ts
 create mode 100644 packages/joint-react/src/models/__tests__/react-link.test.ts
 create mode 100644 packages/joint-react/src/models/__tests__/react-paper.test.ts
 delete mode 100644 packages/joint-react/src/models/__tests__/view-extension.test.ts
 delete mode 100644 packages/joint-react/src/models/react-element-view.ts
 delete mode 100644 packages/joint-react/src/models/react-link-view.ts
 create mode 100644 packages/joint-react/src/models/react-paper.ts
 create mode 100644 packages/joint-react/src/models/react-paper.types.ts
 create mode 100644 packages/joint-react/src/state/update-graph.ts
 create mode 100644 packages/joint-react/src/store/batch-cache.ts
 create mode 100644 packages/joint-react/src/store/clear-view.ts
 create mode 100644 packages/joint-react/src/store/port-cache.ts
 create mode 100644 packages/joint-react/src/store/state-flush.ts
 create mode 100644 packages/joint-react/src/stories/examples/with-cell-actions/code.tsx
 create mode 100644 packages/joint-react/src/stories/examples/with-cell-actions/story.tsx
 delete mode 100644 packages/joint-react/src/types/cell.types.ts
 create mode 100644 packages/joint-react/src/types/scheduler.types.ts
 delete mode 100644 packages/joint-react/src/utils/cell/cell-utilities.ts
 delete mode 100644 packages/joint-react/src/utils/scheduler-old.ts

diff --git a/packages/joint-react/.storybook/decorators/with-simple-data.tsx b/packages/joint-react/.storybook/decorators/with-simple-data.tsx
index 6b4751625..684ee4ae2 100644
--- a/packages/joint-react/.storybook/decorators/with-simple-data.tsx
+++ b/packages/joint-react/.storybook/decorators/with-simple-data.tsx
@@ -12,8 +12,18 @@ import { Paper } from '../../src/components/paper/paper';
 export type StoryFunction = PartialStoryFn<any, any>;
 export type StoryCtx = StoryContext<any, any>;
 
-export const testElements = [
-  {
+export const testElements: Record<string, {
+  id: string;
+  label: string;
+  color: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  hoverColor: string;
+  angle: number;
+}> = {
+  '1': {
     id: '1',
     label: 'Node 1',
     color: PRIMARY,
@@ -24,7 +34,7 @@ export const testElements = [
     hoverColor: 'red',
     angle: 0,
   },
-  {
+  '2': {
     id: '2',
     label: 'Node 2',
     color: PRIMARY,
@@ -35,11 +45,11 @@ export const testElements = [
     hoverColor: 'blue',
     angle: 0,
   },
-];
+};
 
-export type SimpleElement = (typeof testElements)[number];
-export const testLinks: GraphLink[] = [
-  {
+export type SimpleElement = (typeof testElements)[string];
+export const testLinks: Record<string, GraphLink> = {
+  'l-1': {
     id: 'l-1',
     source: '1',
     target: '2',
@@ -49,7 +59,7 @@ export const testLinks: GraphLink[] = [
       },
     },
   },
-];
+};
 
 export function SimpleGraphProviderDecorator({ children }: Readonly<PropsWithChildren>) {
   return (
diff --git a/packages/joint-react/README.md b/packages/joint-react/README.md
index e4879933a..7b767bccf 100644
--- a/packages/joint-react/README.md
+++ b/packages/joint-react/README.md
@@ -56,17 +56,17 @@ bun add @joint/react
 import React from 'react'
 import { GraphProvider } from '@joint/react'
 
-const elements = [
-  { id: 'node1', label: 'Start', x: 100, y: 50, width: 120, height: 60 },
-  { id: 'node2', label: 'End',   x: 100, y: 200, width: 120, height: 60 },
-] as const
+const elements = {
+  'node1': { id: 'node1', label: 'Start', x: 100, y: 50, width: 120, height: 60 },
+  'node2': { id: 'node2', label: 'End',   x: 100, y: 200, width: 120, height: 60 },
+} as const
 
-const links = [
-  { id: 'link1', source: 'node1', target: 'node2' },
-] as const
+const links = {
+  'link1': { id: 'link1', source: 'node1', target: 'node2' },
+} as const
 
-// Narrow element type straight from the array:
-type Element = typeof elements[number]
+// Narrow element type straight from the record:
+type Element = typeof elements[keyof typeof elements]
 
 export default function App() {
   return (
@@ -102,12 +102,14 @@ Share one diagram across views. Give each view a stable `id`.
 import React from 'react'
 import { GraphProvider } from '@joint/react'
 
-const elements = [
-  { id: 'a' as const, label: 'A', x: 40,  y: 60,  width: 80, height: 40 },
-  { id: 'b' as const, label: 'B', x: 260, y: 180, width: 80, height: 40 },
-] as const
+const elements = {
+  'a': { id: 'a' as const, label: 'A', x: 40,  y: 60,  width: 80, height: 40 },
+  'b': { id: 'b' as const, label: 'B', x: 260, y: 180, width: 80, height: 40 },
+} as const
 
-const links = [{ id: 'a-b' as const, source: 'a', target: 'b' }] as const
+const links = {
+  'a-b': { id: 'a-b' as const, source: 'a', target: 'b' },
+} as const
 
 export function MultiView() {
   return (
@@ -166,15 +168,15 @@ Pass `elements/links` + `onElementsChange/onLinksChange` to keep React in charge
 import React, { useState } from 'react'
 import { GraphProvider } from '@joint/react'
 
-const initialElements = [
-  { id: 'n1' as const, label: 'Item', x: 60, y: 60, width: 100, height: 40 },
-] as const
+const initialElements = {
+  'n1': { id: 'n1' as const, label: 'Item', x: 60, y: 60, width: 100, height: 40 },
+} as const
 
-const initialLinks = [] as const
+const initialLinks = {} as const
 
 export function Controlled() {
-  const [els, setEls] = useState([...initialElements])
-  const [lns, setLns] = useState([...initialLinks])
+  const [els, setEls] = useState<Record<string, typeof initialElements[keyof typeof initialElements]>>({ ...initialElements })
+  const [lns, setLns] = useState<Record<string, never>>({ ...initialLinks })
 
   return (
     <GraphProvider
@@ -198,8 +200,8 @@ import { createStore } from 'zustand'
 
 // Create a store compatible with ExternalStoreLike interface
 const useGraphStore = createStore((set) => ({
-  elements: [],
-  links: [],
+  elements: {},
+  links: {},
   setState: (updater) => set(updater),
   getSnapshot: () => useGraphStore.getState(),
   subscribe: (listener) => {
@@ -287,7 +289,7 @@ export function FitOnMount() {
 ## 🧠 Best Practices
 
 - **Define ids as literals**: `id: 'node1' as const` — enables exact typing and prevents mismatches.
-- **Type elements from data**: `type Element = typeof elements[number]` — reuse data as your source of truth.
+- **Type elements from data**: `type Element = typeof elements[keyof typeof elements]` — reuse data as your source of truth.
 - **Memoize renderers & handlers**: `useCallback` to minimize re-renders.
 - **Keep overlay HTML lightweight**: Prefer simple layout; avoid heavy transforms/animations in `<foreignObject>` (Safari can be picky).
 - **Give each view a stable `id`** when rendering multiple `Paper` instances.
diff --git a/packages/joint-react/jest.config.js b/packages/joint-react/jest.config.js
index 651d74e32..6d062dced 100644
--- a/packages/joint-react/jest.config.js
+++ b/packages/joint-react/jest.config.js
@@ -2,7 +2,22 @@ export default {
   testEnvironment: 'jsdom',
   testPathIgnorePatterns: ['/node_modules/', '/dist/'],
   transform: {
-    '^.+\\.tsx?$': 'ts-jest', // Transform TypeScript files
+    '^.+\\.tsx?$': [
+      '@swc/jest',
+      {
+        jsc: {
+          parser: {
+            syntax: 'typescript',
+            tsx: true,
+          },
+          transform: {
+            react: {
+              runtime: 'automatic',
+            },
+          },
+        },
+      },
+    ],
   },
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'], // Recognize file extensions
   setupFilesAfterEnv: [
diff --git a/packages/joint-react/package.json b/packages/joint-react/package.json
index d769c1775..a330dbd15 100644
--- a/packages/joint-react/package.json
+++ b/packages/joint-react/package.json
@@ -65,6 +65,8 @@
     "@storybook/react": "8.6.12",
     "@storybook/react-vite": "8.6.12",
     "@storybook/test": "8.6.12",
+    "@swc/core": "^1.15.11",
+    "@swc/jest": "^0.2.39",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.0.1",
     "@testing-library/react-hooks": "^8.0.1",
@@ -98,7 +100,6 @@
     "storybook": "^8.6.14",
     "storybook-addon-performance": "0.17.3",
     "storybook-multilevel-sort": "2.1.0",
-    "ts-jest": "^29.2.5",
     "ts-node": "^10.9.2",
     "typedoc": "^0.28.5",
     "typedoc-github-theme": "^0.3.0",
diff --git a/packages/joint-react/src/components/graph/graph-provider.stories.tsx b/packages/joint-react/src/components/graph/graph-provider.stories.tsx
index 26ce34ea8..8e7fc33d6 100644
--- a/packages/joint-react/src/components/graph/graph-provider.stories.tsx
+++ b/packages/joint-react/src/components/graph/graph-provider.stories.tsx
@@ -35,19 +35,19 @@ The **GraphProvider** component provides a shared Graph context for all its desc
 \`\`\`tsx
 import { GraphProvider, Paper } from '@joint/react';
 
-const elements = [
-  { id: '1', x: 100, y: 100, width: 100, height: 50 },
-  { id: '2', x: 250, y: 200, width: 100, height: 50 },
-];
+const elements = {
+  '1': { id: '1', x: 100, y: 100, width: 100, height: 50 },
+  '2': { id: '2', x: 250, y: 200, width: 100, height: 50 },
+};
 
-const links = [
-  { id: 'l1', source: '1', target: '2' },
-];
+const links = {
+  'l1': { id: 'l1', source: '1', target: '2' },
+};
 
 function MyDiagram() {
   return (
     <GraphProvider elements={elements} links={links}>
-      <Paper 
+      <Paper
         renderElement={({ width, height }) => (
           <rect width={width} height={height} fill="blue" />
         )}
@@ -58,8 +58,8 @@ function MyDiagram() {
 \`\`\`
     `,
     props: `
-- **elements**: Array of element objects (required)
-- **links**: Array of link objects (required)
+- **elements**: Record of element objects keyed by ID (required)
+- **links**: Record of link objects keyed by ID (required)
 - **children**: React nodes (typically Paper components)
 - **onChange**: Callback fired when graph state changes
     `,
diff --git a/packages/joint-react/src/components/graph/graph-provider.tsx b/packages/joint-react/src/components/graph/graph-provider.tsx
index b3ec9ee04..6c00c15d9 100644
--- a/packages/joint-react/src/components/graph/graph-provider.tsx
+++ b/packages/joint-react/src/components/graph/graph-provider.tsx
@@ -11,10 +11,15 @@ import type { GraphStateSelectors } from '../../state/graph-state-selectors';
 /**
  * Props for GraphProvider component.
  * Supports three modes: uncontrolled, React-controlled, and external-store-controlled.
+ * @template Element - The type of elements in the graph
+ * @template Link - The type of links in the graph
  */
-interface GraphProviderProps {
+interface GraphProviderProps<
+  Element extends GraphElement = GraphElement,
+  Link extends GraphLink = GraphLink,
+> {
   /**
-   * Elements (nodes) to be added to the graph.
+   * Elements (nodes) to be added to the graph as a Record keyed by cell ID.
    *
    * **Controlled mode:** When `onElementsChange` is provided, this prop controls the elements.
    * All changes must go through React state updates.
@@ -22,10 +27,10 @@ interface GraphProviderProps {
    * **Uncontrolled mode:** If `onElementsChange` is not provided, this is only used for initial elements.
    * The graph manages its own state internally.
    */
-  readonly elements?: GraphElement[];
+  readonly elements?: Record<dia.Cell.ID, Element>;
 
   /**
-   * Links (edges) to be added to the graph.
+   * Links (edges) to be added to the graph as a Record keyed by cell ID.
    *
    * **Controlled mode:** When `onLinksChange` is provided, this prop controls the links.
    * All changes must go through React state updates.
@@ -33,7 +38,7 @@ interface GraphProviderProps {
    * **Uncontrolled mode:** If `onLinksChange` is not provided, this is only used for initial links.
    * The graph manages its own state internally.
    */
-  readonly links?: GraphLink[];
+  readonly links?: Record<dia.Cell.ID, Link>;
 
   /**
    * Callback triggered when elements (nodes) change in the graph.
@@ -47,7 +52,7 @@ interface GraphProviderProps {
    * - State persistence
    * - Integration with other React state management
    */
-  readonly onElementsChange?: Dispatch<SetStateAction<GraphElement[]>>;
+  readonly onElementsChange?: Dispatch<SetStateAction<Record<dia.Cell.ID, Element>>>;
 
   /**
    * Callback triggered when links (edges) change in the graph.
@@ -61,16 +66,7 @@ interface GraphProviderProps {
    * - State persistence
    * - Integration with other React state management
    */
-  readonly onLinksChange?: Dispatch<SetStateAction<GraphLink[]>>;
-
-  // readonly linkMapper: {
-  //   toStateSelector: (data: GraphLink) => dia.Link.JSON;
-  //   toDiaGraphSelector: (link: dia.Link.JSON) => GraphLink;
-  // };
-  // readonly elementMapper: {
-  //   toStateSelector: (data: GraphElement) => dia.Element.JSON;
-  //   toDiaGraphSelector: (element: dia.Element.JSON) => GraphElement;
-  // };
+  readonly onLinksChange?: Dispatch<SetStateAction<Record<dia.Cell.ID, Link>>>;
 }
 
 /**
@@ -82,7 +78,7 @@ interface GraphProviderProps {
 export interface GraphProps<
   Element extends GraphElement = GraphElement,
   Link extends GraphLink = GraphLink,
-> extends GraphProviderProps,
+> extends GraphProviderProps<Element, Link>,
     GraphStateSelectors<Element, Link> {
   /**
    * Graph instance to use. If not provided, a new graph instance will be created.
@@ -142,13 +138,6 @@ export interface GraphProps<
    * with most state management libraries.
    */
   readonly externalStore?: ExternalGraphStore;
-
-  /**
-   * If true, batch updates are disabled and synchronization will be real-time.
-   * If false (default), batch updates are enabled for better performance.
-   * @default false
-   */
-  readonly areBatchUpdatesDisabled?: boolean;
 }
 
 /**
@@ -296,8 +285,8 @@ const GraphBaseRouter = forwardRef<GraphStore, GraphProps>(
  *
  * 2. **React-controlled mode:**
  * ```tsx
- * const [elements, setElements] = useState<GraphElement[]>([]);
- * const [links, setLinks] = useState<GraphLink[]>([]);
+ * const [elements, setElements] = useState<Record<string, GraphElement>>({});
+ * const [links, setLinks] = useState<Record<string, GraphLink>>({});
  *
  * <GraphProvider
  *   elements={elements}
diff --git a/packages/joint-react/src/components/highlighters/__tests__/highlighter-cleanup.test.tsx b/packages/joint-react/src/components/highlighters/__tests__/highlighter-cleanup.test.tsx
index f663c613d..a87012761 100644
--- a/packages/joint-react/src/components/highlighters/__tests__/highlighter-cleanup.test.tsx
+++ b/packages/joint-react/src/components/highlighters/__tests__/highlighter-cleanup.test.tsx
@@ -14,15 +14,15 @@ describe('Highlighter cleanup', () => {
       wrapper: paperRenderElementWrapper({
         graphProviderProps: {
           graph,
-          elements: [
-            {
+          elements: {
+            'element-1': {
               id: 'element-1',
               x: 0,
               y: 0,
               width: 100,
               height: 100,
             },
-          ],
+          },
         },
       }),
     };
diff --git a/packages/joint-react/src/components/highlighters/__tests__/stroke.test.tsx b/packages/joint-react/src/components/highlighters/__tests__/stroke.test.tsx
index fef04ae6b..7ffc6ca0a 100644
--- a/packages/joint-react/src/components/highlighters/__tests__/stroke.test.tsx
+++ b/packages/joint-react/src/components/highlighters/__tests__/stroke.test.tsx
@@ -5,13 +5,13 @@ import { Stroke } from '../stroke';
 describe('Stroke highlighter', () => {
   const wrapper = paperRenderElementWrapper({
     graphProviderProps: {
-      elements: [
-        {
+      elements: {
+        '1': {
           id: '1',
           width: 100,
           height: 100,
         },
-      ],
+      },
     },
     paperProps: {
       renderElement: () => <rect />,
diff --git a/packages/joint-react/src/components/link/__tests__/base-link.test.tsx b/packages/joint-react/src/components/link/__tests__/base-link.test.tsx
deleted file mode 100644
index 5e4544a53..000000000
--- a/packages/joint-react/src/components/link/__tests__/base-link.test.tsx
+++ /dev/null
@@ -1,224 +0,0 @@
-/* eslint-disable unicorn/consistent-function-scoping */
- 
-import { render, waitFor } from '@testing-library/react';
-import { getTestGraph, paperRenderLinkWrapper } from '../../../utils/test-wrappers';
-import { dia } from '@joint/core';
-import { BaseLink } from '../base-link';
-
-describe('BaseLink', () => {
-  const getTestWrapper = () => {
-    const graph = getTestGraph();
-    return {
-      graph,
-      wrapper: paperRenderLinkWrapper({
-        graphProviderProps: {
-          graph,
-          elements: [
-            {
-              id: 'element-1',
-              x: 0,
-              y: 0,
-              width: 100,
-              height: 100,
-            },
-            {
-              id: 'element-2',
-              x: 200,
-              y: 200,
-              width: 100,
-              height: 100,
-            },
-          ],
-          links: [
-            {
-              id: 'link-1',
-              source: 'element-1',
-              target: 'element-2',
-            },
-          ],
-        },
-      }),
-    };
-  };
-
-  it('should set stroke attribute correctly', async () => {
-    const { graph, wrapper } = getTestWrapper();
-    const { unmount } = render(<BaseLink stroke="blue" />, { wrapper });
-    await waitFor(() => {
-      const link = graph.getCell('link-1');
-      if (!link) {
-        throw new Error('Link not found in graph');
-      }
-      expect(link).toBeInstanceOf(dia.Link);
-      const line = link.attr('line');
-      expect(line?.stroke).toBe('blue');
-    });
-    unmount();
-  });
-
-  it('should set strokeWidth attribute correctly', async () => {
-    const { graph, wrapper } = getTestWrapper();
-    const { unmount } = render(<BaseLink strokeWidth={3} />, { wrapper });
-    await waitFor(() => {
-      const link = graph.getCell('link-1');
-      if (!link) {
-        throw new Error('Link not found in graph');
-      }
-      const line = link.attr('line');
-      expect(line?.strokeWidth).toBe(3);
-    });
-    unmount();
-  });
-
-  it('should set strokeDasharray attribute correctly', async () => {
-    const { graph, wrapper } = getTestWrapper();
-    const { unmount } = render(<BaseLink strokeDasharray="5,5" />, { wrapper });
-    await waitFor(() => {
-      const link = graph.getCell('link-1');
-      if (!link) {
-        throw new Error('Link not found in graph');
-      }
-      const line = link.attr('line');
-      expect(line?.strokeDasharray).toBe('5,5');
-    });
-    unmount();
-  });
-
-  it('should set strokeDashoffset attribute correctly', async () => {
-    const { graph, wrapper } = getTestWrapper();
-    const { unmount } = render(<BaseLink strokeDashoffset={10} />, { wrapper });
-    await waitFor(() => {
-      const link = graph.getCell('link-1');
-      if (!link) {
-        throw new Error('Link not found in graph');
-      }
-      const line = link.attr('line');
-      expect(line?.strokeDashoffset).toBe(10);
-    });
-    unmount();
-  });
-
-  it('should set strokeLinecap attribute correctly', async () => {
-    const { graph, wrapper } = getTestWrapper();
-    const { unmount } = render(<BaseLink strokeLinecap="round" />, { wrapper });
-    await waitFor(() => {
-      const link = graph.getCell('link-1');
-      if (!link) {
-        throw new Error('Link not found in graph');
-      }
-      const line = link.attr('line');
-      expect(line?.strokeLinecap).toBe('round');
-    });
-    unmount();
-  });
-
-  it('should set strokeLinejoin attribute correctly', async () => {
-    const { graph, wrapper } = getTestWrapper();
-    const { unmount } = render(<BaseLink strokeLinejoin="bevel" />, { wrapper });
-    await waitFor(() => {
-      const link = graph.getCell('link-1');
-      if (!link) {
-        throw new Error('Link not found in graph');
-      }
-      const line = link.attr('line');
-      expect(line?.strokeLinejoin).toBe('bevel');
-    });
-    unmount();
-  });
-
-  it('should set fill attribute correctly', async () => {
-    const { graph, wrapper } = getTestWrapper();
-    const { unmount } = render(<BaseLink fill="red" />, { wrapper });
-    await waitFor(() => {
-      const link = graph.getCell('link-1');
-      if (!link) {
-        throw new Error('Link not found in graph');
-      }
-      const line = link.attr('line');
-      expect(line?.fill).toBe('red');
-    });
-    unmount();
-  });
-
-  it('should set opacity attribute correctly', async () => {
-    const { graph, wrapper } = getTestWrapper();
-    const { unmount } = render(<BaseLink opacity={0.5} />, { wrapper });
-    await waitFor(() => {
-      const link = graph.getCell('link-1');
-      if (!link) {
-        throw new Error('Link not found in graph');
-      }
-      const line = link.attr('line');
-      expect(line?.opacity).toBe(0.5);
-    });
-    unmount();
-  });
-
-  it('should set multiple attributes correctly', async () => {
-    const { graph, wrapper } = getTestWrapper();
-    const { unmount } = render(
-      <BaseLink stroke="green" strokeWidth={4} strokeDasharray="10,5" opacity={0.8} />,
-      { wrapper }
-    );
-    await waitFor(() => {
-      const link = graph.getCell('link-1');
-      if (!link) {
-        throw new Error('Link not found in graph');
-      }
-      const line = link.attr('line');
-      expect(line?.stroke).toBe('green');
-      expect(line?.strokeWidth).toBe(4);
-      expect(line?.strokeDasharray).toBe('10,5');
-      expect(line?.opacity).toBe(0.8);
-    });
-    unmount();
-  });
-
-  it('should restore default attributes on unmount', async () => {
-    const { graph, wrapper } = getTestWrapper();
-    const { unmount } = render(<BaseLink stroke="blue" strokeWidth={5} />, { wrapper });
-    await waitFor(() => {
-      const link = graph.getCell('link-1');
-      if (!link) {
-        throw new Error('Link not found in graph');
-      }
-      const line = link.attr('line');
-      expect(line?.stroke).toBe('blue');
-      expect(line?.strokeWidth).toBe(5);
-    });
-    unmount();
-
-    await waitFor(() => {
-      const link = graph.getCell('link-1');
-      if (!link) {
-        throw new Error('Link not found in graph');
-      }
-      const line = link.attr('line');
-      expect(line?.stroke).toBe('#333333');
-    });
-  });
-
-  it('should update attributes when props change', async () => {
-    const { graph, wrapper } = getTestWrapper();
-    const { rerender } = render(<BaseLink stroke="red" />, { wrapper });
-    await waitFor(() => {
-      const link = graph.getCell('link-1');
-      if (!link) {
-        throw new Error('Link not found in graph');
-      }
-      const line = link.attr('line');
-      expect(line?.stroke).toBe('red');
-    });
-
-    rerender(<BaseLink stroke="purple" strokeWidth={6} />);
-    await waitFor(() => {
-      const link = graph.getCell('link-1');
-      if (!link) {
-        throw new Error('Link not found in graph');
-      }
-      const line = link.attr('line');
-      expect(line?.stroke).toBe('purple');
-      expect(line?.strokeWidth).toBe(6);
-    });
-  });
-});
diff --git a/packages/joint-react/src/components/link/__tests__/link-label.test.tsx b/packages/joint-react/src/components/link/__tests__/link-label.test.tsx
deleted file mode 100644
index c9c537510..000000000
--- a/packages/joint-react/src/components/link/__tests__/link-label.test.tsx
+++ /dev/null
@@ -1,511 +0,0 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
-/* eslint-disable @typescript-eslint/no-shadow */
-/* eslint-disable no-shadow */
-/* eslint-disable @typescript-eslint/prefer-optional-chain */
-/* eslint-disable unicorn/consistent-function-scoping */
-/* eslint-disable react-perf/jsx-no-new-object-as-prop */
-import { render, waitFor, act } from '@testing-library/react';
-import { getTestGraph, paperRenderLinkWrapper } from '../../../utils/test-wrappers';
-import type { dia } from '@joint/core';
-import { LinkLabel } from '../link-label';
-
-interface LinkLabelWithId extends dia.Link.Label {
-  readonly labelId: string;
-}
-
-function isLabelPosition(
-  position: number | dia.LinkView.LabelOptions | undefined
-): position is dia.LinkView.LabelOptions {
-  // eslint-disable-next-line sonarjs/different-types-comparison
-  return typeof position === 'object' && position !== null;
-}
-
-function getLabelPosition(label: LinkLabelWithId): dia.LinkView.LabelOptions {
-  const { position } = label;
-  if (!isLabelPosition(position)) {
-    throw new Error('Expected label position to be an object');
-  }
-  return position;
-}
-
-describe('LinkLabel', () => {
-  const getTestWrapper = () => {
-    const graph = getTestGraph();
-    return {
-      graph,
-      wrapper: paperRenderLinkWrapper({
-        graphProviderProps: {
-          graph,
-          elements: [
-            {
-              id: 'element-1',
-              x: 0,
-              y: 0,
-              width: 100,
-              height: 100,
-            },
-            {
-              id: 'element-2',
-              x: 200,
-              y: 200,
-              width: 100,
-              height: 100,
-            },
-          ],
-          links: [
-            {
-              id: 'link-1',
-              source: 'element-1',
-              target: 'element-2',
-            },
-          ],
-        },
-      }),
-    };
-  };
-
-  describe('mount and unmount', () => {
-    it('should create label on mount', async () => {
-      const { graph, wrapper } = getTestWrapper();
-      render(
-        <LinkLabel distance={0.5}>
-          <text>Test Label</text>
-        </LinkLabel>,
-        { wrapper }
-      );
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        expect(labels.length).toBe(1);
-        const label = labels[0] as LinkLabelWithId;
-        expect(getLabelPosition(label).distance).toBe(0.5);
-        expect(label.labelId).toBeDefined();
-      });
-    });
-
-    it('should remove label on unmount', async () => {
-      const { graph, wrapper } = getTestWrapper();
-      const { unmount } = render(
-        <LinkLabel distance={0.5}>
-          <text>Test Label</text>
-        </LinkLabel>,
-        { wrapper }
-      );
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        expect(link.labels().length).toBe(1);
-      });
-
-      unmount();
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        expect(link.labels().length).toBe(0);
-      });
-    });
-  });
-
-  describe('prop updates', () => {
-    it('should update distance when prop changes', async () => {
-      const { graph, wrapper } = getTestWrapper();
-      const { rerender } = render(<LinkLabel distance={0.3} />, { wrapper });
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        expect(labels.length).toBe(1);
-        const label = labels[0] as LinkLabelWithId;
-        expect(getLabelPosition(label).distance).toBe(0.3);
-      });
-
-      rerender(<LinkLabel distance={0.7} />);
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        expect(labels.length).toBe(1);
-        const label = labels[0] as LinkLabelWithId;
-        expect(getLabelPosition(label).distance).toBe(0.7);
-      });
-    });
-
-    it('should update offset when prop changes', async () => {
-      const { graph, wrapper } = getTestWrapper();
-      const { rerender } = render(<LinkLabel distance={0.5} offset={10} />, { wrapper });
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        const label = labels[0] as LinkLabelWithId;
-        expect(getLabelPosition(label).offset).toBe(10);
-      });
-
-      rerender(<LinkLabel distance={0.5} offset={{ x: 20, y: 30 }} />);
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        const label = labels[0] as LinkLabelWithId;
-        expect(getLabelPosition(label).offset).toEqual({ x: 20, y: 30 });
-      });
-    });
-
-    it('should update angle when prop changes', async () => {
-      const { graph, wrapper } = getTestWrapper();
-      const { rerender } = render(<LinkLabel distance={0.5} angle={0} />, { wrapper });
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        const label = labels[0] as LinkLabelWithId;
-        expect(getLabelPosition(label).angle).toBe(0);
-      });
-
-      rerender(<LinkLabel distance={0.5} angle={45} />);
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        const label = labels[0] as LinkLabelWithId;
-        expect(getLabelPosition(label).angle).toBe(45);
-      });
-    });
-
-    it('should update attrs when prop changes', async () => {
-      const { graph, wrapper } = getTestWrapper();
-      const { rerender } = render(
-        <LinkLabel distance={0.5} attrs={{ text: { text: 'Label 1' } }} />,
-        { wrapper }
-      );
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        const label = labels[0] as LinkLabelWithId;
-        expect(label.attrs?.text?.text).toBe('Label 1');
-      });
-
-      rerender(<LinkLabel distance={0.5} attrs={{ text: { text: 'Label 2' } }} />);
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        const label = labels[0] as LinkLabelWithId;
-        expect(label.attrs?.text?.text).toBe('Label 2');
-      });
-    });
-
-    it('should update size when prop changes', async () => {
-      const { graph, wrapper } = getTestWrapper();
-      const { rerender } = render(<LinkLabel distance={0.5} size={{ width: 50, height: 20 }} />, {
-        wrapper,
-      });
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        const label = labels[0] as LinkLabelWithId;
-        expect(label.size?.width).toBe(50);
-        expect(label.size?.height).toBe(20);
-      });
-
-      rerender(<LinkLabel distance={0.5} size={{ width: 100, height: 40 }} />);
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        const label = labels[0] as LinkLabelWithId;
-        expect(label.size?.width).toBe(100);
-        expect(label.size?.height).toBe(40);
-      });
-    });
-
-    it('should update args when prop changes', async () => {
-      const { graph, wrapper } = getTestWrapper();
-      const { rerender } = render(<LinkLabel distance={0.5} args={{ absoluteDistance: true }} />, {
-        wrapper,
-      });
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        const label = labels[0] as LinkLabelWithId;
-        expect(getLabelPosition(label).args?.absoluteDistance).toBe(true);
-      });
-
-      rerender(<LinkLabel distance={0.5} args={{ absoluteDistance: false }} />);
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        const label = labels[0] as LinkLabelWithId;
-        expect(getLabelPosition(label).args?.absoluteDistance).toBe(false);
-      });
-    });
-
-    it('should update multiple props together', async () => {
-      const { graph, wrapper } = getTestWrapper();
-      const { rerender } = render(
-        <LinkLabel distance={0.3} offset={10} angle={0} attrs={{ text: { text: 'A' } }} />,
-        { wrapper }
-      );
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        const label = labels[0] as LinkLabelWithId;
-        const position = getLabelPosition(label);
-        expect(position.distance).toBe(0.3);
-        expect(position.offset).toBe(10);
-        expect(position.angle).toBe(0);
-        expect(label.attrs?.text?.text).toBe('A');
-      });
-
-      rerender(<LinkLabel distance={0.7} offset={20} angle={90} attrs={{ text: { text: 'B' } }} />);
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        const label = labels[0] as LinkLabelWithId;
-        const position = getLabelPosition(label);
-        expect(position.distance).toBe(0.7);
-        expect(position.offset).toBe(20);
-        expect(position.angle).toBe(90);
-        expect(label.attrs?.text?.text).toBe('B');
-      });
-    });
-  });
-
-  describe('render optimization', () => {
-    it('should not create duplicate labels when props change', async () => {
-      const { graph, wrapper } = getTestWrapper();
-      const { rerender } = render(<LinkLabel distance={0.5} />, { wrapper });
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        expect(link.labels().length).toBe(1);
-      });
-
-      // Update props multiple times
-      rerender(<LinkLabel distance={0.6} />);
-      rerender(<LinkLabel distance={0.7} />);
-      rerender(<LinkLabel distance={0.8} />);
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        // Should still have only one label
-        expect(link.labels().length).toBe(1);
-        const label = link.labels()[0] as LinkLabelWithId;
-        expect(getLabelPosition(label).distance).toBe(0.8);
-      });
-    });
-
-    it('should not re-create label when stable props change', async () => {
-      const { graph, wrapper } = getTestWrapper();
-      let renderCount = 0;
-      const TestComponent = () => {
-        renderCount++;
-        return <LinkLabel distance={0.5}>Test</LinkLabel>;
-      };
-
-      const { rerender } = render(<TestComponent />, { wrapper });
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        expect(link.labels().length).toBe(1);
-      });
-
-      // Get the initial labelId
-      const link = graph.getCell('link-1');
-      if (!link || !link.isLink()) {
-        throw new Error('Link not found');
-      }
-      const initialLabelId = (link.labels()[0] as LinkLabelWithId).labelId;
-
-      // Update props that should trigger update effect, not create effect
-      act(() => {
-        rerender(<TestComponent />);
-      });
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        // Label should still exist with same labelId
-        const labels = link.labels();
-        expect(labels.length).toBe(1);
-        const label = labels[0] as LinkLabelWithId;
-        expect(label.labelId).toBe(initialLabelId);
-      });
-
-      // Component may re-render, but label should not be recreated
-      expect(link.labels().length).toBe(1);
-    });
-
-    it('should only create label once on mount, then update on prop changes', async () => {
-      const { graph, wrapper } = getTestWrapper();
-      const { rerender } = render(<LinkLabel distance={0.5} />, { wrapper });
-
-      // Wait for link to be available and label to be created
-      await waitFor(() => {
-        const foundLink = graph.getCell('link-1');
-        if (!foundLink || !foundLink.isLink()) {
-          throw new Error('Link not found');
-        }
-        expect(foundLink.labels().length).toBe(1);
-      });
-
-      const link = graph.getCell('link-1');
-      if (!link || !link.isLink()) {
-        throw new Error('Link not found');
-      }
-
-      // Get the initial labelId to verify it's the same label being updated
-      const initialLabelId = (link.labels()[0] as LinkLabelWithId).labelId;
-
-      // Update props - should trigger update effect, not create effect
-      rerender(<LinkLabel distance={0.6} />);
-      await waitFor(() => {
-        const labels = link!.labels();
-        expect(labels.length).toBe(1);
-        const label = labels[0] as LinkLabelWithId;
-        expect(label.labelId).toBe(initialLabelId); // Same label, not a new one
-        expect(getLabelPosition(label).distance).toBe(0.6);
-      });
-
-      // Update again
-      rerender(<LinkLabel distance={0.7} />);
-      await waitFor(() => {
-        const labels = link!.labels();
-        expect(labels.length).toBe(1);
-        const label = labels[0] as LinkLabelWithId;
-        expect(label.labelId).toBe(initialLabelId); // Still the same label
-        expect(getLabelPosition(label).distance).toBe(0.7);
-      });
-
-      // Should still have only one label
-      const finalLink = graph.getCell('link-1');
-      if (!finalLink || !finalLink.isLink()) {
-        throw new Error('Link not found');
-      }
-      expect(finalLink.labels().length).toBe(1);
-      const finalLabel = finalLink.labels()[0] as LinkLabelWithId;
-      expect(finalLabel.labelId).toBe(initialLabelId); // Same label throughout
-    });
-  });
-
-  describe('edge cases', () => {
-    it('should handle ensureLegibility prop', async () => {
-      const { graph, wrapper } = getTestWrapper();
-      render(<LinkLabel distance={0.5} ensureLegibility={true} />, { wrapper });
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        const label = labels[0] as LinkLabelWithId;
-        expect(getLabelPosition(label).args?.ensureLegibility).toBe(true);
-      });
-    });
-
-    it('should handle keepGradient prop', async () => {
-      const { graph, wrapper } = getTestWrapper();
-      render(<LinkLabel distance={0.5} keepGradient={true} />, { wrapper });
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        const label = labels[0] as LinkLabelWithId;
-        expect(getLabelPosition(label).args?.keepGradient).toBe(true);
-      });
-    });
-
-    it('should handle undefined optional props', async () => {
-      const { graph, wrapper } = getTestWrapper();
-      render(<LinkLabel distance={0.5} />, { wrapper });
-
-      await waitFor(() => {
-        const link = graph.getCell('link-1');
-        if (!link || !link.isLink()) {
-          throw new Error('Link not found');
-        }
-        const labels = link.labels();
-        expect(labels.length).toBe(1);
-        const label = labels[0] as LinkLabelWithId;
-        const position = getLabelPosition(label);
-        expect(position.distance).toBe(0.5);
-        // Optional props should be undefined or have defaults
-        expect(position.offset).toBeUndefined();
-        expect(position.angle).toBeUndefined();
-      });
-    });
-  });
-});
diff --git a/packages/joint-react/src/components/link/base-link.stories.tsx b/packages/joint-react/src/components/link/base-link.stories.tsx
deleted file mode 100644
index 66cf59946..000000000
--- a/packages/joint-react/src/components/link/base-link.stories.tsx
+++ /dev/null
@@ -1,326 +0,0 @@
-/* eslint-disable react-perf/jsx-no-new-function-as-prop */
-import type { Meta, StoryObj } from '@storybook/react';
-import '../../stories/examples/index.css';
-import { getAPILink } from '../../stories/utils/get-api-documentation-link';
-import { makeRootDocumentation, makeStory } from '../../stories/utils/make-story';
-import { SimpleRenderLinkDecorator } from 'storybook-config/decorators/with-simple-data';
-import { BaseLink } from './base-link';
-
-export type Story = StoryObj<typeof BaseLink>;
-const API_URL = getAPILink('Link.BaseLink', 'variables');
-
-const meta: Meta<typeof BaseLink> = {
-  title: 'Components/Link/BaseLink',
-  component: BaseLink,
-  decorators: [SimpleRenderLinkDecorator],
-  tags: ['component'],
-  parameters: makeRootDocumentation({
-    apiURL: API_URL,
-    description: `
-The **Link.BaseLink** component sets link properties when rendering custom links. It must be used inside the \`renderLink\` function.
-
-**Key Features:**
-- Sets link attributes (stroke, strokeWidth, etc.)
-- Sets link markup
-- Sets other link properties
-- Must be used inside renderLink context
-    `,
-    usage: `
-\`\`\`tsx
-import { Link } from '@joint/react';
-
-function RenderLink({ id }) {
-  return (
-    <>
-      <Link.BaseLink attrs={{ line: { stroke: 'blue', strokeWidth: 2 } }} />
-    </>
-  );
-}
-\`\`\`
-    `,
-    props: `
-- **attrs**: Link attributes to apply
-- **markup**: Link markup to use for rendering
-- **...rest**: Additional link properties
-    `,
-    code: `import { Link } from '@joint/react';
-
-<Link.BaseLink attrs={{ line: { stroke: 'blue' } }} />
-    `,
-  }),
-};
-
-export default meta;
-
-export const Default = makeStory<Story>({
-  args: {
-    stroke: 'blue',
-  },
-  apiURL: API_URL,
-  name: 'Basic link',
-});
-
-export const WithArrowMarkers = makeStory<Story>({
-  args: {
-    stroke: '#0075f2',
-    strokeWidth: 2,
-    startMarker: 'arrow',
-    endMarker: 'arrow',
-  },
-  apiURL: API_URL,
-  name: 'Arrow markers',
-});
-
-export const WithArrowRoundedMarkers = makeStory<Story>({
-  args: {
-    stroke: '#ed2637',
-    strokeWidth: 2,
-    startMarker: 'arrow-rounded',
-    endMarker: 'arrow-rounded',
-  },
-  apiURL: API_URL,
-  name: 'Rounded arrow markers',
-});
-
-export const WithTriangleMarkers = makeStory<Story>({
-  args: {
-    stroke: '#28a745',
-    strokeWidth: 2,
-    startMarker: 'triangle',
-    endMarker: 'triangle',
-  },
-  apiURL: API_URL,
-  name: 'Triangle markers',
-});
-
-export const WithDiamondMarkers = makeStory<Story>({
-  args: {
-    stroke: '#ffc107',
-    strokeWidth: 2,
-    startMarker: 'diamond',
-    endMarker: 'diamond',
-  },
-  apiURL: API_URL,
-  name: 'Diamond markers',
-});
-
-export const WithCircleMarkers = makeStory<Story>({
-  args: {
-    stroke: '#6f42c1',
-    strokeWidth: 2,
-    startMarker: 'circle',
-    endMarker: 'circle',
-  },
-  apiURL: API_URL,
-  name: 'Circle markers',
-});
-
-export const WithDifferentStartEndMarkers = makeStory<Story>({
-  args: {
-    stroke: '#17a2b8',
-    strokeWidth: 2,
-    startMarker: 'arrow',
-    endMarker: 'circle',
-  },
-  apiURL: API_URL,
-  name: 'Different start and end markers',
-});
-
-export const WithCrossMarkers = makeStory<Story>({
-  args: {
-    stroke: '#dc3545',
-    strokeWidth: 2,
-    startMarker: 'cross',
-    endMarker: 'cross',
-  },
-  apiURL: API_URL,
-  name: 'Cross markers',
-});
-
-export const WithLineMarkers = makeStory<Story>({
-  args: {
-    stroke: '#20c997',
-    strokeWidth: 2,
-    startMarker: 'line',
-    endMarker: 'line',
-  },
-  apiURL: API_URL,
-  name: 'Line markers',
-});
-
-export const WithOpenMarkers = makeStory<Story>({
-  args: {
-    stroke: '#fd7e14',
-    strokeWidth: 2,
-    startMarker: 'circle-open',
-    endMarker: 'triangle-open',
-  },
-  apiURL: API_URL,
-  name: 'Open markers',
-});
-
-export const WithRoundedDiamondMarkers = makeStory<Story>({
-  args: {
-    stroke: '#e83e8c',
-    strokeWidth: 2,
-    startMarker: 'diamond-rounded',
-    endMarker: 'diamond-rounded',
-  },
-  apiURL: API_URL,
-  name: 'Rounded diamond markers',
-});
-
-export const NoMarkers = makeStory<Story>({
-  args: {
-    stroke: '#6c757d',
-    strokeWidth: 2,
-    startMarker: 'none',
-    endMarker: 'none',
-  },
-  apiURL: API_URL,
-  name: 'No markers',
-});
-
-// Custom marker function stories
-function CustomStarMarkerStory() {
-  return (
-    <BaseLink
-      stroke="#f39c12"
-      strokeWidth={2}
-      startMarker={(props) => (
-        <path
-          d="M 0 -8 L 2 -2 L 8 -2 L 3 1 L 5 7 L 0 4 L -5 7 L -3 1 L -8 -2 L -2 -2 z"
-          fill={props.color}
-          strokeWidth={props.strokeWidth ?? '1'}
-        />
-      )}
-      endMarker={(props) => (
-        <path
-          d="M 0 -8 L 2 -2 L 8 -2 L 3 1 L 5 7 L 0 4 L -5 7 L -3 1 L -8 -2 L -2 -2 z"
-          fill={props.color}
-          strokeWidth={props.strokeWidth ?? '1'}
-        />
-      )}
-    />
-  );
-}
-
-export const WithCustomStarMarkers = makeStory<Story>({
-  component: CustomStarMarkerStory,
-  apiURL: API_URL,
-  name: 'Custom star markers',
-});
-
-function CustomSquareMarkerStory() {
-  return (
-    <BaseLink
-      stroke="#3498db"
-      strokeWidth={2}
-      startMarker={(props) => (
-        <rect
-          x="-4"
-          y="-4"
-          width="8"
-          height="8"
-          fill={props.color}
-          strokeWidth={props.strokeWidth ?? '1'}
-        />
-      )}
-      endMarker={(props) => (
-        <rect
-          x="-4"
-          y="-4"
-          width="8"
-          height="8"
-          fill={props.color}
-          strokeWidth={props.strokeWidth ?? '1'}
-        />
-      )}
-    />
-  );
-}
-
-export const WithCustomSquareMarkers = makeStory<Story>({
-  component: CustomSquareMarkerStory,
-  apiURL: API_URL,
-  name: 'Custom square markers',
-});
-
-function CustomHeartMarkerStory() {
-  return (
-    <BaseLink
-      stroke="#e74c3c"
-      strokeWidth={2}
-      startMarker={(props) => (
-        <path
-          d="M 0 4 C 0 2, -2 0, -4 0 C -6 0, -6 2, -6 4 C -6 6, -4 8, 0 12 C 4 8, 6 6, 6 4 C 6 2, 6 0, 4 0 C 2 0, 0 2, 0 4 z"
-          fill={props.color}
-          strokeWidth={props.strokeWidth ?? '1'}
-        />
-      )}
-      endMarker={(props) => (
-        <path
-          d="M 0 4 C 0 2, -2 0, -4 0 C -6 0, -6 2, -6 4 C -6 6, -4 8, 0 12 C 4 8, 6 6, 6 4 C 6 2, 6 0, 4 0 C 2 0, 0 2, 0 4 z"
-          fill={props.color}
-          strokeWidth={props.strokeWidth ?? '1'}
-        />
-      )}
-    />
-  );
-}
-
-export const WithCustomHeartMarkers = makeStory<Story>({
-  component: CustomHeartMarkerStory,
-  apiURL: API_URL,
-  name: 'Custom heart markers',
-});
-
-function CustomMixedMarkersStory() {
-  return (
-    <BaseLink
-      stroke="#9b59b6"
-      strokeWidth={2}
-      startMarker="arrow"
-      endMarker={(props) => (
-        <path
-          d="M 0 0 L 10 -6 L 10 6 z M 0 0 L -10 -6 L -10 6 z"
-          fill={props.color}
-          strokeWidth={props.strokeWidth ?? '2'}
-        />
-      )}
-    />
-  );
-}
-
-export const WithMixedPredefinedAndCustomMarkers = makeStory<Story>({
-  component: CustomMixedMarkersStory,
-  apiURL: API_URL,
-  name: 'Mixed predefined and custom markers',
-});
-
-function CustomComplexMarkerStory() {
-  return (
-    <BaseLink
-      stroke="#16a085"
-      strokeWidth={3}
-      startMarker={(props) => (
-        <g>
-          <circle r="6" fill={props.color} />
-          <path d="M -4 -4 L 4 4 M 4 -4 L -4 4" stroke="white" strokeWidth="1.5" />
-        </g>
-      )}
-      endMarker={(props) => (
-        <g>
-          <rect x="-5" y="-5" width="10" height="10" rx="2" fill={props.color} />
-          <path d="M -3 0 L 0 -3 L 3 0 L 0 3 z" fill="white" />
-        </g>
-      )}
-    />
-  );
-}
-
-export const WithCustomComplexMarkers = makeStory<Story>({
-  component: CustomComplexMarkerStory,
-  apiURL: API_URL,
-  name: 'Custom complex markers',
-});
diff --git a/packages/joint-react/src/components/link/base-link.tsx b/packages/joint-react/src/components/link/base-link.tsx
deleted file mode 100644
index 03070ea3b..000000000
--- a/packages/joint-react/src/components/link/base-link.tsx
+++ /dev/null
@@ -1,169 +0,0 @@
-import { memo, useLayoutEffect, useMemo } from 'react';
-import { useGraphStore } from '../../hooks/use-graph-store';
-import { useCellId, usePaperStoreContext } from '../../hooks';
-import type { StandardLinkShapesTypeMapper } from '../../types/link-types';
-import { getLinkArrow, type LinkArrowName, type MarkerProps } from './link.arrows';
-import { jsx } from '../../utils/joint-jsx/jsx-to-markup';
-import type React from 'react';
-import type { OmitWithoutIndexSignature } from '../../types';
-
-type StandardLinkAttributes = Required<StandardLinkShapesTypeMapper['standard.Link']>;
-type LineAttributes = StandardLinkAttributes['line'];
-
-/**
- * Marker configuration - either a predefined arrow name or a direct component function.
- */
-export type MarkerConfig = LinkArrowName | ((props: MarkerProps) => React.JSX.Element);
-
-export interface BaseLinkProps
-  extends OmitWithoutIndexSignature<LineAttributes, 'sourceMarker' | 'targetMarker'> {
-  /**
-   * Arrow marker for the start of the link.
-   * Can be a predefined arrow name from LINK_ARROWS or a direct component function.
-   */
-  readonly startMarker?: MarkerConfig;
-  /**
-   * Arrow marker for the end of the link.
-   * Can be a predefined arrow name from LINK_ARROWS or a direct component function.
-   */
-  readonly endMarker?: MarkerConfig;
-}
-
-// eslint-disable-next-line jsdoc/require-jsdoc
-function Component(props: BaseLinkProps) {
-  const { startMarker, endMarker, ...lineAttributes } = props;
-  const linkId = useCellId();
-  const graphStore = useGraphStore();
-  const { graph } = graphStore;
-  const { paper } = usePaperStoreContext();
-
-  const resolvedLineAttributes = useMemo(() => {
-    const resolved: typeof lineAttributes & {
-      sourceMarker?: { markup: ReturnType<typeof jsx> };
-      targetMarker?: { markup: ReturnType<typeof jsx> };
-    } = { ...lineAttributes };
-
-    // Get the link to check for color attribute
-    const link = graph.getCell(linkId);
-    const linkColor = link?.attr('color') as string | undefined;
-
-    // Determine marker color: use stroke if provided, otherwise inherit from link color, fallback to black
-    const markerColor = (lineAttributes.stroke as string | undefined) ?? linkColor ?? '#000000';
-
-    if (startMarker) {
-      let markerComponent: ((props: MarkerProps) => React.JSX.Element) | undefined;
-
-      // Check if it's a predefined marker name or direct function
-      if (typeof startMarker === 'string') {
-        const marker = getLinkArrow(startMarker);
-        markerComponent = marker?.component;
-      } else {
-        markerComponent = startMarker;
-      }
-
-      if (markerComponent) {
-        // Convert React component to JointJS markup
-        const componentResult = markerComponent({ color: markerColor });
-        resolved.sourceMarker = { markup: jsx(componentResult) };
-      }
-    }
-
-    if (endMarker) {
-      let markerComponent: ((props: MarkerProps) => React.JSX.Element) | undefined;
-
-      // Check if it's a predefined marker name or direct function
-      if (typeof endMarker === 'string') {
-        const marker = getLinkArrow(endMarker);
-        markerComponent = marker?.component;
-      } else {
-        markerComponent = endMarker;
-      }
-
-      if (markerComponent) {
-        // Convert React component to JointJS markup
-        const componentResult = markerComponent({ color: markerColor });
-        resolved.targetMarker = { markup: jsx(componentResult) };
-      }
-    }
-
-    return resolved;
-  }, [graph, linkId, lineAttributes, startMarker, endMarker]);
-
-  // Effect 1: Capture default attributes on mount, restore on unmount
-  // Only depends on paper and graph (stable references) - runs on mount/unmount
-  useLayoutEffect(() => {
-    const link = graph.getCell(linkId);
-
-    if (!link) {
-      throw new Error(`Link with id ${linkId} not found`);
-    }
-    if (!paper) {
-      return;
-    }
-    if (!link.isLink()) {
-      throw new Error(`Cell with id ${linkId} is not a link`);
-    }
-
-    // Capture default attributes for cleanup
-    const defaultAttributes = link.attr();
-
-    return () => {
-      // Restore default attributes via graphStore for batching
-      graphStore.setLink(linkId, defaultAttributes);
-    };
-  }, [graph, graphStore, paper, linkId]); // Only stable dependencies - captures defaults on mount, restores on unmount
-
-  // Effect 2: Update attributes when props change or when link is updated
-  useLayoutEffect(() => {
-    const link = graph.getCell(linkId);
-
-    if (!link) {
-      return;
-    }
-    if (!paper) {
-      return;
-    }
-    if (!link.isLink()) {
-      return;
-    }
-
-    // Always re-apply current attributes via graphStore for batching
-    graphStore.setLink(linkId, {
-      line: resolvedLineAttributes,
-    });
-    graphStore.flushPendingUpdates();
-  }, [graph, graphStore, resolvedLineAttributes, linkId, paper]);
-
-  return null;
-}
-
-/**
- * BaseLink component sets link properties when rendering custom links.
- * Must be used inside `renderLink` function.
- * @group Components
- * @category Link
- * @example
- * ```tsx
- * function RenderLink({ id }) {
- *   return (
- *     <>
- *       <BaseLink stroke="blue" startMarker="arrow" endMarker="arrow" />
- *     </>
- *   );
- * }
- * ```
- * @example
- * ```tsx
- * function RenderLink({ id }) {
- *   return (
- *     <>
- *       <BaseLink
- *         stroke="blue"
- *         startMarker={(props) => <path d="M 0 0 L 10 -5 L 10 5 z" fill={props.color} />}
- *       />
- *     </>
- *   );
- * }
- * ```
- */
-export const BaseLink = memo(Component);
diff --git a/packages/joint-react/src/components/link/base-link.types.ts b/packages/joint-react/src/components/link/base-link.types.ts
deleted file mode 100644
index 372699d71..000000000
--- a/packages/joint-react/src/components/link/base-link.types.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import type { dia } from '@joint/core';
-
-/**
- * Props for the BaseLink component.
- * BaseLink is used to set link properties when rendering custom links.
- */
-export interface BaseLinkProps {
-  /**
-   * Link attributes to apply to the link.
-   */
-  readonly attrs?: dia.Link.Attributes;
-  /**
-   * Link markup to use for rendering.
-   */
-  readonly markup?: dia.MarkupJSON;
-  /**
-   * Additional link properties.
-   */
-  readonly [key: string]: unknown;
-}
diff --git a/packages/joint-react/src/components/link/index.ts b/packages/joint-react/src/components/link/index.ts
index 6fb64836b..5bed4886a 100644
--- a/packages/joint-react/src/components/link/index.ts
+++ b/packages/joint-react/src/components/link/index.ts
@@ -1,61 +1,7 @@
-/* eslint-disable @typescript-eslint/no-namespace */
-
-export * from './base-link.types';
-export * from './link-label.types';
-import { BaseLink } from './base-link';
-import { LinkLabel } from './link-label';
-export type { BaseLinkProps, MarkerConfig } from './base-link';
-export type { LinkLabelProps, LinkLabelPosition } from './link-label.types';
-export { LINK_ARROWS, getLinkArrow, type LinkArrowName, type LinkArrowMarker, type MarkerProps } from './link.arrows';
-
-// Direct exports for convenience
-
-const Component = {
-  Base: BaseLink,
-  Label: LinkLabel,
-};
-
 /**
- * Joint js Links in react.
- * Links are used to connect elements together.
- * BaseLink is used to set link properties, and LinkLabel is used to render labels at specific positions along links.
- * @group Components
- * @experimental This feature is experimental and may change in the future.
- * @example
- * ```tsx
- * import { Link } from '@joint/react';
- *
- * function RenderLink({ id }) {
- *  return (
- *    <>
- *      <Link.BaseLink attrs={{ line: { stroke: 'blue' } }} />
- *      <Link.Label position={{ distance: 0.5 }}>
- *        <text>Label</text>
- *      </Link.Label>
- *    </>
- *  );
- * }
- * ```
+ * Link-related exports
+ * Note: BaseLink and LinkLabel have been removed in favor of useLinkPath() hook
  */
-export namespace Link {
-  /**
-   * BaseLink component sets link properties when rendering custom links.
-   * Must be used inside `renderLink` function.
-   * @experimental This feature is experimental and may change in the future.
-   * @group Components
-   * @category Link
-   */
-   
-  export const { Base } = Component;
-  /**
-   * LinkLabel component renders content at a specific position along a link.
-   * Must be used inside `renderLink` function.
-   * @experimental This feature is experimental and may change in the future.
-   * @group Components
-   * @category Link
-   */
-  export const { Label } = Component;
-}
 
-export { BaseLink } from './base-link';
-export { LinkLabel } from './link-label';
+// Arrow utilities remain useful for custom link rendering
+export { LINK_ARROWS, getLinkArrow, type LinkArrowName, type LinkArrowMarker, type MarkerProps } from './link.arrows';
diff --git a/packages/joint-react/src/components/link/link-label.stories.tsx b/packages/joint-react/src/components/link/link-label.stories.tsx
deleted file mode 100644
index 7d2b73a30..000000000
--- a/packages/joint-react/src/components/link/link-label.stories.tsx
+++ /dev/null
@@ -1,101 +0,0 @@
- 
-import type { Meta, StoryObj } from '@storybook/react';
-import '../../stories/examples/index.css';
-import { Link } from '@joint/react';
-import { getAPILink } from '../../stories/utils/get-api-documentation-link';
-import { makeRootDocumentation, makeStory } from '../../stories/utils/make-story';
-import { SimpleRenderLinkDecorator } from 'storybook-config/decorators/with-simple-data';
-
-export type Story = StoryObj<typeof Link.Label>;
-const API_URL = getAPILink('Link.Label', 'variables');
-
-const meta: Meta<typeof Link.Label> = {
-  title: 'Components/Link/Label',
-  component: Link.Label,
-  decorators: [SimpleRenderLinkDecorator],
-  tags: ['component'],
-  parameters: makeRootDocumentation({
-    apiURL: API_URL,
-    description: `
-The **Link.Label** component renders content at a specific position along a link. It uses React portals to render children into the link label node.
-
-**Key Features:**
-- Renders content at specific positions along links (start, middle, end, custom)
-- Supports custom positioning with distance, offset, and angle
-- Uses React portals for rendering
-- Must be used inside renderLink context
-    `,
-    usage: `
-\`\`\`tsx
-import { Link } from '@joint/react';
-
-function RenderLink({ id }) {
-  return (
-    <>
-      <Link.BaseLink attrs={{ line: { stroke: 'blue' } }} />
-      <Link.Label position={{ distance: 0.5 }}>
-        <text>Label</text>
-      </Link.Label>
-    </>
-  );
-}
-\`\`\`
-    `,
-    props: `
-- **position**: Position of the label along the link (required)
-  - **distance**: 0-1 (0 = start, 0.5 = middle, 1 = end)
-  - **offset**: number (perpendicular) or {x, y} (absolute)
-  - **angle**: rotation angle in degrees
-- **children**: Content to render inside the label portal
-- **attrs**: Label attributes
-- **size**: Label size
-    `,
-    code: `import { Link } from '@joint/react';
-
-<Link.Label position={{ distance: 0.5 }}>
-  <text>Label</text>
-</Link.Label>
-    `,
-  }),
-};
-
-export default meta;
-
-function Component() {
-  const labelWidth = 100;
-  const labelHeight = 20;
-  // Center the label by offsetting by negative half-width and half-height
-  const offsetX = -labelWidth / 2;
-  const offsetY = -labelHeight / 2;
-
-  return (
-    <>
-      <Link.Label distance={0.05}>
-        <foreignObject x={offsetX} y={offsetY} width={labelWidth} height={labelHeight}>
-          <div className="size-full bg-red-400 rounded text-xs flex items-center justify-center">
-            Start
-          </div>
-        </foreignObject>
-      </Link.Label>
-      <Link.Label distance={0.5}>
-        <foreignObject x={offsetX} y={offsetY} width={labelWidth} height={labelHeight}>
-          <div className="size-full bg-red-400 rounded text-xs flex items-center justify-center">
-            Middle
-          </div>
-        </foreignObject>
-      </Link.Label>
-      <Link.Label distance={0.95}>
-        <foreignObject x={offsetX} y={offsetY} width={labelWidth} height={labelHeight}>
-          <div className="size-full bg-red-400 rounded text-xs flex items-center justify-center">
-            End
-          </div>
-        </foreignObject>
-      </Link.Label>
-    </>
-  );
-}
-export const Default = makeStory<Story>({
-  component: Component,
-  apiURL: API_URL,
-  name: 'Label at middle',
-});
diff --git a/packages/joint-react/src/components/link/link-label.tsx b/packages/joint-react/src/components/link/link-label.tsx
deleted file mode 100644
index 09908334a..000000000
--- a/packages/joint-react/src/components/link/link-label.tsx
+++ /dev/null
@@ -1,181 +0,0 @@
-import type { dia } from '@joint/core';
-import { memo, useId, useLayoutEffect, useMemo, useRef } from 'react';
-import { createPortal } from 'react-dom';
-import { useGraphStore } from '../../hooks/use-graph-store';
-import { useGraphInternalStoreSelector } from '../../hooks/use-graph-store-selector';
-import { useCellId, usePaperStoreContext } from '../../hooks';
-
-interface LinkLabelWithId extends dia.Link.Label {
-  readonly labelId: string;
-}
-
-export interface LinkLabelPosition extends dia.LinkView.LabelOptions {
-  /**
-   * Distance along the link (0-1 for relative, or absolute pixels with absoluteDistance: true).
-   * 0 = start, 0.5 = middle, 1 = end
-   */
-  readonly distance?: number;
-  /**
-   * Offset from the link path.
-   * Can be a number (perpendicular offset) or an object with x and y (absolute offset).
-   */
-  readonly offset?: number | { readonly x: number; readonly y: number };
-  /**
-   * Rotation angle in degrees.
-   */
-  readonly angle?: number;
-  /**
-   * Additional position arguments (e.g., absoluteDistance, reverseDistance, absoluteOffset).
-   */
-  readonly args?: Record<string, unknown>;
-}
-
-export interface LinkLabelProps extends LinkLabelPosition {
-  /**
-   * Children to render inside the label portal.
-   */
-  readonly children?: React.ReactNode;
-  /**
-   * Label attributes.
-   */
-  readonly attrs?: dia.Link.Label['attrs'];
-  /**
-   * Label size.
-   */
-  readonly size?: dia.Link.Label['size'];
-}
-
-// eslint-disable-next-line jsdoc/require-jsdoc
-function Component(props: LinkLabelProps) {
-  const { children, attrs, size, angle, args, distance, offset, ensureLegibility, keepGradient } =
-    props;
-  const linkId = useCellId();
-  const graphStore = useGraphStore();
-  const { graph } = graphStore;
-  const paperStore = usePaperStoreContext();
-  const { paper, paperId } = paperStore;
-  const labelsRef = useRef<readonly dia.Link.Label[]>([]);
-  const labelId = useId();
-
-  // Prepare label data during render (synchronous, runs before useLayoutEffect)
-  const labelData = useMemo<LinkLabelWithId | null>(() => {
-    if (!paper) {
-      return null;
-    }
-    const position: dia.Link.LabelPosition = {
-      distance,
-      offset,
-      angle,
-      args: {
-        ...args,
-        ensureLegibility,
-        keepGradient,
-      },
-    };
-
-    return {
-      position,
-      attrs,
-      size,
-      labelId,
-    };
-  }, [paper, distance, offset, angle, args, ensureLegibility, keepGradient, attrs, size, labelId]);
-
-  // Effect 1: Create label on mount, remove on unmount
-  // Only depends on paper and graph (stable references) - runs on mount/unmount
-  useLayoutEffect(() => {
-    if (!labelData) {
-      return;
-    }
-
-    const link = graph.getCell(linkId);
-    if (!link) {
-      throw new Error(`Link with id ${linkId} not found`);
-    }
-    if (!link.isLink()) {
-      throw new Error(`Cell with id ${linkId} is not a link`);
-    }
-
-    // Apply pre-computed label data (faster than computing in effect)
-    graphStore.setLinkLabel(linkId, labelId, labelData);
-    graphStore.flushPendingUpdates();
-    labelsRef.current = link.labels();
-    return () => {
-      // Remove label via graphStore for batching
-      graphStore.removeLinkLabel(linkId, labelId);
-    };
-  }, [graph, graphStore, linkId, labelId, labelData]); // labelData is pre-computed, so effect is faster
-
-  // Effect 2: Update label when props change
-  // Uses pre-computed labelData from useMemo (faster than computing in effect)
-  useLayoutEffect(() => {
-    if (!labelData) {
-      return;
-    }
-
-    const link = graph.getCell(linkId);
-    if (!link) {
-      return;
-    }
-    if (!link.isLink()) {
-      return;
-    }
-
-    const currentLabels = link.labels();
-    const existingLabelIndex = currentLabels.findIndex(
-      (label) => (label as LinkLabelWithId).labelId === labelId
-    );
-
-    if (existingLabelIndex === -1) {
-      return;
-    }
-
-    // Apply pre-computed label data (faster than computing in effect)
-    graphStore.setLinkLabel(linkId, labelId, labelData);
-    labelsRef.current = link.labels();
-  }, [graph, graphStore, linkId, labelId, labelData]); // labelData is pre-computed, so effect is faster
-
-  const portalNode = useGraphInternalStoreSelector((state) => {
-    // Read labels directly from the link model to ensure we have the latest state
-    const link = graph.getCell(linkId);
-    if (!link?.isLink()) {
-      return null;
-    }
-    const labels = link.labels();
-    const labelIndex = labels.findIndex((l) => (l as LinkLabelWithId).labelId === labelId);
-    if (labelIndex === -1) {
-      return null;
-    }
-    const linkLabelId = paperStore.getLinkLabelId(linkId, labelIndex);
-    return state.papers[paperId]?.linksData?.[linkLabelId];
-  });
-
-  // Component always mounts, useLayoutEffect runs immediately to add label to graph
-  // Portal rendering waits until portalNode is available (createPortal requires valid DOM node)
-  if (!portalNode) {
-    return null;
-  }
-
-  return createPortal(children, portalNode);
-}
-
-/**
- * LinkLabel component renders content at a specific position along a link.
- * Must be used inside `renderLink` function.
- * @group Components
- * @category Link
- * @example
- * ```tsx
- * function RenderLink({ id }) {
- *   return (
- *     <>
- *       <BaseLink attrs={{ line: { stroke: 'blue' } }} />
- *       <LinkLabel position={{ distance: 0.5 }}>
- *         <text>Label</text>
- *       </LinkLabel>
- *     </>
- *   );
- * }
- * ```
- */
-export const LinkLabel = memo(Component);
diff --git a/packages/joint-react/src/components/link/link-label.types.ts b/packages/joint-react/src/components/link/link-label.types.ts
deleted file mode 100644
index a51d01e72..000000000
--- a/packages/joint-react/src/components/link/link-label.types.ts
+++ /dev/null
@@ -1,53 +0,0 @@
-import type { dia } from '@joint/core';
-
-/**
- * Position options for link labels.
- * Similar to Joint.js label position system.
- */
-export interface LinkLabelPosition {
-  /**
-   * Distance along the link (0-1 for relative, or absolute pixels with absoluteDistance: true).
-   * 0 = start, 0.5 = middle, 1 = end
-   */
-  readonly distance?: number;
-  /**
-   * Offset from the link path.
-   * Can be a number (perpendicular offset) or an object with x and y (absolute offset).
-   */
-  readonly offset?: number | { readonly x: number; readonly y: number };
-  /**
-   * Rotation angle in degrees.
-   */
-  readonly angle?: number;
-  /**
-   * Additional position arguments (e.g., absoluteDistance, reverseDistance, absoluteOffset).
-   */
-  readonly args?: Record<string, unknown>;
-}
-
-/**
- * Props for the LinkLabel component.
- */
-export interface LinkLabelProps {
-  /**
-   * Position of the label along the link.
-   */
-  readonly position: LinkLabelPosition;
-  /**
-   * Optional unique identifier for the label.
-   * If not provided, the label will be identified by its index in the labels array.
-   */
-  readonly id?: string;
-  /**
-   * Children to render inside the label portal.
-   */
-  readonly children?: React.ReactNode;
-  /**
-   * Label attributes.
-   */
-  readonly attrs?: dia.Link.Label['attrs'];
-  /**
-   * Label size.
-   */
-  readonly size?: dia.Link.Label['size'];
-}
diff --git a/packages/joint-react/src/components/paper/__tests__/graph-provider-controlled-mode.test.tsx b/packages/joint-react/src/components/paper/__tests__/graph-provider-controlled-mode.test.tsx
index b5a1b8715..a8eb9322b 100644
--- a/packages/joint-react/src/components/paper/__tests__/graph-provider-controlled-mode.test.tsx
+++ b/packages/joint-react/src/components/paper/__tests__/graph-provider-controlled-mode.test.tsx
@@ -6,29 +6,28 @@ import { dia } from '@joint/core';
 import { useElements, useLinks, useGraph } from '../../../hooks';
 import type { GraphElement } from '../../../types/element-types';
 import type { GraphLink } from '../../../types/link-types';
-import { mapLinkFromGraph } from '../../../utils/cell/cell-utilities';
 import { GraphProvider } from '../../graph/graph-provider';
 
 describe('GraphProvider Controlled Mode', () => {
   describe('Basic useState integration', () => {
     it('should sync React state to store and graph on initial mount', async () => {
-      const initialElements = [
-        { id: '1', width: 100, height: 100 },
-        { id: '2', width: 200, height: 200 },
-      ];
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100 },
+        '2': { width: 200, height: 200 },
+      };
 
       let elementCount = 0;
       let elementIds: string[] = [];
 
       function TestComponent() {
-        const elements = useElements((items) => items);
+        const elements = useElements((items) => Object.values(items));
         elementCount = elements.length;
-        elementIds = elements.map((element) => String(element.id));
+        elementIds = Object.keys(useElements((items) => items));
         return null;
       }
 
       function ControlledGraph() {
-        const [elements, setElements] = useState<GraphElement[]>(() => initialElements);
+        const [elements, setElements] = useState<Record<string, GraphElement>>(() => initialElements);
         return (
           <GraphProvider elements={elements} onElementsChange={setElements}>
             <TestComponent />
@@ -45,23 +44,25 @@ describe('GraphProvider Controlled Mode', () => {
     });
 
     it('should update store when React state changes via useState', async () => {
-      const initialElements = [{ id: '1', width: 100, height: 100 }];
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100 },
+      };
 
       let elementCount = 0;
       let elementIds: string[] = [];
 
       function TestComponent() {
-        const elements = useElements((items) => items);
+        const elements = useElements((items) => Object.values(items));
         elementCount = elements.length;
-        elementIds = elements.map((element) => String(element.id));
+        elementIds = Object.keys(useElements((items) => items));
         return null;
       }
 
-      let setElementsExternal: ((elements: GraphElement[]) => void) | null = null;
+      let setElementsExternal: ((elements: Record<string, GraphElement>) => void) | null = null;
 
       function ControlledGraph() {
-        const [elements, setElements] = useState<GraphElement[]>(() => initialElements);
-        setElementsExternal = setElements as (elements: GraphElement[]) => void;
+        const [elements, setElements] = useState<Record<string, GraphElement>>(() => initialElements);
+        setElementsExternal = setElements as (elements: Record<string, GraphElement>) => void;
         return (
           <GraphProvider elements={elements} onElementsChange={setElements}>
             <TestComponent />
@@ -77,13 +78,11 @@ describe('GraphProvider Controlled Mode', () => {
       });
 
       act(() => {
-        setElementsExternal?.(
-          [
-            { id: '1', width: 100, height: 100 },
-            { id: '2', width: 200, height: 200 },
-            { id: '3', width: 300, height: 300 },
-          ]
-        );
+        setElementsExternal?.({
+          '1': { width: 100, height: 100 },
+          '2': { width: 200, height: 200 },
+          '3': { width: 300, height: 300 },
+        });
       });
 
       await waitFor(() => {
@@ -93,31 +92,34 @@ describe('GraphProvider Controlled Mode', () => {
     });
 
     it('should handle both elements and links in controlled mode', async () => {
-      const initialElements = [{ id: '1', width: 100, height: 100 }];
-      const initialLink = new dia.Link({
-        id: 'link1',
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100 },
+      };
+      const initialLink: GraphLink = {
         type: 'standard.Link',
         source: { id: '1' },
         target: { id: '2' },
-      });
+      };
 
       let elementCount = 0;
       let linkCount = 0;
 
       function TestComponent() {
-        elementCount = useElements((items) => items.length);
-        linkCount = useLinks((items) => items.length);
+        elementCount = useElements((items) => Object.keys(items).length);
+        linkCount = useLinks((items) => Object.keys(items).length);
         return null;
       }
 
-      let setElementsExternal: ((elements: GraphElement[]) => void) | null = null;
-      let setLinksExternal: ((links: GraphLink[]) => void) | null = null;
+      let setElementsExternal: ((elements: Record<string, GraphElement>) => void) | null = null;
+      let setLinksExternal: ((links: Record<string, GraphLink>) => void) | null = null;
 
       function ControlledGraph() {
-        const [elements, setElements] = useState<GraphElement[]>(() => initialElements);
-        const [links, setLinks] = useState<GraphLink[]>(() => [mapLinkFromGraph(initialLink)]);
-        setElementsExternal = setElements as (elements: GraphElement[]) => void;
-        setLinksExternal = setLinks as (links: GraphLink[]) => void;
+        const [elements, setElements] = useState<Record<string, GraphElement>>(() => initialElements);
+        const [links, setLinks] = useState<Record<string, GraphLink>>(() => ({
+          'link1': initialLink,
+        }));
+        setElementsExternal = setElements as (elements: Record<string, GraphElement>) => void;
+        setLinksExternal = setLinks as (links: Record<string, GraphLink>) => void;
         return (
           <GraphProvider
             elements={elements}
@@ -139,12 +141,10 @@ describe('GraphProvider Controlled Mode', () => {
 
       // Update elements only
       act(() => {
-        setElementsExternal?.(
-          [
-            { id: '1', width: 100, height: 100 },
-            { id: '2', width: 200, height: 200 },
-          ]
-        );
+        setElementsExternal?.({
+          '1': { width: 100, height: 100 },
+          '2': { width: 200, height: 200 },
+        });
       });
 
       await waitFor(() => {
@@ -154,24 +154,18 @@ describe('GraphProvider Controlled Mode', () => {
 
       // Update links only
       act(() => {
-        setLinksExternal?.([
-          mapLinkFromGraph(
-            new dia.Link({
-              id: 'link1',
-              type: 'standard.Link',
-              source: { id: '1' },
-              target: { id: '2' },
-            })
-          ),
-          mapLinkFromGraph(
-            new dia.Link({
-              id: 'link2',
-              type: 'standard.Link',
-              source: { id: '2' },
-              target: { id: '1' },
-            })
-          ),
-        ]);
+        setLinksExternal?.({
+          'link1': {
+            type: 'standard.Link',
+            source: { id: '1' },
+            target: { id: '2' },
+          },
+          'link2': {
+            type: 'standard.Link',
+            source: { id: '2' },
+            target: { id: '1' },
+          },
+        });
       });
 
       await waitFor(() => {
@@ -183,21 +177,23 @@ describe('GraphProvider Controlled Mode', () => {
 
   describe('Rapid consecutive updates', () => {
     it('should handle rapid consecutive state updates correctly', async () => {
-      const initialElements = [{ id: '1', width: 100, height: 100 }];
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100 },
+      };
 
       let elementCount = 0;
 
       function TestComponent() {
-        const count = useElements((items) => items.length);
+        const count = useElements((items) => Object.keys(items).length);
         elementCount = count;
         return null;
       }
 
-      let setElementsExternal: ((elements: GraphElement[]) => void) | null = null;
+      let setElementsExternal: ((elements: Record<string, GraphElement>) => void) | null = null;
 
       function ControlledGraph() {
-        const [elements, setElements] = useState<GraphElement[]>(() => initialElements);
-        setElementsExternal = setElements as (elements: GraphElement[]) => void;
+        const [elements, setElements] = useState<Record<string, GraphElement>>(() => initialElements);
+        setElementsExternal = setElements as (elements: Record<string, GraphElement>) => void;
         return (
           <GraphProvider elements={elements} onElementsChange={setElements}>
             <TestComponent />
@@ -213,27 +209,21 @@ describe('GraphProvider Controlled Mode', () => {
 
       // Rapid consecutive updates
       act(() => {
-        setElementsExternal?.(
-          [
-            { id: '1', width: 100, height: 100 },
-            { id: '2', width: 200, height: 200 },
-          ]
-        );
-        setElementsExternal?.(
-          [
-            { id: '1', width: 100, height: 100 },
-            { id: '2', width: 200, height: 200 },
-            { id: '3', width: 300, height: 300 },
-          ]
-        );
-        setElementsExternal?.(
-          [
-            { id: '1', width: 100, height: 100 },
-            { id: '2', width: 200, height: 200 },
-            { id: '3', width: 300, height: 300 },
-            { id: '4', width: 400, height: 400 },
-          ]
-        );
+        setElementsExternal?.({
+          '1': { width: 100, height: 100 },
+          '2': { width: 200, height: 200 },
+        });
+        setElementsExternal?.({
+          '1': { width: 100, height: 100 },
+          '2': { width: 200, height: 200 },
+          '3': { width: 300, height: 300 },
+        });
+        setElementsExternal?.({
+          '1': { width: 100, height: 100 },
+          '2': { width: 200, height: 200 },
+          '3': { width: 300, height: 300 },
+          '4': { width: 400, height: 400 },
+        });
       });
 
       await waitFor(
@@ -245,20 +235,22 @@ describe('GraphProvider Controlled Mode', () => {
     });
 
     it('should handle 10 rapid updates without losing state', async () => {
-      const initialElements = [{ id: '1', width: 100, height: 100 }];
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100 },
+      };
 
       let elementCount = 0;
 
       function TestComponent() {
-        elementCount = useElements((items) => items.length);
+        elementCount = useElements((items) => Object.keys(items).length);
         return null;
       }
 
-      let setElementsExternal: ((elements: GraphElement[]) => void) | null = null;
+      let setElementsExternal: ((elements: Record<string, GraphElement>) => void) | null = null;
 
       function ControlledGraph() {
-        const [elements, setElements] = useState<GraphElement[]>(() => initialElements);
-        setElementsExternal = setElements as (elements: GraphElement[]) => void;
+        const [elements, setElements] = useState<Record<string, GraphElement>>(() => initialElements);
+        setElementsExternal = setElements as (elements: Record<string, GraphElement>) => void;
         return (
           <GraphProvider elements={elements} onElementsChange={setElements}>
             <TestComponent />
@@ -275,13 +267,14 @@ describe('GraphProvider Controlled Mode', () => {
       // 10 rapid updates
       act(() => {
         for (let index = 2; index <= 11; index++) {
-          setElementsExternal?.(
-            Array.from({ length: index }, (_, elementIndex) => ({
-                id: String(elementIndex + 1),
-                width: 100 * (elementIndex + 1),
-                height: 100 * (elementIndex + 1),
-              }))
-          );
+          const newElements: Record<string, GraphElement> = {};
+          for (let elementIndex = 1; elementIndex <= index; elementIndex++) {
+            newElements[String(elementIndex)] = {
+              width: 100 * elementIndex,
+              height: 100 * elementIndex,
+            };
+          }
+          setElementsExternal?.(newElements);
         }
       });
 
@@ -296,31 +289,34 @@ describe('GraphProvider Controlled Mode', () => {
 
   describe('Concurrent updates', () => {
     it('should handle concurrent element and link updates', async () => {
-      const initialElements = [{ id: '1', width: 100, height: 100 }];
-      const initialLink = new dia.Link({
-        id: 'link1',
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100 },
+      };
+      const initialLink: GraphLink = {
         type: 'standard.Link',
         source: { id: '1' },
         target: { id: '2' },
-      });
+      };
 
       let elementCount = 0;
       let linkCount = 0;
 
       function TestComponent() {
-        elementCount = useElements((items) => items.length);
-        linkCount = useLinks((items) => items.length);
+        elementCount = useElements((items) => Object.keys(items).length);
+        linkCount = useLinks((items) => Object.keys(items).length);
         return null;
       }
 
-      let setElementsExternal: ((elements: GraphElement[]) => void) | null = null;
-      let setLinksExternal: ((links: GraphLink[]) => void) | null = null;
+      let setElementsExternal: ((elements: Record<string, GraphElement>) => void) | null = null;
+      let setLinksExternal: ((links: Record<string, GraphLink>) => void) | null = null;
 
       function ControlledGraph() {
-        const [elements, setElements] = useState<GraphElement[]>(() => initialElements);
-        const [links, setLinks] = useState<GraphLink[]>(() => [mapLinkFromGraph(initialLink)]);
-        setElementsExternal = setElements as (elements: GraphElement[]) => void;
-        setLinksExternal = setLinks as (links: GraphLink[]) => void;
+        const [elements, setElements] = useState<Record<string, GraphElement>>(() => initialElements);
+        const [links, setLinks] = useState<Record<string, GraphLink>>(() => ({
+          'link1': initialLink,
+        }));
+        setElementsExternal = setElements as (elements: Record<string, GraphElement>) => void;
+        setLinksExternal = setLinks as (links: Record<string, GraphLink>) => void;
         return (
           <GraphProvider
             elements={elements}
@@ -342,30 +338,22 @@ describe('GraphProvider Controlled Mode', () => {
 
       // Concurrent updates
       act(() => {
-        setElementsExternal?.(
-          [
-            { id: '1', width: 100, height: 100 },
-            { id: '2', width: 200, height: 200 },
-          ]
-        );
-        setLinksExternal?.([
-          mapLinkFromGraph(
-            new dia.Link({
-              id: 'link1',
-              type: 'standard.Link',
-              source: { id: '1' },
-              target: { id: '2' },
-            })
-          ),
-          mapLinkFromGraph(
-            new dia.Link({
-              id: 'link2',
-              type: 'standard.Link',
-              source: { id: '2' },
-              target: { id: '1' },
-            })
-          ),
-        ]);
+        setElementsExternal?.({
+          '1': { width: 100, height: 100 },
+          '2': { width: 200, height: 200 },
+        });
+        setLinksExternal?.({
+          'link1': {
+            type: 'standard.Link',
+            source: { id: '1' },
+            target: { id: '2' },
+          },
+          'link2': {
+            type: 'standard.Link',
+            source: { id: '2' },
+            target: { id: '1' },
+          },
+        });
       });
 
       await waitFor(
@@ -378,28 +366,32 @@ describe('GraphProvider Controlled Mode', () => {
     });
 
     it('should handle multiple rapid updates with callbacks', async () => {
-      const initialElements = [{ id: '1', width: 100, height: 100 }];
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100 },
+      };
 
       let elementCount = 0;
 
       function TestComponent() {
-        const count = useElements((items) => items.length);
+        const count = useElements((items) => Object.keys(items).length);
         elementCount = count;
         return null;
       }
 
       function ControlledGraph() {
-        const [elements, setElements] = useState<GraphElement[]>(() => initialElements);
+        const [elements, setElements] = useState<Record<string, GraphElement>>(() => initialElements);
 
         const handleAddElement = useCallback(() => {
-          setElements((previous) => [
-            ...previous,
-            {
-              id: String(previous.length + 1),
-              width: 100 * (previous.length + 1),
-              height: 100 * (previous.length + 1),
-            },
-          ]);
+          setElements((previous) => {
+            const newId = String(Object.keys(previous).length + 1);
+            return {
+              ...previous,
+              [newId]: {
+                width: 100 * (Object.keys(previous).length + 1),
+                height: 100 * (Object.keys(previous).length + 1),
+              },
+            };
+          });
         }, []);
 
         return (
@@ -437,10 +429,12 @@ describe('GraphProvider Controlled Mode', () => {
 
   describe('User interaction sync back to React state', () => {
     it('should sync graph changes back to React state in controlled mode', async () => {
-      const initialElements = [{ id: '1', width: 100, height: 100 }];
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100 },
+      };
 
-      let reactStateElements: GraphElement[] = [];
-      let storeElements: GraphElement[] = [];
+      let reactStateElements: Record<string, GraphElement> = {};
+      let storeElements: Record<string, GraphElement> = {};
 
       function TestComponent() {
         storeElements = useElements((items) => items);
@@ -448,7 +442,7 @@ describe('GraphProvider Controlled Mode', () => {
       }
 
       function ControlledGraph() {
-        const [elements, setElements] = useState<GraphElement[]>(() => initialElements);
+        const [elements, setElements] = useState<Record<string, GraphElement>>(() => initialElements);
         reactStateElements = elements;
 
         return (
@@ -484,8 +478,8 @@ describe('GraphProvider Controlled Mode', () => {
       const { getByRole } = render(<ControlledGraph />);
 
       await waitFor(() => {
-        expect(reactStateElements.length).toBe(1);
-        expect(storeElements.length).toBe(1);
+        expect(Object.keys(reactStateElements).length).toBe(1);
+        expect(Object.keys(storeElements).length).toBe(1);
       });
 
       // Simulate user interaction
@@ -496,22 +490,24 @@ describe('GraphProvider Controlled Mode', () => {
       // Graph change should sync back to React state
       await waitFor(
         () => {
-          expect(reactStateElements.length).toBe(2);
-          expect(storeElements.length).toBe(2);
-          expect(reactStateElements.some((element) => element.id === '2')).toBe(true);
-          expect(storeElements.some((element) => element.id === '2')).toBe(true);
+          expect(Object.keys(reactStateElements).length).toBe(2);
+          expect(Object.keys(storeElements).length).toBe(2);
+          expect(reactStateElements['2']).toBeDefined();
+          expect(storeElements['2']).toBeDefined();
         },
         { timeout: 3000 }
       );
     });
 
     it('should handle element position changes from user interaction', async () => {
-      const initialElements = [{ id: '1', width: 100, height: 100, x: 0, y: 0 }];
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100, x: 0, y: 0 },
+      };
 
-      let reactStateElements: GraphElement[] = [];
+      let reactStateElements: Record<string, GraphElement> = {};
 
       function ControlledGraph() {
-        const [elements, setElements] = useState<GraphElement[]>(() => initialElements);
+        const [elements, setElements] = useState<Record<string, GraphElement>>(() => initialElements);
         reactStateElements = elements;
 
         return (
@@ -542,9 +538,9 @@ describe('GraphProvider Controlled Mode', () => {
       const { getByRole } = render(<ControlledGraph />);
 
       await waitFor(() => {
-        expect(reactStateElements.length).toBe(1);
-        expect(reactStateElements[0]?.x).toBe(0);
-        expect(reactStateElements[0]?.y).toBe(0);
+        expect(Object.keys(reactStateElements).length).toBe(1);
+        expect(reactStateElements['1']?.x).toBe(0);
+        expect(reactStateElements['1']?.y).toBe(0);
       });
 
       // Simulate user interaction
@@ -555,9 +551,9 @@ describe('GraphProvider Controlled Mode', () => {
       // Graph change should sync back to React state
       await waitFor(
         () => {
-          expect(reactStateElements.length).toBe(1);
-          expect(reactStateElements[0]?.x).toBe(100);
-          expect(reactStateElements[0]?.y).toBe(100);
+          expect(Object.keys(reactStateElements).length).toBe(1);
+          expect(reactStateElements['1']?.x).toBe(100);
+          expect(reactStateElements['1']?.y).toBe(100);
         },
         { timeout: 3000 }
       );
@@ -565,21 +561,23 @@ describe('GraphProvider Controlled Mode', () => {
   });
 
   describe('Edge cases', () => {
-    it('should handle empty arrays correctly', async () => {
-      const initialElements = [{ id: '1', width: 100, height: 100 }];
+    it('should handle empty records correctly', async () => {
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100 },
+      };
 
       let elementCount = 0;
 
       function TestComponent() {
-        elementCount = useElements((items) => items.length);
+        elementCount = useElements((items) => Object.keys(items).length);
         return null;
       }
 
-      let setElementsExternal: ((elements: GraphElement[]) => void) | null = null;
+      let setElementsExternal: ((elements: Record<string, GraphElement>) => void) | null = null;
 
       function ControlledGraph() {
-        const [elements, setElements] = useState<GraphElement[]>(() => initialElements);
-        setElementsExternal = setElements as (elements: GraphElement[]) => void;
+        const [elements, setElements] = useState<Record<string, GraphElement>>(() => initialElements);
+        setElementsExternal = setElements as (elements: Record<string, GraphElement>) => void;
         return (
           <GraphProvider elements={elements} onElementsChange={setElements}>
             <TestComponent />
@@ -595,7 +593,7 @@ describe('GraphProvider Controlled Mode', () => {
 
       // Clear all elements
       act(() => {
-        setElementsExternal?.([]);
+        setElementsExternal?.({});
       });
 
       await waitFor(() => {
@@ -604,12 +602,10 @@ describe('GraphProvider Controlled Mode', () => {
 
       // Add elements back
       act(() => {
-        setElementsExternal?.(
-          [
-            { id: '1', width: 100, height: 100 },
-            { id: '2', width: 200, height: 200 },
-          ]
-        );
+        setElementsExternal?.({
+          '1': { width: 100, height: 100 },
+          '2': { width: 200, height: 200 },
+        });
       });
 
       await waitFor(() => {
@@ -622,14 +618,14 @@ describe('GraphProvider Controlled Mode', () => {
       let linkCount = 0;
 
       function TestComponent() {
-        elementCount = useElements((items) => items.length);
-        linkCount = useLinks((items) => items.length);
+        elementCount = useElements((items) => Object.keys(items).length);
+        linkCount = useLinks((items) => Object.keys(items).length);
         return null;
       }
 
       function ControlledGraph() {
-        const [elements, setElements] = useState<GraphElement[]>([]);
-        const [links, setLinks] = useState<GraphLink[]>([]);
+        const [elements, setElements] = useState<Record<string, GraphElement>>({});
+        const [links, setLinks] = useState<Record<string, GraphLink>>({});
         return (
           <GraphProvider
             elements={elements}
diff --git a/packages/joint-react/src/components/paper/__tests__/graph-provider-coverage.test.tsx b/packages/joint-react/src/components/paper/__tests__/graph-provider-coverage.test.tsx
index 96be297c8..d182d0865 100644
--- a/packages/joint-react/src/components/paper/__tests__/graph-provider-coverage.test.tsx
+++ b/packages/joint-react/src/components/paper/__tests__/graph-provider-coverage.test.tsx
@@ -6,7 +6,6 @@ import { dia } from '@joint/core';
 import { useElements, useLinks } from '../../../hooks';
 import type { GraphElement } from '../../../types/element-types';
 import type { GraphLink } from '../../../types/link-types';
-import { mapLinkFromGraph } from '../../../utils/cell/cell-utilities';
 import { GraphProvider } from '../../graph/graph-provider';
 import { GraphStore } from '../../../store';
 
@@ -16,12 +15,12 @@ describe('GraphProvider Coverage Tests', () => {
       let elementCount = 0;
 
       function TestComponent() {
-        elementCount = useElements((items) => items.length);
+        elementCount = useElements((items) => Object.keys(items).length);
         return null;
       }
 
       function ControlledGraph() {
-        const [elements, setElements] = useState<GraphElement[]>([]);
+        const [elements, setElements] = useState<Record<string, GraphElement>>({});
         return (
           <GraphProvider elements={elements} onElementsChange={setElements}>
             <TestComponent />
@@ -40,12 +39,12 @@ describe('GraphProvider Coverage Tests', () => {
       let linkCount = 0;
 
       function TestComponent() {
-        linkCount = useLinks((items) => items.length);
+        linkCount = useLinks((items) => Object.keys(items).length);
         return null;
       }
 
       function ControlledGraph() {
-        const [links, setLinks] = useState<GraphLink[]>([]);
+        const [links, setLinks] = useState<Record<string, GraphLink>>({});
         return (
           <GraphProvider links={links} onLinksChange={setLinks}>
             <TestComponent />
@@ -61,21 +60,21 @@ describe('GraphProvider Coverage Tests', () => {
     });
 
     it('should handle only elements controlled (not links)', async () => {
-      const initialElements = [
-        { id: '1', width: 100, height: 100, type: 'ReactElement' },
-      ];
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100, type: 'ReactElement' },
+      };
 
       let elementCount = 0;
       let linkCount = 0;
 
       function TestComponent() {
-        elementCount = useElements((items) => items.length);
-        linkCount = useLinks((items) => items.length);
+        elementCount = useElements((items) => Object.keys(items).length);
+        linkCount = useLinks((items) => Object.keys(items).length);
         return null;
       }
 
       function ControlledGraph() {
-        const [elements, setElements] = useState<GraphElement[]>(initialElements);
+        const [elements, setElements] = useState<Record<string, GraphElement>>(initialElements);
         return (
           <GraphProvider elements={elements} onElementsChange={setElements}>
             <TestComponent />
@@ -92,24 +91,25 @@ describe('GraphProvider Coverage Tests', () => {
     });
 
     it('should handle only links controlled (not elements)', async () => {
-      const initialLink = new dia.Link({
-        id: 'link1',
+      const initialLink: GraphLink = {
         type: 'standard.Link',
         source: { id: '1' },
         target: { id: '2' },
-      });
+      };
 
       let elementCount = 0;
       let linkCount = 0;
 
       function TestComponent() {
-        elementCount = useElements((items) => items.length);
-        linkCount = useLinks((items) => items.length);
+        elementCount = useElements((items) => Object.keys(items).length);
+        linkCount = useLinks((items) => Object.keys(items).length);
         return null;
       }
 
       function ControlledGraph() {
-        const [links, setLinks] = useState<GraphLink[]>(() => [mapLinkFromGraph(initialLink)]);
+        const [links, setLinks] = useState<Record<string, GraphLink>>(() => ({
+          'link1': initialLink,
+        }));
         return (
           <GraphProvider links={links} onLinksChange={setLinks}>
             <TestComponent />
@@ -137,20 +137,20 @@ describe('GraphProvider Coverage Tests', () => {
 
   describe('GraphProvider edge cases', () => {
     it('should handle unmeasured elements (width/height <= 1)', async () => {
-      const unmeasuredElements = [
-        { id: '1', width: 0, height: 0, type: 'ReactElement' },
-        { id: '2', width: 1, height: 1, type: 'ReactElement' },
-      ];
+      const unmeasuredElements: Record<string, GraphElement> = {
+        '1': { width: 0, height: 0, type: 'ReactElement' },
+        '2': { width: 1, height: 1, type: 'ReactElement' },
+      };
 
       let elementCount = 0;
 
       function TestComponent() {
-        elementCount = useElements((items) => items.length);
+        elementCount = useElements((items) => Object.keys(items).length);
         return null;
       }
 
       function ControlledGraph() {
-        const [elements, setElements] = useState<GraphElement[]>(unmeasuredElements);
+        const [elements, setElements] = useState<Record<string, GraphElement>>(unmeasuredElements);
         return (
           <GraphProvider elements={elements} onElementsChange={setElements}>
             <TestComponent />
diff --git a/packages/joint-react/src/components/paper/__tests__/graph-provider.test.tsx b/packages/joint-react/src/components/paper/__tests__/graph-provider.test.tsx
index 3f25333b2..e841c6f29 100644
--- a/packages/joint-react/src/components/paper/__tests__/graph-provider.test.tsx
+++ b/packages/joint-react/src/components/paper/__tests__/graph-provider.test.tsx
@@ -1,13 +1,12 @@
-/* eslint-disable react-perf/jsx-no-new-array-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import React, { createRef, useState, useCallback } from 'react';
 import { act, render, waitFor } from '@testing-library/react';
 import { GraphStoreContext } from '../../../context';
-import { GraphStore } from '../../../store';
+import { GraphStore, DEFAULT_CELL_NAMESPACE } from '../../../store';
 import { dia, shapes } from '@joint/core';
 import { useElements, useLinks } from '../../../hooks';
 import type { GraphElement } from '../../../types/element-types';
 import type { GraphLink } from '../../../types/link-types';
-import { mapLinkFromGraph } from '../../../utils/cell/cell-utilities';
 import { GraphProvider } from '../../graph/graph-provider';
 import { Paper } from '../../paper/paper';
 import type { RenderLink } from '../../paper/paper.types';
@@ -42,25 +41,24 @@ describe('graph', () => {
   });
 
   it('should render graph provider with links and elements', async () => {
-    const elements = [
-      {
+    const elements: Record<string, GraphElement> = {
+      'element1': {
         width: 100,
         height: 100,
-        id: 'element1',
       },
-    ];
-    const link = new dia.Link({ id: 'link1', type: 'standard.Link', source: { id: 'element1' } });
+    };
+    const link: GraphLink = { type: 'standard.Link', source: { id: 'element1' }, target: {} };
     let linkCount = 0;
     let elementCount = 0;
     function TestComponent() {
-      linkCount = useElements((items) => items.length);
+      linkCount = useElements((items) => Object.keys(items).length);
       elementCount = useLinks((items) => {
-        return items.length;
+        return Object.keys(items).length;
       });
       return null;
     }
     render(
-      <GraphProvider elements={elements} links={[mapLinkFromGraph(link)]}>
+      <GraphProvider elements={elements} links={{ 'link1': link }}>
         <TestComponent />
       </GraphProvider>
     );
@@ -71,14 +69,14 @@ describe('graph', () => {
     });
   });
   it('should add elements and links after initial load and useElements and useLinks should catch them', async () => {
-    const graph = new dia.Graph();
+    const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
     let linkCount = 0;
     let elementCount = 0;
     // eslint-disable-next-line sonarjs/no-identical-functions
     function TestComponent() {
-      linkCount = useElements((items) => items.length);
+      linkCount = useElements((items) => Object.keys(items).length);
       elementCount = useLinks((items) => {
-        return items.length;
+        return Object.keys(items).length;
       });
       return null;
     }
@@ -93,27 +91,32 @@ describe('graph', () => {
       expect(elementCount).toBe(0);
     });
 
-    act(() => {
+    await act(async () => {
       graph.addCells([
         new dia.Element({ id: 'element1', type: 'standard.Rectangle' }),
         new dia.Link({ id: 'link1', type: 'standard.Link', source: { id: 'element1' } }),
       ]);
     });
 
+    // Allow multiple scheduler ticks to flush
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    });
+
     await waitFor(() => {
       expect(linkCount).toBe(1);
       expect(elementCount).toBe(1);
-    });
+    }, { timeout: 2000 });
   });
 
   it('should initialize with default elements', async () => {
-    const elements = [
-      { width: 100, height: 100, id: 'element1' },
-      { width: 200, height: 200, id: 'element2' },
-    ];
+    const elements: Record<string, GraphElement> = {
+      'element1': { width: 100, height: 100 },
+      'element2': { width: 200, height: 200 },
+    };
     let elementCount = 0;
     function TestComponent() {
-      elementCount = useElements((items) => items.length);
+      elementCount = useElements((items) => Object.keys(items).length);
       return null;
     }
     render(
@@ -147,7 +150,7 @@ describe('graph', () => {
     const graph = new dia.Graph({}, { cellNamespace: shapes });
     const cell = new dia.Element({ id: 'element1', type: 'standard.Rectangle' });
     graph.addCell(cell);
-    let currentElements: GraphElement[] = [];
+    let currentElements: Record<string, GraphElement> = {};
     function Elements() {
       const elements = useElements();
       currentElements = elements;
@@ -163,7 +166,7 @@ describe('graph', () => {
 
     await waitFor(() => {
       expect(graph.getCells()).toHaveLength(1);
-      expect(currentElements).toHaveLength(1);
+      expect(Object.keys(currentElements)).toHaveLength(1);
       expect(graph.getCell('element1')).toBeDefined();
     });
 
@@ -174,14 +177,14 @@ describe('graph', () => {
     await waitFor(() => {
       expect(graph.getCell('element2')).toBeDefined();
       expect(graph.getCells()).toHaveLength(2);
-      expect(currentElements).toHaveLength(2);
+      expect(Object.keys(currentElements)).toHaveLength(2);
     });
 
     // its external graph, so we do not destroy it
     unmount();
     await waitFor(() => {
       expect(graph.getCells()).toHaveLength(2);
-      expect(currentElements).toHaveLength(2);
+      expect(Object.keys(currentElements)).toHaveLength(2);
     });
   });
 
@@ -190,7 +193,7 @@ describe('graph', () => {
     const store = new GraphStore({ graph });
     const cell = new dia.Element({ id: 'element1', type: 'standard.Rectangle' });
     graph.addCell(cell);
-    let currentElements: GraphElement[] = [];
+    let currentElements: Record<string, GraphElement> = {};
     // eslint-disable-next-line sonarjs/no-identical-functions
     function Elements() {
       const elements = useElements();
@@ -209,7 +212,7 @@ describe('graph', () => {
 
     await waitFor(() => {
       expect(graph.getCells()).toHaveLength(1);
-      expect(currentElements).toHaveLength(1);
+      expect(Object.keys(currentElements)).toHaveLength(1);
     });
 
     act(() => {
@@ -219,39 +222,38 @@ describe('graph', () => {
     await waitFor(() => {
       expect(graph.getCell('element2')).toBeDefined();
       expect(graph.getCells()).toHaveLength(2);
-      expect(currentElements).toHaveLength(2);
+      expect(Object.keys(currentElements)).toHaveLength(2);
     });
 
     // its external graph, so we do not destroy it
     unmount();
     await waitFor(() => {
       expect(graph.getCells()).toHaveLength(2);
-      expect(currentElements).toHaveLength(2);
+      expect(Object.keys(currentElements)).toHaveLength(2);
     });
   });
 
   it('should render graph provider with links and elements - with explicit react type', async () => {
-    const elements = [
-      {
+    const elements: Record<string, GraphElement> = {
+      'element1': {
         width: 100,
         height: 100,
-        id: 'element1',
         type: 'ReactElement',
       },
-    ];
-    const link = new dia.Link({ id: 'link1', type: 'standard.Link', source: { id: 'element1' } });
+    };
+    const link: GraphLink = { type: 'standard.Link', source: { id: 'element1' }, target: {} };
     let linkCount = 0;
     let elementCount = 0;
     // eslint-disable-next-line sonarjs/no-identical-functions
     function TestComponent() {
-      linkCount = useElements((items) => items.length);
+      linkCount = useElements((items) => Object.keys(items).length);
       elementCount = useLinks((items) => {
-        return items.length;
+        return Object.keys(items).length;
       });
       return null;
     }
     render(
-      <GraphProvider elements={elements} links={[mapLinkFromGraph(link)]}>
+      <GraphProvider elements={elements} links={{ 'link1': link }}>
         <TestComponent />
       </GraphProvider>
     );
@@ -263,39 +265,40 @@ describe('graph', () => {
   });
 
   it('should update graph in controlled mode', async () => {
-    const initialElements = [
-      {
+    const initialElements: Record<string, GraphElement> = {
+      'element1': {
         width: 100,
         height: 100,
-        id: 'element1',
         type: 'ReactElement',
       },
-    ];
-    const initialLink = new dia.Link({
-      id: 'link1',
+    };
+    const initialLink: GraphLink = {
       type: 'standard.Link',
       source: { id: 'element1' },
-    });
+      target: {},
+    };
     let linkCount = 0;
     let elementCount = 0;
     function TestComponent() {
       linkCount = useLinks((items) => {
-        return items.length;
+        return Object.keys(items).length;
       });
       elementCount = useElements((items) => {
-        return items.length;
+        return Object.keys(items).length;
       });
       return null;
     }
 
-    let setElementsOutside: ((elements: GraphElement[]) => void) | null = null;
-    let setLinksOutside: ((links: GraphLink[]) => void) | null = null;
+    let setElementsOutside: ((elements: Record<string, GraphElement>) => void) | null = null;
+    let setLinksOutside: ((links: Record<string, GraphLink>) => void) | null = null;
 
     function Graph() {
-      const [elements, setElements] = useState<GraphElement[]>(() => initialElements);
-      const [links, setLinks] = useState<GraphLink[]>(() => [mapLinkFromGraph(initialLink)]);
-      setElementsOutside = setElements as unknown as (elements: GraphElement[]) => void;
-      setLinksOutside = setLinks as unknown as (links: GraphLink[]) => void;
+      const [elements, setElements] = useState<Record<string, GraphElement>>(() => initialElements);
+      const [links, setLinks] = useState<Record<string, GraphLink>>(() => ({
+        'link1': initialLink,
+      }));
+      setElementsOutside = setElements as unknown as (elements: Record<string, GraphElement>) => void;
+      setLinksOutside = setLinks as unknown as (links: Record<string, GraphLink>) => void;
       return (
         <GraphProvider
           elements={elements}
@@ -315,20 +318,18 @@ describe('graph', () => {
     });
 
     act(() => {
-      setElementsOutside?.([
-        {
+      setElementsOutside?.({
+        'element1': {
           width: 100,
           height: 100,
-          id: 'element1',
           type: 'ReactElement',
         },
-        {
+        'element2': {
           width: 10,
           height: 10,
-          id: 'element2',
           type: 'ReactElement',
         },
-      ]);
+      });
     });
 
     await waitFor(() => {
@@ -338,24 +339,18 @@ describe('graph', () => {
 
     // add link
     act(() => {
-      setLinksOutside?.([
-        mapLinkFromGraph(
-          new dia.Link({
-            id: 'link2',
-            type: 'standard.Link',
-            source: { id: 'element1' },
-            target: { id: 'element2' },
-          })
-        ),
-        mapLinkFromGraph(
-          new dia.Link({
-            id: 'link3',
-            type: 'standard.Link',
-            source: { id: 'element1' },
-            target: { id: 'element2' },
-          })
-        ),
-      ]);
+      setLinksOutside?.({
+        'link2': {
+          type: 'standard.Link',
+          source: { id: 'element1' },
+          target: { id: 'element2' },
+        },
+        'link3': {
+          type: 'standard.Link',
+          source: { id: 'element1' },
+          target: { id: 'element2' },
+        },
+      });
     });
 
     await waitFor(() => {
@@ -373,47 +368,43 @@ describe('graph', () => {
   });
 
   it('should pass correct link data to renderLink function', async () => {
-    const elements = [
-      {
-        id: 'element-1',
+    const elements: Record<string, GraphElement> = {
+      'element-1': {
         x: 0,
         y: 0,
         width: 100,
         height: 100,
       },
-      {
-        id: 'element-2',
+      'element-2': {
         x: 200,
         y: 200,
         width: 100,
         height: 100,
       },
-    ];
+    };
 
-    const links: GraphLink[] = [
-      {
-        id: 'link-1',
+    const links: Record<string, GraphLink> = {
+      'link-1': {
         source: 'element-1',
         target: 'element-2',
         type: 'ReactLink',
         z: 1,
       },
-      {
-        id: 'link-2',
+      'link-2': {
         source: 'element-2',
         target: 'element-1',
         type: 'ReactLink',
         z: 2,
         customProperty: 'custom-value',
       },
-    ];
+    };
 
     const receivedLinks: GraphLink[] = [];
 
     function TestComponent() {
       const renderLink: RenderLink = useCallback((link) => {
         receivedLinks.push(link);
-        return <g data-testid={`link-${link.id}`} />;
+        return <g data-testid="link" />;
       }, []);
 
       return (
@@ -437,64 +428,54 @@ describe('graph', () => {
       expect(receivedLinks.length).toBe(2);
     });
 
-    // Verify first link data
-    const link1 = receivedLinks.find((link) => link.id === 'link-1');
+    // Verify link data was passed (links no longer have id property)
+    const link1 = receivedLinks.find((link) => link.source === 'element-1' && link.target === 'element-2');
     expect(link1).toBeDefined();
-    expect(link1?.id).toBe('link-1');
-    expect(link1?.source).toBe('element-1');
-    expect(link1?.target).toBe('element-2');
     expect(link1?.type).toBe('ReactLink');
     expect(link1?.z).toBe(1);
 
-    // Verify second link data
-    const link2 = receivedLinks.find((link) => link.id === 'link-2');
+    const link2 = receivedLinks.find((link) => link.source === 'element-2' && link.target === 'element-1');
     expect(link2).toBeDefined();
-    expect(link2?.id).toBe('link-2');
-    expect(link2?.source).toBe('element-2');
-    expect(link2?.target).toBe('element-1');
     expect(link2?.type).toBe('ReactLink');
     expect(link2?.z).toBe(2);
     expect(link2?.customProperty).toBe('custom-value');
   });
 
   it('should pass updated link data to renderLink when links change', async () => {
-    const elements = [
-      {
-        id: 'element-1',
+    const elements: Record<string, GraphElement> = {
+      'element-1': {
         x: 0,
         y: 0,
         width: 100,
         height: 100,
       },
-      {
-        id: 'element-2',
+      'element-2': {
         x: 200,
         y: 200,
         width: 100,
         height: 100,
       },
-    ];
+    };
 
-    const initialLinks: GraphLink[] = [
-      {
-        id: 'link-1',
+    const initialLinks: Record<string, GraphLink> = {
+      'link-1': {
         source: 'element-1',
         target: 'element-2',
         type: 'ReactLink',
       },
-    ];
+    };
 
     const receivedLinks: GraphLink[] = [];
 
-    let setLinksExternal: ((links: GraphLink[]) => void) | null = null;
+    let setLinksExternal: ((links: Record<string, GraphLink>) => void) | null = null;
 
     function ControlledGraph() {
-      const [links, setLinks] = useState<GraphLink[]>(() => initialLinks);
-      setLinksExternal = setLinks as unknown as (links: GraphLink[]) => void;
+      const [links, setLinks] = useState<Record<string, GraphLink>>(() => initialLinks);
+      setLinksExternal = setLinks as unknown as (links: Record<string, GraphLink>) => void;
 
       const renderLink: RenderLink = useCallback((link) => {
         receivedLinks.push(link);
-        return <g data-testid={`link-${link.id}`} />;
+        return <g data-testid="link" />;
       }, []);
 
       return (
@@ -516,36 +497,34 @@ describe('graph', () => {
       expect(receivedLinks.length).toBeGreaterThanOrEqual(1);
     });
 
-    const initialLink = receivedLinks.find((link) => link.id === 'link-1');
+    // Verify initial link was received
+    const initialLink = receivedLinks.find((link) => link.source === 'element-1' && link.target === 'element-2');
     expect(initialLink).toBeDefined();
-    expect(initialLink?.source).toBe('element-1');
-    expect(initialLink?.target).toBe('element-2');
+    expect(initialLink?.type).toBe('ReactLink');
 
     // Clear received links to track new ones
     receivedLinks.length = 0;
 
     // Update links
     act(() => {
-      setLinksExternal?.([
-        {
-          id: 'link-2',
+      setLinksExternal?.({
+        'link-2': {
           source: 'element-2',
           target: 'element-1',
           type: 'ReactLink',
           customProperty: 'updated-value',
         },
-      ]);
+      });
     });
 
     await waitFor(() => {
       expect(receivedLinks.length).toBeGreaterThanOrEqual(1);
     });
 
-    const updatedLink = receivedLinks.find((link) => link.id === 'link-2');
+    // Verify updated link was received
+    const updatedLink = receivedLinks.find((link) => link.source === 'element-2' && link.target === 'element-1');
     expect(updatedLink).toBeDefined();
-    expect(updatedLink?.id).toBe('link-2');
-    expect(updatedLink?.source).toBe('element-2');
-    expect(updatedLink?.target).toBe('element-1');
+    expect(updatedLink?.type).toBe('ReactLink');
     expect(updatedLink?.customProperty).toBe('updated-value');
   });
 });
diff --git a/packages/joint-react/src/components/paper/__tests__/paper-html-overlay-links.test.tsx b/packages/joint-react/src/components/paper/__tests__/paper-html-overlay-links.test.tsx
index 8d0fb5af3..88c2f7d12 100644
--- a/packages/joint-react/src/components/paper/__tests__/paper-html-overlay-links.test.tsx
+++ b/packages/joint-react/src/components/paper/__tests__/paper-html-overlay-links.test.tsx
@@ -1,24 +1,26 @@
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
-import { render, waitFor, screen } from '@testing-library/react';
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
+import { render, waitFor, screen, act } from '@testing-library/react';
 import '@testing-library/jest-dom';
-import { GraphProvider, Paper, type GraphElement, type GraphLink } from '../../../index';
+import { GraphProvider, Paper, useCellActions, type GraphElement, type GraphLink } from '../../../index';
+import { useCallback } from 'react';
 
 interface TestElement extends GraphElement {
   label: string;
 }
 
-const elements: TestElement[] = [
-  { id: '1', label: 'Hello', x: 100, y: 0, width: 100, height: 50 },
-  { id: '2', label: 'World', x: 100, y: 200, width: 100, height: 50 },
-];
+const elements: Record<string, TestElement> = {
+  '1': { id: '1', label: 'Hello', x: 100, y: 0, width: 100, height: 50 },
+  '2': { id: '2', label: 'World', x: 100, y: 200, width: 100, height: 50 },
+};
 
-const links: GraphLink[] = [
-  {
+const links: Record<string, GraphLink> = {
+  'link-1': {
     id: 'link-1',
     source: '1',
     target: '2',
   },
-];
+};
 
 describe('Paper with useHTMLOverlay and links', () => {
   it('renders links when useHTMLOverlay is enabled', async () => {
@@ -38,15 +40,24 @@ describe('Paper with useHTMLOverlay and links', () => {
     });
 
     await waitFor(() => {
-      // The link should be present with a path element
-      const linkPath = container.querySelector('.joint-type-reactlink path[joint-selector="line"]');
-      expect(linkPath).toBeInTheDocument();
-
-      const d = linkPath?.getAttribute('d');
-      // Link should have a path (jsdom may not fully compute SVG geometry,
-      // so we just verify the path exists and isn't completely empty)
-      expect(d).toBeTruthy();
+      // ReactLink has empty markup (no SVG content), so we just check that
+      // the link view container exists in the DOM
+      // The link view is added by JointJS but ReactLink doesn't render SVG paths
+      const linkView = container.querySelector('.joint-type-reactlink');
+      expect(linkView).toBeInTheDocument();
     });
+
+    // Also verify initial links have valid paths
+    await waitFor(
+      () => {
+        const linkPath = container.querySelector('.joint-link path[joint-selector="line"]');
+        expect(linkPath).toBeInTheDocument();
+        const pathD = linkPath?.getAttribute('d');
+        expect(pathD).toBeTruthy();
+        expect(pathD?.startsWith('M')).toBe(true);
+      },
+      { timeout: 2000 }
+    );
   });
 
   it('renders placeholder rect in SVG element when useHTMLOverlay is enabled', async () => {
@@ -77,4 +88,121 @@ describe('Paper with useHTMLOverlay and links', () => {
       }
     });
   });
+
+  it('renders link with valid path when adding a new link dynamically via useCellActions', async () => {
+    let setLinkAction: (() => void) | null = null;
+
+    function AddLinkButton() {
+      const { set } = useCellActions();
+      setLinkAction = useCallback(() => {
+        set('new-link', {
+          source: '1',
+          target: '2',
+          attrs: {
+            line: { stroke: '#FF0000' },
+          },
+        });
+      }, [set]);
+      return null;
+    }
+
+    const initialElements: Record<string, TestElement> = {
+      '1': { id: '1', label: 'Element1', x: 100, y: 0, width: 100, height: 50 },
+      '2': { id: '2', label: 'Element2', x: 100, y: 200, width: 100, height: 50 },
+    };
+
+    const { container } = render(
+      <GraphProvider elements={initialElements}>
+        <Paper<TestElement>
+          useHTMLOverlay
+          renderElement={({ label }) => <div className="html-node">{label}</div>}
+        />
+        <AddLinkButton />
+      </GraphProvider>
+    );
+
+    // Wait for elements to render
+    await waitFor(() => {
+      expect(screen.getByText('Element1')).toBeInTheDocument();
+      expect(screen.getByText('Element2')).toBeInTheDocument();
+    });
+
+    // Initially there should be no links
+    await waitFor(() => {
+      const linkViews = container.querySelectorAll('.joint-link');
+      expect(linkViews.length).toBe(0);
+    });
+
+    // Add a new link dynamically
+    await act(async () => {
+      setLinkAction?.();
+    });
+
+    // Wait for the link to be rendered
+    await waitFor(
+      () => {
+        const linkViews = container.querySelectorAll('.joint-link');
+        expect(linkViews.length).toBe(1);
+      },
+      { timeout: 2000 }
+    );
+
+    // Verify the link has a valid path (not empty)
+    await waitFor(
+      () => {
+        const linkPath = container.querySelector('.joint-link path[joint-selector="line"]');
+        expect(linkPath).toBeInTheDocument();
+        const pathD = linkPath?.getAttribute('d');
+        // The path should have a valid d attribute (not empty or null)
+        expect(pathD).toBeTruthy();
+        expect(pathD?.length).toBeGreaterThan(0);
+        // A valid path should start with 'M' (moveto command)
+        expect(pathD?.startsWith('M')).toBe(true);
+      },
+      { timeout: 2000 }
+    );
+  });
+
+  it('removes link correctly when using useCellActions.remove', async () => {
+    let removeLinkAction: (() => void) | null = null;
+
+    function RemoveLinkButton() {
+      const { remove } = useCellActions();
+      removeLinkAction = useCallback(() => {
+        remove('link-1');
+      }, [remove]);
+      return null;
+    }
+
+    const { container } = render(
+      <GraphProvider elements={elements} links={links}>
+        <Paper<TestElement>
+          useHTMLOverlay
+          renderElement={({ label }) => <div className="html-node">{label}</div>}
+        />
+        <RemoveLinkButton />
+      </GraphProvider>
+    );
+
+    // Wait for elements and link to render
+    await waitFor(() => {
+      expect(screen.getByText('Hello')).toBeInTheDocument();
+      const linkViews = container.querySelectorAll('.joint-link');
+      expect(linkViews.length).toBe(1);
+    });
+
+    // Remove the link
+    await act(async () => {
+      removeLinkAction?.();
+    });
+
+    // Wait for the link to be removed
+    await waitFor(
+      () => {
+        const linkViews = container.querySelectorAll('.joint-link');
+        expect(linkViews.length).toBe(0);
+      },
+      { timeout: 2000 }
+    );
+  });
 });
diff --git a/packages/joint-react/src/components/paper/__tests__/paper.test.tsx b/packages/joint-react/src/components/paper/__tests__/paper.test.tsx
index 841876a72..440fc3b6a 100644
--- a/packages/joint-react/src/components/paper/__tests__/paper.test.tsx
+++ b/packages/joint-react/src/components/paper/__tests__/paper.test.tsx
@@ -1,4 +1,4 @@
-/* eslint-disable react-perf/jsx-no-new-array-as-prop */
+ 
 /* eslint-disable @eslint-react/web-api/no-leaked-timeout */
 /* eslint-disable react-perf/jsx-no-new-object-as-prop */
 /* eslint-disable sonarjs/no-nested-functions */
@@ -9,17 +9,26 @@ import React from 'react';
 import { useNodeSize } from '../../../hooks/use-node-size';
 import { act, useEffect, useRef, useState, type RefObject } from 'react';
 import type { PaperStore } from '../../../store';
-import { useGraph, usePaperStoreContext } from '../../../hooks';
+import { useGraph, usePaperStoreContext, useCellId } from '../../../hooks';
 import type { GraphElement } from '../../../types/element-types';
 import { GraphProvider } from '../../graph/graph-provider';
 import { Paper } from '../paper';
 
-const elements = [
-  { id: '1', label: 'Node 1', width: 10, height: 10 },
-  { id: '2', label: 'Node 2', width: 10, height: 10 },
-];
+const elements: Record<string, { label: string; width: number; height: number }> = {
+  '1': { label: 'Node 1', width: 10, height: 10 },
+  '2': { label: 'Node 2', width: 10, height: 10 },
+};
+
+function TestNode({ width, height }: Readonly<{ width?: number; height?: number }>) {
+  const id = useCellId();
+  return (
+    <div id={`node-${id}`} style={{ width, height }} className="test-node">
+      {id}
+    </div>
+  );
+}
 
-type Element = (typeof elements)[number];
+type Element = (typeof elements)[keyof typeof elements];
 const WIDTH = 200;
 
 // we need to mock `new ResizeObserver`, to return the size width 50 and height 50 for test purposes
@@ -100,10 +109,10 @@ describe('Paper Component', () => {
 
   it('calls onElementsSizeChange when element sizes change', async () => {
     const onElementsSizeChangeMock = jest.fn();
-    const updatedElements = [
-      { id: '1', label: 'Node 1', width: 100, height: 50 },
-      { id: '2', label: 'Node 2', width: 150, height: 75 },
-    ];
+    const updatedElements: Record<string, { id: string; label: string; width: number; height: number }> = {
+      '1': { id: '1', label: 'Node 1', width: 100, height: 50 },
+      '2': { id: '2', label: 'Node 2', width: 150, height: 75 },
+    };
 
     const { rerender } = render(
       <GraphProvider elements={elements}>
@@ -323,10 +332,10 @@ describe('Paper Component', () => {
 
   it('should set elements and positions via react state, when change it via paper api', async () => {
     // Create elements with initial x/y so they can be synced back
-    const elementsWithPosition = [
-      { id: '1', label: 'Node 1', x: 0, y: 0, width: 10, height: 10 },
-      { id: '2', label: 'Node 2', x: 0, y: 0, width: 10, height: 10 },
-    ];
+    const elementsWithPosition: Record<string, { id: string; label: string; x: number; y: number; width: number; height: number }> = {
+      '1': { id: '1', label: 'Node 1', x: 0, y: 0, width: 10, height: 10 },
+      '2': { id: '2', label: 'Node 2', x: 0, y: 0, width: 10, height: 10 },
+    };
     // eslint-disable-next-line unicorn/consistent-function-scoping
     function UpdatePosition() {
       const graph = useGraph();
@@ -338,10 +347,10 @@ describe('Paper Component', () => {
       }, [graph]);
       return null;
     }
-    let currentOutsideElements: Element[] = [];
+    let currentOutsideElements: Record<string, Element> = {};
     function Content() {
-      const [currentElements, setCurrentElements] = useState<GraphElement[]>(elementsWithPosition);
-      currentOutsideElements = currentElements as Element[];
+      const [currentElements, setCurrentElements] = useState<Record<string, GraphElement>>(elementsWithPosition);
+      currentOutsideElements = currentElements as Record<string, Element>;
       return (
         <GraphProvider elements={currentElements} onElementsChange={setCurrentElements}>
           <Paper<Element> renderElement={() => <div>Test</div>} />
@@ -351,7 +360,7 @@ describe('Paper Component', () => {
     }
     render(<Content />);
     await waitFor(() => {
-      const element1 = currentOutsideElements.find((element) => element.id === '1');
+      const element1 = currentOutsideElements['1'];
       expect(element1).toBeDefined();
       // @ts-expect-error we know it's element
       expect(element1.x).toBe(100);
@@ -361,27 +370,25 @@ describe('Paper Component', () => {
   });
   it('should update elements via react state, and then reflect the changes in the paper', async () => {
     function Content() {
-      const [currentElements, setCurrentElements] = useState<GraphElement[]>(elements);
+      const [currentElements, setCurrentElements] = useState<Record<string, GraphElement>>(elements);
 
       return (
         <GraphProvider elements={currentElements} onElementsChange={setCurrentElements}>
           <Paper<Element>
-            renderElement={({ width, height, id }) => {
-              return (
-                <div id={`node-${id}`} style={{ width, height }} className="test-node">
-                  {id}
-                </div>
-              );
+            renderElement={({ width, height }) => {
+              return <TestNode width={width} height={height} />;
             }}
           />
           <button
             type="button"
             onClick={() => {
-              setCurrentElements((els) =>
-                els.map((element) =>
-                  element.id === '1' ? { ...element, width: 200, height: 200 } : element
-                )
-              );
+              setCurrentElements((els) => {
+                const newEls = { ...els };
+                if (newEls['1']) {
+                  newEls['1'] = { ...newEls['1'], width: 200, height: 200 };
+                }
+                return newEls;
+              });
             }}
           >
             Update Element 1
diff --git a/packages/joint-react/src/components/paper/paper.stories.tsx b/packages/joint-react/src/components/paper/paper.stories.tsx
index 9102c97dc..6f6245287 100644
--- a/packages/joint-react/src/components/paper/paper.stories.tsx
+++ b/packages/joint-react/src/components/paper/paper.stories.tsx
@@ -1,5 +1,5 @@
 /* eslint-disable react-hooks/rules-of-hooks */
-/* eslint-disable react-perf/jsx-no-new-array-as-prop */
+ 
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
 /* eslint-disable react-perf/jsx-no-new-object-as-prop */
 
@@ -359,9 +359,8 @@ export const WithOnClickColorChange: Story = {
     };
     return (
       <GraphProvider
-        areBatchUpdatesDisabled
-        elements={[
-          {
+        elements={{
+          '1': {
             width: 100,
             height: 40,
             id: '1',
@@ -370,7 +369,7 @@ export const WithOnClickColorChange: Story = {
             y: 50,
             hoverColor: 'red',
           } as GraphElement & { label: string; hoverColor: string },
-          {
+          '2': {
             width: 100,
             height: 40,
             id: '2',
@@ -379,9 +378,9 @@ export const WithOnClickColorChange: Story = {
             y: 250,
             hoverColor: 'red',
           } as GraphElement & { label: string; hoverColor: string },
-        ]}
-        links={[
-          {
+        }}
+        links={{
+          'l1': {
             id: 'l1',
             source: '1',
             target: '2',
@@ -391,7 +390,7 @@ export const WithOnClickColorChange: Story = {
               },
             },
           },
-        ]}
+        }}
       >
         <Paper
           id="main"
@@ -446,21 +445,19 @@ export const WithDataWithoutWidthAndHeightAndXAndY: Story = {
     };
     return (
       <GraphProvider
-        areBatchUpdatesDisabled
-        elements={[
-          {
-            id: '1',
+        elements={{
+          '1': {
             label: 'Element 1',
             hoverColor: 'red',
             somethingMine: true,
           } as GraphElement & { label: string; hoverColor: string },
-          { id: '2', label: 'Element 1', hoverColor: 'red' } as GraphElement & {
+          '2': { label: 'Element 1', hoverColor: 'red' } as GraphElement & {
             label: string;
             hoverColor: string;
           },
-        ]}
-        links={[
-          {
+        }}
+        links={{
+          'l1': {
             id: 'l1',
             source: '1',
             target: '2',
@@ -470,7 +467,7 @@ export const WithDataWithoutWidthAndHeightAndXAndY: Story = {
               },
             },
           },
-        ]}
+        }}
       >
         <Paper
           id="main"
diff --git a/packages/joint-react/src/components/paper/paper.tsx b/packages/joint-react/src/components/paper/paper.tsx
index a5128e19a..15fd6b00b 100644
--- a/packages/joint-react/src/components/paper/paper.tsx
+++ b/packages/joint-react/src/components/paper/paper.tsx
@@ -39,8 +39,6 @@ import {
 import { createPortal } from 'react-dom';
 import { handlePaperEvents, PAPER_EVENT_KEYS } from '../../utils/handle-paper-events';
 import type { PaperStore } from '../../store';
-import { ReactElementView } from '../../models/react-element-view';
-import { ReactLinkView } from '../../models/react-link-view';
 import {
   useAreElementsMeasured,
   useGraphInternalStoreSelector,
@@ -114,14 +112,28 @@ function PaperBase<ElementItem extends GraphElement = GraphElement>(
   useDebugValue(elementsState);
   useDebugValue(linksState);
 
+  // Compute element and link IDs once for reuse throughout the component
+  const elementIds = useMemo(() => Object.keys(elementsState), [elementsState]);
+  const linkIds = useMemo(() => Object.keys(linksState), [linksState]);
+
   // Defer rendering for large graphs to improve initial render performance
   // Threshold: only defer if we have more than 100 elements or links
   // Always call useDeferredValue (hooks rules), but only use deferred value when threshold is met
   const deferredElementsStateRaw = useDeferredValue(elementsState);
   const deferredLinksStateRaw = useDeferredValue(linksState);
-  const shouldDefer = elementsState.length > 100 || linksState.length > 100;
+  const shouldDefer = elementIds.length > 100 || linkIds.length > 100;
   const deferredElementsState = shouldDefer ? deferredElementsStateRaw : elementsState;
   const deferredLinksState = shouldDefer ? deferredLinksStateRaw : linksState;
+
+  // Compute deferred IDs for rendering (reuse non-deferred if not deferring)
+  const deferredElementIds = useMemo(
+    () => (shouldDefer ? Object.keys(deferredElementsState) : elementIds),
+    [shouldDefer, deferredElementsState, elementIds]
+  );
+  const deferredLinkIds = useMemo(
+    () => (shouldDefer ? Object.keys(deferredLinksState) : linkIds),
+    [shouldDefer, deferredLinksState, linkIds]
+  );
   const reactId = useId();
   const id = props.id ?? `paper-${reactId}`;
   const { overWrite } = useContext(PaperConfigContext) ?? {};
@@ -247,7 +259,7 @@ function PaperBase<ElementItem extends GraphElement = GraphElement>(
     }
   }, [areElementsMeasured, isReady, onElementsSizeReady, paper]);
 
-  // Whenever elements change (or we’ve just become measured) compare old ↔ new
+  // Whenever elements change (or we've just become measured) compare old ↔ new
   useEffect(() => {
     if (!isReady) return;
     if (!onElementsSizeChange) return;
@@ -256,9 +268,11 @@ function PaperBase<ElementItem extends GraphElement = GraphElement>(
 
     // Build current list of [currWidth, currHeight] to avoid shadowing outer scope variables
     // Use elementsState (not deferred) for accurate size tracking
-    const currentSizes = elementsState.map(
-      ({ width: elementWidth = 0, height: elementHeight = 0 }) => [elementWidth, elementHeight]
-    );
+    // Reuse elementIds computed above for performance
+    const currentSizes = elementIds.map((elementId) => {
+      const element = elementsState[elementId];
+      return [element?.width ?? 0, element?.height ?? 0];
+    });
     const previousSizes = previousSizesRef.current;
     let changed = false;
 
@@ -284,7 +298,7 @@ function PaperBase<ElementItem extends GraphElement = GraphElement>(
     // store for next time
     previousSizesRef.current = currentSizes;
     onElementsSizeChange({ paper, graph: paper.model });
-  }, [areElementsMeasured, elementsState, isReady, onElementsSizeChange, paper]);
+  }, [areElementsMeasured, elementsState, elementIds, isReady, onElementsSizeChange, paper]);
 
   useLayoutEffect(() => {
     if (!paper) {
@@ -315,11 +329,14 @@ function PaperBase<ElementItem extends GraphElement = GraphElement>(
     if (!hasRenderElement) {
       return null;
     }
-    return deferredElementsState.map((elementState) => {
-      if (!elementState.id) {
+
+    return deferredElementIds.map((elementId) => {
+      const elementState = deferredElementsState[elementId];
+      if (!elementState) {
         return null;
       }
-      const elementView = paperElementViews[elementState.id];
+
+      const elementView = paperElementViews[elementId];
       if (!elementView) {
         return null;
       }
@@ -329,13 +346,8 @@ function PaperBase<ElementItem extends GraphElement = GraphElement>(
         return null;
       }
 
-      const isReactElement = elementView instanceof ReactElementView;
-      if (!isReactElement) {
-        return null;
-      }
-
       return (
-        <CellIdContext.Provider key={elementState.id} value={elementState.id}>
+        <CellIdContext.Provider key={elementId} value={elementId}>
           {useHTMLOverlay && HTMLRendererContainer ? (
             <>
               <HTMLElementItem
@@ -343,6 +355,7 @@ function PaperBase<ElementItem extends GraphElement = GraphElement>(
                 portalElement={HTMLRendererContainer}
                 renderElement={renderElement}
                 areElementsMeasured={areElementsMeasured}
+                id={elementId}
               />
               {/* We need to render this element too, its kind of hack - placeholder */}
               <SVGElementItem
@@ -350,6 +363,7 @@ function PaperBase<ElementItem extends GraphElement = GraphElement>(
                 portalElement={SVG as SVGAElement}
                 renderElement={DefaultRectElement}
                 areElementsMeasured={areElementsMeasured}
+                id={elementId}
               />
             </>
           ) : (
@@ -358,6 +372,7 @@ function PaperBase<ElementItem extends GraphElement = GraphElement>(
               portalElement={SVG as SVGAElement}
               renderElement={renderElement}
               areElementsMeasured={areElementsMeasured}
+              id={elementId}
             />
           )}
         </CellIdContext.Provider>
@@ -365,6 +380,7 @@ function PaperBase<ElementItem extends GraphElement = GraphElement>(
     });
   }, [
     hasRenderElement,
+    deferredElementIds,
     deferredElementsState,
     paperElementViews,
     useHTMLOverlay,
@@ -377,12 +393,14 @@ function PaperBase<ElementItem extends GraphElement = GraphElement>(
     if (!hasRenderLink) {
       return null;
     }
-    return deferredLinksState.map((linkState) => {
-      if (!linkState.id) {
+
+    return deferredLinkIds.map((linkId) => {
+      const linkState = deferredLinksState[linkId];
+      if (!linkState) {
         return null;
       }
 
-      const linkView = paperLinkViews[linkState.id];
+      const linkView = paperLinkViews[linkId];
       if (!linkView) {
         return null;
       }
@@ -392,23 +410,17 @@ function PaperBase<ElementItem extends GraphElement = GraphElement>(
         return null;
       }
 
-      const isReactLink = linkView instanceof ReactLinkView;
-
-      if (!isReactLink) {
-        return null;
-      }
-
       if (!renderLink) {
         return null;
       }
 
       return (
-        <CellIdContext.Provider key={linkState.id} value={linkState.id}>
+        <CellIdContext.Provider key={linkId} value={linkId}>
           <LinkItem link={linkState} portalElement={SVG as SVGAElement} renderLink={renderLink} />
         </CellIdContext.Provider>
       );
     });
-  }, [hasRenderLink, deferredLinksState, paperLinkViews, renderLink]);
+  }, [hasRenderLink, deferredLinkIds, deferredLinksState, paperLinkViews, renderLink]);
 
   const content = (
     <>
diff --git a/packages/joint-react/src/components/paper/paper.types.ts b/packages/joint-react/src/components/paper/paper.types.ts
index 71d7254df..379140753 100644
--- a/packages/joint-react/src/components/paper/paper.types.ts
+++ b/packages/joint-react/src/components/paper/paper.types.ts
@@ -11,7 +11,10 @@ export interface OnLoadOptions {
   readonly graph: dia.Graph;
 }
 
-type ReactPaperOptionsBase = OmitWithoutIndexSignature<dia.Paper.Options, 'frozen' | 'defaultLink'>;
+type ReactPaperOptionsBase = OmitWithoutIndexSignature<
+  dia.Paper.Options,
+  'frozen' | 'defaultLink' | 'autoFreeze' | 'viewManagement'
+>;
 export interface ReactPaperOptions extends ReactPaperOptionsBase {
   /**
    * Default link for the paper - for example if there is new element added, this will be used as default.
@@ -26,9 +29,7 @@ export type RenderElement<ElementItem extends GraphElement = GraphElement> = (
   element: ElementItem
 ) => ReactNode;
 
-export type RenderLink<LinkItem extends GraphLink = GraphLink> = (
-  link: LinkItem
-) => ReactNode;
+export type RenderLink<LinkItem extends GraphLink = GraphLink> = (link: LinkItem) => ReactNode;
 
 /**
  * The props for the Paper component. Extend the `dia.Paper.Options` interface.
@@ -69,10 +70,10 @@ export interface PaperProps<ElementItem extends GraphElement = GraphElement>
   readonly renderElement?: RenderElement<ElementItem>;
   /**
    * A function that renders the link.
-   * 
+   *
    * Note: JointJS works with SVG by default, so `renderLink` content is appended inside an SVG node.
    * To render HTML elements, use an SVG `foreignObject`.
-   * 
+   *
    * This is called when the link data changes.
    * @example
    * Example with `global component`:
diff --git a/packages/joint-react/src/components/paper/render-element/paper-element-item.tsx b/packages/joint-react/src/components/paper/render-element/paper-element-item.tsx
index 43e52cb4a..86baf4454 100644
--- a/packages/joint-react/src/components/paper/render-element/paper-element-item.tsx
+++ b/packages/joint-react/src/components/paper/render-element/paper-element-item.tsx
@@ -1,11 +1,10 @@
 import { useLayoutEffect, useMemo, type CSSProperties, type ReactNode } from 'react';
 import { createPortal } from 'react-dom';
-import type { CellWithId } from '../../../types/cell.types';
 import typedMemo from '../../../utils/typed-react';
 import type { GraphElement } from '../../../types/element-types';
 import { useGraphStore, useNodeLayout } from '../../../hooks';
 
-export interface ElementItemProps<Data extends CellWithId = GraphElement> {
+export interface ElementItemProps<Data extends GraphElement = GraphElement> {
   /**
    * A function that renders the element. It is called every time the element is rendered.
    */
@@ -16,13 +15,14 @@ export interface ElementItemProps<Data extends CellWithId = GraphElement> {
   readonly portalElement: SVGElement | HTMLElement | null;
 
   readonly areElementsMeasured: boolean;
+  readonly id: string;
 }
 
 // eslint-disable-next-line jsdoc/require-jsdoc
 function SVGElementItemComponent<Data extends GraphElement = GraphElement>(
   props: ElementItemProps<Data>
 ) {
-  const { renderElement, portalElement, areElementsMeasured, ...rest } = props;
+  const { renderElement, portalElement, areElementsMeasured, id, ...rest } = props;
   const cell = rest as Data;
   const graphStore = useGraphStore();
 
@@ -31,10 +31,10 @@ function SVGElementItemComponent<Data extends GraphElement = GraphElement>(
       return;
     }
     graphStore.scheduleClearView({
-      cellId: cell.id,
+      cellId: id,
     });
     graphStore.flushPendingUpdates();
-  }, [cell.id, graphStore, areElementsMeasured]);
+  }, [id, graphStore, areElementsMeasured]);
 
   if (!portalElement) {
     return null;
@@ -73,12 +73,11 @@ export const SVGElementItem = typedMemo(SVGElementItemComponent);
 function HTMLElementItemComponent<Data extends GraphElement = GraphElement>(
   props: ElementItemProps<Data>
 ) {
-  const { renderElement, portalElement, areElementsMeasured, ...rest } = props;
+  const { renderElement, portalElement, areElementsMeasured, id, ...rest } = props;
   const cell = rest as Data;
   // we must use renderElement and not cell data, because user can select different data, so then, the width and height do not have to be inside the cell data.
   const element = renderElement(cell);
-  const { width, height, x, y, id } = cell;
-
+  const { width, height, x, y } = cell;
   const graphStore = useGraphStore();
 
   useLayoutEffect(() => {
@@ -86,10 +85,10 @@ function HTMLElementItemComponent<Data extends GraphElement = GraphElement>(
       return;
     }
     graphStore.scheduleClearView({
-      cellId: cell.id,
+      cellId: id,
     });
     graphStore.flushPendingUpdates();
-  }, [cell.id, graphStore, areElementsMeasured]);
+  }, [id, graphStore, areElementsMeasured]);
 
   // WE NEED TO COMPARE WHAT IS CHANGED HERE...
 
@@ -133,14 +132,15 @@ export const HTMLElementItem = typedMemo(HTMLElementItemComponent);
 
 /**
  * Default rectangle element renderer.
- * Renders a blue rectangle with rounded corners using the node's layout data.
+ * Renders a transparent rectangle placeholder using the node's layout data.
  * @group Components
  * @description
- * This component renders a blue rectangle with rounded corners.
+ * This component renders a transparent rectangle placeholder.
  * It uses the `useNodeLayout` hook to get the node's layout data (width and height).
  * @returns The rendered rectangle element.
  */
 export function DefaultRectElement() {
-  const { width, height } = useNodeLayout();
+  const layout = useNodeLayout();
+  const { width, height } = layout;
   return <rect width={width} height={height} fill="transparent" />;
 }
diff --git a/packages/joint-react/src/components/port/__tests__/port-group.test.tsx b/packages/joint-react/src/components/port/__tests__/port-group.test.tsx
index 2cb18a11b..477881067 100644
--- a/packages/joint-react/src/components/port/__tests__/port-group.test.tsx
+++ b/packages/joint-react/src/components/port/__tests__/port-group.test.tsx
@@ -21,15 +21,15 @@ describe('PortGroup cleanup', () => {
       wrapper: paperRenderElementWrapper({
         graphProviderProps: {
           graph,
-          elements: [
-            {
+          elements: {
+            'element-1': {
               id: 'element-1',
               x: 0,
               y: 0,
               width: 100,
               height: 100,
             },
-          ],
+          },
         },
       }),
     };
diff --git a/packages/joint-react/src/components/port/__tests__/port-item.test.tsx b/packages/joint-react/src/components/port/__tests__/port-item.test.tsx
index be039675f..958a68a57 100644
--- a/packages/joint-react/src/components/port/__tests__/port-item.test.tsx
+++ b/packages/joint-react/src/components/port/__tests__/port-item.test.tsx
@@ -22,15 +22,15 @@ describe('PortItem cleanup', () => {
       wrapper: paperRenderElementWrapper({
         graphProviderProps: {
           graph,
-          elements: [
-            {
+          elements: {
+            'element-1': {
               id: 'element-1',
               x: 0,
               y: 0,
               width: 100,
               height: 100,
             },
-          ],
+          },
         },
       }),
     };
diff --git a/packages/joint-react/src/components/port/__tests__/port.test.tsx b/packages/joint-react/src/components/port/__tests__/port.test.tsx
index d8c648e14..6c28f5b27 100644
--- a/packages/joint-react/src/components/port/__tests__/port.test.tsx
+++ b/packages/joint-react/src/components/port/__tests__/port.test.tsx
@@ -1,20 +1,62 @@
-import { render, waitFor } from '@testing-library/react';
+/* eslint-disable sonarjs/no-nested-functions */
+import { render, waitFor, act } from '@testing-library/react';
+import { useState } from 'react';
 import { Port } from '..';
 import { paperRenderElementWrapper } from '../../../utils/test-wrappers';
 import { dia } from '@joint/core';
 import { ReactElement } from '../../../models/react-element';
+import '@testing-library/jest-dom';
 
 describe('port', () => {
+  it('should render port content via portal (portalNode is created)', async () => {
+    const graph = new dia.Graph({}, { cellNamespace: { ReactElement } });
+    const { container } = render(
+      <Port.Item id="port-test" x={10} y={11}>
+        <rect data-testid="port-rect" width={10} height={10} fill="red" />
+      </Port.Item>,
+      {
+        wrapper: paperRenderElementWrapper({
+          graphProviderProps: {
+            graph,
+            elements: {
+              'element-1': {
+                id: 'element-1',
+                width: 100,
+                height: 100,
+              },
+            },
+          },
+        }),
+      }
+    );
+
+    // Wait for the port to be created in the graph
+    await waitFor(() => {
+      const element = graph.getCell('element-1');
+      expect(element?.isElement() && element.hasPort('port-test')).toBe(true);
+    });
+
+    // Wait for the portal node to be created and port content to be rendered
+    await waitFor(
+      () => {
+        // The port's rect should be rendered in the DOM via portal
+        const portRect = container.querySelector('[data-testid="port-rect"]');
+        expect(portRect).toBeInTheDocument();
+      },
+      { timeout: 2000 }
+    );
+  });
+
   it('should check if the port is created on the graph instance properly', async () => {
     const graph = new dia.Graph({}, { cellNamespace: { ReactElement } });
     const wrapper = paperRenderElementWrapper({
       graphProviderProps: {
         graph,
-        elements: [
-          {
+        elements: {
+          'element-1': {
             id: 'element-1',
           },
-        ],
+        },
       },
     });
     render(
@@ -49,11 +91,11 @@ describe('port', () => {
     const wrapper = paperRenderElementWrapper({
       graphProviderProps: {
         graph,
-        elements: [
-          {
+        elements: {
+          'element-1': {
             id: 'element-1',
           },
-        ],
+        },
       },
     });
     render(
@@ -85,4 +127,157 @@ describe('port', () => {
       });
     });
   });
+
+  it('should add ports dynamically without causing infinite loop (Maximum call stack)', async () => {
+    const graph = new dia.Graph({}, { cellNamespace: { ReactElement } });
+
+    // Track how many times addPort is called externally
+    let addPortTrigger: (() => void) | null = null;
+
+    function DynamicPorts() {
+      const [ports, setPorts] = useState([{ id: 'port-1' }]);
+
+       
+      addPortTrigger = () => {
+        setPorts((previous) => [...previous, { id: `port-${previous.length + 1}` }]);
+      };
+
+      return (
+        <Port.Group id="dynamic-group" position="bottom">
+          {ports.map((port, index) => (
+            <Port.Item key={port.id} id={port.id} x={index * 50}>
+              <rect data-testid={`port-rect-${port.id}`} width={10} height={10} fill="red" />
+            </Port.Item>
+          ))}
+        </Port.Group>
+      );
+    }
+
+    const wrapper = paperRenderElementWrapper({
+      graphProviderProps: {
+        graph,
+        elements: {
+          'element-1': {
+            id: 'element-1',
+            width: 200,
+            height: 100,
+          },
+        },
+      },
+    });
+
+    const { container } = render(<DynamicPorts />, { wrapper });
+
+    // Wait for initial port to be created
+    await waitFor(() => {
+      const element = graph.getCell('element-1');
+      expect(element?.isElement() && element.hasPort('port-1')).toBe(true);
+    });
+
+    // Wait for initial port to render via portal
+    await waitFor(
+      () => {
+        const portRect = container.querySelector('[data-testid="port-rect-port-1"]');
+        expect(portRect).toBeInTheDocument();
+      },
+      { timeout: 2000 }
+    );
+
+    // Add a second port dynamically - this should NOT cause Maximum call stack exceeded
+    act(() => {
+      addPortTrigger?.();
+    });
+
+    // Wait for second port to be created in the graph
+    await waitFor(
+      () => {
+        const element = graph.getCell('element-1');
+        expect(element?.isElement() && element.hasPort('port-2')).toBe(true);
+      },
+      { timeout: 2000 }
+    );
+
+    // Wait for second port to render via portal
+    await waitFor(
+      () => {
+        const portRect = container.querySelector('[data-testid="port-rect-port-2"]');
+        expect(portRect).toBeInTheDocument();
+      },
+      { timeout: 2000 }
+    );
+
+    // Add a third port to ensure no infinite loop
+    act(() => {
+      addPortTrigger?.();
+    });
+
+    await waitFor(
+      () => {
+        const element = graph.getCell('element-1');
+        expect(element?.isElement() && element.hasPort('port-3')).toBe(true);
+      },
+      { timeout: 2000 }
+    );
+
+    await waitFor(
+      () => {
+        const portRect = container.querySelector('[data-testid="port-rect-port-3"]');
+        expect(portRect).toBeInTheDocument();
+      },
+      { timeout: 2000 }
+    );
+  });
+
+  it('should position ports at bottom when position="bottom" is set', async () => {
+    const graph = new dia.Graph({}, { cellNamespace: { ReactElement } });
+
+    const wrapper = paperRenderElementWrapper({
+      graphProviderProps: {
+        graph,
+        elements: {
+          'element-1': {
+            id: 'element-1',
+            width: 200,
+            height: 100,
+            x: 0,
+            y: 0,
+          },
+        },
+      },
+    });
+
+    render(
+      <Port.Group id="bottom-group" position="bottom">
+        <Port.Item id="bottom-port">
+          <rect data-testid="bottom-port-rect" width={10} height={10} fill="red" />
+        </Port.Item>
+      </Port.Group>,
+      { wrapper }
+    );
+
+    // Wait for port to be created
+    await waitFor(() => {
+      const element = graph.getCell('element-1');
+      expect(element?.isElement() && element.hasPort('bottom-port')).toBe(true);
+    });
+
+    // Wait for port to render
+    await waitFor(
+      () => {
+        const portRect = document.querySelector('[data-testid="bottom-port-rect"]');
+        expect(portRect).toBeInTheDocument();
+      },
+      { timeout: 2000 }
+    );
+
+    // Check port group position is set correctly
+    await waitFor(() => {
+      const element = graph.getCell('element-1') as dia.Element;
+      const portGroups = element.get('ports')?.groups;
+      const position = portGroups?.['bottom-group']?.position;
+      // Position can be a string or an object with name property
+      const positionName = typeof position === 'string' ? position : position?.name;
+      expect(positionName).toBe('bottom');
+    });
+  });
 });
diff --git a/packages/joint-react/src/components/port/port-group.stories.tsx b/packages/joint-react/src/components/port/port-group.stories.tsx
index 22850600c..7d8e84d2b 100644
--- a/packages/joint-react/src/components/port/port-group.stories.tsx
+++ b/packages/joint-react/src/components/port/port-group.stories.tsx
@@ -10,27 +10,37 @@ import { getAPILink } from '../../stories/utils/get-api-documentation-link';
 import { makeRootDocumentation, makeStory } from '../../stories/utils/make-story';
 import { Paper } from '../paper/paper';
 
-const initialElements = [
-  {
+const initialElements: Record<string, {
+  id: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}> = {
+  '1': {
     id: '1',
     x: 100,
     y: 20,
     width: 100,
     height: 50,
   },
-  {
+  '2': {
     id: '2',
     x: 200,
     y: 250,
     width: 100,
     height: 50,
   },
-];
+};
 
-const initialLinks = [
-  {
+const initialLinks: Record<string, {
+  id: string;
+  target: { id: string; port: string };
+  source: { id: string; port: string };
+  attrs: { line: { stroke: string } };
+}> = {
+  'e1-2': {
     id: 'e1-2',
-
     target: {
       id: '2',
       port: 'port-one',
@@ -45,7 +55,7 @@ const initialLinks = [
       },
     },
   },
-];
+};
 
 export type Story = StoryObj<typeof PortGroup>;
 const API_URL = getAPILink('Port.Group', 'variables');
diff --git a/packages/joint-react/src/components/port/port-item.stories.tsx b/packages/joint-react/src/components/port/port-item.stories.tsx
index 6568b88a3..3e51c1bd7 100644
--- a/packages/joint-react/src/components/port/port-item.stories.tsx
+++ b/packages/joint-react/src/components/port/port-item.stories.tsx
@@ -9,21 +9,30 @@ import { getAPILink } from '../../stories/utils/get-api-documentation-link';
 import { makeRootDocumentation, makeStory } from '../../stories/utils/make-story';
 import { Paper } from '../paper/paper';
 
-const initialElements = [
-  {
+const initialElements: Record<string, {
+  id: string;
+  x: number;
+  y: number;
+}> = {
+  '1': {
     id: '1',
     x: 100,
     y: 20,
   },
-  {
+  '2': {
     id: '2',
     x: 200,
     y: 250,
   },
-];
+};
 
-const initialLinks = [
-  {
+const initialLinks: Record<string, {
+  id: string;
+  source: { id: string; port: string };
+  target: { id: string; port: string };
+  attrs: { line: { stroke: string } };
+}> = {
+  'link-1': {
     id: 'link-1',
     source: {
       id: '1',
@@ -39,7 +48,7 @@ const initialLinks = [
       },
     },
   },
-];
+};
 
 export type Story = StoryObj<typeof Port.Item>;
 const API_URL = getAPILink('Port.Item', 'variables');
@@ -62,7 +71,7 @@ function PaperDecorator(Story: React.FC) {
   return (
     <GraphProvider elements={initialElements} links={initialLinks}>
       <Paper
-        defaultLink={initialLinks[0]}
+        defaultLink={initialLinks['link-1']}
         className={PAPER_CLASSNAME}
         width={'100%'}
         height={350}
diff --git a/packages/joint-react/src/hooks/__tests__/use-cell-actions.test.tsx b/packages/joint-react/src/hooks/__tests__/use-cell-actions.test.tsx
index 3e1f6d34f..68c8de797 100644
--- a/packages/joint-react/src/hooks/__tests__/use-cell-actions.test.tsx
+++ b/packages/joint-react/src/hooks/__tests__/use-cell-actions.test.tsx
@@ -1,5 +1,3 @@
-/* eslint-disable @typescript-eslint/no-shadow */
-/* eslint-disable no-shadow */
 import { renderHook, waitFor } from '@testing-library/react';
 import { graphProviderWrapper } from '../../utils/test-wrappers';
 import { useGraph } from '../use-graph';
@@ -8,31 +6,33 @@ import { useElements } from '../use-elements';
 import { act } from 'react';
 import type { ReducerType } from '@reduxjs/toolkit';
 import { useLinks } from '../use-links';
+import { useNodeLayout } from '../use-node-layout';
 
 describe('useCellActions', () => {
   // @ts-expect-error - We setup in beforeEach
   let wrapper: ReducerType<React.JSX.Element, unknown>;
   beforeEach(() => {
     wrapper = graphProviderWrapper({
-      elements: [
-        {
-          id: '1',
+      elements: {
+        '1': {
+          x: 50,
+          y: 50,
           width: 97,
           height: 99,
         },
-        {
-          id: '2',
+        '2': {
+          x: 200,
+          y: 200,
           width: 97,
           height: 99,
         },
-      ],
-      links: [
-        {
-          id: '3',
+      },
+      links: {
+        '3': {
           source: '1',
           target: '2',
         },
-      ],
+      },
     });
   });
 
@@ -55,32 +55,32 @@ describe('useCellActions', () => {
       expect(renders).toHaveBeenCalledTimes(1);
       const { graph } = result.current;
       expect(graph.getElements().length).toBe(2);
-      expect(result.current.reactElementsSizeCheck.length).toBe(2);
-      expect(result.current.reactElementsSizeCheck[0].width).toBe(97);
+      expect(Object.keys(result.current.reactElementsSizeCheck).length).toBe(2);
+      expect(result.current.reactElementsSizeCheck['1'].width).toBe(97);
     });
 
     act(() => {
-      result.current.actions.set({ id: '1', width: 1000 });
+      result.current.actions.set('1', { width: 1000 });
     });
 
     // check if the element is set in the graph
     await waitFor(() => {
       const { graph } = result.current;
       expect(graph.getElements().length).toBe(2);
-      expect(result.current.reactElementsSizeCheck.length).toBe(2);
-      expect(result.current.reactElementsSizeCheck[0].width).toBe(1000);
+      expect(Object.keys(result.current.reactElementsSizeCheck).length).toBe(2);
+      expect(result.current.reactElementsSizeCheck['1'].width).toBe(1000);
     });
 
     act(() => {
-      result.current.actions.set({ id: '10', width: 999 });
+      result.current.actions.set('10', { width: 999 });
     });
 
     // check if the element is set in the graph
     await waitFor(() => {
       const { graph } = result.current;
       expect(graph.getElements().length).toBe(3);
-      expect(result.current.reactElementsSizeCheck.length).toBe(3);
-      expect(result.current.reactElementsSizeCheck[2].width).toBe(999);
+      expect(Object.keys(result.current.reactElementsSizeCheck).length).toBe(3);
+      expect(result.current.reactElementsSizeCheck['10'].width).toBe(999);
     });
 
     act(() => {
@@ -91,8 +91,8 @@ describe('useCellActions', () => {
     await waitFor(() => {
       const { graph } = result.current;
       expect(graph.getElements().length).toBe(3);
-      expect(result.current.reactElementsSizeCheck.length).toBe(3);
-      expect(result.current.reactElementsSizeCheck[1].width).toBe(500);
+      expect(Object.keys(result.current.reactElementsSizeCheck).length).toBe(3);
+      expect(result.current.reactElementsSizeCheck['2'].width).toBe(500);
     });
 
     // remove element
@@ -103,18 +103,16 @@ describe('useCellActions', () => {
     await waitFor(() => {
       const { graph } = result.current;
       expect(graph.getElements().length).toBe(2);
-      expect(result.current.reactElementsSizeCheck.length).toBe(2);
-      expect(
-        result.current.reactElementsSizeCheck.find((element) => element.id === '1')
-      ).toBeUndefined();
+      expect(Object.keys(result.current.reactElementsSizeCheck).length).toBe(2);
+      expect(result.current.reactElementsSizeCheck['1']).toBeUndefined();
     });
 
     // check if other element is still there
     await waitFor(() => {
       const { graph } = result.current;
       expect(graph.getElements().length).toBe(2);
-      expect(result.current.reactElementsSizeCheck.length).toBe(2);
-      const element = result.current.reactElementsSizeCheck.find((element) => element.id === '2');
+      expect(Object.keys(result.current.reactElementsSizeCheck).length).toBe(2);
+      const element = result.current.reactElementsSizeCheck['2'];
       expect(element).toBeDefined();
       expect(element?.width).toBe(500);
     });
@@ -142,8 +140,7 @@ describe('useCellActions', () => {
     });
 
     act(() => {
-      result.current.actions.set({
-        id: '3',
+      result.current.actions.set('3', {
         source: { id: '1' },
         target: { id: '2' },
         attrs: {
@@ -157,8 +154,8 @@ describe('useCellActions', () => {
       const { graph } = result.current;
       expect(graph.getLinks().length).toBe(1);
       const link = graph.getCell('3');
-      expect(result.current.links.length).toBe(1);
-      expect(result.current.links[0].id).toBe('3');
+      expect(Object.keys(result.current.links).length).toBe(1);
+      expect(result.current.links['3'].source).toBeDefined();
       expect(link).toBeDefined();
       expect(link?.get('attrs')?.line?.stroke ?? '').toBe('#001DFF');
     });
@@ -178,16 +175,15 @@ describe('useCellActions', () => {
       const { graph } = result.current;
       expect(graph.getLinks().length).toBe(1);
       const link = graph.getCell('3');
-      expect(result.current.links.length).toBe(1);
-      expect(result.current.links[0].id).toBe('3');
+      expect(Object.keys(result.current.links).length).toBe(1);
+      expect(result.current.links['3'].source).toBeDefined();
       expect(link).toBeDefined();
       expect(link?.get('attrs')?.line?.stroke ?? '').toBe('#FF0000');
     });
 
     // add new link
     act(() => {
-      result.current.actions.set({
-        id: '30',
+      result.current.actions.set('30', {
         source: { id: '2' },
         target: { id: '1' },
         attrs: {
@@ -201,8 +197,8 @@ describe('useCellActions', () => {
       const { graph } = result.current;
       expect(graph.getLinks().length).toBe(2);
       const link = graph.getCell('30');
-      expect(result.current.links.length).toBe(2);
-      expect(result.current.links.find((l) => l.id === '30')?.id).toBe('30');
+      expect(Object.keys(result.current.links).length).toBe(2);
+      expect(result.current.links['30']?.source).toBeDefined();
       expect(link).toBeDefined();
       expect(link?.get('attrs')?.line?.stroke ?? '').toBe('#00FF00');
     });
@@ -215,8 +211,8 @@ describe('useCellActions', () => {
     await waitFor(() => {
       const { graph } = result.current;
       expect(graph.getLinks().length).toBe(1);
-      expect(result.current.links.length).toBe(1);
-      expect(result.current.links[0].id).toBe('30');
+      expect(Object.keys(result.current.links).length).toBe(1);
+      expect(result.current.links['30'].source).toBeDefined();
       const link = graph.getCell('3');
       expect(link).toBeUndefined();
     });
@@ -229,9 +225,275 @@ describe('useCellActions', () => {
     await waitFor(() => {
       const { graph } = result.current;
       expect(graph.getLinks().length).toBe(0);
-      expect(result.current.links.length).toBe(0);
+      expect(Object.keys(result.current.links).length).toBe(0);
       const link = graph.getCell('30');
       expect(link).toBeUndefined();
     });
   });
+
+  it('should set position using nested position object', async () => {
+    const { result } = renderHook(
+      () => {
+        return {
+          actions: useCellActions(),
+          graph: useGraph(),
+          elements: useElements(),
+        };
+      },
+      { wrapper }
+    );
+
+    // Wait for initial render
+    await waitFor(() => {
+      expect(result.current.elements['1']).toBeDefined();
+      expect(result.current.elements['1'].x).toBe(50);
+      expect(result.current.elements['1'].y).toBe(50);
+    });
+
+    // Set position using nested position object (JointJS-style)
+    act(() => {
+      result.current.actions.set('1', (previous) => ({
+        ...previous,
+        position: { x: 100, y: 150 },
+      }));
+    });
+
+    // Verify the graph element has the new position
+    await waitFor(() => {
+      const { graph } = result.current;
+      const element = graph.getCell('1');
+      expect(element).toBeDefined();
+      const position = element?.get('position');
+      expect(position?.x).toBe(100);
+      expect(position?.y).toBe(150);
+      // Also verify React state
+      expect(result.current.elements['1'].x).toBe(100);
+      expect(result.current.elements['1'].y).toBe(150);
+    });
+  });
+
+  it('should set size using nested size object', async () => {
+    const { result } = renderHook(
+      () => {
+        return {
+          actions: useCellActions(),
+          graph: useGraph(),
+          elements: useElements(),
+        };
+      },
+      { wrapper }
+    );
+
+    // Wait for initial render
+    await waitFor(() => {
+      expect(result.current.elements['1']).toBeDefined();
+      expect(result.current.elements['1'].width).toBe(97);
+      expect(result.current.elements['1'].height).toBe(99);
+    });
+
+    // Set size using nested size object (JointJS-style)
+    act(() => {
+      result.current.actions.set('1', (previous) => ({
+        ...previous,
+        size: { width: 200, height: 250 },
+      }));
+    });
+
+    // Verify the graph element has the new size
+    await waitFor(() => {
+      const { graph } = result.current;
+      const element = graph.getCell('1');
+      expect(element).toBeDefined();
+      const size = element?.get('size');
+      expect(size?.width).toBe(200);
+      expect(size?.height).toBe(250);
+    });
+
+    // Verify the React state has the new size (flat format)
+    await waitFor(() => {
+      expect(result.current.elements['1'].width).toBe(200);
+      expect(result.current.elements['1'].height).toBe(250);
+    });
+  });
+
+  it('should set size using flat width/height properties', async () => {
+    const { result } = renderHook(
+      () => {
+        return {
+          actions: useCellActions(),
+          graph: useGraph(),
+          elements: useElements(),
+        };
+      },
+      { wrapper }
+    );
+
+    // Wait for initial render
+    await waitFor(() => {
+      expect(result.current.elements['1']).toBeDefined();
+      expect(result.current.elements['1'].width).toBe(97);
+      expect(result.current.elements['1'].height).toBe(99);
+    });
+
+    // Set size using flat width/height properties
+    act(() => {
+      result.current.actions.set('1', (previous) => ({
+        ...previous,
+        width: 300,
+        height: 350,
+      }));
+    });
+
+    // Verify the graph element has the new size
+    await waitFor(() => {
+      const { graph } = result.current;
+      const element = graph.getCell('1');
+      expect(element).toBeDefined();
+      const size = element?.get('size');
+      expect(size?.width).toBe(300);
+      expect(size?.height).toBe(350);
+    });
+
+    // Verify the React state has the new size
+    await waitFor(() => {
+      expect(result.current.elements['1'].width).toBe(300);
+      expect(result.current.elements['1'].height).toBe(350);
+    });
+  });
+
+  it('should set angle correctly', async () => {
+    const { result } = renderHook(
+      () => {
+        return {
+          actions: useCellActions(),
+          graph: useGraph(),
+          elements: useElements(),
+        };
+      },
+      { wrapper }
+    );
+
+    // Wait for initial render
+    await waitFor(() => {
+      expect(result.current.elements['1']).toBeDefined();
+    });
+
+    // Set angle
+    act(() => {
+      result.current.actions.set('1', (previous) => ({
+        ...previous,
+        angle: 45,
+      }));
+    });
+
+    // Verify the graph element has the new angle
+    await waitFor(() => {
+      const { graph } = result.current;
+      const element = graph.getCell('1');
+      expect(element).toBeDefined();
+      expect(element?.get('angle')).toBe(45);
+    });
+
+    // Verify the React state has the new angle
+    await waitFor(() => {
+      expect(result.current.elements['1'].angle).toBe(45);
+    });
+  });
+
+  it('should create a new link via set and make it visible in graph', async () => {
+    const { result } = renderHook(
+      () => {
+        return {
+          actions: useCellActions(),
+          graph: useGraph(),
+          links: useLinks(),
+        };
+      },
+      { wrapper }
+    );
+
+    // Wait for initial render with the existing link
+    await waitFor(() => {
+      expect(result.current.links['3']).toBeDefined();
+      expect(result.current.graph.getLinks().length).toBe(1);
+    });
+
+    // Create a new link
+    act(() => {
+      result.current.actions.set('new-link', {
+        source: '2',
+        target: '1',
+        attrs: {
+          line: { stroke: '#FF0000' },
+        },
+      });
+    });
+
+    // Verify the link exists in React state
+    await waitFor(() => {
+      expect(Object.keys(result.current.links).length).toBe(2);
+      expect(result.current.links['new-link']).toBeDefined();
+      expect(result.current.links['new-link'].source).toBe('2');
+      expect(result.current.links['new-link'].target).toBe('1');
+    });
+
+    // Verify the link exists in the graph
+    await waitFor(() => {
+      const { graph } = result.current;
+      expect(graph.getLinks().length).toBe(2);
+      const link = graph.getCell('new-link');
+      expect(link).toBeDefined();
+      expect(link?.get('source')).toEqual({ id: '2' });
+      expect(link?.get('target')).toEqual({ id: '1' });
+    });
+  });
+
+  it('should update layout state when size is changed via set', async () => {
+    const { result } = renderHook(
+      () => {
+        return {
+          actions: useCellActions(),
+          graph: useGraph(),
+          elements: useElements(),
+          layout: useNodeLayout('1'),
+        };
+      },
+      { wrapper }
+    );
+
+    // Wait for initial render with layout state
+    await waitFor(() => {
+      expect(result.current.elements['1']).toBeDefined();
+      expect(result.current.layout).toBeDefined();
+      expect(result.current.layout?.width).toBe(97);
+      expect(result.current.layout?.height).toBe(99);
+    });
+
+    // Set size using useCellActions
+    act(() => {
+      result.current.actions.set('1', (previous) => ({
+        ...previous,
+        width: 400,
+        height: 450,
+      }));
+    });
+
+    // Verify the layout state is updated (this was the bug - layout state wasn't updating)
+    await waitFor(() => {
+      expect(result.current.layout).toBeDefined();
+      expect(result.current.layout?.width).toBe(400);
+      expect(result.current.layout?.height).toBe(450);
+    });
+
+    // Also verify graph and elements state are updated
+    await waitFor(() => {
+      const { graph } = result.current;
+      const element = graph.getCell('1');
+      const size = element?.get('size');
+      expect(size?.width).toBe(400);
+      expect(size?.height).toBe(450);
+      expect(result.current.elements['1'].width).toBe(400);
+      expect(result.current.elements['1'].height).toBe(450);
+    });
+  });
 });
diff --git a/packages/joint-react/src/hooks/__tests__/use-cell-id.test.tsx b/packages/joint-react/src/hooks/__tests__/use-cell-id.test.tsx
index da998e7b0..2a82252ac 100644
--- a/packages/joint-react/src/hooks/__tests__/use-cell-id.test.tsx
+++ b/packages/joint-react/src/hooks/__tests__/use-cell-id.test.tsx
@@ -6,13 +6,13 @@ describe('use-cell-id', () => {
   it('should return cell id when used inside renderElement', async () => {
     const wrapper = paperRenderElementWrapper({
       graphProviderProps: {
-        elements: [
-          {
+        elements: {
+          'test-cell-id': {
             id: 'test-cell-id',
             width: 100,
             height: 100,
           },
-        ],
+        },
       },
       paperProps: {
         renderElement: () => <rect />,
diff --git a/packages/joint-react/src/hooks/__tests__/use-element.test.tsx b/packages/joint-react/src/hooks/__tests__/use-element.test.tsx
index 69b04b4b9..8ab1b24ea 100644
--- a/packages/joint-react/src/hooks/__tests__/use-element.test.tsx
+++ b/packages/joint-react/src/hooks/__tests__/use-element.test.tsx
@@ -5,15 +5,15 @@ import { useElement } from '../use-element';
 describe('use-element', () => {
   const wrapper = paperRenderElementWrapper({
     graphProviderProps: {
-      elements: [
-        {
+      elements: {
+        '1': {
           id: '1',
           width: 100,
           height: 100,
           x: 10,
           y: 20,
         },
-      ],
+      },
     },
     paperProps: {
       renderElement: () => <rect />,
diff --git a/packages/joint-react/src/hooks/__tests__/use-elements.test.ts b/packages/joint-react/src/hooks/__tests__/use-elements.test.ts
index cefe9f61c..cfd1de22c 100644
--- a/packages/joint-react/src/hooks/__tests__/use-elements.test.ts
+++ b/packages/joint-react/src/hooks/__tests__/use-elements.test.ts
@@ -4,25 +4,25 @@ import { useElements } from '../use-elements';
 
 describe('use-elements', () => {
   const wrapper = graphProviderWrapper({
-    elements: [
-      {
+    elements: {
+      '1': {
         id: '1',
         width: 97,
         height: 99,
       },
-      {
+      '2': {
         id: '2',
         width: 97,
         height: 99,
       },
-    ],
-    links: [
-      {
+    },
+    links: {
+      '3': {
         id: '3',
         source: '1',
         target: '2',
       },
-    ],
+    },
   });
 
   it('should get elements properly without selector', async () => {
@@ -39,12 +39,12 @@ describe('use-elements', () => {
 
     await waitFor(() => {
       expect(renders).toHaveBeenCalledTimes(1);
-      expect(result.current.length).toBe(2);
-      expect(result.current[0].width).toBe(97);
-      expect(result.current[0].height).toBe(99);
+      expect(Object.keys(result.current).length).toBe(2);
+      expect(result.current['1'].width).toBe(97);
+      expect(result.current['1'].height).toBe(99);
 
-      expect(result.current[1].width).toBe(97);
-      expect(result.current[1].height).toBe(99);
+      expect(result.current['2'].width).toBe(97);
+      expect(result.current['2'].height).toBe(99);
     });
   });
 
@@ -54,7 +54,7 @@ describe('use-elements', () => {
       () => {
         renders();
         // eslint-disable-next-line sonarjs/no-nested-functions
-        return useElements((element) => element.map((items) => items.width));
+        return useElements((elements) => Object.values(elements).map((item) => item.width));
       },
       {
         wrapper,
diff --git a/packages/joint-react/src/hooks/__tests__/use-graph.test.ts b/packages/joint-react/src/hooks/__tests__/use-graph.test.ts
index 95a9a9959..9d4828988 100644
--- a/packages/joint-react/src/hooks/__tests__/use-graph.test.ts
+++ b/packages/joint-react/src/hooks/__tests__/use-graph.test.ts
@@ -4,13 +4,13 @@ import { useGraph } from '../use-graph';
 
 describe('use-graph', () => {
   const wrapper = graphProviderWrapper({
-    elements: [
-      {
+    elements: {
+      '1': {
         id: '1',
         width: 100,
         height: 100,
       },
-    ],
+    },
   });
 
   it('should return graph instance', async () => {
diff --git a/packages/joint-react/src/hooks/__tests__/use-link-layout.test.tsx b/packages/joint-react/src/hooks/__tests__/use-link-layout.test.tsx
new file mode 100644
index 000000000..32c4582ef
--- /dev/null
+++ b/packages/joint-react/src/hooks/__tests__/use-link-layout.test.tsx
@@ -0,0 +1,84 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import { paperRenderLinkWrapper, getTestGraph } from '../../utils/test-wrappers';
+import { useLinkLayout } from '../use-link-layout';
+
+describe('useLinkLayout', () => {
+  it('should return link layout when used inside renderLink', async () => {
+    const graph = getTestGraph();
+    const wrapper = paperRenderLinkWrapper({
+      graphProviderProps: {
+        graph,
+        elements: {
+          'element-1': { x: 0, y: 0, width: 100, height: 100 },
+          'element-2': { x: 300, y: 300, width: 100, height: 100 },
+        },
+        links: {
+          'link-1': { source: 'element-1', target: 'element-2' },
+        },
+      },
+    });
+
+    const { result } = renderHook(() => useLinkLayout(), { wrapper });
+
+    await waitFor(() => {
+      // Layout might be undefined initially until paper renders
+      if (result.current) {
+        expect(result.current).toHaveProperty('sourceX');
+        expect(result.current).toHaveProperty('sourceY');
+        expect(result.current).toHaveProperty('targetX');
+        expect(result.current).toHaveProperty('targetY');
+        expect(result.current).toHaveProperty('d');
+      }
+    });
+  });
+
+  it('should have correct structure for link layout', async () => {
+    const graph = getTestGraph();
+    const wrapper = paperRenderLinkWrapper({
+      graphProviderProps: {
+        graph,
+        elements: {
+          'element-1': { x: 0, y: 0, width: 100, height: 100 },
+          'element-2': { x: 300, y: 300, width: 100, height: 100 },
+        },
+        links: {
+          'link-1': { source: 'element-1', target: 'element-2' },
+        },
+      },
+    });
+
+    const { result } = renderHook(() => useLinkLayout(), { wrapper });
+
+    await waitFor(() => {
+      if (result.current) {
+        expect(typeof result.current.sourceX).toBe('number');
+        expect(typeof result.current.sourceY).toBe('number');
+        expect(typeof result.current.targetX).toBe('number');
+        expect(typeof result.current.targetY).toBe('number');
+        expect(typeof result.current.d).toBe('string');
+      }
+    });
+  });
+
+  it('should return undefined for non-existent link', async () => {
+    const graph = getTestGraph();
+    const wrapper = paperRenderLinkWrapper({
+      graphProviderProps: {
+        graph,
+        elements: {
+          'element-1': { x: 0, y: 0, width: 100, height: 100 },
+          'element-2': { x: 300, y: 300, width: 100, height: 100 },
+        },
+        links: {
+          'link-1': { source: 'element-1', target: 'element-2' },
+        },
+      },
+    });
+
+    const { result } = renderHook(() => useLinkLayout('non-existent-link'), { wrapper });
+
+    await waitFor(() => {
+      expect(result.current).toBeUndefined();
+    });
+  });
+});
diff --git a/packages/joint-react/src/hooks/__tests__/use-links.test.ts b/packages/joint-react/src/hooks/__tests__/use-links.test.ts
index df1fa31c6..70670d5b3 100644
--- a/packages/joint-react/src/hooks/__tests__/use-links.test.ts
+++ b/packages/joint-react/src/hooks/__tests__/use-links.test.ts
@@ -14,25 +14,25 @@ function getLinkSourceId(link: GraphLink) {
 
 describe('use-links', () => {
   const wrapper = graphProviderWrapper({
-    elements: [
-      {
+    elements: {
+      '1': {
         id: '1',
         width: 97,
         height: 99,
       },
-      {
+      '2': {
         id: '2',
         width: 97,
         height: 99,
       },
-    ],
-    links: [
-      {
+    },
+    links: {
+      '3': {
         id: '3',
         source: '1',
         target: '2',
       },
-    ],
+    },
   });
 
   it('should get links properly without selector', async () => {
@@ -49,8 +49,8 @@ describe('use-links', () => {
 
     await waitFor(() => {
       expect(renders).toHaveBeenCalledTimes(1);
-      expect(result.current.length).toBe(1);
-      expect(result.current[0].id).toBe('3');
+      expect(Object.keys(result.current).length).toBe(1);
+      expect(result.current['3'].id).toBe('3');
     });
   });
 
@@ -59,7 +59,7 @@ describe('use-links', () => {
     const { result } = renderHook(
       () => {
         renders();
-        return useLinks((links) => links.map(getLinkSourceId));
+        return useLinks((links) => Object.values(links).map(getLinkSourceId));
       },
       {
         wrapper,
diff --git a/packages/joint-react/src/hooks/__tests__/use-paper-context.test.tsx b/packages/joint-react/src/hooks/__tests__/use-paper-context.test.tsx
index 521a14b9e..ea188628f 100644
--- a/packages/joint-react/src/hooks/__tests__/use-paper-context.test.tsx
+++ b/packages/joint-react/src/hooks/__tests__/use-paper-context.test.tsx
@@ -5,13 +5,13 @@ import { usePaperStoreContext } from '../use-paper-context';
 describe('use-paper-context', () => {
   const wrapper = paperRenderElementWrapper({
     graphProviderProps: {
-      elements: [
-        {
+      elements: {
+        '1': {
           id: '1',
           width: 100,
           height: 100,
         },
-      ],
+      },
     },
     paperProps: {
       renderElement: () => <rect />,
diff --git a/packages/joint-react/src/hooks/index.ts b/packages/joint-react/src/hooks/index.ts
index fd84748b5..800b3c614 100644
--- a/packages/joint-react/src/hooks/index.ts
+++ b/packages/joint-react/src/hooks/index.ts
@@ -14,3 +14,4 @@ export * from './use-paper-context';
 export * from './use-element-views';
 export * from './use-combined-ref';
 export * from './use-ref-value';
+export * from './use-link-layout';
diff --git a/packages/joint-react/src/hooks/use-cell-actions.stories.tsx b/packages/joint-react/src/hooks/use-cell-actions.stories.tsx
index cd583f85f..7814bd5fb 100644
--- a/packages/joint-react/src/hooks/use-cell-actions.stories.tsx
+++ b/packages/joint-react/src/hooks/use-cell-actions.stories.tsx
@@ -1,4 +1,3 @@
- 
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
 import type { Meta, StoryObj } from '@storybook/react';
 import type { SimpleElement } from '../../.storybook/decorators/with-simple-data';
@@ -182,7 +181,6 @@ function HookSetPosition({  label , id }: SimpleElement) {
 
 function HookSetSize({ label, id }: Readonly<SimpleElement>) {
   const { set } = useCellActions<SimpleElement>();
-
   return (
     <HTMLNode className="node">
       <button
@@ -386,8 +384,7 @@ function HookSetAndRemoveLink({ label, id }: Readonly<SimpleElement>) {
       <button
         className={BUTTON_CLASSNAME}
         onClick={() =>
-          set({
-            id: 'l-1',
+          set('l-1', {
             source: id,
             target: id === '1' ? '2' : '1',
             attrs: {
diff --git a/packages/joint-react/src/hooks/use-cell-actions.ts b/packages/joint-react/src/hooks/use-cell-actions.ts
index cca12eb73..026ae2bb3 100644
--- a/packages/joint-react/src/hooks/use-cell-actions.ts
+++ b/packages/joint-react/src/hooks/use-cell-actions.ts
@@ -1,12 +1,43 @@
-/* eslint-disable sonarjs/cognitive-complexity */
 import { useMemo } from 'react';
-import { dia } from '@joint/core';
+import type { dia } from '@joint/core';
 import type { GraphElement } from '../types/element-types';
-import type { CellWithId } from '../types/cell.types';
 import type { GraphLink } from '../types/link-types';
 import type { GraphStoreSnapshot } from '../store';
 import { useGraphStore } from './use-graph-store';
 
+/**
+ * Normalizes element attributes to the GraphElement format.
+ * Converts nested JointJS format (position: {x, y}, size: {width, height})
+ * to flat format (x, y, width, height).
+ * @param attributes
+ */
+function normalizeElementAttributes<T extends GraphElement>(attributes: T): T {
+  const {
+    position,
+    size,
+    ...rest
+  } = attributes as T & {
+    position?: { x: number; y: number };
+    size?: { width: number; height: number };
+  };
+
+  const normalized = { ...rest } as T;
+
+  // Convert position to flat x, y (prefer position over existing x, y)
+  if (position !== undefined) {
+    (normalized as GraphElement).x = position.x;
+    (normalized as GraphElement).y = position.y;
+  }
+
+  // Convert size to flat width, height (prefer size over existing width, height)
+  if (size !== undefined) {
+    (normalized as GraphElement).width = size.width;
+    (normalized as GraphElement).height = size.height;
+  }
+
+  return normalized;
+}
+
 /**
  * Actions for manipulating cells (elements and links) in the graph.
  * @template Attributes - The type of cell attributes, which can be an element or a link
@@ -15,14 +46,11 @@ interface CellActions<Attributes extends dia.Element | GraphElement> {
   /**
    * Sets or updates a cell in the graph.
    * Can be called in two ways:
-   * 1. With full attributes: `set({ id: '1', ...attributes })`
+   * 1. With ID and attributes: `set('1', { x: 100, y: 150 })`
    * 2. With ID and updater: `set('1', (prev) => ({ ...prev, label: 'New' }))`
    * If the cell doesn't exist, it will be added.
    */
-  set: {
-    (attributes: Attributes): void;
-    (id: dia.Cell.ID, updater: (previous: Attributes) => Attributes): void;
-  };
+  set: (id: dia.Cell.ID, attributesOrUpdater: Attributes | ((previous: Attributes) => Attributes)) => void;
   /**
    * Removes a cell from the graph by its ID.
    * @param id - The ID of the cell to remove
@@ -35,8 +63,8 @@ interface CellActions<Attributes extends dia.Element | GraphElement> {
  * @param cell - The cell to check.
  * @returns True if the cell is a link, false otherwise.
  */
-function isLink(cell: CellWithId): cell is GraphLink {
-  return cell instanceof dia.Link || ('source' in cell && 'target' in cell);
+function isLink(cell: GraphElement | GraphLink): cell is GraphLink {
+  return 'source' in cell && 'target' in cell;
 }
 
 /**
@@ -63,11 +91,11 @@ function isLink(cell: CellWithId): cell is GraphLink {
  * ```tsx
  * const { set, remove } = useCellActions<GraphElement | GraphLink<"standard.Link">>();
  *
- * // Add or update element with full attributes
- * set({ id: '1', position: { x: 100, y: 150 }, width: 100, height: 50 });
+ * // Add or update element with ID and attributes
+ * set('1', { x: 100, y: 150, width: 100, height: 50 });
  *
  * // Update element with updater function (safer, preserves other properties)
- * set('1', (cell) => ({ ...cell, position: { x: 200, y: 250 } }));
+ * set('1', (cell) => ({ ...cell, x: 200, y: 250 }));
  *
  * // Remove element
  * remove('1');
@@ -81,60 +109,43 @@ export function useCellActions<
   return useMemo(
     (): CellActions<Attributes> => ({
       set(
-        attributesOrId: Attributes | dia.Cell.ID,
-        maybeUpdater?: (previousAttributes: Attributes) => Attributes
+        id: dia.Cell.ID,
+        attributesOrUpdater: Attributes | ((previousAttributes: Attributes) => Attributes)
       ) {
         let attributes: Attributes;
         const { elements, links } = publicState.getSnapshot();
-        if (
-          typeof attributesOrId !== 'object' &&
-          maybeUpdater &&
-          typeof maybeUpdater === 'function'
-        ) {
-          const cell: GraphElement | GraphLink | undefined =
-            elements.find((data: GraphElement) => data.id === attributesOrId) ||
-            links.find((data: GraphLink) => data.id === attributesOrId);
-
-          if (!cell) throw new Error(`Cell with id "${attributesOrId}" not found.`);
-          attributes = maybeUpdater(cell as Attributes);
-        } else if (typeof attributesOrId === 'object') {
-          attributes = attributesOrId;
+
+        if (typeof attributesOrUpdater === 'function') {
+          const cell: GraphElement | GraphLink | undefined = elements[id] || links[id];
+
+          if (!cell) throw new Error(`Cell with id "${id}" not found.`);
+          attributes = attributesOrUpdater(cell as Attributes);
         } else {
-          throw new TypeError('Invalid arguments for set().');
+          attributes = attributesOrUpdater;
         }
 
         const areAttributesLink = isLink(attributes);
-        const targetId = typeof attributesOrId === 'object' ? attributes.id : attributesOrId;
-
-        let hasElement = false;
-        let hasLink = false;
-        const newLinks = [...links];
-        const newElements = [...elements];
-
-        for (let index = 0; index < newElements.length; index++) {
-          if (newElements[index].id === targetId) {
-            newElements[index] = attributes;
-            hasElement = true;
-            break;
-          }
-        }
-        if (!hasElement) {
-          for (let index = 0; index < newLinks.length; index++) {
-            if (newLinks[index].id === targetId) {
-              newLinks[index] = attributes as GraphLink;
-              hasLink = true;
-              break;
-            }
-          }
-        }
+        const targetId = id;
+
+        const hasElement = targetId in elements;
+        const hasLink = targetId in links;
         const isFound = hasElement || hasLink;
-        if (!isFound) {
+
+        const newElements = { ...elements };
+        const newLinks = { ...links };
+
+        if (hasElement) {
+          newElements[targetId] = normalizeElementAttributes(attributes);
+        } else if (hasLink) {
+          newLinks[targetId] = attributes as GraphLink;
+        } else if (!isFound) {
           if (areAttributesLink) {
-            newLinks.push(attributes as GraphLink);
+            newLinks[targetId] = attributes as GraphLink;
           } else {
-            newElements.push(attributes);
+            newElements[targetId] = normalizeElementAttributes(attributes);
           }
         }
+
         publicState.setState((previous: GraphStoreSnapshot) => ({
           ...previous,
           elements: newElements,
diff --git a/packages/joint-react/src/hooks/use-element.ts b/packages/joint-react/src/hooks/use-element.ts
index 9b9e184de..ce3e73680 100644
--- a/packages/joint-react/src/hooks/use-element.ts
+++ b/packages/joint-react/src/hooks/use-element.ts
@@ -1,7 +1,7 @@
 import { util } from '@joint/core';
 import { useCellId } from './use-cell-id';
 import type { GraphElement } from '../types/element-types';
-import { useGraphStoreSelector, useDerivedGraphStoreSelector } from './use-graph-store-selector';
+import { useGraphStoreSelector } from './use-graph-store-selector';
 
 /**
  * A hook to access a specific graph element from the current `Paper` context.
@@ -37,13 +37,8 @@ export function useElement<Element extends GraphElement, ReturnedElements = Elem
 ): ReturnedElements {
   const id = useCellId();
 
-  const index = useDerivedGraphStoreSelector((store) => store.elementIds[id]);
-
   return useGraphStoreSelector<ReturnedElements>((store) => {
-    if (index == undefined) {
-      return undefined as ReturnedElements;
-    }
-    const element = store.elements[index] as Element;
+    const element = store.elements[id] as Element | undefined;
     if (!element) {
       return undefined as ReturnedElements;
     }
diff --git a/packages/joint-react/src/hooks/use-elements.stories.tsx b/packages/joint-react/src/hooks/use-elements.stories.tsx
index b46875ec0..f648392bd 100644
--- a/packages/joint-react/src/hooks/use-elements.stories.tsx
+++ b/packages/joint-react/src/hooks/use-elements.stories.tsx
@@ -21,7 +21,7 @@ const meta: Meta<typeof HookTester> = {
 The **useElements** hook provides access to all elements in the graph. It supports selector functions for optimized re-renders, only updating when selected element properties change.
 
 **Key Features:**
-- Returns all elements in the graph
+- Returns all elements in the graph as a Record keyed by ID
 - Supports selector functions for performance optimization
 - Only re-renders when selected properties change
 - Can be used anywhere within GraphProvider context
@@ -30,37 +30,37 @@ The **useElements** hook provides access to all elements in the graph. It suppor
 \`\`\`tsx
 import { useElements } from '@joint/react';
 
-// Get all elements
+// Get all elements (returns Record<string, GraphElement>)
 function Component() {
   const elements = useElements();
-  return <div>Total elements: {elements.length}</div>;
+  return <div>Total elements: {Object.keys(elements).length}</div>;
 }
 
 // Get specific properties (optimized)
 function OptimizedComponent() {
-  const elementIds = useElements((elements) => 
-    elements.map(element => element.id)
+  const elementIds = useElements((elements) =>
+    Object.values(elements).map(element => element.id)
   );
   return <div>Element IDs: {elementIds.join(', ')}</div>;
 }
 \`\`\`
     `,
     props: `
-- **selector** (optional): Function that transforms the elements array
-  - Returns: Transformed elements data or full elements array if no selector provided
+- **selector** (optional): Function that transforms the elements Record
+  - Returns: Transformed elements data or full elements Record if no selector provided
   - Re-renders only when selected properties change
     `,
     code: `import { useElements } from '@joint/react'
 
 function Component() {
   const elements = useElements();
-  return <div>Total elements: {elements.length}</div>;
+  return <div>Total elements: {Object.keys(elements).length}</div>;
 }
 
 // With selector for optimization
 function OptimizedComponent() {
-  const elementIds = useElements((elements) => 
-    elements.map(element => element.id)
+  const elementIds = useElements((elements) =>
+    Object.values(elements).map(element => element.id)
   );
   return <div>Element IDs: {elementIds.join(', ')}</div>;
 }`,
@@ -92,16 +92,16 @@ export const Default = makeStory<Story>({
   code: `import { useElements } from '@joint/react'
 
 function Component() {
-  const elements = useElements();
+  const elements = useElements(); // returns Record<string, GraphElement>
   return <div>elements are: {JSON.stringify(elements)}</div>;
 }`,
-  description: 'Get all elements.',
+  description: 'Get all elements as a Record keyed by ID.',
 });
 
 export const WithSelectedJustIds = makeStory<Story>({
   args: {
     useHook: useElements,
-    hookArgs: [(elements) => elements.map((element) => element.id)],
+    hookArgs: [(elements) => Object.values(elements).map((element) => element.id)],
     render: (result) => (
       <span>
         <Paper
@@ -119,7 +119,7 @@ export const WithSelectedJustIds = makeStory<Story>({
   code: `import { useElements } from '@joint/react'
 
 function Component() {
-  const elementIds = useElements((elements) => elements.map((element) => element.id));
+  const elementIds = useElements((elements) => Object.values(elements).map((element) => element.id));
   return <div>element ids are: {JSON.stringify(elementIds)}</div>;
 }`,
   description: 'Get the ids of the elements.',
@@ -128,7 +128,7 @@ function Component() {
 export const WithGetJustSize = makeStory<Story>({
   args: {
     useHook: useElements,
-    hookArgs: [(elements) => elements.length],
+    hookArgs: [(elements) => Object.keys(elements).length],
     render: (result) => (
       <div>
         <Paper
@@ -146,7 +146,7 @@ export const WithGetJustSize = makeStory<Story>({
   code: `import { useElements } from '@joint/react'
 
 function Component() {
-  const size = useElements((elements) => elements.length);
+  const size = useElements((elements) => Object.keys(elements).length);
   return <div>size of elements is: {JSON.stringify(size)}</div>;
 }`,
   description: 'Get the size of the elements.',
@@ -157,7 +157,7 @@ export const WithJustPosition = makeStory<Story>({
     useHook: useElements,
     hookArgs: [
       (elements) =>
-        elements.map((element) => ({
+        Object.values(elements).map((element) => ({
           x: element.x,
           y: element.y,
         })),
@@ -180,7 +180,7 @@ export const WithJustPosition = makeStory<Story>({
 
 function Component() {
   const positions = useElements((elements) =>
-    elements.map((element) => ({ x: element.x, y: element.y }))
+    Object.values(elements).map((element) => ({ x: element.x, y: element.y }))
   );
   return <div>positions are: {JSON.stringify(positions)}</div>;
 }`,
@@ -192,7 +192,7 @@ export const WithJustPositionButNotReRenderBecauseCompareFN = makeStory<Story>({
     useHook: useElements,
     hookArgs: [
       (elements) =>
-        elements.map((element) => ({
+        Object.values(elements).map((element) => ({
           x: element.x,
           y: element.y,
         })),
@@ -216,7 +216,7 @@ export const WithJustPositionButNotReRenderBecauseCompareFN = makeStory<Story>({
 
 function Component() {
   const positions = useElements(
-    (elements) => elements.map((element) => ({ x: element.x, y: element.y })),
+    (elements) => Object.values(elements).map((element) => ({ x: element.x, y: element.y })),
     (_previous, _next) => true
   );
   return <div>positions are: {JSON.stringify(positions)}</div>;
@@ -228,7 +228,7 @@ function Component() {
 export const WithAdditionalData = makeStory<Story>({
   args: {
     useHook: useElements,
-    hookArgs: [(elements) => elements.map((element) => ({ id: element.id, other: 'something' }))],
+    hookArgs: [(elements) => Object.values(elements).map((element) => ({ id: element.id, other: 'something' }))],
     render: (result) => (
       <div>
         <Paper
@@ -247,7 +247,7 @@ export const WithAdditionalData = makeStory<Story>({
 
 function Component() {
   const elements = useElements((elements) =>
-    elements.map((element) => ({ id: element.id, data: element.data, other: 'something' }))
+    Object.values(elements).map((element) => ({ id: element.id, data: element.data, other: 'something' }))
   );
   return <div>elements with new data are: {JSON.stringify(elements)}</div>;
 }`,
diff --git a/packages/joint-react/src/hooks/use-elements.ts b/packages/joint-react/src/hooks/use-elements.ts
index 10599d493..a54b11def 100644
--- a/packages/joint-react/src/hooks/use-elements.ts
+++ b/packages/joint-react/src/hooks/use-elements.ts
@@ -1,3 +1,4 @@
+import type { dia } from '@joint/core';
 import { util } from '@joint/core';
 import type { GraphElement } from '../types/element-types';
 import { useGraphStoreSelector } from './use-graph-store-selector';
@@ -8,8 +9,8 @@ import { useGraphStoreSelector } from './use-graph-store-selector';
  * @returns - The selected items.
  */
 function defaultSelector<Elements extends GraphElement = GraphElement>(
-  items: Elements[]
-): Elements[] {
+  items: Record<dia.Cell.ID, Elements>
+): Record<dia.Cell.ID, Elements> {
   return items;
 }
 
@@ -17,7 +18,7 @@ function defaultSelector<Elements extends GraphElement = GraphElement>(
  * A hook to access `dia.graph` elements
  *
  * This hook returns the selected elements from the graph store. It accepts:
- * - a selector function, which extracts the desired portion from the elements map.
+ * - a selector function, which extracts the desired portion from the elements record.
  * - an optional `isEqual` function, used to compare previous and new values—ensuring
  * the component only re-renders when necessary.
  *
@@ -28,26 +29,27 @@ function defaultSelector<Elements extends GraphElement = GraphElement>(
  * references on each call), the `isEqual` comparator (defaulting to a deep comparison)
  * checks if the selected value really changed.
  * @example
- * Using without a selector (returns all elements):
+ * Using without a selector (returns all elements as a Record):
  * ```tsx
  * const elements = useElements();
+ * // elements is Record<dia.Cell.ID, GraphElement>
  * ```
  * @example
  * Using with a selector (extract part of each element):
  * ```tsx
- * const elementIds = useElements((elements) => elements.map((element) => element.id));
+ * const elementIds = useElements((elements) => Object.keys(elements));
  * ```
  * @example
- * Using with a selector (extract id):
+ * Using with a selector (extract specific element by id):
  * ```tsx
- * const maybeElementById = useElements((elements) => elements.get('id'));
+ * const maybeElementById = useElements((elements) => elements['id']);
  * ```
  * @example
- * Using with a custom isEqual function (e.g. comparing the size of the returned map):
+ * Using with a custom isEqual function (e.g. comparing the count of elements):
  * ```tsx
- * const elementLength = useElements(
+ * const elementCount = useElements(
  *   (elements) => elements,
- *   (prev, next) => prev.size === next.size
+ *   (prev, next) => Object.keys(prev).length === Object.keys(next).length
  * );
  * ```
  * @group Hooks
@@ -57,15 +59,15 @@ function defaultSelector<Elements extends GraphElement = GraphElement>(
  */
 export function useElements<
   Elements extends GraphElement = GraphElement,
-  SelectorReturnType = Elements[],
+  SelectorReturnType = Record<dia.Cell.ID, Elements>,
 >(
-  selector: (items: Elements[]) => SelectorReturnType = defaultSelector as () => SelectorReturnType,
+  selector: (items: Record<dia.Cell.ID, Elements>) => SelectorReturnType = defaultSelector as () => SelectorReturnType,
   isEqual: (a: SelectorReturnType, b: SelectorReturnType) => boolean = util.isEqual as (
     a: SelectorReturnType,
     b: SelectorReturnType
   ) => boolean
 ): SelectorReturnType {
   return useGraphStoreSelector((snapshot) => {
-    return selector(snapshot.elements as Elements[]);
+    return selector(snapshot.elements as Record<dia.Cell.ID, Elements>);
   }, isEqual);
 }
diff --git a/packages/joint-react/src/hooks/use-graph-store-selector.ts b/packages/joint-react/src/hooks/use-graph-store-selector.ts
index dc456f422..db7ec0404 100644
--- a/packages/joint-react/src/hooks/use-graph-store-selector.ts
+++ b/packages/joint-react/src/hooks/use-graph-store-selector.ts
@@ -1,5 +1,4 @@
 import type {
-  GraphStoreDerivedSnapshot,
   GraphStoreSnapshot,
   GraphStoreInternalSnapshot,
 } from '../store';
@@ -66,20 +65,6 @@ export function useGraphInternalStoreSelector<Selection>(
   return useStoreSelector(internalState, selector, isEqual);
 }
 
-/**
- * Hook to select data from the ids store state.
- * @param selector - The selector function.
- * @param isEqual - The equality function.
- * @returns The selected data.
- */
-export function useDerivedGraphStoreSelector<Selection>(
-  selector: (snapshot: MarkDeepReadOnly<GraphStoreDerivedSnapshot>) => Selection,
-  isEqual?: (a: Selection, b: Selection) => boolean
-): Selection {
-  const { derivedStore } = useGraphStore();
-  return useStoreSelector(derivedStore, selector, isEqual);
-}
-
 /**
  * Hook to access whether all elements have been measured (have width and height).
  * Computed based on actual graph cell sizes, not state data.
diff --git a/packages/joint-react/src/hooks/use-link-layout.ts b/packages/joint-react/src/hooks/use-link-layout.ts
new file mode 100644
index 000000000..d93f1f9a3
--- /dev/null
+++ b/packages/joint-react/src/hooks/use-link-layout.ts
@@ -0,0 +1,63 @@
+import { useContext } from 'react';
+import { useGraphStore } from './use-graph-store';
+import { usePaperStoreContext } from './use-paper-context';
+import { useStoreSelector } from './use-graph-store-selector';
+import type { LinkLayout } from '../store/graph-store';
+
+// Re-export LinkLayout for convenience
+export type { LinkLayout } from '../store/graph-store';
+import type { dia } from '@joint/core';
+import { CellIdContext } from '../context';
+
+/**
+ * Hook to get layout data (geometry) for a specific link.
+ * Returns sourceX, sourceY, targetX, targetY, and d (path) from the link view.
+ * @param id - Optional ID of the link to get layout for. If not provided, uses the current cell ID from context.
+ * @returns The layout data or undefined if not found
+ * @group Hooks
+ * @example
+ * ```tsx
+ * // With explicit ID
+ * function MyComponent() {
+ *   const layout = useLinkLayout('link-1');
+ *
+ *   if (!layout) {
+ *     return <div>Loading...</div>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       Source: ({layout.sourceX}, {layout.sourceY})
+ *       Target: ({layout.targetX}, {layout.targetY})
+ *     </div>
+ *   );
+ * }
+ * ```
+ * @example
+ * ```tsx
+ * // Using context (inside renderLink)
+ * function MyLink() {
+ *   const layout = useLinkLayout(); // Uses CellIdContext
+ *
+ *   return (
+ *     <path d={layout?.d} stroke="blue" fill="none" />
+ *   );
+ * }
+ * ```
+ */
+export function useLinkLayout<Id extends dia.Cell.ID | undefined = undefined>(
+  id?: Id
+): Id extends dia.Cell.ID ? LinkLayout | undefined : LinkLayout | undefined {
+  const contextId = useContext(CellIdContext);
+  const { layoutState } = useGraphStore();
+  const { paperId } = usePaperStoreContext();
+  const actualId = id ?? contextId;
+  if (!actualId) {
+    throw new Error('useLinkLayout must be used inside Paper renderLink or provide an id');
+  }
+
+  return useStoreSelector(layoutState, (snapshot) => {
+    const paperLinkLayouts = snapshot.links[paperId];
+    return paperLinkLayouts?.[actualId];
+  });
+}
diff --git a/packages/joint-react/src/hooks/use-links.stories.tsx b/packages/joint-react/src/hooks/use-links.stories.tsx
index bdb8eddf9..c77c2715d 100644
--- a/packages/joint-react/src/hooks/use-links.stories.tsx
+++ b/packages/joint-react/src/hooks/use-links.stories.tsx
@@ -20,7 +20,7 @@ const meta: Meta<typeof HookTester> = {
 The **useLinks** hook provides access to all links in the graph. It supports selector functions for optimized re-renders, only updating when selected link properties change.
 
 **Key Features:**
-- Returns all links in the graph
+- Returns all links in the graph as a Record keyed by ID
 - Supports selector functions for performance optimization
 - Only re-renders when selected properties change
 - Can be used anywhere within GraphProvider context
@@ -29,34 +29,34 @@ The **useLinks** hook provides access to all links in the graph. It supports sel
 \`\`\`tsx
 import { useLinks } from '@joint/react';
 
-// Get all links
+// Get all links (returns Record<string, GraphLink>)
 function Component() {
   const links = useLinks();
-  return <div>Total links: {links.length}</div>;
+  return <div>Total links: {Object.keys(links).length}</div>;
 }
 
 // Get specific properties (optimized)
 function OptimizedComponent() {
-  const linkIds = useLinks((links) => links.map(link => link.id));
+  const linkIds = useLinks((links) => Object.values(links).map(link => link.id));
   return <div>Link IDs: {linkIds.join(', ')}</div>;
 }
 \`\`\`
     `,
     props: `
-- **selector** (optional): Function that transforms the links array
-  - Returns: Transformed links data or full links array if no selector provided
+- **selector** (optional): Function that transforms the links Record
+  - Returns: Transformed links data or full links Record if no selector provided
   - Re-renders only when selected properties change
     `,
     code: `import { useLinks } from '@joint/react'
 
 function Component() {
   const links = useLinks();
-  return <div>Total links: {links.length}</div>;
+  return <div>Total links: {Object.keys(links).length}</div>;
 }
 
 // With selector for optimization
 function OptimizedComponent() {
-  const linkIds = useLinks((links) => links.map(link => link.id));
+  const linkIds = useLinks((links) => Object.values(links).map(link => link.id));
   return <div>Link IDs: {linkIds.join(', ')}</div>;
 }`,
   }),
@@ -74,16 +74,16 @@ export const GetAllLinks: Story = makeStory<Story>({
   code: `import { useLinks } from '@joint/react'
 
 function Component() {
-  const links = useLinks();
+  const links = useLinks(); // returns Record<string, GraphLink>
   return (
     <div>
-      <p>Total links: {links.length}</p>
+      <p>Total links: {Object.keys(links).length}</p>
       <pre>{JSON.stringify(links, null, 2)}</pre>
     </div>
   );
 }`,
   description:
-    'Retrieves all links in the graph. The component re-renders whenever any link is added, removed, or modified.',
+    'Retrieves all links in the graph as a Record keyed by ID. The component re-renders whenever any link is added, removed, or modified.',
   details:
     '**Use Case:** Display link count, render link lists, or perform operations on all links.',
 });
@@ -92,14 +92,14 @@ export const GetLinkIds: Story = makeStory<Story>({
   args: {
     useHook: useLinks,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    hookArgs: [(links: any) => links.map((link: any) => link.id)],
+    hookArgs: [(links: any) => Object.values(links).map((link: any) => link.id)],
     render: (result) => <DataRenderer data={result} name="Link IDs" />,
   },
   apiURL: API_URL,
   code: `import { useLinks } from '@joint/react'
 
 function Component() {
-  const linkIds = useLinks((links) => links.map(link => link.id));
+  const linkIds = useLinks((links) => Object.values(links).map(link => link.id));
   return <div>Link IDs: {linkIds.join(', ')}</div>;
 }`,
   description:
diff --git a/packages/joint-react/src/hooks/use-links.ts b/packages/joint-react/src/hooks/use-links.ts
index a45d5c6be..af07e8922 100644
--- a/packages/joint-react/src/hooks/use-links.ts
+++ b/packages/joint-react/src/hooks/use-links.ts
@@ -1,19 +1,22 @@
-import { useGraphStore } from './use-graph-store';
+import type { dia } from '@joint/core';
 import { util } from '@joint/core';
-import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/with-selector';
 import type { GraphLink } from '../types/link-types';
+import { useGraphStoreSelector } from './use-graph-store-selector';
 
 /**
  * Default selector function that returns all links unchanged.
  * Used when no custom selector is provided to useLinks.
  * @template Link - The type of links
- * @param items - The links array to select from
- * @returns The same links array
+ * @param items - The links record to select from
+ * @returns The same links record
  * @internal
  */
-function defaultSelector<Link extends GraphLink = GraphLink>(items: Link[]): Link[] {
-  return items.map((item) => item) as Link[];
+function defaultSelector<Link extends GraphLink = GraphLink>(
+  items: Record<dia.Cell.ID, Link>
+): Record<dia.Cell.ID, Link> {
+  return items;
 }
+
 /**
  * Hook to access and subscribe to links (edges) from the graph store.
  *
@@ -40,35 +43,34 @@ function defaultSelector<Link extends GraphLink = GraphLink>(items: Link[]): Lin
  * @group Hooks
  * @example
  * ```ts
- * // Get all links
+ * // Get all links as a Record
  * const links = useLinks();
+ * // links is Record<dia.Cell.ID, GraphLink>
  * ```
  * @example
  * ```ts
  * // Extract only link IDs
- * const linkIds = useLinks((links) => links.map(link => link.id));
+ * const linkIds = useLinks((links) => Object.keys(links));
+ * ```
+ * @example
+ * ```ts
+ * // Get a specific link by ID
+ * const link = useLinks((links) => links['link-1']);
  * ```
  * @example
  * ```ts
  * // Custom equality check (only re-render if count changes)
  * const linkCount = useLinks(
- *   (links) => links.length,
+ *   (links) => Object.keys(links).length,
  *   (prev, next) => prev === next
  * );
  * ```
  */
-export function useLinks<Link extends GraphLink = GraphLink, SelectorReturnType = Link[]>(
-  selector: (items: Link[]) => SelectorReturnType = defaultSelector as () => SelectorReturnType,
+export function useLinks<Link extends GraphLink = GraphLink, SelectorReturnType = Record<dia.Cell.ID, Link>>(
+  selector: (items: Record<dia.Cell.ID, Link>) => SelectorReturnType = defaultSelector as () => SelectorReturnType,
   isEqual: (a: SelectorReturnType, b: SelectorReturnType) => boolean = util.isEqual
 ): SelectorReturnType {
-  const { publicState } = useGraphStore();
-  const getLinks = () => publicState.getSnapshot().links as Link[];
-  const elements = useSyncExternalStoreWithSelector(
-    publicState.subscribe,
-    getLinks,
-    getLinks,
-    selector,
-    isEqual
-  );
-  return elements;
+  return useGraphStoreSelector((snapshot) => {
+    return selector(snapshot.links as Record<dia.Cell.ID, Link>);
+  }, isEqual);
 }
diff --git a/packages/joint-react/src/hooks/use-node-layout.ts b/packages/joint-react/src/hooks/use-node-layout.ts
index cc31ede5e..225cdd26b 100644
--- a/packages/joint-react/src/hooks/use-node-layout.ts
+++ b/packages/joint-react/src/hooks/use-node-layout.ts
@@ -54,6 +54,6 @@ export function useNodeLayout<Id extends dia.Cell.ID | undefined = undefined>(
   }
 
   return useStoreSelector(layoutState, (snapshot) => {
-    return snapshot.layouts[actualId];
+    return snapshot.elements[actualId];
   });
 }
diff --git a/packages/joint-react/src/hooks/use-state-to-external-store.ts b/packages/joint-react/src/hooks/use-state-to-external-store.ts
index 051913846..60e84c648 100644
--- a/packages/joint-react/src/hooks/use-state-to-external-store.ts
+++ b/packages/joint-react/src/hooks/use-state-to-external-store.ts
@@ -20,15 +20,15 @@ import type { dia } from '@joint/core';
  * @template Element - The type of elements
  * @template Link - The type of links
  */
-interface Options<Element extends dia.Element | GraphElement, Link extends dia.Link | GraphLink> {
-  /** Current elements array from React state */
-  readonly elements?: Element[];
-  /** Current links array from React state */
-  readonly links?: Link[];
+interface Options<Element extends GraphElement, Link extends GraphLink> {
+  /** Current elements Record from React state, keyed by cell ID */
+  readonly elements?: Record<dia.Cell.ID, Element>;
+  /** Current links Record from React state, keyed by cell ID */
+  readonly links?: Record<dia.Cell.ID, Link>;
   /** Callback function called when elements change */
-  readonly onElementsChange?: Dispatch<SetStateAction<Element[]>>;
+  readonly onElementsChange?: Dispatch<SetStateAction<Record<dia.Cell.ID, Element>>>;
   /** Callback function called when links change */
-  readonly onLinksChange?: Dispatch<SetStateAction<Link[]>>;
+  readonly onLinksChange?: Dispatch<SetStateAction<Record<dia.Cell.ID, Link>>>;
 }
 
 /**
@@ -49,7 +49,7 @@ interface Options<Element extends dia.Element | GraphElement, Link extends dia.L
 export function useStateToExternalStore<Element extends GraphElement, Link extends GraphLink>(
   options: Options<Element, Link>
 ): ExternalStoreLike<GraphStoreSnapshot<Element, Link>> | undefined {
-  const { elements = [], links = [], onElementsChange, onLinksChange } = options;
+  const { elements = {}, links = {}, onElementsChange, onLinksChange } = options;
   const subscribers = useRef<Set<() => void>>(new Set());
   const snapshot = useRef<GraphStoreSnapshot<Element, Link>>({ elements, links });
 
diff --git a/packages/joint-react/src/index.ts b/packages/joint-react/src/index.ts
index a76d7cdea..58969679e 100644
--- a/packages/joint-react/src/index.ts
+++ b/packages/joint-react/src/index.ts
@@ -5,20 +5,19 @@
 export * from './components';
 export * from './hooks';
 
-export * from './utils/cell/cell-utilities';
 export * from './utils/joint-jsx/jsx-to-markup';
 export * from './utils/link-utilities';
 export * from './utils/object-utilities';
 
 export * from './models/react-element';
-export * from './models/react-element-view';
-export * from './models/react-link-view';
+export { ReactPaper } from './models/react-paper';
+export type { IReactPaper } from './models/react-paper.types';
 
 export * from './types/element-types';
 export * from './types/paper.types';
 export * from './types/link-types';
-export * from './types/cell.types';
 export * from './types/event.types';
+export * from './types/scheduler.types';
 
 export * from './context';
 export * from './store';
diff --git a/packages/joint-react/src/models/__tests__/react-element-view.test.ts b/packages/joint-react/src/models/__tests__/react-element-view.test.ts
deleted file mode 100644
index ca43b3958..000000000
--- a/packages/joint-react/src/models/__tests__/react-element-view.test.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-import { ReactElementView } from '../react-element-view';
-
-describe('ReactElementView', () => {
-  it('should be a view class that extends dia.ElementView', () => {
-    expect(ReactElementView).toBeDefined();
-    expect(typeof ReactElementView.extend).toBe('function');
-  });
-});
diff --git a/packages/joint-react/src/models/__tests__/react-element.test.ts b/packages/joint-react/src/models/__tests__/react-element.test.ts
index b65abe8c5..83ace4218 100644
--- a/packages/joint-react/src/models/__tests__/react-element.test.ts
+++ b/packages/joint-react/src/models/__tests__/react-element.test.ts
@@ -56,6 +56,13 @@ describe('react-element', () => {
 
       expect(element).toBeInstanceOf(ReactElement);
     });
+
+    describe('markup', () => {
+      it('should have empty markup array', () => {
+        const element = new ReactElement({ id: 'test' });
+        expect(element.markup).toEqual([]);
+      });
+    });
   });
 
   describe('createElement', () => {
diff --git a/packages/joint-react/src/models/__tests__/react-link-view.test.ts b/packages/joint-react/src/models/__tests__/react-link-view.test.ts
deleted file mode 100644
index 5b8408d7e..000000000
--- a/packages/joint-react/src/models/__tests__/react-link-view.test.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-import { ReactLinkView } from '../react-link-view';
-
-describe('ReactLinkView', () => {
-  it('should be a view class that extends dia.LinkView', () => {
-    expect(ReactLinkView).toBeDefined();
-    expect(typeof ReactLinkView.extend).toBe('function');
-  });
-});
diff --git a/packages/joint-react/src/models/__tests__/react-link.test.ts b/packages/joint-react/src/models/__tests__/react-link.test.ts
new file mode 100644
index 000000000..d5bd6dde3
--- /dev/null
+++ b/packages/joint-react/src/models/__tests__/react-link.test.ts
@@ -0,0 +1,63 @@
+import { ReactLink, REACT_LINK_TYPE } from '../react-link';
+
+describe('ReactLink', () => {
+  describe('markup', () => {
+    it('should have wrapper and line path markup for link rendering', () => {
+      const link = new ReactLink({ id: 'test' });
+      expect(link.markup).toEqual([
+        {
+          tagName: 'path',
+          selector: 'wrapper',
+          attributes: {
+            fill: 'none',
+            cursor: 'pointer',
+            stroke: 'transparent',
+            'stroke-linecap': 'round',
+          },
+        },
+        {
+          tagName: 'path',
+          selector: 'line',
+          attributes: {
+            fill: 'none',
+            'pointer-events': 'none',
+          },
+        },
+      ]);
+    });
+  });
+
+  describe('defaults', () => {
+    it('should have REACT_LINK_TYPE as type', () => {
+      const link = new ReactLink({ id: 'test' });
+      expect(link.get('type')).toBe(REACT_LINK_TYPE);
+    });
+
+    it('should have connection: true attrs for path computation', () => {
+      // This is critical for JointJS to compute the link path (d attribute)
+      // Without connection: true, the path d attribute will be empty/null
+      const link = new ReactLink({ id: 'test' });
+      const attributes = link.get('attrs');
+
+      expect(attributes?.wrapper?.connection).toBe(true);
+      expect(attributes?.line?.connection).toBe(true);
+    });
+
+    it('should have default stroke and strokeWidth for line', () => {
+      const link = new ReactLink({ id: 'test' });
+      const attributes = link.get('attrs');
+
+      expect(attributes?.line?.stroke).toBe('#333333');
+      expect(attributes?.line?.strokeWidth).toBe(2);
+      expect(attributes?.line?.strokeLinejoin).toBe('round');
+    });
+
+    it('should have default strokeWidth for wrapper (click target)', () => {
+      const link = new ReactLink({ id: 'test' });
+      const attributes = link.get('attrs');
+
+      expect(attributes?.wrapper?.strokeWidth).toBe(10);
+      expect(attributes?.wrapper?.strokeLinejoin).toBe('round');
+    });
+  });
+});
diff --git a/packages/joint-react/src/models/__tests__/react-paper.test.ts b/packages/joint-react/src/models/__tests__/react-paper.test.ts
new file mode 100644
index 000000000..d1fc7d281
--- /dev/null
+++ b/packages/joint-react/src/models/__tests__/react-paper.test.ts
@@ -0,0 +1,294 @@
+import { dia, shapes } from '@joint/core';
+import { ReactPaper } from '../react-paper';
+import { GraphStore } from '../../store/graph-store';
+import type { ReactElementViewCache, ReactLinkViewCache } from '../../types/paper.types';
+
+const DEFAULT_CELL_NAMESPACE = shapes;
+
+describe('ReactPaper', () => {
+  let graphStore: GraphStore;
+  let paper: ReactPaper;
+  let container: HTMLElement;
+  let elementCache: ReactElementViewCache;
+  let linkCache: ReactLinkViewCache;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.append(container);
+    graphStore = new GraphStore({});
+
+    // Initialize caches that PaperStore would normally set up
+    elementCache = {
+      elementViews: {},
+      portsData: {},
+    };
+    linkCache = {
+      linkViews: {},
+      linksData: {},
+    };
+  });
+
+  afterEach(() => {
+    paper?.remove();
+    graphStore?.destroy(false);
+    container?.remove();
+  });
+
+  /**
+   * Helper to create a ReactPaper with caches properly initialized
+   */
+  function createPaper(options: Partial<dia.Paper.Options> = {}): ReactPaper {
+    const p = new ReactPaper({
+      el: container,
+      model: graphStore.graph,
+      graphStore,
+      cellNamespace: DEFAULT_CELL_NAMESPACE,
+      async: false, // Synchronous for testing
+      ...options,
+    });
+    p.reactElementCache = elementCache;
+    p.reactLinkCache = linkCache;
+    return p;
+  }
+
+  describe('constructor', () => {
+    it('should create a paper instance', () => {
+      paper = createPaper();
+
+      expect(paper).toBeInstanceOf(dia.Paper);
+    });
+
+    it('should store graphStore reference', () => {
+      paper = createPaper();
+
+      // Access private property for testing
+      expect((paper as unknown as { graphStore: GraphStore }).graphStore).toBe(graphStore);
+    });
+  });
+
+  describe('insertView', () => {
+    it('should add element view to reactElementCache when inserted', () => {
+      paper = createPaper();
+
+      const element = new shapes.standard.Rectangle({
+        id: 'el1',
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      graphStore.graph.addCell(element);
+
+      // After adding cell, view should be in elementCache
+      expect(elementCache.elementViews['el1']).toBeDefined();
+      expect(elementCache.elementViews['el1'].model).toBe(element);
+    });
+
+    it('should add link view to reactLinkCache when inserted', () => {
+      paper = createPaper();
+
+      const element1 = new shapes.standard.Rectangle({
+        id: 'el1',
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const element2 = new shapes.standard.Rectangle({
+        id: 'el2',
+        position: { x: 200, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const link = new shapes.standard.Link({
+        id: 'link1',
+        source: { id: 'el1' },
+        target: { id: 'el2' },
+      });
+      graphStore.graph.addCells([element1, element2, link]);
+
+      expect(linkCache.linkViews['link1']).toBeDefined();
+      expect(linkCache.linkViews['link1'].model).toBe(link);
+    });
+
+    it('should set magnet=false on element views', () => {
+      paper = createPaper();
+
+      const element = new shapes.standard.Rectangle({
+        id: 'el1',
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      graphStore.graph.addCell(element);
+
+      const view = elementCache.elementViews['el1'];
+      expect(view.el.getAttribute('magnet')).toBe('false');
+    });
+
+    it('should NOT set magnet=false on link views', () => {
+      paper = createPaper();
+
+      const element1 = new shapes.standard.Rectangle({
+        id: 'el1',
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const element2 = new shapes.standard.Rectangle({
+        id: 'el2',
+        position: { x: 200, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const link = new shapes.standard.Link({
+        id: 'link1',
+        source: { id: 'el1' },
+        target: { id: 'el2' },
+      });
+      graphStore.graph.addCells([element1, element2, link]);
+
+      const linkView = linkCache.linkViews['link1'];
+      expect(linkView.el.getAttribute('magnet')).not.toBe('false');
+    });
+
+    it('should call schedulePaperUpdate when view is inserted', () => {
+      const scheduleSpy = jest.spyOn(graphStore, 'schedulePaperUpdate');
+
+      paper = createPaper();
+
+      const element = new shapes.standard.Rectangle({
+        id: 'el1',
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      graphStore.graph.addCell(element);
+
+      expect(scheduleSpy).toHaveBeenCalled();
+    });
+  });
+
+  describe('removeView', () => {
+    it('should remove view from reactElementCache when cell is removed', () => {
+      paper = createPaper();
+
+      const element = new shapes.standard.Rectangle({
+        id: 'el1',
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      graphStore.graph.addCell(element);
+      expect(elementCache.elementViews['el1']).toBeDefined();
+
+      graphStore.graph.removeCells([element]);
+      expect(elementCache.elementViews['el1']).toBeUndefined();
+    });
+
+    it('should remove view from reactLinkCache when link is removed', () => {
+      paper = createPaper();
+
+      const element1 = new shapes.standard.Rectangle({
+        id: 'el1',
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const element2 = new shapes.standard.Rectangle({
+        id: 'el2',
+        position: { x: 200, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const link = new shapes.standard.Link({
+        id: 'link1',
+        source: { id: 'el1' },
+        target: { id: 'el2' },
+      });
+      graphStore.graph.addCells([element1, element2, link]);
+      expect(linkCache.linkViews['link1']).toBeDefined();
+
+      graphStore.graph.removeCells([link]);
+      expect(linkCache.linkViews['link1']).toBeUndefined();
+    });
+
+    it('should call schedulePaperUpdate when view is removed', () => {
+      paper = createPaper();
+
+      const element = new shapes.standard.Rectangle({
+        id: 'el1',
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      graphStore.graph.addCell(element);
+
+      const scheduleSpy = jest.spyOn(graphStore, 'schedulePaperUpdate');
+      scheduleSpy.mockClear();
+
+      graphStore.graph.removeCells([element]);
+      expect(scheduleSpy).toHaveBeenCalled();
+    });
+  });
+
+  describe('_hideCellView (viewport culling)', () => {
+    it('should remove element view from reactElementCache when hidden', () => {
+      paper = createPaper({
+        width: 100,
+        height: 100,
+      });
+
+      const element = new shapes.standard.Rectangle({
+        id: 'el1',
+        position: { x: 0, y: 0 },
+        size: { width: 50, height: 50 },
+      });
+      graphStore.graph.addCell(element);
+      expect(elementCache.elementViews['el1']).toBeDefined();
+
+      // Get the view and call _hideCellView directly
+      const view = paper.findViewByModel(element);
+      paper._hideCellView(view);
+
+      expect(elementCache.elementViews['el1']).toBeUndefined();
+    });
+
+    it('should remove link view from reactLinkCache when hidden', () => {
+      paper = createPaper({
+        width: 100,
+        height: 100,
+      });
+
+      const element1 = new shapes.standard.Rectangle({
+        id: 'el1',
+        position: { x: 0, y: 0 },
+        size: { width: 50, height: 50 },
+      });
+      const element2 = new shapes.standard.Rectangle({
+        id: 'el2',
+        position: { x: 200, y: 0 },
+        size: { width: 50, height: 50 },
+      });
+      const link = new shapes.standard.Link({
+        id: 'link1',
+        source: { id: 'el1' },
+        target: { id: 'el2' },
+      });
+      graphStore.graph.addCells([element1, element2, link]);
+      expect(linkCache.linkViews['link1']).toBeDefined();
+
+      // Get the link view and call _hideCellView directly
+      const linkView = paper.findViewByModel(link);
+      paper._hideCellView(linkView);
+
+      expect(linkCache.linkViews['link1']).toBeUndefined();
+    });
+
+    it('should call schedulePaperUpdate when view is hidden', () => {
+      paper = createPaper();
+
+      const element = new shapes.standard.Rectangle({
+        id: 'el1',
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      graphStore.graph.addCell(element);
+
+      const scheduleSpy = jest.spyOn(graphStore, 'schedulePaperUpdate');
+      scheduleSpy.mockClear();
+
+      const view = paper.findViewByModel(element);
+      paper._hideCellView(view);
+
+      expect(scheduleSpy).toHaveBeenCalled();
+    });
+  });
+});
diff --git a/packages/joint-react/src/models/__tests__/view-extension.test.ts b/packages/joint-react/src/models/__tests__/view-extension.test.ts
deleted file mode 100644
index 0a47ccb14..000000000
--- a/packages/joint-react/src/models/__tests__/view-extension.test.ts
+++ /dev/null
@@ -1,39 +0,0 @@
-import { ReactElementView, ReactLinkView } from '../../index';
-
-describe('View Extension', () => {
-  describe('ReactElementView', () => {
-    it('should be defined and extendable', () => {
-      expect(ReactElementView).toBeDefined();
-      expect(typeof ReactElementView.extend).toBe('function');
-    });
-
-    it('should allow extending with custom behavior', () => {
-      const CustomView = ReactElementView.extend({
-        customMethod() {
-          return 'custom';
-        },
-      });
-
-      expect(CustomView).toBeDefined();
-      expect(typeof CustomView.extend).toBe('function');
-    });
-  });
-
-  describe('ReactLinkView', () => {
-    it('should be defined and extendable', () => {
-      expect(ReactLinkView).toBeDefined();
-      expect(typeof ReactLinkView.extend).toBe('function');
-    });
-
-    it('should allow extending with custom behavior', () => {
-      const CustomView = ReactLinkView.extend({
-        customMethod() {
-          return 'custom';
-        },
-      });
-
-      expect(CustomView).toBeDefined();
-      expect(typeof CustomView.extend).toBe('function');
-    });
-  });
-});
diff --git a/packages/joint-react/src/models/react-element-view.ts b/packages/joint-react/src/models/react-element-view.ts
deleted file mode 100644
index ff4db412e..000000000
--- a/packages/joint-react/src/models/react-element-view.ts
+++ /dev/null
@@ -1,68 +0,0 @@
-import { dia } from '@joint/core';
-import type { PortElementsCacheEntry } from '../store/paper-store';
-import type { ReactPaper } from '../types/paper.types';
-
-export type {
-  ReactElementViewCache,
-  ReactElementViewGraphStoreRef,
-  ReactElementViewPaperStoreRef,
-} from '../types/paper.types';
-
-/**
- * Custom JointJS ElementView class for React element rendering.
- *
- * This class extends dia.ElementView and:
- * - Disables magnet behavior on elements
- * - Tracks element views in the cache for React portal rendering
- * - Handles port rendering with custom portal element caching
- *
- * Dependencies are accessed through `this.paper` which must have
- * `reactElementCache`, `reactElementGraphStore`, and `reactElementPaperStore` properties.
- * @example
- * ```typescript
- * // Use ReactElementView with a paper that has React properties
- * const paper = new dia.Paper({ elementView: ReactElementView });
- * paper.reactElementCache = { elementViews: {}, portsData: {} };
- * paper.reactElementGraphStore = graphStore;
- * paper.reactElementPaperStore = paperStore;
- * ```
- */
-export const ReactElementView = dia.ElementView.extend({
-  renderMarkup() {
-    const ele: HTMLElement = this.vel;
-    ele.setAttribute('magnet', 'false');
-    const selectors = (this.selectors = {} as Record<string, SVGElement | SVGElement[]>);
-    selectors[this.selector] = this.el;
-  },
-  onRender() {
-    // eslint-disable-next-line unicorn/no-this-assignment, @typescript-eslint/no-this-alias
-    const view: dia.ElementView = this;
-    const paper = view.paper as ReactPaper;
-    const { reactElementCache, reactElementGraphStore } = paper;
-
-    const cellId = view.model.id as dia.Cell.ID;
-    reactElementCache.elementViews = {
-      ...reactElementCache.elementViews,
-      [cellId]: view,
-    };
-    reactElementGraphStore.schedulePaperUpdate();
-  },
-  _renderPorts() {
-    // @ts-expect-error we use private jointjs api
-    dia.ElementView.prototype._renderPorts.call(this);
-    // eslint-disable-next-line unicorn/no-this-assignment, @typescript-eslint/no-this-alias
-    const view: dia.ElementView = this;
-    const paper = view.paper as ReactPaper;
-    const { reactElementCache, reactElementGraphStore, reactElementPaperStore } = paper;
-
-    const portElementsCache: Record<string, PortElementsCacheEntry> = this._portElementsCache;
-    const newPorts = reactElementPaperStore.getNewPorts({
-      state: reactElementGraphStore.internalState,
-      cellId: view.model.id as dia.Cell.ID,
-      portElementsCache,
-      portsData: reactElementCache.portsData,
-    });
-    reactElementCache.portsData = newPorts ?? {};
-    reactElementGraphStore.schedulePaperUpdate();
-  },
-});
diff --git a/packages/joint-react/src/models/react-element.tsx b/packages/joint-react/src/models/react-element.tsx
index be2856330..76573fa67 100644
--- a/packages/joint-react/src/models/react-element.tsx
+++ b/packages/joint-react/src/models/react-element.tsx
@@ -18,6 +18,11 @@ export const REACT_TYPE = 'ReactElement';
 export class ReactElement<Attributes = dia.Element.Attributes> extends dia.Element<
   dia.Element.Attributes & Attributes
 > {
+  /**
+   * Empty markup - React will render content via portal into view.el
+   */
+  markup: dia.MarkupJSON = [];
+
   /**
    * Sets the default attributes for the ReactElement.
    * @returns The default attributes.
diff --git a/packages/joint-react/src/models/react-link-view.ts b/packages/joint-react/src/models/react-link-view.ts
deleted file mode 100644
index 5c6fc8a47..000000000
--- a/packages/joint-react/src/models/react-link-view.ts
+++ /dev/null
@@ -1,121 +0,0 @@
-/* eslint-disable sonarjs/cognitive-complexity */
-import { dia, util } from '@joint/core';
-import type { ReactPaper } from '../types/paper.types';
-
-export type {
-  ReactLinkViewCache,
-  ReactLinkViewGraphStoreRef,
-  ReactLinkViewPaperStoreRef,
-} from '../types/paper.types';
-
-/**
- * Custom JointJS LinkView class for React link rendering.
- *
- * This class extends dia.LinkView and:
- * - Tracks link views in the cache for React portal rendering
- * - Handles label rendering with support for React-rendered labels
- * - Manages label cleanup for dynamic React labels
- *
- * Dependencies are accessed through `this.paper` which must have
- * `reactLinkCache`, `reactLinkGraphStore`, and `reactLinkPaperStore` properties.
- * @example
- * ```typescript
- * // Use ReactLinkView with a paper that has React properties
- * const paper = new dia.Paper({ linkView: ReactLinkView });
- * paper.reactLinkCache = { linkViews: {}, linksData: {} };
- * paper.reactLinkGraphStore = graphStore;
- * paper.reactLinkPaperStore = paperStore;
- * ```
- */
-export const ReactLinkView = dia.LinkView.extend({
-  onRender() {
-    // eslint-disable-next-line unicorn/no-this-assignment, @typescript-eslint/no-this-alias
-    const view: dia.LinkView = this;
-    const paper = view.paper as ReactPaper;
-    const { reactLinkCache, reactLinkGraphStore } = paper;
-
-    const linkId = view.model.id as dia.Cell.ID;
-    reactLinkCache.linkViews = {
-      ...reactLinkCache.linkViews,
-      [linkId]: view,
-    };
-    reactLinkGraphStore.flushPendingUpdates();
-    reactLinkGraphStore.schedulePaperUpdate();
-  },
-  renderLabels() {
-    // @ts-expect-error renderLabels exists on LinkView but not in types
-    dia.LinkView.prototype.renderLabels.call(this);
-
-    // eslint-disable-next-line unicorn/no-this-assignment, @typescript-eslint/no-this-alias
-    const view: dia.LinkView = this;
-    const paper = view.paper as ReactPaper;
-    const { reactLinkCache, reactLinkGraphStore, reactLinkPaperStore } = paper;
-
-    const linkId = view.model.id as dia.Cell.ID;
-    const link = view.model;
-    // @ts-expect-error we use private jointjs api
-    const labelCache: Record<number, SVGElement> = view._labelCache;
-    // @ts-expect-error we use private jointjs api
-    const labelSelectors: Record<number, Record<string, SVGElement>> = view._labelSelectors;
-
-    if (!labelCache || !labelSelectors) {
-      return this;
-    }
-
-    const newLinksData = { ...reactLinkCache.linksData };
-    let isChanged = false;
-
-    const existingLabelIds = new Set<string>();
-    for (const labelId in reactLinkCache.linksData) {
-      if (labelId.startsWith(`${linkId}-label-`)) {
-        existingLabelIds.add(labelId);
-      }
-    }
-
-    const linkLabels = link.isLink() ? link.labels() : [];
-    for (const labelIndex in labelCache) {
-      const index = Number.parseInt(labelIndex, 10);
-      const label = linkLabels[index];
-
-      if (!label || !('labelId' in label)) {
-        continue;
-      }
-
-      const portalElement = labelCache[index];
-      if (!portalElement) {
-        continue;
-      }
-
-      const linkLabelId = reactLinkPaperStore.getLinkLabelId(linkId, index);
-      existingLabelIds.delete(linkLabelId);
-
-      if (util.isEqual(newLinksData[linkLabelId], portalElement)) {
-        continue;
-      }
-      if (!portalElement.isConnected) {
-        continue;
-      }
-      isChanged = true;
-      newLinksData[linkLabelId] = portalElement;
-    }
-
-    if (existingLabelIds.size > 0) {
-      const hasRenderedLabels = Object.keys(labelCache).length > 0;
-      const linkHasLabels = link.isLink() && link.labels().length > 0;
-      if (hasRenderedLabels || !linkHasLabels) {
-        for (const removedLabelId of existingLabelIds) {
-          // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
-          delete newLinksData[removedLabelId];
-        }
-        isChanged = true;
-      }
-    }
-
-    if (isChanged && !util.isEqual(reactLinkCache.linksData, newLinksData)) {
-      reactLinkCache.linksData = newLinksData;
-      reactLinkGraphStore.schedulePaperUpdate();
-    }
-
-    return this;
-  },
-});
diff --git a/packages/joint-react/src/models/react-link.ts b/packages/joint-react/src/models/react-link.ts
index 2be2b4812..94407973b 100644
--- a/packages/joint-react/src/models/react-link.ts
+++ b/packages/joint-react/src/models/react-link.ts
@@ -3,6 +3,7 @@ export const REACT_LINK_TYPE = 'ReactLink';
 
 /**
  * A custom JointJS link that can render React components.
+ * Uses empty markup - React renders content via portal using useLinkPath hook.
  * @group Models
  * @example
  * ```ts
@@ -20,36 +21,30 @@ export class ReactLink<Attributes = dia.Link.Attributes> extends dia.Link<
 > {
   /**
    * Sets the default attributes for the ReactLink.
+   * Includes `connection: true` attrs which are required for JointJS to compute link paths.
    * @returns The default attributes.
    */
   defaults() {
     return {
       ...super.defaults,
+      type: REACT_LINK_TYPE,
       attrs: {
-        line: {
+        wrapper: {
           connection: true,
-          stroke: '#333333',
-          strokeWidth: 2,
+          strokeWidth: 10,
           strokeLinejoin: 'round',
-          targetMarker: {
-            type: 'path',
-            d: 'M 10 -5 0 0 10 5 z',
-          },
         },
-        wrapper: {
+        line: {
           connection: true,
-          strokeWidth: 10,
+          stroke: '#333333',
+          strokeWidth: 2,
           strokeLinejoin: 'round',
         },
       },
-      // defaultLabel: {
-      //   markup: []
-      // },
-      type: REACT_LINK_TYPE,
     } as unknown as dia.Link.Attributes & Attributes;
   }
 
-  markup: string | dia.MarkupJSON = [
+  markup: dia.MarkupJSON = [
     {
       tagName: 'path',
       selector: 'wrapper',
diff --git a/packages/joint-react/src/models/react-paper.ts b/packages/joint-react/src/models/react-paper.ts
new file mode 100644
index 000000000..59c0bdc54
--- /dev/null
+++ b/packages/joint-react/src/models/react-paper.ts
@@ -0,0 +1,127 @@
+import { dia } from '@joint/core';
+import type { GraphStore } from '../store/graph-store';
+import type { ReactPaperOptions } from './react-paper.types';
+import type { ReactElementViewCache, ReactLinkViewCache } from '../types/paper.types';
+
+/**
+ * Extended Paper class that manages React view lifecycle.
+ *
+ * ReactPaper centralizes view management by:
+ * - Tracking mounted views in React caches for portal rendering
+ * - Scheduling React updates when views mount/unmount
+ * - Disabling magnets on React elements
+ * @example
+ * ```typescript
+ * const paper = new ReactPaper({
+ *   el: container,
+ *   model: graph,
+ *   graphStore,
+ * });
+ * ```
+ */
+export class ReactPaper extends dia.Paper {
+  /** Reference to GraphStore for scheduling updates */
+  private graphStore: GraphStore;
+
+  /** Cache for element views - set by PaperStore */
+  public reactElementCache!: ReactElementViewCache;
+
+  /** Cache for link views - set by PaperStore */
+  public reactLinkCache!: ReactLinkViewCache;
+
+  constructor(options: ReactPaperOptions) {
+    super(options);
+    this.graphStore = options.graphStore;
+  }
+
+  /**
+   * Called when a view is mounted into the DOM.
+   * Adds view to appropriate cache and schedules React update.
+   * @param view - The cell view being inserted
+   * @param isInitialInsert - Whether this is the initial insert
+   */
+  insertView(view: dia.CellView, isInitialInsert: boolean): void {
+    // Call parent implementation first
+    super.insertView(view, isInitialInsert);
+
+    const cellId = view.model.id;
+
+    if (view.model.isElement()) {
+      // Disable magnet on React elements (prevents them from being connection targets)
+      view.el.setAttribute('magnet', 'false');
+
+      // Add to element views cache
+      this.reactElementCache.elementViews = {
+        ...this.reactElementCache.elementViews,
+        [cellId]: view as dia.ElementView,
+      };
+    } else if (view.model.isLink()) {
+      const linkView = view as dia.LinkView;
+
+      // Add to link views cache
+      this.reactLinkCache.linkViews = {
+        ...this.reactLinkCache.linkViews,
+        [cellId]: linkView,
+      };
+    }
+
+    // Schedule React update
+    this.graphStore.schedulePaperUpdate();
+  }
+
+  /**
+   * Called when a cell is deleted from the graph.
+   * Removes view from appropriate cache and schedules React update.
+   * @param cell - The cell being removed
+   * @returns The removed cell view
+   */
+  removeView(cell: dia.Cell): dia.CellView {
+    const cellId = cell.id;
+
+    if (cell.isElement()) {
+      // Remove from element views cache
+      const newElementViews = { ...this.reactElementCache.elementViews };
+      Reflect.deleteProperty(newElementViews, cellId);
+      this.reactElementCache.elementViews = newElementViews;
+    } else if (cell.isLink()) {
+      // Remove from link views cache
+      const newLinkViews = { ...this.reactLinkCache.linkViews };
+      Reflect.deleteProperty(newLinkViews, cellId);
+      this.reactLinkCache.linkViews = newLinkViews;
+    }
+
+    // Schedule React update
+    this.graphStore.schedulePaperUpdate();
+
+    // Call parent implementation
+    return super.removeView(cell);
+  }
+
+  /**
+   * Called when a view is hidden (viewport culling).
+   * Removes view from appropriate cache and schedules React update.
+   * @param cellView - The cell view being hidden
+   * @internal
+   */
+  _hideCellView(cellView: dia.CellView): void {
+    const cellId = cellView.model.id;
+
+    if (cellView.model.isElement()) {
+      // Remove from element views cache
+      const newElementViews = { ...this.reactElementCache.elementViews };
+      Reflect.deleteProperty(newElementViews, cellId);
+      this.reactElementCache.elementViews = newElementViews;
+    } else if (cellView.model.isLink()) {
+      // Remove from link views cache
+      const newLinkViews = { ...this.reactLinkCache.linkViews };
+      Reflect.deleteProperty(newLinkViews, cellId);
+      this.reactLinkCache.linkViews = newLinkViews;
+    }
+
+    // Schedule React update
+    this.graphStore.schedulePaperUpdate();
+
+    // Call parent implementation
+    super._hideCellView(cellView);
+  }
+}
diff --git a/packages/joint-react/src/models/react-paper.types.ts b/packages/joint-react/src/models/react-paper.types.ts
new file mode 100644
index 000000000..e63d042af
--- /dev/null
+++ b/packages/joint-react/src/models/react-paper.types.ts
@@ -0,0 +1,28 @@
+import type { dia } from '@joint/core';
+import type { GraphStore } from '../store/graph-store';
+
+/**
+ * Options for creating a ReactPaper instance.
+ * Extends dia.Paper.Options with required graphStore reference.
+ */
+export interface ReactPaperOptions extends dia.Paper.Options {
+  /** Reference to the GraphStore for scheduling updates */
+  readonly graphStore: GraphStore;
+}
+
+/**
+ * Extended Paper class with React-specific view management.
+ * Uses reactElementCache and reactLinkCache to track mounted views for portal rendering.
+ */
+export interface IReactPaper extends dia.Paper {
+  /** Cache for element views - managed by ReactPaper */
+  readonly reactElementCache: {
+    elementViews: Record<dia.Cell.ID, dia.ElementView>;
+    portsData: Record<string, SVGElement>;
+  };
+  /** Cache for link views - managed by ReactPaper */
+  readonly reactLinkCache: {
+    linkViews: Record<dia.Cell.ID, dia.LinkView>;
+    linksData: Record<string, SVGElement>;
+  };
+}
diff --git a/packages/joint-react/src/state/__tests__/graph-state-selectors.test.ts b/packages/joint-react/src/state/__tests__/graph-state-selectors.test.ts
index 25dcb00d8..c438d2d1a 100644
--- a/packages/joint-react/src/state/__tests__/graph-state-selectors.test.ts
+++ b/packages/joint-react/src/state/__tests__/graph-state-selectors.test.ts
@@ -5,9 +5,9 @@ import { ReactElement } from '../../models/react-element';
 import type { GraphElement } from '../../types/element-types';
 import type { GraphLink } from '../../types/link-types';
 import {
-  defaultGraphToElementSelector,
+  mapElementAttributesToData,
   defaultMapDataToElementAttributes,
-  defaultGraphToLinkSelector,
+  mapLinkAttributesToData,
   defaultMapDataToLinkAttributes,
   createDefaultElementMapper,
   createDefaultGraphToElementMapper,
@@ -23,19 +23,23 @@ const DEFAULT_CELL_NAMESPACE = { ...shapes, ReactElement };
 
 // Helper functions to create options with defaultAttributes
 const createElementToGraphOptions = <E extends GraphElement>(
+  id: string,
   data: E,
   graph: dia.Graph
 ): ElementToGraphOptions<E> => ({
+  id,
   data,
   graph,
-  defaultAttributes: createDefaultElementMapper(data),
+  defaultAttributes: createDefaultElementMapper(id, data),
 });
 
 const createGraphToElementOptions = <E extends GraphElement>(
+  id: string,
   cell: dia.Element,
   graph: dia.Graph,
   previous?: E
 ): GraphToElementOptions<E> => ({
+  id,
   cell,
   graph,
   previous,
@@ -43,19 +47,23 @@ const createGraphToElementOptions = <E extends GraphElement>(
 });
 
 const createLinkToGraphOptions = <L extends GraphLink>(
+  id: string,
   data: L,
   graph: dia.Graph
 ): LinkToGraphOptions<L> => ({
+  id,
   data,
   graph,
-  defaultAttributes: createDefaultLinkMapper(data, graph),
+  defaultAttributes: createDefaultLinkMapper(id, data, graph),
 });
 
 const createGraphToLinkOptions = <L extends GraphLink>(
+  id: string,
   cell: dia.Link,
   graph: dia.Graph,
   previous?: L
 ): GraphToLinkOptions<L> => ({
+  id,
   cell,
   graph,
   previous,
@@ -75,8 +83,8 @@ describe('graph-state-selectors', () => {
 
   describe('defaultAttributes function', () => {
     it('should pass defaultAttributes in ElementToGraphOptions', () => {
+      const id = 'element-1';
       const data: GraphElement = {
-        id: 'element-1',
         x: 100,
         y: 50,
         width: 200,
@@ -90,7 +98,7 @@ describe('graph-state-selectors', () => {
         return options.defaultAttributes();
       };
 
-      const options = createElementToGraphOptions(data, graph);
+      const options = createElementToGraphOptions(id, data, graph);
       customSelector(options);
 
       expect(receivedDefaultMapper).toBeDefined();
@@ -99,8 +107,8 @@ describe('graph-state-selectors', () => {
 
   describe('defaultMapDataToElementAttributes', () => {
     it('should map element to graph cell JSON', () => {
+      const id = 'element-1';
       const data: GraphElement = {
-        id: 'element-1',
         x: 10,
         y: 20,
         width: 100,
@@ -108,7 +116,7 @@ describe('graph-state-selectors', () => {
         type: 'ReactElement',
       };
 
-      const options = createElementToGraphOptions(data, graph);
+      const options = createElementToGraphOptions(id, data, graph);
 
       const elementAsGraphJson = defaultMapDataToElementAttributes(options);
 
@@ -123,12 +131,11 @@ describe('graph-state-selectors', () => {
       graph.syncCells([elementAsGraphJson], { remove: true });
 
       const cell = graph.getCell('element-1') as dia.Element<dia.Element.Attributes>;
-      const elementFromGraph = defaultGraphToElementSelector(
-        createGraphToElementOptions(cell, graph)
+      const elementFromGraph = mapElementAttributesToData(
+        createGraphToElementOptions(id, cell, graph)
       );
 
       expect(elementFromGraph).toMatchObject({
-        id: 'element-1',
         x: 10,
         y: 20,
         width: 100,
@@ -137,15 +144,15 @@ describe('graph-state-selectors', () => {
     });
 
     it('should handle element without type (defaults to REACT_TYPE)', () => {
+      const id = 'element-1';
       const data: GraphElement = {
-        id: 'element-1',
         x: 10,
         y: 20,
         width: 100,
         height: 50,
       };
 
-      const options = createElementToGraphOptions(data, graph);
+      const options = createElementToGraphOptions(id, data, graph);
 
       const elementAsGraphJson = defaultMapDataToElementAttributes(options);
 
@@ -155,12 +162,11 @@ describe('graph-state-selectors', () => {
       graph.syncCells([elementAsGraphJson], { remove: true });
 
       const cell = graph.getCell('element-1') as dia.Element<dia.Element.Attributes>;
-      const elementFromGraph = defaultGraphToElementSelector(
-        createGraphToElementOptions(cell, graph)
+      const elementFromGraph = mapElementAttributesToData(
+        createGraphToElementOptions(id, cell, graph)
       );
 
       expect(elementFromGraph).toMatchObject({
-        id: 'element-1',
         x: 10,
         y: 20,
         width: 100,
@@ -169,8 +175,8 @@ describe('graph-state-selectors', () => {
     });
 
     it('should preserve all element properties', () => {
+      const id = 'element-1';
       const data: GraphElement = {
-        id: 'element-1',
         x: 10,
         y: 20,
         width: 100,
@@ -180,7 +186,7 @@ describe('graph-state-selectors', () => {
         angle: 45,
       };
 
-      const options = createElementToGraphOptions(data, graph);
+      const options = createElementToGraphOptions(id, data, graph);
 
       const elementAsGraphJson = defaultMapDataToElementAttributes(options);
 
@@ -194,12 +200,11 @@ describe('graph-state-selectors', () => {
       graph.syncCells([elementAsGraphJson], { remove: true });
 
       const cell = graph.getCell('element-1') as dia.Element<dia.Element.Attributes>;
-      const elementFromGraph = defaultGraphToElementSelector(
-        createGraphToElementOptions(cell, graph)
+      const elementFromGraph = mapElementAttributesToData(
+        createGraphToElementOptions(id, cell, graph)
       );
 
       expect(elementFromGraph).toMatchObject({
-        id: 'element-1',
         x: 10,
         y: 20,
         width: 100,
@@ -210,8 +215,9 @@ describe('graph-state-selectors', () => {
     });
   });
 
-  describe('defaultGraphToElementSelector', () => {
+  describe('mapElementAttributesToData', () => {
     it('should map graph cell to element without previous state', () => {
+      const id = 'element-1';
       const elementAsGraphJson = {
         type: 'ReactElement',
         position: { x: 10, y: 20 },
@@ -221,12 +227,11 @@ describe('graph-state-selectors', () => {
       graph.syncCells([elementAsGraphJson], { remove: true });
       const cell = graph.getCell('element-1') as dia.Element;
 
-      const options = createGraphToElementOptions(cell, graph);
+      const options = createGraphToElementOptions(id, cell, graph);
 
-      const elementFromGraph = defaultGraphToElementSelector(options);
+      const elementFromGraph = mapElementAttributesToData(options);
 
       expect(elementFromGraph).toMatchObject({
-        id: 'element-1',
         x: 10,
         y: 20,
         width: 100,
@@ -235,18 +240,17 @@ describe('graph-state-selectors', () => {
 
       // Round-trip: element → graph → element
       const recreatedElementAsGraphJson = defaultMapDataToElementAttributes(
-        createElementToGraphOptions(elementFromGraph, graph)
+        createElementToGraphOptions(id, elementFromGraph, graph)
       );
       graph.clear();
       graph.syncCells([recreatedElementAsGraphJson], { remove: true });
 
       const roundTripCell = graph.getCell('element-1') as dia.Element<dia.Element.Attributes>;
-      const elementFromRoundTrip = defaultGraphToElementSelector(
-        createGraphToElementOptions(roundTripCell, graph)
+      const elementFromRoundTrip = mapElementAttributesToData(
+        createGraphToElementOptions(id, roundTripCell, graph)
       );
 
       expect(elementFromRoundTrip).toMatchObject({
-        id: 'element-1',
         x: 10,
         y: 20,
         width: 100,
@@ -255,6 +259,7 @@ describe('graph-state-selectors', () => {
     });
 
     it('should map graph cell to element with previous state, filtering properties', () => {
+      const id = 'element-1';
       const elementAsGraphJson = {
         type: 'ReactElement',
         position: { x: 10, y: 20 },
@@ -271,7 +276,6 @@ describe('graph-state-selectors', () => {
       };
 
       const previous: ExtendedElement = {
-        id: 'element-1',
         x: 5,
         y: 15,
         width: 80,
@@ -280,13 +284,12 @@ describe('graph-state-selectors', () => {
         // extraProp is not in previous, so it should be filtered out
       };
 
-      const options = createGraphToElementOptions(cell, graph, previous);
+      const options = createGraphToElementOptions(id, cell, graph, previous);
 
-      const result = defaultGraphToElementSelector(options);
+      const result = mapElementAttributesToData(options);
 
       // Should only include properties that exist in previous state
       expect(result).toMatchObject({
-        id: 'element-1',
         x: 10, // Updated from graph
         y: 20, // Updated from graph
         width: 100, // Updated from graph
@@ -299,6 +302,7 @@ describe('graph-state-selectors', () => {
     });
 
     it('should preserve undefined properties from previous state', () => {
+      const id = 'element-1';
       const elementAsGraphJson = {
         type: 'ReactElement',
         position: { x: 10, y: 20 },
@@ -313,7 +317,6 @@ describe('graph-state-selectors', () => {
       };
 
       const previous: ExtendedElement = {
-        id: 'element-1',
         x: 5,
         y: 15,
         width: 80,
@@ -321,9 +324,9 @@ describe('graph-state-selectors', () => {
         customProp: undefined, // Explicitly undefined in previous
       };
 
-      const options = createGraphToElementOptions(cell, graph, previous);
+      const options = createGraphToElementOptions(id, cell, graph, previous);
 
-      const result = defaultGraphToElementSelector(options);
+      const result = mapElementAttributesToData(options);
 
       // Should include customProp even though it's undefined in previous
       expect(result).toHaveProperty('customProp');
@@ -331,6 +334,7 @@ describe('graph-state-selectors', () => {
     });
 
     it('should handle element with non-REACT_TYPE', () => {
+      const id = 'element-1';
       const elementAsGraphJson = {
         type: 'standard.Rectangle',
         position: { x: 10, y: 20 },
@@ -340,14 +344,15 @@ describe('graph-state-selectors', () => {
       graph.syncCells([elementAsGraphJson], { remove: true });
       const cell = graph.getCell('element-1') as dia.Element;
 
-      const options = createGraphToElementOptions(cell, graph);
+      const options = createGraphToElementOptions(id, cell, graph);
 
-      const elementFromGraph = defaultGraphToElementSelector(options);
+      const elementFromGraph = mapElementAttributesToData(options);
 
-      expect(elementFromGraph.type).toBe('standard.Rectangle');
+      expect(elementFromGraph.type).toBeUndefined();
     });
 
     it('should extract ports from cell', () => {
+      const id = 'element-1';
       const ports = {
         items: [
           {
@@ -366,9 +371,9 @@ describe('graph-state-selectors', () => {
       graph.syncCells([elementAsGraphJson], { remove: true });
       const cell = graph.getCell('element-1') as dia.Element;
 
-      const options = createGraphToElementOptions(cell, graph);
+      const options = createGraphToElementOptions(id, cell, graph);
 
-      const result = defaultGraphToElementSelector(options);
+      const result = mapElementAttributesToData(options);
 
       expect(result.ports).toEqual(ports);
     });
@@ -376,14 +381,14 @@ describe('graph-state-selectors', () => {
 
   describe('defaultMapDataToLinkAttributes', () => {
     it('should map link to graph cell JSON', () => {
+      const id = 'link-1';
       const link: GraphLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
       };
 
-      const options = createLinkToGraphOptions(link, graph);
+      const options = createLinkToGraphOptions(id, link, graph);
 
       const linkAsGraphJson = defaultMapDataToLinkAttributes(options);
 
@@ -398,10 +403,9 @@ describe('graph-state-selectors', () => {
       graph.syncCells([linkAsGraphJson], { remove: true });
 
       const linkCell = graph.getCell('link-1') as dia.Link<dia.Link.Attributes>;
-      const linkFromGraph = defaultGraphToLinkSelector(createGraphToLinkOptions(linkCell, graph));
+      const linkFromGraph = mapLinkAttributesToData(createGraphToLinkOptions(id, linkCell, graph));
 
       expect(linkFromGraph).toMatchObject({
-        id: 'link-1',
         source: { id: 'element-1' },
         target: { id: 'element-2' },
         type: 'standard.Link',
@@ -409,14 +413,14 @@ describe('graph-state-selectors', () => {
     });
 
     it('should handle link with object source and target', () => {
+      const id = 'link-1';
       const link: GraphLink = {
-        id: 'link-1',
         source: { id: 'element-1', port: 'port-1' },
         target: { id: 'element-2', port: 'port-2' },
         type: 'standard.Link',
       };
 
-      const options = createLinkToGraphOptions(link, graph);
+      const options = createLinkToGraphOptions(id, link, graph);
 
       const linkAsGraphJson = defaultMapDataToLinkAttributes(options);
 
@@ -431,10 +435,9 @@ describe('graph-state-selectors', () => {
       graph.syncCells([linkAsGraphJson], { remove: true });
 
       const linkCell = graph.getCell('link-1') as dia.Link<dia.Link.Attributes>;
-      const linkFromGraph = defaultGraphToLinkSelector(createGraphToLinkOptions(linkCell, graph));
+      const linkFromGraph = mapLinkAttributesToData(createGraphToLinkOptions(id, linkCell, graph));
 
       expect(linkFromGraph).toMatchObject({
-        id: 'link-1',
         source: { id: 'element-1', port: 'port-1' },
         target: { id: 'element-2', port: 'port-2' },
         type: 'standard.Link',
@@ -442,8 +445,8 @@ describe('graph-state-selectors', () => {
     });
 
     it('should merge attrs with defaults from cell namespace', () => {
+      const id = 'link-1';
       const link: GraphLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
@@ -454,7 +457,7 @@ describe('graph-state-selectors', () => {
         },
       };
 
-      const options = createLinkToGraphOptions(link, graph);
+      const options = createLinkToGraphOptions(id, link, graph);
 
       const linkAsGraphJson = defaultMapDataToLinkAttributes(options);
 
@@ -463,8 +466,8 @@ describe('graph-state-selectors', () => {
     });
 
     it('should preserve all link properties', () => {
+      const id = 'link-1';
       const link: GraphLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
@@ -473,7 +476,7 @@ describe('graph-state-selectors', () => {
         defaultLabel: { markup: [{ tagName: 'text' }] },
       };
 
-      const options = createLinkToGraphOptions(link, graph);
+      const options = createLinkToGraphOptions(id, link, graph);
 
       const linkAsGraphJson = defaultMapDataToLinkAttributes(options);
 
@@ -486,8 +489,9 @@ describe('graph-state-selectors', () => {
     });
   });
 
-  describe('defaultGraphToLinkSelector', () => {
+  describe('mapLinkAttributesToData', () => {
     it('should map graph link to link without previous state', () => {
+      const id = 'link-1';
       const linkAsGraphJson = {
         type: 'standard.Link',
         source: { id: 'element-1' },
@@ -498,12 +502,11 @@ describe('graph-state-selectors', () => {
       graph.syncCells([linkAsGraphJson], { remove: true });
       const linkCell = graph.getCell('link-1') as dia.Link;
 
-      const options = createGraphToLinkOptions(linkCell, graph);
+      const options = createGraphToLinkOptions(id, linkCell, graph);
 
-      const linkFromGraph = defaultGraphToLinkSelector(options);
+      const linkFromGraph = mapLinkAttributesToData(options);
 
       expect(linkFromGraph).toMatchObject({
-        id: 'link-1',
         source: { id: 'element-1' },
         target: { id: 'element-2' },
         type: 'standard.Link',
@@ -512,6 +515,7 @@ describe('graph-state-selectors', () => {
     });
 
     it('should map graph link to link with previous state, filtering properties', () => {
+      const id = 'link-1';
       const linkAsGraphJson = {
         type: 'standard.Link',
         source: { id: 'element-1' },
@@ -529,7 +533,6 @@ describe('graph-state-selectors', () => {
       };
 
       const previous: ExtendedLink = {
-        id: 'link-1',
         source: { id: 'element-1' },
         target: { id: 'element-2' },
         type: 'standard.Link',
@@ -538,13 +541,12 @@ describe('graph-state-selectors', () => {
         // extraProp is not in previous, so it should be filtered out
       };
 
-      const options = createGraphToLinkOptions(linkCell, graph, previous);
+      const options = createGraphToLinkOptions(id, linkCell, graph, previous);
 
-      const linkFromGraph = defaultGraphToLinkSelector(options);
+      const linkFromGraph = mapLinkAttributesToData(options);
 
       // Should only include properties that exist in previous state
       expect(linkFromGraph).toMatchObject({
-        id: 'link-1',
         source: { id: 'element-1' },
         target: { id: 'element-2' },
         type: 'standard.Link',
@@ -557,6 +559,7 @@ describe('graph-state-selectors', () => {
     });
 
     it('should preserve undefined properties from previous state', () => {
+      const id = 'link-1';
       const linkAsGraphJson = {
         type: 'standard.Link',
         source: { id: 'element-1' },
@@ -571,16 +574,15 @@ describe('graph-state-selectors', () => {
       };
 
       const previous: ExtendedLink = {
-        id: 'link-1',
         source: { id: 'element-1' },
         target: { id: 'element-2' },
         type: 'standard.Link',
         customProp: undefined, // Explicitly undefined in previous
       };
 
-      const options = createGraphToLinkOptions(linkCell, graph, previous);
+      const options = createGraphToLinkOptions(id, linkCell, graph, previous);
 
-      const linkFromGraph = defaultGraphToLinkSelector(options);
+      const linkFromGraph = mapLinkAttributesToData(options);
 
       // Should include customProp even though it's undefined in previous
       expect(linkFromGraph).toHaveProperty('customProp');
@@ -588,6 +590,7 @@ describe('graph-state-selectors', () => {
     });
 
     it('should extract source and target from cell', () => {
+      const id = 'link-1';
       const linkAsGraphJson = {
         type: 'standard.Link',
         source: { id: 'element-1', port: 'port-1' },
@@ -597,15 +600,16 @@ describe('graph-state-selectors', () => {
       graph.syncCells([linkAsGraphJson], { remove: true });
       const linkCell = graph.getCell('link-1') as dia.Link;
 
-      const options = createGraphToLinkOptions(linkCell, graph);
+      const options = createGraphToLinkOptions(id, linkCell, graph);
 
-      const linkFromGraph = defaultGraphToLinkSelector(options);
+      const linkFromGraph = mapLinkAttributesToData(options);
 
       expect(linkFromGraph.source).toEqual({ id: 'element-1', port: 'port-1' });
       expect(linkFromGraph.target).toEqual({ id: 'element-2', port: 'port-2' });
     });
 
     it('should extract z, markup, and defaultLabel from cell', () => {
+      const id = 'link-1';
       const linkAsGraphJson = {
         type: 'standard.Link',
         source: { id: 'element-1' },
@@ -618,9 +622,9 @@ describe('graph-state-selectors', () => {
       graph.syncCells([linkAsGraphJson], { remove: true });
       const linkCell = graph.getCell('link-1') as dia.Link;
 
-      const options = createGraphToLinkOptions(linkCell, graph);
+      const options = createGraphToLinkOptions(id, linkCell, graph);
 
-      const linkFromGraph = defaultGraphToLinkSelector(options);
+      const linkFromGraph = mapLinkAttributesToData(options);
 
       expect(linkFromGraph.z).toBe(10);
       expect(linkFromGraph.markup).toEqual([{ tagName: 'path' }]);
@@ -628,6 +632,7 @@ describe('graph-state-selectors', () => {
     });
 
     it('should include all cell attributes when no previous state', () => {
+      const id = 'link-1';
       const linkAsGraphJson = {
         type: 'standard.Link',
         source: { id: 'element-1' },
@@ -643,9 +648,9 @@ describe('graph-state-selectors', () => {
       graph.syncCells([linkAsGraphJson], { remove: true });
       const linkCell = graph.getCell('link-1') as dia.Link;
 
-      const options = createGraphToLinkOptions(linkCell, graph);
+      const options = createGraphToLinkOptions(id, linkCell, graph);
 
-      const linkFromGraph = defaultGraphToLinkSelector(options);
+      const linkFromGraph = mapLinkAttributesToData(options);
 
       expect(linkFromGraph.attrs).toBeDefined();
       expect(linkFromGraph.attrs).toMatchObject({
@@ -659,6 +664,7 @@ describe('graph-state-selectors', () => {
 
   describe('integration: state is source of truth', () => {
     it('should not add new properties from graph when previous state exists', () => {
+      const id = 'element-1';
       // Create element in graph with extra properties
       const elementAsGraphJson = {
         type: 'ReactElement',
@@ -672,7 +678,6 @@ describe('graph-state-selectors', () => {
 
       // Previous state only has specific properties
       const previous: GraphElement = {
-        id: 'element-1',
         x: 5,
         y: 15,
         width: 80,
@@ -680,19 +685,20 @@ describe('graph-state-selectors', () => {
         // graphOnlyProp and anotherGraphProp are NOT in previous state
       };
 
-      const options = createGraphToElementOptions(cell, graph, previous);
+      const options = createGraphToElementOptions(id, cell, graph, previous);
 
-      const elementFromGraph = defaultGraphToElementSelector(options);
+      const elementFromGraph = mapElementAttributesToData(options);
 
       // Should only have properties from previous state
       expect(elementFromGraph).not.toHaveProperty('graphOnlyProp');
       expect(elementFromGraph).not.toHaveProperty('anotherGraphProp');
       expect(Object.keys(elementFromGraph).toSorted()).toEqual(
-        ['id', 'x', 'y', 'width', 'height'].toSorted()
+        ['x', 'y', 'width', 'height'].toSorted()
       );
     });
 
     it('should update existing properties from graph even if undefined in previous', () => {
+      const id = 'element-1';
       const elementAsGraphJson = {
         type: 'ReactElement',
         position: { x: 10, y: 20 },
@@ -708,7 +714,6 @@ describe('graph-state-selectors', () => {
       };
 
       const previous: ExtendedElement = {
-        id: 'element-1',
         x: 5,
         y: 15,
         width: 80,
@@ -716,9 +721,9 @@ describe('graph-state-selectors', () => {
         customProp: undefined, // Exists but undefined
       };
 
-      const options = createGraphToElementOptions(cell, graph, previous);
+      const options = createGraphToElementOptions(id, cell, graph, previous);
 
-      const elementFromGraph = defaultGraphToElementSelector(options);
+      const elementFromGraph = mapElementAttributesToData(options);
 
       // Should update customProp from graph data
       expect((elementFromGraph as ExtendedElement).customProp).toBe('updated-value');
@@ -727,8 +732,8 @@ describe('graph-state-selectors', () => {
 
   describe('integration: links with syncCells', () => {
     it('should handle link round-trip using syncCells', () => {
+      const id = 'link-1';
       const link: GraphLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
@@ -736,7 +741,7 @@ describe('graph-state-selectors', () => {
       };
 
       // Convert link to graph JSON
-      const linkAsGraphJson = defaultMapDataToLinkAttributes(createLinkToGraphOptions(link, graph));
+      const linkAsGraphJson = defaultMapDataToLinkAttributes(createLinkToGraphOptions(id, link, graph));
 
       // Store in graph using syncCells
       graph.syncCells([linkAsGraphJson], { remove: true });
@@ -746,12 +751,11 @@ describe('graph-state-selectors', () => {
       expect(graphLinkCell).toBeDefined();
 
       // Convert back to link
-      const linkFromGraph = defaultGraphToLinkSelector(
-        createGraphToLinkOptions(graphLinkCell, graph)
+      const linkFromGraph = mapLinkAttributesToData(
+        createGraphToLinkOptions(id, graphLinkCell, graph)
       );
 
       expect(linkFromGraph).toMatchObject({
-        id: 'link-1',
         source: { id: 'element-1' },
         target: { id: 'element-2' },
         type: 'standard.Link',
@@ -760,8 +764,8 @@ describe('graph-state-selectors', () => {
     });
 
     it('should handle link with complex properties using syncCells', () => {
+      const id = 'link-1';
       const link: GraphLink = {
-        id: 'link-1',
         source: { id: 'element-1', port: 'port-1' },
         target: { id: 'element-2', port: 'port-2' },
         type: 'standard.Link',
@@ -776,17 +780,16 @@ describe('graph-state-selectors', () => {
         },
       };
 
-      const linkAsGraphJson = defaultMapDataToLinkAttributes(createLinkToGraphOptions(link, graph));
+      const linkAsGraphJson = defaultMapDataToLinkAttributes(createLinkToGraphOptions(id, link, graph));
 
       graph.syncCells([linkAsGraphJson], { remove: true });
 
       const graphLinkCell = graph.getCell('link-1') as dia.Link;
-      const linkFromGraph = defaultGraphToLinkSelector(
-        createGraphToLinkOptions(graphLinkCell, graph)
+      const linkFromGraph = mapLinkAttributesToData(
+        createGraphToLinkOptions(id, graphLinkCell, graph)
       );
 
       expect(linkFromGraph).toMatchObject({
-        id: 'link-1',
         source: { id: 'element-1', port: 'port-1' },
         target: { id: 'element-2', port: 'port-2' },
         type: 'standard.Link',
@@ -804,8 +807,8 @@ describe('graph-state-selectors', () => {
         anotherProp?: number;
       };
 
+      const id = 'link-1';
       const link: ExtendedLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
@@ -815,7 +818,7 @@ describe('graph-state-selectors', () => {
         anotherProp: 42,
       };
 
-      const linkAsGraphJson = defaultMapDataToLinkAttributes(createLinkToGraphOptions(link, graph));
+      const linkAsGraphJson = defaultMapDataToLinkAttributes(createLinkToGraphOptions(id, link, graph));
 
       // Add extra properties to graph JSON that don't exist in state
       const linkWithExtraProps = {
@@ -827,7 +830,6 @@ describe('graph-state-selectors', () => {
       graph.syncCells([linkWithExtraProps], { remove: true });
 
       const previous: ExtendedLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
@@ -838,13 +840,12 @@ describe('graph-state-selectors', () => {
       };
 
       const graphLinkCell = graph.getCell('link-1') as dia.Link;
-      const linkFromGraph = defaultGraphToLinkSelector(
-        createGraphToLinkOptions(graphLinkCell, graph, previous)
+      const linkFromGraph = mapLinkAttributesToData(
+        createGraphToLinkOptions(id, graphLinkCell, graph, previous)
       );
 
       // Should only include properties that exist in previous state
       expect(linkFromGraph).toMatchObject({
-        id: 'link-1',
         source: { id: 'element-1' },
         target: { id: 'element-2' },
         type: 'standard.Link',
@@ -865,79 +866,89 @@ describe('graph-state-selectors', () => {
         metadata?: Record<string, unknown>;
       };
 
-      const links: ExtendedLink[] = [
+      const links: Array<{ id: string; data: ExtendedLink }> = [
         {
           id: 'link-1',
-          source: 'element-1',
-          target: 'element-2',
-          type: 'standard.Link',
-          z: 1,
-          label: 'Link 1',
+          data: {
+            source: 'element-1',
+            target: 'element-2',
+            type: 'standard.Link',
+            z: 1,
+            label: 'Link 1',
+          },
         },
         {
           id: 'link-2',
-          source: 'element-2',
-          target: 'element-3',
-          type: 'standard.Link',
-          z: 2,
-          metadata: { key: 'value' },
+          data: {
+            source: 'element-2',
+            target: 'element-3',
+            type: 'standard.Link',
+            z: 2,
+            metadata: { key: 'value' },
+          },
         },
       ];
 
-      const linksAsGraphJson = links.map((link) =>
-        defaultMapDataToLinkAttributes(createLinkToGraphOptions(link, graph))
+      const linksAsGraphJson = links.map(({ id, data }) =>
+        defaultMapDataToLinkAttributes(createLinkToGraphOptions(id, data, graph))
       );
 
       graph.syncCells(linksAsGraphJson, { remove: true });
 
       // Previous state only has specific properties for each link
-      const previousLinks: ExtendedLink[] = [
+      const previousLinks: Array<{ id: string; data: ExtendedLink }> = [
         {
           id: 'link-1',
-          source: 'element-1',
-          target: 'element-2',
-          type: 'standard.Link',
-          z: 0, // Exists in previous
-          label: undefined, // Exists but undefined
+          data: {
+            source: 'element-1',
+            target: 'element-2',
+            type: 'standard.Link',
+            z: 0, // Exists in previous
+            label: undefined, // Exists but undefined
+          },
         },
         {
           id: 'link-2',
-          source: 'element-2',
-          target: 'element-3',
-          type: 'standard.Link',
-          z: 0, // Exists in previous
-          metadata: undefined, // Exists but undefined
+          data: {
+            source: 'element-2',
+            target: 'element-3',
+            type: 'standard.Link',
+            z: 0, // Exists in previous
+            metadata: undefined, // Exists but undefined
+          },
         },
       ];
 
       const retrievedLinks = graph.getLinks().map((graphLinkCell) => {
-        const previous = previousLinks.find((l) => l.id === graphLinkCell.id);
-        return defaultGraphToLinkSelector(createGraphToLinkOptions(graphLinkCell, graph, previous));
+        const id = graphLinkCell.id as string;
+        const previous = previousLinks.find((l) => l.id === id)?.data;
+        return {
+          id,
+          data: mapLinkAttributesToData(createGraphToLinkOptions(id, graphLinkCell, graph, previous)),
+        };
       });
 
       expect(retrievedLinks).toHaveLength(2);
 
       const link1 = retrievedLinks.find((l) => l.id === 'link-1');
-      expect(link1).toMatchObject({
-        id: 'link-1',
+      expect(link1?.data).toMatchObject({
         source: { id: 'element-1' },
         target: { id: 'element-2' },
         type: 'standard.Link',
         z: 1, // Updated from graph
         label: 'Link 1', // Updated from graph data
       });
-      expect(link1).not.toHaveProperty('metadata');
+      expect(link1?.data).not.toHaveProperty('metadata');
 
       const link2 = retrievedLinks.find((l) => l.id === 'link-2');
-      expect(link2).toMatchObject({
-        id: 'link-2',
+      expect(link2?.data).toMatchObject({
         source: { id: 'element-2' },
         target: { id: 'element-3' },
         type: 'standard.Link',
         z: 2, // Updated from graph
         metadata: { key: 'value' }, // Updated from graph data
       });
-      expect(link2).not.toHaveProperty('label');
+      expect(link2?.data).not.toHaveProperty('label');
     });
 
     it('should preserve undefined properties from previous state when using syncCells', () => {
@@ -946,20 +957,19 @@ describe('graph-state-selectors', () => {
         anotherOptionalProp?: number;
       };
 
+      const id = 'link-1';
       const link: ExtendedLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
         optionalProp: 'has-value',
       };
 
-      const linkAsGraphJson = defaultMapDataToLinkAttributes(createLinkToGraphOptions(link, graph));
+      const linkAsGraphJson = defaultMapDataToLinkAttributes(createLinkToGraphOptions(id, link, graph));
 
       graph.syncCells([linkAsGraphJson], { remove: true });
 
       const previous: ExtendedLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
@@ -968,8 +978,8 @@ describe('graph-state-selectors', () => {
       };
 
       const graphLinkCell = graph.getCell('link-1') as dia.Link;
-      const linkFromGraph = defaultGraphToLinkSelector(
-        createGraphToLinkOptions(graphLinkCell, graph, previous)
+      const linkFromGraph = mapLinkAttributesToData(
+        createGraphToLinkOptions(id, graphLinkCell, graph, previous)
       );
 
       // Should include optionalProp with value from graph data
@@ -985,9 +995,9 @@ describe('graph-state-selectors', () => {
         weight?: number;
       };
 
+      const id = 'link-1';
       // Initial link
       const initialLink: ExtendedLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
@@ -996,14 +1006,13 @@ describe('graph-state-selectors', () => {
       };
 
       const initialLinkAsGraphJson = defaultMapDataToLinkAttributes(
-        createLinkToGraphOptions(initialLink, graph)
+        createLinkToGraphOptions(id, initialLink, graph)
       );
 
       graph.syncCells([initialLinkAsGraphJson], { remove: true });
 
       // Update link with new values
-      const updatedLink: ExtendedLink = {
-        id: 'link-1',
+      const updatedLink: ExtendedLink & { newProp?: string } = {
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
@@ -1013,14 +1022,13 @@ describe('graph-state-selectors', () => {
       };
 
       const updatedLinkAsGraphJson = defaultMapDataToLinkAttributes(
-        createLinkToGraphOptions(updatedLink, graph)
+        createLinkToGraphOptions(id, updatedLink, graph)
       );
 
       graph.syncCells([updatedLinkAsGraphJson], { remove: true });
 
       // Previous state only has status and weight
       const previous: ExtendedLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
@@ -1029,13 +1037,12 @@ describe('graph-state-selectors', () => {
       };
 
       const graphLinkCell = graph.getCell('link-1') as dia.Link;
-      const linkFromGraph = defaultGraphToLinkSelector(
-        createGraphToLinkOptions(graphLinkCell, graph, previous)
+      const linkFromGraph = mapLinkAttributesToData(
+        createGraphToLinkOptions(id, graphLinkCell, graph, previous)
       );
 
       // Should only include properties from previous state
       expect(linkFromGraph).toMatchObject({
-        id: 'link-1',
         source: { id: 'element-1' },
         target: { id: 'element-2' },
         type: 'standard.Link',
@@ -1048,8 +1055,8 @@ describe('graph-state-selectors', () => {
     });
 
     it('should handle link with attrs merging when using syncCells', () => {
+      const id = 'link-1';
       const link: GraphLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
@@ -1061,13 +1068,13 @@ describe('graph-state-selectors', () => {
         },
       };
 
-      const linkAsGraphJson = defaultMapDataToLinkAttributes(createLinkToGraphOptions(link, graph));
+      const linkAsGraphJson = defaultMapDataToLinkAttributes(createLinkToGraphOptions(id, link, graph));
 
       graph.syncCells([linkAsGraphJson], { remove: true });
 
       const graphLinkCell = graph.getCell('link-1') as dia.Link;
-      const linkFromGraph = defaultGraphToLinkSelector(
-        createGraphToLinkOptions(graphLinkCell, graph)
+      const linkFromGraph = mapLinkAttributesToData(
+        createGraphToLinkOptions(id, graphLinkCell, graph)
       );
 
       expect(linkFromGraph.attrs).toBeDefined();
@@ -1087,9 +1094,9 @@ describe('graph-state-selectors', () => {
         anotherNewProperty?: number;
       };
 
+      const id = 'element-1';
       // Create element in graph with new properties
       const element: ExtendedElement = {
-        id: 'element-1',
         x: 10,
         y: 20,
         width: 100,
@@ -1099,14 +1106,13 @@ describe('graph-state-selectors', () => {
       };
 
       const elementAsGraphJson = defaultMapDataToElementAttributes(
-        createElementToGraphOptions(element, graph)
+        createElementToGraphOptions(id, element, graph)
       );
 
       graph.syncCells([elementAsGraphJson], { remove: true });
 
       // Previous state has newProperty defined (but undefined) and anotherNewProperty defined
       const previous: ExtendedElement = {
-        id: 'element-1',
         x: 5,
         y: 15,
         width: 80,
@@ -1116,8 +1122,8 @@ describe('graph-state-selectors', () => {
       };
 
       const graphElement = graph.getCell('element-1') as dia.Element;
-      const elementFromGraph = defaultGraphToElementSelector(
-        createGraphToElementOptions(graphElement, graph, previous)
+      const elementFromGraph = mapElementAttributesToData(
+        createGraphToElementOptions(id, graphElement, graph, previous)
       );
 
       // Should return newProperty with value from graph data
@@ -1133,9 +1139,9 @@ describe('graph-state-selectors', () => {
         metadata?: Record<string, unknown>;
       };
 
+      const id = 'link-1';
       // Create link in graph with new properties
       const link: ExtendedLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
@@ -1144,13 +1150,12 @@ describe('graph-state-selectors', () => {
         metadata: { key: 'value' },
       };
 
-      const linkAsGraphJson = defaultMapDataToLinkAttributes(createLinkToGraphOptions(link, graph));
+      const linkAsGraphJson = defaultMapDataToLinkAttributes(createLinkToGraphOptions(id, link, graph));
 
       graph.syncCells([linkAsGraphJson], { remove: true });
 
       // Previous state has all properties defined (some undefined)
       const previous: ExtendedLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
@@ -1160,8 +1165,8 @@ describe('graph-state-selectors', () => {
       };
 
       const graphLinkCell = graph.getCell('link-1') as dia.Link;
-      const linkFromGraph = defaultGraphToLinkSelector(
-        createGraphToLinkOptions(graphLinkCell, graph, previous)
+      const linkFromGraph = mapLinkAttributesToData(
+        createGraphToLinkOptions(id, graphLinkCell, graph, previous)
       );
 
       // Should return all properties with values from graph data
@@ -1178,8 +1183,8 @@ describe('graph-state-selectors', () => {
         score?: number;
       };
 
+      const id = 'element-1';
       const element: ExtendedElement = {
-        id: 'element-1',
         x: 10,
         y: 20,
         width: 100,
@@ -1191,14 +1196,13 @@ describe('graph-state-selectors', () => {
       };
 
       const elementAsGraphJson = defaultMapDataToElementAttributes(
-        createElementToGraphOptions(element, graph)
+        createElementToGraphOptions(id, element, graph)
       );
 
       graph.syncCells([elementAsGraphJson], { remove: true });
 
       // Previous state defines all properties (some undefined)
       const previous: ExtendedElement = {
-        id: 'element-1',
         x: 5,
         y: 15,
         width: 80,
@@ -1210,8 +1214,8 @@ describe('graph-state-selectors', () => {
       };
 
       const graphElement = graph.getCell('element-1') as dia.Element;
-      const elementFromGraph = defaultGraphToElementSelector(
-        createGraphToElementOptions(graphElement, graph, previous)
+      const elementFromGraph = mapElementAttributesToData(
+        createGraphToElementOptions(id, graphElement, graph, previous)
       );
 
       // All properties should be returned with values from graph data
@@ -1231,8 +1235,8 @@ describe('graph-state-selectors', () => {
         customData?: Record<string, unknown>;
       };
 
+      const id = 'link-1';
       const link: ExtendedLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
@@ -1250,24 +1254,22 @@ describe('graph-state-selectors', () => {
         },
       };
 
-      const linkAsGraphJson = defaultMapDataToLinkAttributes(createLinkToGraphOptions(link, graph));
+      const linkAsGraphJson = defaultMapDataToLinkAttributes(createLinkToGraphOptions(id, link, graph));
 
       graph.syncCells([linkAsGraphJson], { remove: true });
 
       // Previous state defines all properties (all undefined)
       const previous: ExtendedLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
         config: undefined,
-        labels: undefined,
         customData: undefined,
       };
 
       const graphLinkCell = graph.getCell('link-1') as dia.Link;
-      const linkFromGraph = defaultGraphToLinkSelector(
-        createGraphToLinkOptions(graphLinkCell, graph, previous)
+      const linkFromGraph = mapLinkAttributesToData(
+        createGraphToLinkOptions(id, graphLinkCell, graph, previous)
       );
 
       // All complex properties should be returned with values from graph data
@@ -1275,10 +1277,6 @@ describe('graph-state-selectors', () => {
         style: 'dashed',
         animation: true,
       });
-      expect((linkFromGraph as ExtendedLink).labels).toEqual([
-        { text: 'Label 1', position: 0.3 },
-        { text: 'Label 2', position: 0.7 },
-      ]);
       expect((linkFromGraph as ExtendedLink).customData).toEqual({
         source: 'api',
         timestamp: 1_234_567_890,
@@ -1292,8 +1290,8 @@ describe('graph-state-selectors', () => {
         notInPreviousProperty?: boolean;
       };
 
+      const id = 'element-1';
       const element: ExtendedElement = {
-        id: 'element-1',
         x: 10,
         y: 20,
         width: 100,
@@ -1304,14 +1302,13 @@ describe('graph-state-selectors', () => {
       };
 
       const elementAsGraphJson = defaultMapDataToElementAttributes(
-        createElementToGraphOptions(element, graph)
+        createElementToGraphOptions(id, element, graph)
       );
 
       graph.syncCells([elementAsGraphJson], { remove: true });
 
       // Previous state only defines some properties
       const previous: ExtendedElement = {
-        id: 'element-1',
         x: 5,
         y: 15,
         width: 80,
@@ -1322,8 +1319,8 @@ describe('graph-state-selectors', () => {
       };
 
       const graphElement = graph.getCell('element-1') as dia.Element;
-      const elementFromGraph = defaultGraphToElementSelector(
-        createGraphToElementOptions(graphElement, graph, previous)
+      const elementFromGraph = mapElementAttributesToData(
+        createGraphToElementOptions(id, graphElement, graph, previous)
       );
 
       // Properties defined in previous should be returned from graph data
@@ -1340,8 +1337,8 @@ describe('graph-state-selectors', () => {
         weight?: number;
       };
 
+      const id = 'link-1';
       const link: ExtendedLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
@@ -1351,13 +1348,12 @@ describe('graph-state-selectors', () => {
         weight: 10, // New property
       };
 
-      const linkAsGraphJson = defaultMapDataToLinkAttributes(createLinkToGraphOptions(link, graph));
+      const linkAsGraphJson = defaultMapDataToLinkAttributes(createLinkToGraphOptions(id, link, graph));
 
       graph.syncCells([linkAsGraphJson], { remove: true });
 
       // Previous state has both existing and new properties
       const previous: ExtendedLink = {
-        id: 'link-1',
         source: 'element-1',
         target: 'element-2',
         type: 'standard.Link',
@@ -1367,8 +1363,8 @@ describe('graph-state-selectors', () => {
       };
 
       const graphLinkCell = graph.getCell('link-1') as dia.Link;
-      const linkFromGraph = defaultGraphToLinkSelector(
-        createGraphToLinkOptions(graphLinkCell, graph, previous)
+      const linkFromGraph = mapLinkAttributesToData(
+        createGraphToLinkOptions(id, graphLinkCell, graph, previous)
       );
 
       // All properties should be returned
@@ -1383,9 +1379,9 @@ describe('graph-state-selectors', () => {
         lastModified?: string;
       };
 
+      const id = 'element-1';
       // Initial element without new properties
       const initialElement: ExtendedElement = {
-        id: 'element-1',
         x: 10,
         y: 20,
         width: 100,
@@ -1393,14 +1389,13 @@ describe('graph-state-selectors', () => {
       };
 
       const initialElementAsGraphJson = defaultMapDataToElementAttributes(
-        createElementToGraphOptions(initialElement, graph)
+        createElementToGraphOptions(id, initialElement, graph)
       );
 
       graph.syncCells([initialElementAsGraphJson], { remove: true });
 
       // Update element with new properties
       const updatedElement: ExtendedElement = {
-        id: 'element-1',
         x: 15,
         y: 25,
         width: 120,
@@ -1410,14 +1405,13 @@ describe('graph-state-selectors', () => {
       };
 
       const updatedElementAsGraphJson = defaultMapDataToElementAttributes(
-        createElementToGraphOptions(updatedElement, graph)
+        createElementToGraphOptions(id, updatedElement, graph)
       );
 
       graph.syncCells([updatedElementAsGraphJson], { remove: true });
 
       // Previous state now includes the new properties
       const previous: ExtendedElement = {
-        id: 'element-1',
         x: 10,
         y: 20,
         width: 100,
@@ -1427,8 +1421,8 @@ describe('graph-state-selectors', () => {
       };
 
       const graphElement = graph.getCell('element-1') as dia.Element;
-      const elementFromGraph = defaultGraphToElementSelector(
-        createGraphToElementOptions(graphElement, graph, previous)
+      const elementFromGraph = mapElementAttributesToData(
+        createGraphToElementOptions(id, graphElement, graph, previous)
       );
 
       // Should return all properties including new ones from graph data
@@ -1444,8 +1438,8 @@ describe('graph-state-selectors', () => {
   describe('custom selector with defaultAttributes', () => {
     it('should allow using defaultAttributes as-is', () => {
       type CustomElement = GraphElement & { label: string };
+      const id = 'node1';
       const element: CustomElement = {
-        id: 'node1',
         x: 100,
         y: 50,
         width: 200,
@@ -1457,8 +1451,8 @@ describe('graph-state-selectors', () => {
         return options.defaultAttributes();
       };
 
-      const defaultAttributes = createDefaultElementMapper(element);
-      const result = customSelector({ data: element, graph, defaultAttributes });
+      const defaultAttributes = createDefaultElementMapper(id, element);
+      const result = customSelector({ id, data: element, graph, defaultAttributes });
 
       expect(result.data).toEqual({ label: 'Test' });
       expect(result.position).toEqual({ x: 100, y: 50 });
@@ -1466,8 +1460,8 @@ describe('graph-state-selectors', () => {
 
     it('should allow modifying defaultAttributes result', () => {
       type CustomElement = GraphElement & { label: string };
+      const id = 'node1';
       const element: CustomElement = {
-        id: 'node1',
         x: 100,
         y: 50,
         width: 200,
@@ -1481,8 +1475,8 @@ describe('graph-state-selectors', () => {
         return base;
       };
 
-      const defaultAttributes = createDefaultElementMapper(element);
-      const result = customSelector({ data: element, graph, defaultAttributes });
+      const defaultAttributes = createDefaultElementMapper(id, element);
+      const result = customSelector({ id, data: element, graph, defaultAttributes });
 
       expect(result.attrs).toEqual({ root: { fill: 'red' } });
       expect(result.data).toEqual({ label: 'Test' });
@@ -1490,8 +1484,8 @@ describe('graph-state-selectors', () => {
 
     it('should allow custom selector to ignore defaultAttributes and return custom result', () => {
       type CustomElement = GraphElement & { label: string };
+      const id = 'node1';
       const element: CustomElement = {
-        id: 'node1',
         x: 100,
         y: 50,
         width: 200,
@@ -1502,14 +1496,14 @@ describe('graph-state-selectors', () => {
       const customSelector = (options: ElementToGraphOptions<CustomElement>) => {
         // Ignore defaultAttributes and return completely custom result
         return {
-          id: options.data.id,
+          id: options.id,
           type: 'custom.Element',
           customData: { label: options.data.label },
         };
       };
 
-      const defaultAttributes = createDefaultElementMapper(element);
-      const result = customSelector({ data: element, graph, defaultAttributes });
+      const defaultAttributes = createDefaultElementMapper(id, element);
+      const result = customSelector({ id, data: element, graph, defaultAttributes });
 
       expect(result.type).toBe('custom.Element');
       expect(result.customData).toEqual({ label: 'Test' });
@@ -1519,8 +1513,8 @@ describe('graph-state-selectors', () => {
 
     it('should allow custom link selector to use defaultAttributes', () => {
       type CustomLink = GraphLink & { weight: number };
+      const id = 'link1';
       const data: CustomLink = {
-        id: 'link1',
         source: 'node1',
         target: 'node2',
         weight: 5,
@@ -1530,8 +1524,8 @@ describe('graph-state-selectors', () => {
         return options.defaultAttributes();
       };
 
-      const defaultAttributes = createDefaultLinkMapper(data, graph);
-      const result = customSelector({ data, graph, defaultAttributes });
+      const defaultAttributes = createDefaultLinkMapper(id, data, graph);
+      const result = customSelector({ id, data, graph, defaultAttributes });
 
       expect(result.data).toEqual({ weight: 5 });
       expect(result.source).toEqual({ id: 'node1' });
@@ -1540,8 +1534,8 @@ describe('graph-state-selectors', () => {
 
     it('should allow custom link selector to modify defaultAttributes result', () => {
       type CustomLink = GraphLink & { weight: number };
+      const id = 'link1';
       const data: CustomLink = {
-        id: 'link1',
         source: 'node1',
         target: 'node2',
         weight: 5,
@@ -1553,8 +1547,8 @@ describe('graph-state-selectors', () => {
         return base;
       };
 
-      const defaultAttributes = createDefaultLinkMapper(data, graph);
-      const result = customSelector({ data, graph, defaultAttributes });
+      const defaultAttributes = createDefaultLinkMapper(id, data, graph);
+      const result = customSelector({ id, data, graph, defaultAttributes });
 
       expect(result.attrs).toEqual({ line: { stroke: 'blue', strokeWidth: 2 } });
       expect(result.data).toEqual({ weight: 5 });
diff --git a/packages/joint-react/src/state/__tests__/state-sync.test.ts b/packages/joint-react/src/state/__tests__/state-sync.test.ts
index 389aa4910..26f0761bd 100644
--- a/packages/joint-react/src/state/__tests__/state-sync.test.ts
+++ b/packages/joint-react/src/state/__tests__/state-sync.test.ts
@@ -1,1169 +1,968 @@
-/* eslint-disable unicorn/consistent-function-scoping */
-/* eslint-disable sonarjs/no-element-overwrite */
 /* eslint-disable sonarjs/no-nested-functions */
 import { dia } from '@joint/core';
-import {
-  DEFAULT_CELL_NAMESPACE,
-  type GraphStoreSnapshot,
-  type GraphStoreDerivedSnapshot,
-} from '../../store/graph-store';
+import { DEFAULT_CELL_NAMESPACE, type GraphStoreSnapshot } from '../../store/graph-store';
 import { stateSync } from '../state-sync';
+import { updateGraph } from '../update-graph';
 import { createState } from '../../utils/create-state';
 import type { GraphElement } from '../../types/element-types';
 import type { GraphLink } from '../../types/link-types';
 import {
   defaultMapDataToElementAttributes,
   defaultMapDataToLinkAttributes,
+  mapElementAttributesToData,
+  mapLinkAttributesToData,
   createDefaultElementMapper,
   createDefaultLinkMapper,
+  createDefaultGraphToElementMapper,
   type ElementToGraphOptions,
   type LinkToGraphOptions,
 } from '../graph-state-selectors';
+import { Scheduler } from '../../utils/scheduler';
+import type { GraphSchedulerData } from '../../types/scheduler.types';
 
 // Helper to create ElementToGraphOptions
 function createElementToGraphOptions<E extends GraphElement>(
+  id: string,
   element: E,
   graph: dia.Graph
 ): ElementToGraphOptions<E> {
   return {
+    id,
     data: element,
     graph,
-    defaultAttributes: createDefaultElementMapper(element),
+    defaultAttributes: createDefaultElementMapper(id, element),
   };
 }
 
 // Helper to create LinkToGraphOptions
-function createLinkToGraphOptions<L extends GraphLink>(
+function _createLinkToGraphOptions<L extends GraphLink>(
+  id: string,
   data: L,
   graph: dia.Graph
 ): LinkToGraphOptions<L> {
   return {
+    id,
     data,
     graph,
-    defaultAttributes: createDefaultLinkMapper(data, graph),
+    defaultAttributes: createDefaultLinkMapper(id, data, graph),
   };
 }
 
-// Helper to create getIdsSnapshot function
-function createGetIdsSnapshot<E extends GraphElement, L extends GraphLink>(
-  state: ReturnType<typeof createState<GraphStoreSnapshot<E, L>>>
-): () => GraphStoreDerivedSnapshot {
-  return () => {
-    const snapshot = state.getSnapshot();
-    const elementIds: Record<dia.Cell.ID, number> = {};
-    const linkIds: Record<dia.Cell.ID, number> = {};
-
-    for (const [index, element] of snapshot.elements.entries()) {
-      elementIds[element.id as dia.Cell.ID] = index;
-    }
-    for (const [index, link] of snapshot.links.entries()) {
-      linkIds[link.id as dia.Cell.ID] = index;
-    }
-
-    return { elementIds, linkIds };
+// Helper to create a mock scheduler that tracks scheduled data
+function createMockScheduler() {
+  const scheduledData: GraphSchedulerData[] = [];
+  let flushCallback: ((data: GraphSchedulerData) => void) | null = null;
+
+  const scheduler = new Scheduler<GraphSchedulerData>({
+    onFlush: (data) => {
+      scheduledData.push(data);
+      if (flushCallback) {
+        flushCallback(data);
+      }
+    },
+  });
+
+  return {
+    scheduler,
+    scheduledData,
+    setFlushCallback: (cb: (data: GraphSchedulerData) => void) => {
+      flushCallback = cb;
+    },
+    // Force flush for testing
+    getScheduledCount: () => scheduledData.length,
   };
 }
 
+// Helper to flush scheduler synchronously for tests
+async function flushScheduler(): Promise<void> {
+  // Use setTimeout to allow React scheduler to flush
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
 describe('stateSync', () => {
-  it('should sync dia.graph <-> state effectively', () => {
-    const graph = new dia.Graph(
-      {},
-      {
-        cellNamespace: {
-          ...DEFAULT_CELL_NAMESPACE,
-        },
-      }
-    );
-    const elements = [
-      {
-        id: '1',
-        width: 100,
-        height: 100,
-        type: 'ReactElement',
-      },
-      {
-        id: '2',
-        width: 100,
-        height: 100,
-        type: 'ReactElement',
-      },
-    ];
-    const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
-      newState: () => ({ elements, links: [] }),
-      name: 'elements',
-    });
+  describe('basic synchronization', () => {
+    it('should sync elements from state to graph on initialization', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
-    // Mock the setState method to be able to test the state updates.
-    const mockedSetState = jest.fn().mockImplementation(state.setState);
-    state.setState = mockedSetState;
-
-    const getIdsSnapshot = createGetIdsSnapshot(state);
-
-    // Here we initially sync the graph with the state.
-    // State should not be updated yet.
-    stateSync({ graph, store: state, getIdsSnapshot });
-    expect(graph.getElements()).toHaveLength(2);
-    expect(state.getSnapshot().elements).toHaveLength(2);
-    expect(mockedSetState).toHaveBeenCalledTimes(0);
-    // Here we update state via state API.
-    // State should not be updated yet.
-    state.setState((previous: GraphStoreSnapshot<GraphElement, GraphLink>) => ({
-      ...previous,
-      elements: [...previous.elements, { id: '3', width: 100, height: 100, type: 'ReactElement' }],
-    }));
-    expect(graph.getElements()).toHaveLength(3);
-    expect(state.getSnapshot().elements).toHaveLength(3);
-    expect(mockedSetState).toHaveBeenCalledTimes(1);
-
-    // Here we update dia.graph itself via graph.syncCells.
-    // State should be updated now with 1 update call.
-    const newElements = [
-      ...state.getSnapshot().elements,
-      { id: '4', width: 100, height: 100, type: 'ReactElement' },
-    ];
-    const elementItems = newElements.map((element) =>
-      defaultMapDataToElementAttributes(createElementToGraphOptions(element, graph))
-    );
-    graph.syncCells(elementItems, { remove: true });
-    expect(graph.getElements()).toHaveLength(4);
-    expect(state.getSnapshot().elements).toHaveLength(4);
-    expect(mockedSetState).toHaveBeenCalledTimes(2);
-  });
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100, type: 'ReactElement' },
+        '2': { width: 100, height: 100, type: 'ReactElement' },
+      };
 
-  it('should sync dia.graph <-> state effectively using normal JointJS API', () => {
-    const graph = new dia.Graph(
-      {},
-      {
-        cellNamespace: {
-          ...DEFAULT_CELL_NAMESPACE,
-        },
-      }
-    );
-    const elements = [
-      {
-        id: '1',
-        width: 100,
-        height: 100,
-        type: 'ReactElement',
-      },
-      {
-        id: '2',
-        width: 100,
-        height: 100,
-        type: 'ReactElement',
-      },
-    ];
-    const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
-      newState: () => ({ elements, links: [] }),
-      name: 'elements',
-    });
+      const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
+        newState: () => ({ elements: initialElements, links: {} }),
+        name: 'elements',
+      });
 
-    // Mock the setState method to be able to test the state updates.
-    const mockedSetState = jest.fn().mockImplementation(state.setState);
-    state.setState = mockedSetState;
-
-    const getIdsSnapshot = createGetIdsSnapshot(state);
-
-    // Here we initially sync the graph with the state.
-    // State should not be updated yet.
-    stateSync({ graph, store: state, getIdsSnapshot });
-    expect(graph.getElements()).toHaveLength(2);
-    expect(state.getSnapshot().elements).toHaveLength(2);
-    expect(mockedSetState).toHaveBeenCalledTimes(0);
-
-    // Here we update state via state API.
-    // State should not be updated yet.
-    state.setState((previous: GraphStoreSnapshot<GraphElement, GraphLink>) => ({
-      ...previous,
-      elements: [...previous.elements, { id: '3', width: 100, height: 100, type: 'ReactElement' }],
-    }));
-    expect(graph.getElements()).toHaveLength(3);
-    expect(state.getSnapshot().elements).toHaveLength(3);
-    expect(mockedSetState).toHaveBeenCalledTimes(1);
-
-    // Here we update dia.graph itself via normal JointJS API (not syncCells/batch).
-    // State should be updated now with 1 update call.
-    const newElement = new dia.Element({
-      id: '4',
-      type: 'ReactElement',
-      position: { x: 0, y: 0 },
-      size: { width: 100, height: 100 },
+      const { scheduler } = createMockScheduler();
+
+      stateSync({ graph, store: state, scheduler });
+
+      // Graph should have the elements from state
+      expect(graph.getElements()).toHaveLength(2);
+      expect(graph.getCell('1')).toBeDefined();
+      expect(graph.getCell('2')).toBeDefined();
     });
-    graph.addCell(newElement);
-    expect(graph.getElements()).toHaveLength(4);
-    expect(state.getSnapshot().elements).toHaveLength(4);
-    expect(mockedSetState).toHaveBeenCalledTimes(2);
-  });
 
-  it('should sync existing graph cells to store when store is empty', () => {
-    const graph = new dia.Graph(
-      {},
-      {
-        cellNamespace: {
-          ...DEFAULT_CELL_NAMESPACE,
-        },
-      }
-    );
+    it('should sync links from state to graph on initialization', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
-    // Add elements directly to graph before creating store
-    const existingElements = [
-      {
-        id: '1',
-        width: 100,
-        height: 100,
-        type: 'ReactElement',
-      },
-      {
-        id: '2',
-        width: 100,
-        height: 100,
-        type: 'ReactElement',
-      },
-    ];
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100, type: 'ReactElement' },
+        '2': { width: 100, height: 100, type: 'ReactElement' },
+      };
 
-    // Add elements to graph using syncCells
-    const elementItems = existingElements.map((element) =>
-      defaultMapDataToElementAttributes(createElementToGraphOptions(element, graph))
-    );
-    graph.syncCells(elementItems, { remove: true });
+      const initialLinks: Record<string, GraphLink> = {
+        link1: { source: '1', target: '2' },
+      };
 
-    // Create empty store
-    const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
-      newState: () => ({ elements: [], links: [] }),
-      name: 'elements',
-    });
+      const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
+        newState: () => ({ elements: initialElements, links: initialLinks }),
+        name: 'elements',
+      });
 
-    // Mock the setState method to be able to test the state updates.
-    const mockedSetState = jest.fn().mockImplementation(state.setState);
-    state.setState = mockedSetState;
+      const { scheduler } = createMockScheduler();
 
-    const getIdsSnapshot = createGetIdsSnapshot(state);
+      stateSync({ graph, store: state, scheduler });
 
-    // Graph has 2 elements, store is empty
-    expect(graph.getElements()).toHaveLength(2);
-    expect(state.getSnapshot().elements).toHaveLength(0);
+      expect(graph.getElements()).toHaveLength(2);
+      expect(graph.getLinks()).toHaveLength(1);
+      expect(graph.getCell('link1')).toBeDefined();
+    });
+  });
 
-    // Initialize stateSync - it should sync existing graph cells to store
-    stateSync({ graph, store: state, getIdsSnapshot });
+  describe('graph to state synchronization', () => {
+    it('should schedule element updates when graph element is added', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
-    // Store should now have the 2 elements from the graph
-    expect(state.getSnapshot().elements).toHaveLength(2);
-    expect(state.getSnapshot().elements[0].id).toBe('1');
-    expect(state.getSnapshot().elements[1].id).toBe('2');
-    expect(mockedSetState).toHaveBeenCalledTimes(1);
+      const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
+        newState: () => ({ elements: {}, links: {} }),
+        name: 'elements',
+      });
 
-    // Graph should still have 2 elements
-    expect(graph.getElements()).toHaveLength(2);
-  });
+      const { scheduler, setFlushCallback } = createMockScheduler();
 
-  it('should not sync existing graph cells to store when store already has elements', () => {
-    const graph = new dia.Graph(
-      {},
-      {
-        cellNamespace: {
-          ...DEFAULT_CELL_NAMESPACE,
-        },
-      }
-    );
+      // Track state updates via scheduler flush
+      setFlushCallback((data) => {
+        if (data.elementsToUpdate) {
+          const newElements: Record<string, GraphElement> = { ...state.getSnapshot().elements };
+          for (const [id, element] of data.elementsToUpdate) {
+            newElements[id] = element;
+          }
+          state.setState(() => ({ ...state.getSnapshot(), elements: newElements }));
+        }
+      });
 
-    // Add elements directly to graph
-    const graphElements = [
-      {
-        id: '1',
-        width: 100,
-        height: 100,
-        type: 'ReactElement',
-      },
-    ];
+      stateSync({ graph, store: state, scheduler });
 
-    const elementItems = graphElements.map((element) =>
-      defaultMapDataToElementAttributes(createElementToGraphOptions(element, graph))
-    );
-    graph.syncCells(elementItems, { remove: true });
-
-    // Create store with different elements
-    const storeElements = [
-      {
-        id: '2',
-        width: 100,
-        height: 100,
+      // Add element to graph
+      const element = new dia.Element({
+        id: 'new-element',
         type: 'ReactElement',
-      },
-    ];
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      graph.addCell(element);
 
-    const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
-      newState: () => ({ elements: storeElements, links: [] }),
-      name: 'elements',
+      // Wait for scheduler to flush
+      await flushScheduler();
+
+      // State should have the new element
+      expect(state.getSnapshot().elements['new-element']).toBeDefined();
     });
 
-    // Mock the setState method to be able to test the state updates.
-    const mockedSetState = jest.fn().mockImplementation(state.setState);
-    state.setState = mockedSetState;
+    it('should schedule element deletion when graph element is removed', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
-    const getIdsSnapshot = createGetIdsSnapshot(state);
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100, type: 'ReactElement' },
+      };
 
-    // Graph has 1 element, store has 1 different element
-    expect(graph.getElements()).toHaveLength(1);
-    expect(state.getSnapshot().elements).toHaveLength(1);
-    expect(state.getSnapshot().elements[0].id).toBe('2');
+      const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
+        newState: () => ({ elements: initialElements, links: {} }),
+        name: 'elements',
+      });
 
-    // Initialize stateSync - it should NOT sync graph cells to store since store is not empty
-    stateSync({ graph, store: state, getIdsSnapshot });
+      const { scheduler, setFlushCallback } = createMockScheduler();
 
-    // Store should still have its original element
-    expect(state.getSnapshot().elements).toHaveLength(1);
-    expect(state.getSnapshot().elements[0].id).toBe('2');
-    // setState should be called to sync store to graph, not the other way around
-    expect(mockedSetState).toHaveBeenCalledTimes(0);
+      setFlushCallback((data) => {
+        const currentSnapshot = state.getSnapshot();
+        const newElements = { ...currentSnapshot.elements };
 
-    // Graph should now have the element from store (synced from store to graph)
-    expect(graph.getElements()).toHaveLength(1);
-    expect(graph.getCell('2')).toBeDefined();
-  });
+        if (data.elementsToDelete) {
+          for (const [id] of data.elementsToDelete) {
+            // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+            delete newElements[id];
+          }
+        }
 
-  it('should sync existing graph links to store when store is empty', () => {
-    const graph = new dia.Graph(
-      {},
-      {
-        cellNamespace: {
-          ...DEFAULT_CELL_NAMESPACE,
-        },
-      }
-    );
+        state.setState(() => ({ ...currentSnapshot, elements: newElements }));
+      });
 
-    // Add elements and links directly to graph before creating store
-    const existingElements = [
-      {
-        id: '1',
-        width: 100,
-        height: 100,
-        type: 'ReactElement',
-      },
-      {
-        id: '2',
-        width: 100,
-        height: 100,
-        type: 'ReactElement',
-      },
-    ];
+      stateSync({ graph, store: state, scheduler });
 
-    const elementItems = existingElements.map((element) =>
-      defaultMapDataToElementAttributes(createElementToGraphOptions(element, graph))
-    );
-    const link = { id: 'link1', source: '1', target: '2' };
-    const linkItems = [defaultMapDataToLinkAttributes(createLinkToGraphOptions(link, graph))];
-    graph.syncCells([...elementItems, ...linkItems], { remove: true });
-
-    // Create empty store
-    const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
-      newState: () => ({ elements: [], links: [] }),
-      name: 'elements',
-    });
+      // Verify element was synced to graph
+      expect(graph.getCell('1')).toBeDefined();
 
-    // Mock the setState method to be able to test the state updates.
-    const mockedSetState = jest.fn().mockImplementation(state.setState);
-    state.setState = mockedSetState;
+      // Remove element from graph
+      graph.removeCells([graph.getCell('1')!]);
 
-    const getIdsSnapshot = createGetIdsSnapshot(state);
+      await flushScheduler();
 
-    // Graph has 2 elements and 1 link, store is empty
-    expect(graph.getElements()).toHaveLength(2);
-    expect(graph.getLinks()).toHaveLength(1);
-    expect(state.getSnapshot().elements).toHaveLength(0);
-    expect(state.getSnapshot().links).toHaveLength(0);
+      // State should not have the element
+      expect(state.getSnapshot().elements['1']).toBeUndefined();
+    });
 
-    // Initialize stateSync - it should sync existing graph cells (elements and links) to store
-    stateSync({ graph, store: state, getIdsSnapshot });
+    it('should schedule link updates when graph link is added', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
-    // Store should now have the 2 elements and 1 link from the graph
-    expect(state.getSnapshot().elements).toHaveLength(2);
-    expect(state.getSnapshot().links).toHaveLength(1);
-    expect(state.getSnapshot().links[0].id).toBe('link1');
-    expect(mockedSetState).toHaveBeenCalledTimes(1);
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100, type: 'ReactElement' },
+        '2': { width: 100, height: 100, type: 'ReactElement' },
+      };
 
-    // Graph should still have 2 elements and 1 link
-    expect(graph.getElements()).toHaveLength(2);
-    expect(graph.getLinks()).toHaveLength(1);
-  });
+      const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
+        newState: () => ({ elements: initialElements, links: {} }),
+        name: 'elements',
+      });
 
-  it('should handle cleanup properly and unsubscribe from all listeners', () => {
-    const graph = new dia.Graph(
-      {},
-      {
-        cellNamespace: {
-          ...DEFAULT_CELL_NAMESPACE,
-        },
-      }
-    );
-    const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
-      newState: () => ({ elements: [], links: [] }),
-      name: 'elements',
-    });
+      const { scheduler, setFlushCallback } = createMockScheduler();
+
+      setFlushCallback((data) => {
+        const currentSnapshot = state.getSnapshot();
+        const newLinks = { ...currentSnapshot.links };
 
-    const unsubscribeSpy = jest.fn();
-    state.subscribe = jest.fn(() => unsubscribeSpy);
+        if (data.linksToUpdate) {
+          for (const [id, link] of data.linksToUpdate) {
+            newLinks[id] = link;
+          }
+        }
 
-    const getIdsSnapshot = createGetIdsSnapshot(state);
-    const sync = stateSync({ graph, store: state, getIdsSnapshot });
+        state.setState(() => ({ ...currentSnapshot, links: newLinks }));
+      });
 
-    // Verify subscription was set up
-    expect(state.subscribe).toHaveBeenCalledTimes(1);
+      stateSync({ graph, store: state, scheduler });
 
-    // Cleanup
-    sync.cleanup();
+      // Add link to graph
+      const link = new dia.Link({
+        id: 'new-link',
+        type: 'ReactLink',
+        source: { id: '1' },
+        target: { id: '2' },
+      });
+      graph.addCell(link);
 
-    // Verify unsubscribe was called
-    expect(unsubscribeSpy).toHaveBeenCalledTimes(1);
-  });
+      await flushScheduler();
 
-  it('should subscribe to cell changes and allow unsubscribing', () => {
-    const graph = new dia.Graph(
-      {},
-      {
-        cellNamespace: {
-          ...DEFAULT_CELL_NAMESPACE,
-        },
-      }
-    );
-    const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
-      newState: () => ({ elements: [], links: [] }),
-      name: 'elements',
+      expect(state.getSnapshot().links['new-link']).toBeDefined();
     });
+  });
 
-    const getIdsSnapshot = createGetIdsSnapshot(state);
-    const sync = stateSync({ graph, store: state, getIdsSnapshot });
+  describe('state to graph synchronization', () => {
+    it('should update graph when state elements change', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
-    // eslint-disable-next-line unicorn/consistent-function-scoping
-    const cellChangeCallback = jest.fn(() => () => {});
-    const unsubscribe = sync.subscribeToGraphChange(cellChangeCallback);
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100, type: 'ReactElement' },
+      };
 
-    // Add a cell to trigger change
-    const element = new dia.Element({
-      id: 'test',
-      type: 'ReactElement',
-      position: { x: 0, y: 0 },
-      size: { width: 100, height: 100 },
-    });
-    graph.addCell(element);
+      const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
+        newState: () => ({ elements: initialElements, links: {} }),
+        name: 'elements',
+      });
 
-    // Wait a bit for the change to propagate
-    // The callback should have been called
-    // Note: This is a simplified test - in reality, the callback is called by listenToCellChange
+      const { scheduler } = createMockScheduler();
 
-    // Unsubscribe
-    unsubscribe();
+      stateSync({ graph, store: state, scheduler });
 
-    // Add another cell - callback should not be called again (though we can't easily test this without more setup)
-    // The important thing is that unsubscribe doesn't throw
-    expect(() => unsubscribe()).not.toThrow();
-  });
+      // Verify initial state
+      expect(graph.getElements()).toHaveLength(1);
 
-  it('should not sync existing graph cells when store has setState but it is undefined', () => {
-    const graph = new dia.Graph(
-      {},
-      {
-        cellNamespace: {
-          ...DEFAULT_CELL_NAMESPACE,
+      // Update state with new element
+      state.setState((previous) => ({
+        ...previous,
+        elements: {
+          ...previous.elements,
+          '2': { width: 100, height: 100, type: 'ReactElement' },
         },
-      }
-    );
+      }));
 
-    // Add elements to graph
-    const existingElements = [
-      {
-        id: '1',
-        width: 100,
-        height: 100,
-        type: 'ReactElement',
-      },
-    ];
+      // Graph should have the new element
+      expect(graph.getElements()).toHaveLength(2);
+      expect(graph.getCell('2')).toBeDefined();
+    });
 
-    const elementItems = existingElements.map((element) =>
-      defaultMapDataToElementAttributes(createElementToGraphOptions(element, graph))
-    );
-    graph.syncCells(elementItems, { remove: true });
+    it('should remove graph elements when state elements are removed', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
-    // Create store without setState
-    const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
-      newState: () => ({ elements: [], links: [] }),
-      name: 'elements',
-    });
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100, type: 'ReactElement' },
+        '2': { width: 100, height: 100, type: 'ReactElement' },
+      };
 
-    // Remove setState to simulate a read-only store
-    const originalSetState = state.setState;
-    // @ts-expect-error Testing edge case where setState might be undefined
-    state.setState = undefined;
+      const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
+        newState: () => ({ elements: initialElements, links: {} }),
+        name: 'elements',
+      });
 
-    const getIdsSnapshot = createGetIdsSnapshot(state);
+      const { scheduler } = createMockScheduler();
 
-    // Graph has 1 element, store is empty
-    expect(graph.getElements()).toHaveLength(1);
-    expect(state.getSnapshot().elements).toHaveLength(0);
+      stateSync({ graph, store: state, scheduler });
 
-    // Initialize stateSync - it should not crash and should not sync since setState is undefined
-    expect(() => {
-      stateSync({ graph, store: state, getIdsSnapshot });
-    }).not.toThrow();
+      // Verify initial state
+      expect(graph.getElements()).toHaveLength(2);
 
-    // Store should still be empty since setState was undefined
-    expect(state.getSnapshot().elements).toHaveLength(0);
+      // Remove element from state
+      state.setState((previous) => {
+        // eslint-disable-next-line sonarjs/no-unused-vars
+        const { '1': _, ...rest } = previous.elements;
+        return { ...previous, elements: rest };
+      });
 
-    // Restore setState for cleanup
-    state.setState = originalSetState;
+      // Graph should not have the element
+      expect(graph.getElements()).toHaveLength(1);
+      expect(graph.getCell('1')).toBeUndefined();
+      expect(graph.getCell('2')).toBeDefined();
+    });
   });
 
-  it('should handle graph with existing cells and initial elements/links - initial elements take precedence', () => {
-    const graph = new dia.Graph(
-      {},
-      {
-        cellNamespace: {
-          ...DEFAULT_CELL_NAMESPACE,
-        },
-      }
-    );
+  describe('circular update prevention', () => {
+    it('should not trigger state update when graph is updated from state (isUpdateFromReact flag)', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
-    // Add elements to graph
-    const graphElements = [
-      {
-        id: 'graph-element',
-        width: 100,
-        height: 100,
-        type: 'ReactElement',
-      },
-    ];
+      const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
+        newState: () => ({ elements: {}, links: {} }),
+        name: 'elements',
+      });
 
-    const elementItems = graphElements.map((element) =>
-      defaultMapDataToElementAttributes(createElementToGraphOptions(element, graph))
-    );
-    graph.syncCells(elementItems, { remove: true });
-
-    // Create store with initial elements (different from graph)
-    const initialElements = [
-      {
-        id: 'initial-element',
-        width: 100,
-        height: 100,
-        type: 'ReactElement',
-      },
-    ];
+      const { scheduler, scheduledData } = createMockScheduler();
 
-    const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
-      newState: () => ({ elements: initialElements, links: [] }),
-      name: 'elements',
-    });
+      stateSync({ graph, store: state, scheduler });
 
-    // Mock the setState method
-    const mockedSetState = jest.fn().mockImplementation(state.setState);
-    state.setState = mockedSetState;
+      const initialScheduledCount = scheduledData.length;
 
-    const getIdsSnapshot = createGetIdsSnapshot(state);
+      // Update state - this should update graph but NOT schedule data back
+      state.setState((previous) => ({
+        ...previous,
+        elements: {
+          '1': { width: 100, height: 100, type: 'ReactElement' },
+        },
+      }));
 
-    // Graph has 1 element, store has 1 different element
-    expect(graph.getElements()).toHaveLength(1);
-    expect(state.getSnapshot().elements).toHaveLength(1);
-    expect(state.getSnapshot().elements[0].id).toBe('initial-element');
+      await flushScheduler();
 
-    // Initialize stateSync
-    stateSync({ graph, store: state, getIdsSnapshot });
+      // Graph should have the element
+      expect(graph.getCell('1')).toBeDefined();
 
-    // Since store has initial elements, they should take precedence
-    // The graph should be synced to match the store (initial elements)
-    expect(graph.getElements()).toHaveLength(1);
-    expect(graph.getCell('initial-element')).toBeDefined();
-    expect(graph.getCell('graph-element')).toBeUndefined();
+      // No new data should have been scheduled (because isUpdateFromReact prevents it)
+      expect(scheduledData.length).toBe(initialScheduledCount);
+    });
   });
 
-  it('should handle external store with existing graph cells - store takes precedence', () => {
-    const graph = new dia.Graph(
-      {},
-      {
-        cellNamespace: {
-          ...DEFAULT_CELL_NAMESPACE,
-        },
-      }
-    );
-
-    // Add elements to graph
-    const graphElements = [
-      {
-        id: 'graph-element',
-        width: 100,
-        height: 100,
-        type: 'ReactElement',
-      },
-    ];
+  describe('sync existing graph cells', () => {
+    it('should sync existing graph cells to empty store on initialization', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
-    const elementItems = graphElements.map((element) =>
-      defaultMapDataToElementAttributes(createElementToGraphOptions(element, graph))
-    );
-    graph.syncCells(elementItems, { remove: true });
-
-    // Create external store with different elements
-    const externalElements = [
-      {
-        id: 'external-element',
-        width: 100,
-        height: 100,
-        type: 'ReactElement',
-      },
-    ];
+      // Add elements to graph before creating stateSync
+      const existingElements = [
+        { id: '1', data: { width: 100, height: 100, type: 'ReactElement' } },
+        { id: '2', data: { width: 100, height: 100, type: 'ReactElement' } },
+      ];
 
-    const externalStore = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
-      newState: () => ({ elements: externalElements, links: [] }),
-      name: 'external',
-    });
+      const elementItems = existingElements.map(({ id, data }) =>
+        defaultMapDataToElementAttributes(createElementToGraphOptions(id, data, graph))
+      );
+      graph.syncCells(elementItems, { remove: true });
 
-    // Mock the setState method
-    const mockedSetState = jest.fn().mockImplementation(externalStore.setState);
-    externalStore.setState = mockedSetState;
+      // Create empty store
+      const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
+        newState: () => ({ elements: {}, links: {} }),
+        name: 'elements',
+      });
 
-    const getIdsSnapshot = createGetIdsSnapshot(externalStore);
+      const { scheduler, setFlushCallback } = createMockScheduler();
 
-    // Graph has 1 element, external store has 1 different element
-    expect(graph.getElements()).toHaveLength(1);
-    expect(externalStore.getSnapshot().elements).toHaveLength(1);
-    expect(externalStore.getSnapshot().elements[0].id).toBe('external-element');
+      setFlushCallback((data) => {
+        const currentSnapshot = state.getSnapshot();
+        const newElements = { ...currentSnapshot.elements };
 
-    // Initialize stateSync with external store
-    stateSync({ graph, store: externalStore, getIdsSnapshot });
+        if (data.elementsToUpdate) {
+          for (const [id, element] of data.elementsToUpdate) {
+            newElements[id] = element;
+          }
+        }
 
-    // External store should take precedence - graph should be synced to match external store
-    expect(graph.getElements()).toHaveLength(1);
-    expect(graph.getCell('external-element')).toBeDefined();
-    expect(graph.getCell('graph-element')).toBeUndefined();
+        state.setState(() => ({ ...currentSnapshot, elements: newElements }));
+      });
 
-    // External store should not be modified (it's the source of truth)
-    expect(externalStore.getSnapshot().elements).toHaveLength(1);
-    expect(externalStore.getSnapshot().elements[0].id).toBe('external-element');
-  });
+      // Graph has 2 elements, store is empty
+      expect(graph.getElements()).toHaveLength(2);
+      expect(Object.keys(state.getSnapshot().elements)).toHaveLength(0);
 
-  it('should prevent circular updates when syncing from state to graph', () => {
-    const graph = new dia.Graph(
-      {},
-      {
-        cellNamespace: {
-          ...DEFAULT_CELL_NAMESPACE,
-        },
-      }
-    );
+      stateSync({ graph, store: state, scheduler });
 
-    const elements = [
-      {
-        id: '1',
-        width: 100,
-        height: 100,
-        type: 'ReactElement',
-      },
-    ];
+      await flushScheduler();
 
-    const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
-      newState: () => ({ elements, links: [] }),
-      name: 'elements',
+      // Store should now have the 2 elements from the graph
+      expect(Object.keys(state.getSnapshot().elements)).toHaveLength(2);
     });
 
-    const getIdsSnapshot = createGetIdsSnapshot(state);
+    it('should NOT sync existing graph cells when store already has elements', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
-    // Initialize stateSync first
-    stateSync({ graph, store: state, getIdsSnapshot });
+      // Add elements to graph
+      const graphElements = [
+        { id: 'graph-element', data: { width: 100, height: 100, type: 'ReactElement' } },
+      ];
+      const elementItems = graphElements.map(({ id, data }) =>
+        defaultMapDataToElementAttributes(createElementToGraphOptions(id, data, graph))
+      );
+      graph.syncCells(elementItems, { remove: true });
 
-    // Verify initial state
-    expect(graph.getElements()).toHaveLength(1);
-    expect(state.getSnapshot().elements).toHaveLength(1);
-
-    // Update state - this should trigger graph sync, but not cause circular updates
-    // The graph sync should update the graph, but the graph change should not trigger
-    // another state update because of the isSyncingFromState flag
-    state.setState((previous) => ({
-      ...previous,
-      elements: [...previous.elements, { id: '2', width: 100, height: 100, type: 'ReactElement' }],
-    }));
-
-    // Graph should have 2 elements (synced from state)
-    expect(graph.getElements()).toHaveLength(2);
-    expect(graph.getCell('1')).toBeDefined();
-    expect(graph.getCell('2')).toBeDefined();
+      // Create store with different elements
+      const storeElements: Record<string, GraphElement> = {
+        'store-element': { width: 100, height: 100, type: 'ReactElement' },
+      };
 
-    // State should still have 2 elements
-    expect(state.getSnapshot().elements).toHaveLength(2);
+      const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
+        newState: () => ({ elements: storeElements, links: {} }),
+        name: 'elements',
+      });
 
-    // Now update graph directly - this should update state, but not cause circular updates
-    const newElement = new dia.Element({
-      id: '3',
-      type: 'ReactElement',
-      position: { x: 0, y: 0 },
-      size: { width: 100, height: 100 },
-    });
-    graph.addCell(newElement);
+      const { scheduler } = createMockScheduler();
 
-    // Graph should have 3 elements
-    expect(graph.getElements()).toHaveLength(3);
+      // Graph has 1 element, store has 1 different element
+      expect(graph.getElements()).toHaveLength(1);
+      expect(Object.keys(state.getSnapshot().elements)).toHaveLength(1);
+      expect(state.getSnapshot().elements['store-element']).toBeDefined();
 
-    // State should be updated with the new element (from graph)
-    // This verifies that graph -> state sync works without causing state -> graph -> state loops
-    expect(state.getSnapshot().elements).toHaveLength(3);
-    expect(state.getSnapshot().elements.find((element) => element.id === '3')).toBeDefined();
-  });
+      stateSync({ graph, store: state, scheduler });
 
-  describe('shape preservation', () => {
-    it('should preserve element shape (only include user-defined properties) after reset', () => {
-      const graph = new dia.Graph(
-        {},
-        {
-          cellNamespace: {
-            ...DEFAULT_CELL_NAMESPACE,
-          },
-        }
-      );
+      // Store should keep its elements (state takes precedence)
+      expect(state.getSnapshot().elements['store-element']).toBeDefined();
 
-      // User defines elements WITHOUT x/y properties
-      type CustomElement = GraphElement & { label: string };
-      const elements: CustomElement[] = [
-        {
-          id: '1',
-          width: 100,
-          height: 100,
-          type: 'ReactElement',
-          label: 'Element 1',
-        },
-      ];
+      // Graph should be synced to match store
+      expect(graph.getCell('store-element')).toBeDefined();
+      expect(graph.getCell('graph-element')).toBeUndefined();
+    });
+  });
 
-      const state = createState<GraphStoreSnapshot<CustomElement, GraphLink>>({
-        newState: () => ({ elements, links: [] }),
+  describe('cleanup', () => {
+    it('should properly cleanup all listeners on cleanup()', () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
+
+      const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
+        newState: () => ({ elements: {}, links: {} }),
         name: 'elements',
       });
 
-      const getIdsSnapshot = createGetIdsSnapshot(state);
+      const unsubscribeSpy = jest.fn();
+      state.subscribe = jest.fn(() => unsubscribeSpy);
 
-      // Initialize stateSync
-      stateSync({ graph, store: state, getIdsSnapshot });
+      const { scheduler } = createMockScheduler();
 
-      // Graph should have the element with position added by JointJS
-      expect(graph.getElements()).toHaveLength(1);
-      const cell = graph.getCell('1');
-      expect(cell?.get('position')).toBeDefined();
+      const sync = stateSync({ graph, store: state, scheduler });
 
-      // Trigger a reset by clearing and re-adding
-      graph.resetCells([
-        {
-          id: '1',
-          type: 'ReactElement',
-          position: { x: 150, y: 200 },
-          size: { width: 100, height: 100 },
-          data: { label: 'Element 1' },
-        },
-      ]);
+      // Verify subscription was set up
+      expect(state.subscribe).toHaveBeenCalledTimes(1);
 
-      // State should NOT have x/y because they weren't in original state
-      const snapshot = state.getSnapshot();
-      expect(snapshot.elements).toHaveLength(1);
-      expect(snapshot.elements[0]).not.toHaveProperty('x');
-      expect(snapshot.elements[0]).not.toHaveProperty('y');
-      expect(snapshot.elements[0].label).toBe('Element 1');
+      // Cleanup
+      sync.cleanup();
+
+      // Verify unsubscribe was called
+      expect(unsubscribeSpy).toHaveBeenCalledTimes(1);
     });
+  });
 
-    it('should include x/y in state after reset when user defines them (even as undefined)', () => {
-      const graph = new dia.Graph(
-        {},
-        {
-          cellNamespace: {
-            ...DEFAULT_CELL_NAMESPACE,
-          },
-        }
-      );
+  describe('reset handling', () => {
+    it('should handle graph reset correctly', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
-      // User defines elements WITH x/y properties (as undefined)
-      type CustomElement = GraphElement & { label: string };
-      const elements: CustomElement[] = [
-        {
-          id: '1',
-          x: undefined,
-          y: undefined,
-          width: 100,
-          height: 100,
-          type: 'ReactElement',
-          label: 'Element 1',
-        },
-      ];
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100, type: 'ReactElement' },
+        '2': { width: 100, height: 100, type: 'ReactElement' },
+      };
 
-      const state = createState<GraphStoreSnapshot<CustomElement, GraphLink>>({
-        newState: () => ({ elements, links: [] }),
+      const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
+        newState: () => ({ elements: initialElements, links: {} }),
         name: 'elements',
       });
 
-      const getIdsSnapshot = createGetIdsSnapshot(state);
+      const { scheduler, setFlushCallback } = createMockScheduler();
+
+      setFlushCallback((data) => {
+        const currentSnapshot = state.getSnapshot();
+        const newElements = { ...currentSnapshot.elements };
+
+        if (data.elementsToUpdate) {
+          for (const [id, element] of data.elementsToUpdate) {
+            newElements[id] = element;
+          }
+        }
+
+        if (data.elementsToDelete) {
+          for (const [id] of data.elementsToDelete) {
+            // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+            delete newElements[id];
+          }
+        }
+
+        state.setState(() => ({ elements: newElements, links: currentSnapshot.links }));
+      });
 
-      // Initialize stateSync
-      stateSync({ graph, store: state, getIdsSnapshot });
+      stateSync({ graph, store: state, scheduler });
 
-      // Trigger a reset
+      // Verify initial state
+      expect(graph.getElements()).toHaveLength(2);
+
+      // Reset graph with new cells
       graph.resetCells([
         {
-          id: '1',
+          id: '3',
           type: 'ReactElement',
-          position: { x: 150, y: 200 },
+          position: { x: 0, y: 0 },
           size: { width: 100, height: 100 },
-          data: { label: 'Element 1' },
         },
       ]);
 
-      // State SHOULD have x/y because they were in original state
+      await flushScheduler();
+
+      // State should have only the new element
       const snapshot = state.getSnapshot();
-      expect(snapshot.elements).toHaveLength(1);
-      expect(snapshot.elements[0].x).toBe(150);
-      expect(snapshot.elements[0].y).toBe(200);
-      expect(snapshot.elements[0].label).toBe('Element 1');
+      expect(snapshot.elements['3']).toBeDefined();
+      expect(snapshot.elements['1']).toBeUndefined();
+      expect(snapshot.elements['2']).toBeUndefined();
     });
+  });
+});
 
-    it('should preserve link shape (only include user-defined properties) after reset', () => {
-      const graph = new dia.Graph(
-        {},
-        {
-          cellNamespace: {
-            ...DEFAULT_CELL_NAMESPACE,
-          },
-        }
-      );
+describe('stateSync - comprehensive edge cases', () => {
+  describe('batching behavior', () => {
+    it('should batch multiple element updates into single scheduler call', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
-      // User defines links WITHOUT attrs property
-      type CustomLink = GraphLink & { label: string };
-      const elements = [
-        { id: '1', width: 100, height: 100, type: 'ReactElement' },
-        { id: '2', width: 100, height: 100, type: 'ReactElement' },
-      ];
-      const links: CustomLink[] = [
-        {
-          id: 'link-1',
-          source: '1',
-          target: '2',
-          label: 'Connection',
-          // Note: attrs is NOT defined
-        },
-      ];
-
-      const state = createState<GraphStoreSnapshot<GraphElement, CustomLink>>({
-        newState: () => ({ elements, links }),
+      const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
+        newState: () => ({ elements: {}, links: {} }),
         name: 'elements',
       });
 
-      const getIdsSnapshot = createGetIdsSnapshot(state);
+      let flushCount = 0;
+      const { scheduler, setFlushCallback } = createMockScheduler();
 
-      // Initialize stateSync
-      stateSync({ graph, store: state, getIdsSnapshot });
+      setFlushCallback(() => {
+        flushCount++;
+      });
 
-      // Graph should have the link with attrs added by JointJS
-      expect(graph.getLinks()).toHaveLength(1);
-      const linkCell = graph.getCell('link-1') as dia.Link;
-      expect(linkCell.attr()).toBeDefined();
+      stateSync({ graph, store: state, scheduler });
 
-      // Trigger a reset
-      const resetElements = elements.map((element) =>
-        defaultMapDataToElementAttributes(createElementToGraphOptions(element, graph))
-      );
-      graph.resetCells([
-        ...resetElements,
-        {
-          id: 'link-1',
-          type: 'standard.Link',
-          source: { id: '1' },
-          target: { id: '2' },
-          data: { label: 'Connection' },
-          attrs: { line: { stroke: 'red' } }, // JointJS adds attrs
-        },
+      // Add multiple elements rapidly - should be batched
+      graph.addCells([
+        { id: '1', type: 'ReactElement', size: { width: 100, height: 100 } },
+        { id: '2', type: 'ReactElement', size: { width: 100, height: 100 } },
+        { id: '3', type: 'ReactElement', size: { width: 100, height: 100 } },
       ]);
 
-      // State should NOT have attrs because it wasn't in original state
-      const snapshot = state.getSnapshot();
-      expect(snapshot.links).toHaveLength(1);
-      expect(snapshot.links[0]).not.toHaveProperty('attrs');
-      expect(snapshot.links[0].label).toBe('Connection');
+      await flushScheduler();
+
+      // Should have batched into single flush (or minimal number of flushes)
+      expect(flushCount).toBeLessThanOrEqual(2);
     });
-  });
 
-  describe('cell change listeners optimization', () => {
-    it('should batch listener calls in onIncrementalChange instead of calling immediately', () => {
-      const graph = new dia.Graph(
-        {},
-        {
-          cellNamespace: {
-            ...DEFAULT_CELL_NAMESPACE,
-          },
-        }
-      );
+    it('should handle rapid add/remove cycles', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
       const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
-        newState: () => ({ elements: [], links: [] }),
+        newState: () => ({ elements: {}, links: {} }),
         name: 'elements',
       });
 
-      const getIdsSnapshot = createGetIdsSnapshot(state);
-      const sync = stateSync({ graph, store: state, getIdsSnapshot });
+      const { scheduler, setFlushCallback } = createMockScheduler();
 
-      const listenerCalls: Array<{ type: string; cellId?: string }> = [];
-      const cellChangeCallback = jest.fn((change) => {
-        if (change.type === 'reset') {
-          listenerCalls.push({ type: 'reset' });
-        } else {
-          listenerCalls.push({ type: change.type, cellId: change.cell.id.toString() });
+      setFlushCallback((data) => {
+        const currentSnapshot = state.getSnapshot();
+        const newElements = { ...currentSnapshot.elements };
+
+        if (data.elementsToUpdate) {
+          for (const [id, element] of data.elementsToUpdate) {
+            newElements[id] = element;
+          }
         }
-        return () => {};
-      });
 
-      sync.subscribeToGraphChange(cellChangeCallback);
+        if (data.elementsToDelete) {
+          for (const [id] of data.elementsToDelete) {
+            // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+            delete newElements[id];
+          }
+        }
 
-      // Add multiple cells in quick succession
-      const element1 = new dia.Element({
-        id: '1',
-        type: 'ReactElement',
-        position: { x: 0, y: 0 },
-        size: { width: 100, height: 100 },
+        state.setState(() => ({ ...currentSnapshot, elements: newElements }));
       });
-      const element2 = new dia.Element({
-        id: '2',
+
+      stateSync({ graph, store: state, scheduler });
+
+      // Add then remove quickly
+      const element = new dia.Element({
+        id: 'temp',
         type: 'ReactElement',
-        position: { x: 100, y: 100 },
         size: { width: 100, height: 100 },
       });
+      graph.addCell(element);
+      graph.removeCells([element]);
 
-      graph.addCell(element1);
-      graph.addCell(element2);
-
-      // Listeners should be called in batches via onIncrementalChange
-      // Not immediately on each cell change
-      // The exact number depends on batching, but should be called
-      expect(cellChangeCallback).toHaveBeenCalled();
-      expect(listenerCalls.length).toBeGreaterThan(0);
+      await flushScheduler();
 
-      // Verify we received the correct change types
-      const addCalls = listenerCalls.filter((call) => call.type === 'add');
-      expect(addCalls.length).toBeGreaterThanOrEqual(2);
+      // Element should be removed (delete wins over add)
+      expect(state.getSnapshot().elements['temp']).toBeUndefined();
     });
+  });
 
-    it('should call listeners before isEqual check in onIncrementalChange', () => {
-      const graph = new dia.Graph(
-        {},
-        {
-          cellNamespace: {
-            ...DEFAULT_CELL_NAMESPACE,
-          },
-        }
-      );
+  describe('element and link updates', () => {
+    it('should handle element position updates', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
-      const elements = [
-        {
-          id: '1',
-          x: 0,
-          y: 0,
-          width: 100,
-          height: 100,
-          type: 'ReactElement',
-        },
-      ];
+      const initialElements: Record<string, GraphElement> = {
+        '1': { x: 0, y: 0, width: 100, height: 100, type: 'ReactElement' },
+      };
 
       const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
-        newState: () => ({ elements, links: [] }),
+        newState: () => ({ elements: initialElements, links: {} }),
         name: 'elements',
       });
 
-      const getIdsSnapshot = createGetIdsSnapshot(state);
-      const sync = stateSync({ graph, store: state, getIdsSnapshot });
-
-      let listenerCalledBeforeIsEqual = false;
-      const cellChangeCallback = jest.fn((change) => {
-        // This listener should be called before isEqual check
-        // We can verify this by checking that the graph has the updated cell
-        // even if state doesn't have layout data (x/y/width/height)
-        if (change.type !== 'reset' && change.cell) {
-          const cell = graph.getCell(change.cell.id);
-          listenerCalledBeforeIsEqual = cell != null;
+      const { scheduler, setFlushCallback } = createMockScheduler();
+
+      setFlushCallback((data) => {
+        if (data.elementsToUpdate) {
+          const newElements: Record<string, GraphElement> = { ...state.getSnapshot().elements };
+          for (const [id, element] of data.elementsToUpdate) {
+            newElements[id] = element;
+          }
+          state.setState((previous) => ({ ...previous, elements: newElements }));
         }
-        return () => {};
       });
 
-      sync.subscribeToGraphChange(cellChangeCallback);
+      stateSync({ graph, store: state, scheduler });
 
-      // Modify a cell in the graph
-      const cell = graph.getCell('1');
-      if (cell) {
-        cell.set('position', { x: 50, y: 50 });
-      }
+      // Move element in graph
+      const element = graph.getCell('1') as dia.Element;
+      element.position(50, 50);
 
-      // Listener should have been called
-      expect(cellChangeCallback).toHaveBeenCalled();
-      expect(listenerCalledBeforeIsEqual).toBe(true);
+      await flushScheduler();
+
+      const updatedElement = state.getSnapshot().elements['1'];
+      expect(updatedElement.x).toBe(50);
+      expect(updatedElement.y).toBe(50);
     });
 
-    it('should call listeners in onBatchStop when syncing from state', () => {
-      const graph = new dia.Graph(
-        {},
-        {
-          cellNamespace: {
-            ...DEFAULT_CELL_NAMESPACE,
-          },
-        }
-      );
+    it('should handle element resize updates', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
+
+      const initialElements: Record<string, GraphElement> = {
+        '1': { x: 0, y: 0, width: 100, height: 100, type: 'ReactElement' },
+      };
 
       const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
-        newState: () => ({ elements: [], links: [] }),
+        newState: () => ({ elements: initialElements, links: {} }),
         name: 'elements',
       });
 
-      const getIdsSnapshot = createGetIdsSnapshot(state);
-      const sync = stateSync({ graph, store: state, getIdsSnapshot });
+      const { scheduler, setFlushCallback } = createMockScheduler();
 
-      const listenerCalls: Array<{ type: string; cellId?: string }> = [];
-      const cellChangeCallback = jest.fn((change) => {
-        if (change.type === 'reset') {
-          listenerCalls.push({ type: 'reset' });
-        } else {
-          listenerCalls.push({ type: change.type, cellId: change.cell.id.toString() });
+      setFlushCallback((data) => {
+        if (data.elementsToUpdate) {
+          const newElements: Record<string, GraphElement> = { ...state.getSnapshot().elements };
+          for (const [id, element] of data.elementsToUpdate) {
+            newElements[id] = element;
+          }
+          state.setState((previous) => ({ ...previous, elements: newElements }));
         }
-        return () => {};
       });
 
-      sync.subscribeToGraphChange(cellChangeCallback);
+      stateSync({ graph, store: state, scheduler });
 
-      // Update state - this triggers sync from state to graph
-      // The sync happens in a batch, and listeners should be called in onBatchStop
-      state.setState((previous) => ({
-        ...previous,
-        elements: [
-          { id: '1', x: 0, y: 0, width: 100, height: 100, type: 'ReactElement' },
-          { id: '2', x: 100, y: 100, width: 100, height: 100, type: 'ReactElement' },
-        ],
-      }));
+      // Resize element in graph
+      const element = graph.getCell('1') as dia.Element;
+      element.resize(200, 200);
 
-      // Graph should have the elements
-      expect(graph.getElements()).toHaveLength(2);
-
-      // Listeners should have been called (in onBatchStop when syncing from state)
-      expect(cellChangeCallback).toHaveBeenCalled();
-      expect(listenerCalls.length).toBeGreaterThan(0);
+      await flushScheduler();
 
-      // Verify we received add calls for the new elements
-      const addCalls = listenerCalls.filter((call) => call.type === 'add');
-      expect(addCalls.length).toBeGreaterThanOrEqual(2);
+      const updatedElement = state.getSnapshot().elements['1'];
+      expect(updatedElement.width).toBe(200);
+      expect(updatedElement.height).toBe(200);
     });
 
-    it('should handle reset changes correctly in batched listener calls', () => {
-      const graph = new dia.Graph(
-        {},
-        {
-          cellNamespace: {
-            ...DEFAULT_CELL_NAMESPACE,
-          },
-        }
-      );
+    it('should handle link source/target updates', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
-      const elements = [
-        {
-          id: '1',
-          x: 0,
-          y: 0,
-          width: 100,
-          height: 100,
-          type: 'ReactElement',
-        },
-      ];
+      const initialElements: Record<string, GraphElement> = {
+        '1': { width: 100, height: 100, type: 'ReactElement' },
+        '2': { width: 100, height: 100, type: 'ReactElement' },
+        '3': { width: 100, height: 100, type: 'ReactElement' },
+      };
+
+      const initialLinks: Record<string, GraphLink> = {
+        link1: { source: '1', target: '2' },
+      };
 
       const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
-        newState: () => ({ elements, links: [] }),
+        newState: () => ({ elements: initialElements, links: initialLinks }),
         name: 'elements',
       });
 
-      const getIdsSnapshot = createGetIdsSnapshot(state);
-      const sync = stateSync({ graph, store: state, getIdsSnapshot });
+      const { scheduler, setFlushCallback } = createMockScheduler();
 
-      const resetCalls: Array<{ type: string; cellsCount?: number }> = [];
-      const cellChangeCallback = jest.fn((change) => {
-        if (change.type === 'reset') {
-          resetCalls.push({
-            type: 'reset',
-            cellsCount: change.cells?.length ?? 0,
-          });
+      setFlushCallback((data) => {
+        if (data.linksToUpdate) {
+          const newLinks: Record<string, GraphLink> = { ...state.getSnapshot().links };
+          for (const [id, link] of data.linksToUpdate) {
+            newLinks[id] = link;
+          }
+          state.setState((previous) => ({ ...previous, links: newLinks }));
         }
-        return () => {};
       });
 
-      sync.subscribeToGraphChange(cellChangeCallback);
+      stateSync({ graph, store: state, scheduler });
 
-      // Wait for initial sync to complete
-      expect(graph.getElements()).toHaveLength(1);
+      // Update link target
+      const link = graph.getCell('link1') as dia.Link;
+      link.target({ id: '3' });
+
+      await flushScheduler();
+
+      const updatedLink = state.getSnapshot().links['link1'];
+      // Link target from JointJS is an object with id property
+      expect(updatedLink.target).toEqual({ id: '3' });
+    });
+  });
+
+  describe('error handling and edge cases', () => {
+    it('should handle empty graph gracefully', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
+
+      const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
+        newState: () => ({ elements: {}, links: {} }),
+        name: 'elements',
+      });
+
+      const { scheduler } = createMockScheduler();
 
-      // Clear the graph to trigger reset
-      // Note: graph.clear() triggers reset event which is stored and called in onIncrementalChange
-      graph.clear();
+      // Should not throw
+      const sync = stateSync({ graph, store: state, scheduler });
 
-      // Verify graph is cleared
       expect(graph.getElements()).toHaveLength(0);
+      expect(graph.getLinks()).toHaveLength(0);
 
-      // The reset event should be stored and listeners called in onIncrementalChange
-      // Verify that the callback was invoked (reset might be batched)
-      expect(cellChangeCallback).toHaveBeenCalled();
+      sync.cleanup();
+    });
 
-      // Verify that reset changes are properly handled by checking the callback structure
-      // Reset changes are batched, so they may not appear immediately
-      // The important thing is that the mechanism exists to handle reset in onIncrementalChange
-      const allCallTypes = cellChangeCallback.mock.calls.map((call) => call[0]?.type);
+    it('should handle removing non-existent elements gracefully', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
-      // Verify reset can be handled (either was called or mechanism exists)
-      // If reset was called, verify structure
-      if (resetCalls.length > 0) {
-        expect(resetCalls[0]?.type).toBe('reset');
-        expect(resetCalls[0]?.cellsCount).toBeDefined();
-      }
+      const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
+        newState: () => ({ elements: {}, links: {} }),
+        name: 'elements',
+      });
+
+      const { scheduler } = createMockScheduler();
 
-      // Verify the callback receives proper change objects
-      expect(allCallTypes.length).toBeGreaterThan(0);
+      stateSync({ graph, store: state, scheduler });
+
+      // Try to remove non-existent cell - should not throw
+      expect(() => {
+        state.setState((previous) => {
+          // eslint-disable-next-line sonarjs/no-unused-vars
+          const { 'non-existent': _, ...rest } = previous.elements;
+          return { ...previous, elements: rest };
+        });
+      }).not.toThrow();
     });
 
-    it('should clear pending changes after calling listeners', () => {
-      const graph = new dia.Graph(
-        {},
-        {
-          cellNamespace: {
-            ...DEFAULT_CELL_NAMESPACE,
-          },
-        }
-      );
+    it('should handle multiple cleanup calls gracefully', () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
 
       const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
-        newState: () => ({ elements: [], links: [] }),
+        newState: () => ({ elements: {}, links: {} }),
         name: 'elements',
       });
 
-      const getIdsSnapshot = createGetIdsSnapshot(state);
-      const sync = stateSync({ graph, store: state, getIdsSnapshot });
+      const { scheduler } = createMockScheduler();
+
+      const sync = stateSync({ graph, store: state, scheduler });
+
+      // Should not throw on multiple cleanup calls
+      expect(() => {
+        sync.cleanup();
+        sync.cleanup();
+      }).not.toThrow();
+    });
+  });
+
+  describe('concurrent updates', () => {
+    it('should handle simultaneous graph and state updates', async () => {
+      const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
+
+      const initialElements: Record<string, GraphElement> = {
+        '1': { x: 0, y: 0, width: 100, height: 100, type: 'ReactElement' },
+      };
 
-      let callCount = 0;
-      const cellChangeCallback = jest.fn((_change) => {
-        callCount++;
-        return () => {};
+      const state = createState<GraphStoreSnapshot<GraphElement, GraphLink>>({
+        newState: () => ({ elements: initialElements, links: {} }),
+        name: 'elements',
       });
 
-      sync.subscribeToGraphChange(cellChangeCallback);
+      const { scheduler, setFlushCallback } = createMockScheduler();
 
-      // Add a cell
-      const element = new dia.Element({
-        id: '1',
-        type: 'ReactElement',
-        position: { x: 0, y: 0 },
-        size: { width: 100, height: 100 },
+      setFlushCallback((data) => {
+        if (data.elementsToUpdate) {
+          const newElements: Record<string, GraphElement> = { ...state.getSnapshot().elements };
+          for (const [id, element] of data.elementsToUpdate) {
+            newElements[id] = element;
+          }
+          state.setState((previous) => ({ ...previous, elements: newElements }));
+        }
       });
-      graph.addCell(element);
 
-      // Modify the same cell multiple times to test batching
-      const cell = graph.getCell('1');
-      if (cell) {
-        // Intentionally modify cell multiple times to test that changes are batched
-        cell.set('position', { x: 10, y: 10 });
-        cell.set('size', { width: 110, height: 110 });
-        cell.set('position', { x: 20, y: 20 });
-      }
+      stateSync({ graph, store: state, scheduler });
+
+      // Update from state (React side)
+      state.setState((previous) => ({
+        ...previous,
+        elements: {
+          ...previous.elements,
+          '2': { x: 100, y: 100, width: 100, height: 100, type: 'ReactElement' },
+        },
+      }));
+
+      // Update from graph (JointJS side) simultaneously
+      const element = graph.getCell('1') as dia.Element;
+      element.position(50, 50);
+
+      await flushScheduler();
+
+      // Both updates should be reflected
+      expect(graph.getCell('2')).toBeDefined();
+    });
+  });
+});
+
+describe('updateGraph', () => {
+  it('should update graph when elements differ', () => {
+    const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
+
+    const elements: Record<string, GraphElement> = {
+      '1': { width: 100, height: 100, type: 'ReactElement' },
+    };
+
+    const result = updateGraph({
+      graph,
+      elements,
+      links: {},
+      graphToElementSelector: (options) => mapElementAttributesToData(options),
+      graphToLinkSelector: (options) => mapLinkAttributesToData(options),
+      mapDataToElementAttributes: (options) => defaultMapDataToElementAttributes(options),
+      mapDataToLinkAttributes: (options) => defaultMapDataToLinkAttributes(options),
+    });
+
+    expect(result).toBe(true);
+    expect(graph.getElements()).toHaveLength(1);
+    expect(graph.getCell('1')).toBeDefined();
+  });
 
-      // Listener should be called, but changes should be batched
-      // Each change should be tracked, but listener might be called once per batch
-      expect(cellChangeCallback).toHaveBeenCalled();
-      expect(callCount).toBeGreaterThan(0);
+  it('should return false when graph is already in sync', () => {
+    const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
+
+    // Include x and y as they are returned by mapElementAttributesToData
+    const elements: Record<string, GraphElement> = {
+      '1': { width: 100, height: 100, x: 0, y: 0, type: 'ReactElement' },
+    };
+
+    // First sync
+    updateGraph({
+      graph,
+      elements,
+      links: {},
+      graphToElementSelector: (options) => mapElementAttributesToData(options),
+      graphToLinkSelector: (options) => mapLinkAttributesToData(options),
+      mapDataToElementAttributes: (options) => defaultMapDataToElementAttributes(options),
+      mapDataToLinkAttributes: (options) => defaultMapDataToLinkAttributes(options),
     });
+
+    // Get what the graph now thinks the element is
+    const [graphElement] = graph.getElements();
+    const id = graphElement.id as string;
+    const defaultAttributes = createDefaultGraphToElementMapper(graphElement);
+    const graphElementData = mapElementAttributesToData({
+      id,
+      cell: graphElement,
+      graph,
+      defaultAttributes,
+    });
+
+    // Second sync with the actual graph state should return false
+    const result = updateGraph({
+      graph,
+      elements: { [id]: graphElementData },
+      links: {},
+      graphToElementSelector: (options) => mapElementAttributesToData(options),
+      graphToLinkSelector: (options) => mapLinkAttributesToData(options),
+      mapDataToElementAttributes: (options) => defaultMapDataToElementAttributes(options),
+      mapDataToLinkAttributes: (options) => defaultMapDataToLinkAttributes(options),
+    });
+
+    expect(result).toBe(false);
+  });
+
+  it('should return false when graph has active batch', () => {
+    const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
+
+    const elements: Record<string, GraphElement> = {
+      '1': { width: 100, height: 100, type: 'ReactElement' },
+    };
+
+    // Start a batch
+    graph.startBatch('test');
+
+    const result = updateGraph({
+      graph,
+      elements,
+      links: {},
+      graphToElementSelector: (options) => mapElementAttributesToData(options),
+      graphToLinkSelector: (options) => mapLinkAttributesToData(options),
+      mapDataToElementAttributes: (options) => defaultMapDataToElementAttributes(options),
+      mapDataToLinkAttributes: (options) => defaultMapDataToLinkAttributes(options),
+    });
+
+    expect(result).toBe(false);
+    expect(graph.getElements()).toHaveLength(0);
+
+    // End batch
+    graph.stopBatch('test');
+  });
+
+  it('should use isUpdateFromReact flag when syncing', () => {
+    const graph = new dia.Graph({}, { cellNamespace: DEFAULT_CELL_NAMESPACE });
+
+    const elements: Record<string, GraphElement> = {
+      '1': { width: 100, height: 100, type: 'ReactElement' },
+    };
+
+    // Spy on syncCells
+    const syncCellsSpy = jest.spyOn(graph, 'syncCells');
+
+    updateGraph({
+      graph,
+      elements,
+      links: {},
+      graphToElementSelector: (options) => mapElementAttributesToData(options),
+      graphToLinkSelector: (options) => mapLinkAttributesToData(options),
+      mapDataToElementAttributes: (options) => defaultMapDataToElementAttributes(options),
+      mapDataToLinkAttributes: (options) => defaultMapDataToLinkAttributes(options),
+      isUpdateFromReact: true,
+    });
+
+    expect(syncCellsSpy).toHaveBeenCalledWith(
+      expect.any(Array),
+      expect.objectContaining({ isUpdateFromReact: true })
+    );
   });
 });
diff --git a/packages/joint-react/src/state/graph-state-selectors.ts b/packages/joint-react/src/state/graph-state-selectors.ts
index 91684b408..1dabb0d44 100644
--- a/packages/joint-react/src/state/graph-state-selectors.ts
+++ b/packages/joint-react/src/state/graph-state-selectors.ts
@@ -6,12 +6,14 @@ import { REACT_TYPE } from '../models/react-element';
 import { REACT_LINK_TYPE } from '../models/react-link';
 
 export interface ElementToGraphOptions<Element extends GraphElement> {
+  readonly id: string;
   readonly data: Element;
   readonly graph: dia.Graph;
   readonly defaultAttributes: () => dia.Cell.JSON;
 }
 
 export interface GraphToElementOptions<Element extends GraphElement> {
+  readonly id: string;
   readonly cell: dia.Element;
   readonly previous?: Element;
   readonly graph: dia.Graph;
@@ -19,12 +21,14 @@ export interface GraphToElementOptions<Element extends GraphElement> {
 }
 
 export interface LinkToGraphOptions<Link extends GraphLink> {
+  readonly id: string;
   readonly data: Link;
   readonly graph: dia.Graph;
   readonly defaultAttributes: () => dia.Cell.JSON;
 }
 
 export interface GraphToLinkOptions<Link extends GraphLink> {
+  readonly id: string;
   readonly cell: dia.Link;
   readonly previous?: Link;
   readonly graph: dia.Graph;
@@ -43,34 +47,42 @@ export interface GraphStateSelectors<Element extends GraphElement, Link extends
 /**
  * Creates the default mapper function for element to graph conversion.
  * Separates user data into the `data` property.
+ * Supports both flat format (x, y, width, height) and nested format (position, size).
+ * @param id
  * @param data - The element to convert
  * @returns A function that returns the JointJS Cell JSON representation
  */
 export function createDefaultElementMapper<Element extends GraphElement>(
+  id: string,
   data: Element
 ): () => dia.Cell.JSON {
   return () => {
-    // Extract built-in JointJS element properties: id, x, y, width, height, angle, z, ports
-    // Remaining properties are user data
-    const { id, x, y, width, height, angle, z, ports, ...userData } = data as GraphElement & {
-      z?: number;
-      ports?: { groups?: Record<string, dia.Element.PortGroup>; items?: dia.Element.Port[] };
-      attrs?: dia.Cell.Selectors;
-      markup?: dia.MarkupJSON;
-    };
-    const { attrs: elementAttributes, markup, ...restUserData } = userData;
+    // Extract built-in JointJS element properties
+    // Support both flat format (x, y, width, height) and nested format (position, size)
+    const { x, y, width, height, angle, z, ports, position, size, ...userData } =
+      data as GraphElement & {
+        position?: { x: number; y: number };
+        size?: { width: number; height: number };
+      };
+    const { attrs: elementAttributes, markup, ...restUserData } = userData as GraphElement;
 
     const attributes: dia.Cell.JSON = {
       id,
       type: REACT_TYPE,
     };
 
-    if (x !== undefined && y !== undefined) {
-      attributes.position = { x, y };
+    // Position: prefer nested position object, fallback to flat x, y
+    const positionX = position?.x ?? x;
+    const positionY = position?.y ?? y;
+    if (positionX !== undefined && positionY !== undefined) {
+      attributes.position = { x: positionX, y: positionY };
     }
 
-    if (width !== undefined && height !== undefined) {
-      attributes.size = { width, height };
+    // Size: prefer nested size object, fallback to flat width, height
+    const sizeWidth = size?.width ?? width;
+    const sizeHeight = size?.height ?? height;
+    if (sizeWidth !== undefined && sizeHeight !== undefined) {
+      attributes.size = { width: sizeWidth, height: sizeHeight };
     }
 
     if (angle !== undefined) attributes.angle = angle;
@@ -113,15 +125,9 @@ function applyShapePreservation<Element extends GraphElement>(
  * @returns The extracted cell data as a record
  */
 function extractBaseCellData(cell: dia.Element): Record<string, unknown> {
-  const { size, position, data, type, angle, z, parent, ports } = cell.attributes;
-
-  const cellData: Record<string, unknown> = {
-    id: cell.id,
-  };
+  const { size, position, data, angle, z, ports } = cell.attributes;
 
-  if (type !== REACT_TYPE) {
-    cellData.type = type;
-  }
+  const cellData: Record<string, unknown> = {};
 
   if (position) {
     cellData.x = position.x;
@@ -135,9 +141,7 @@ function extractBaseCellData(cell: dia.Element): Record<string, unknown> {
 
   if (angle !== undefined) cellData.angle = angle;
   if (z !== undefined) cellData.z = z;
-  if (parent !== undefined) cellData.parent = parent;
   if (ports !== undefined) cellData.ports = ports;
-
   // Spread user data from data property to top level
   if (data && typeof data === 'object') {
     for (const [key, value] of Object.entries(data)) {
@@ -173,18 +177,19 @@ export function createDefaultGraphToElementMapper<Element extends GraphElement>(
 /**
  * Creates the default mapper function for link to graph conversion.
  * Separates user data into the `data` property.
+ * @param id
  * @param data - The link to convert
  * @param graph - The JointJS graph instance
  * @returns A function that returns the JointJS Cell JSON representation
  */
 export function createDefaultLinkMapper<Link extends GraphLink>(
+  id: string,
   data: Link,
   graph: dia.Graph
 ): () => dia.Cell.JSON {
   return () => {
     // Extract built-in JointJS link properties, remaining properties are user data
     const {
-      id,
       source: linkSource,
       target: linkTarget,
       attrs,
@@ -203,9 +208,7 @@ export function createDefaultLinkMapper<Link extends GraphLink>(
     const target = getTargetOrSource(linkTarget);
 
     const typeClass = util.getByPath(graph.layerCollection.cellNamespace, type, '.');
-    const defaults = typeClass
-      ? util.result(typeClass.prototype, 'defaults', {})
-      : {};
+    const defaults = typeClass ? util.result(typeClass.prototype, 'defaults', {}) : {};
 
     const existingCell = graph.getCell(id);
     const existingAttributes = existingCell?.isLink() ? existingCell.attr() : {};
@@ -252,7 +255,6 @@ export function createDefaultGraphToLinkMapper<Link extends GraphLink>(
 
     const cellData: Record<string, unknown> = {
       ...attributes,
-      id: cell.id,
       source: cell.get('source') as dia.Cell.ID,
       target: cell.get('target') as dia.Cell.ID,
       type: cell.attributes.type,
@@ -325,7 +327,7 @@ export function defaultMapDataToElementAttributes<Element extends GraphElement>(
  * This selector uses the defaultAttributes to convert the JointJS link cell to a Link.
  * The defaultAttributes handles data extraction and shape preservation.
  */
-export function defaultGraphToLinkSelector<Link extends GraphLink>(
+export function mapLinkAttributesToData<Link extends GraphLink>(
   options: GraphToLinkOptions<Link>
 ): Link {
   const { defaultAttributes } = options;
@@ -341,7 +343,7 @@ export function defaultGraphToLinkSelector<Link extends GraphLink>(
  * This selector uses the defaultAttributes to convert the JointJS element cell to a GraphElement.
  * The defaultAttributes handles data extraction and shape preservation.
  */
-export function defaultGraphToElementSelector<Element extends GraphElement>(
+export function mapElementAttributesToData<Element extends GraphElement>(
   options: GraphToElementOptions<Element>
 ): GraphElement {
   const { defaultAttributes } = options;
diff --git a/packages/joint-react/src/state/state-sync.ts b/packages/joint-react/src/state/state-sync.ts
index 7f4b353e4..38b4b47fa 100644
--- a/packages/joint-react/src/state/state-sync.ts
+++ b/packages/joint-react/src/state/state-sync.ts
@@ -1,9 +1,7 @@
-/* eslint-disable sonarjs/no-duplicated-branches */
-/* eslint-disable sonarjs/cognitive-complexity */
-import type { GraphStoreDerivedSnapshot, GraphStoreSnapshot } from '../store/graph-store';
+import type { GraphStoreSnapshot } from '../store/graph-store';
 import { listenToCellChange, type OnChangeOptions } from '../utils/cell/listen-to-cell-change';
 import { removeDeepReadOnly, type ExternalStoreLike } from '../utils/create-state';
-import { util, type dia } from '@joint/core';
+import type { dia } from '@joint/core';
 import type { GraphElement } from '../types/element-types';
 import type { GraphLink } from '../types/link-types';
 import type {
@@ -15,746 +13,327 @@ import type {
 } from './graph-state-selectors';
 import {
   defaultMapDataToElementAttributes,
-  defaultGraphToElementSelector,
+  mapElementAttributesToData,
   defaultMapDataToLinkAttributes,
-  defaultGraphToLinkSelector,
-  createDefaultElementMapper,
-  createDefaultGraphToElementMapper,
-  createDefaultLinkMapper,
-  createDefaultGraphToLinkMapper,
+  mapLinkAttributesToData,
 } from './graph-state-selectors';
-import { fastElementArrayEqual, isPositionOnlyUpdate } from '../utils/fast-equality';
+import type { GraphSchedulerData } from '../types/scheduler.types';
+import type { Scheduler } from '../utils/scheduler';
+import { updateGraph, mapGraphElement, mapGraphLink } from './update-graph';
 
-/**
- * Interface for state synchronization instance.
- * Provides methods to subscribe to cell changes and clean up resources.
- */
 export interface StateSync {
-  /**
-   * Subscribes to cell change events in the graph - but this happened only when the graph is updated from the external store.
-   * The callback receives change information and should return a cleanup function.
-   * @param callback - Function that receives change options and returns a cleanup function
-   * @returns Unsubscribe function to remove the listener
-   */
-  subscribeToGraphChange: (callback: (change: OnChangeOptions) => () => void) => () => void;
-
-  /**
-   * Subscribes to cell change events in the graph.
-   * The callback receives change information and should return a cleanup function.
-   * @param callback - Function that receives change options and returns a cleanup function
-   * @returns Unsubscribe function to remove the listener
-   */
-  subscribeToCellChange: (callback: (change: OnChangeOptions) => () => void) => () => void;
+  readonly cleanup: () => void;
+}
 
+interface StateSyncOptions<
+  Graph extends dia.Graph,
+  Element extends GraphElement,
+  Link extends GraphLink,
+> extends GraphStateSelectors<Element, Link> {
+  readonly graph: Graph;
+  readonly store: Omit<ExternalStoreLike<GraphStoreSnapshot<Element, Link>>, 'setState'>;
+  readonly scheduler: Scheduler<GraphSchedulerData>;
+  readonly graphToElementSelector?: (
+    options: GraphToElementOptions<Element> & { readonly graph: Graph }
+  ) => Element;
+  readonly graphToLinkSelector?: (
+    options: GraphToLinkOptions<Link> & { readonly graph: Graph }
+  ) => Link;
   /**
-   * Cleans up all subscriptions and event listeners.
-   * Should be called when the synchronization is no longer needed.
+   * Callback invoked after the graph is successfully updated from the store.
+   * Used to trigger layout updates when changes come from React state (e.g., useCellActions).
    */
-  cleanup: () => void;
+  readonly onGraphUpdated?: () => void;
 }
 
 /**
- * Configuration options for state synchronization.
- * @template Graph - The type of JointJS graph instance
- * @template Element - The type of elements in the graph
- * @template Link - The type of links in the graph
+ * Helper to update a Map immutably - add/set operation.
+ * @param map
+ * @param key
+ * @param value
  */
-interface Options<Graph extends dia.Graph, Element extends GraphElement, Link extends GraphLink>
-  extends GraphStateSelectors<Element, Link> {
-  /** The JointJS graph instance to synchronize */
-  readonly graph: Graph;
-  /** The external store containing elements and links to sync with */
-  readonly store: ExternalStoreLike<GraphStoreSnapshot<Element, Link>>;
-  readonly getIdsSnapshot: () => GraphStoreDerivedSnapshot;
-  /**
-   * If true, batch updates are disabled and synchronization will be real-time.
-   * If false (default), batch updates are enabled for better performance.
-   * @default false
-   */
-  readonly areBatchUpdatesDisabled?: boolean;
+function mapSet<K, V>(map: Map<K, V> | undefined, key: K, value: V): Map<K, V> {
+  const newMap = new Map(map);
+  newMap.set(key, value);
+  return newMap;
 }
-const BATCH_START_EVENT_NAME = 'batch:start';
-const BATCH_STOP_EVENT_NAME = 'batch:stop';
 
 /**
- * Configuration options for updating a JointJS graph.
- * @template Graph - The type of JointJS graph instance
- * @template Element - The type of elements in the graph
- * @template Link - The type of links in the graph
+ * Helper to update a Map immutably - delete operation.
+ * @param map
+ * @param key
  */
-export interface UpdateGraphOptions<
-  Graph extends dia.Graph,
-  Element extends GraphElement,
-  Link extends GraphLink,
-> {
-  /** The JointJS graph instance to update */
-  readonly graph: Graph;
-  /** The elements to sync to the graph */
-  readonly elements: readonly Element[];
-  /** The links to sync to the graph */
-  readonly links: readonly Link[];
-  /** Selector to convert graph elements to Element format for comparison */
-  readonly graphToElementSelector: (
-    options: GraphToElementOptions<Element> & { readonly graph: Graph }
-  ) => Element;
-  /** Selector to convert graph links to Link format for comparison */
-  readonly graphToLinkSelector: (
-    options: GraphToLinkOptions<Link> & { readonly graph: Graph }
-  ) => Link;
-  /** Selector to convert Element to JointJS Cell JSON format */
-  readonly mapDataToElementAttributes: (
-    options: ElementToGraphOptions<Element> & { readonly graph: Graph }
-  ) => dia.Cell.JSON;
-  /** Selector to convert Link to JointJS Cell JSON format */
-  readonly mapDataToLinkAttributes: (
-    options: LinkToGraphOptions<Link> & { readonly graph: Graph }
-  ) => dia.Cell.JSON;
-
-  readonly getIdsSnapshot: () => GraphStoreDerivedSnapshot;
+function mapDelete<K, V>(map: Map<K, V> | undefined, key: K): Map<K, V> {
+  const newMap = new Map(map);
+  newMap.delete(key);
+  return newMap;
 }
 
 /**
- * Updates a JointJS graph with the provided elements and links.
- * Compares the current graph state with the provided state and only syncs if they differ.
- * @template Graph - The type of JointJS graph instance
- * @template Element - The type of elements in the graph
- * @template Link - The type of links in the graph
- * @param options - Configuration options for updating the graph
- * @returns true if the graph was synced, false if it was already in sync or skipped due to active batch
+ * Maps all cells to their typed representations.
+ * @param cells
+ * @param graph
+ * @param elementSelector
+ * @param linkSelector
+ * @param previousElements
+ * @param previousLinks
  */
-export function updateGraph<
+function mapCellsToData<
   Graph extends dia.Graph,
   Element extends GraphElement,
   Link extends GraphLink,
->(options: UpdateGraphOptions<Graph, Element, Link>): boolean {
-  const {
-    graph,
-    elements,
-    links,
-    graphToElementSelector,
-    graphToLinkSelector,
-    mapDataToElementAttributes,
-    mapDataToLinkAttributes,
-    getIdsSnapshot,
-  } = options;
-
-  if (graph.hasActiveBatch()) {
-    return false;
-  }
-  const { elementIds, linkIds } = getIdsSnapshot();
-  // Compare current graph state with provided state to avoid unnecessary syncs
-  // This prevents syncing when graph and provided state are already in sync
-  const graphElements = graph.getElements().map((element) => {
-    const previousIndex = elementIds[element.id];
-    const previous =
-      previousIndex != null && previousIndex >= 0 && previousIndex < elements.length
-        ? elements[previousIndex]
-        : undefined;
-    const defaultAttributes = createDefaultGraphToElementMapper(element, previous);
-    return graphToElementSelector({
-      cell: element,
-      graph,
-      previous,
-      defaultAttributes,
-    });
-  });
-  const graphLinks = graph.getLinks().map((link) => {
-    const previousIndex = linkIds[link.id];
-    const previous =
-      previousIndex != null && previousIndex >= 0 && previousIndex < links.length
-        ? links[previousIndex]
-        : undefined;
-    const defaultAttributes = createDefaultGraphToLinkMapper(link, previous);
-    return graphToLinkSelector({
-      cell: link,
-      graph,
-      previous,
-      defaultAttributes,
-    });
-  });
-
-  // Fast path: Check if arrays have same length first
-  if (elements.length !== graphElements.length || links.length !== graphLinks.length) {
-    // Length mismatch, need to sync
-  } else if (isPositionOnlyUpdate(graphElements as Element[], elements as Element[])) {
-    // Position-only update: use fast equality check
-    if (
-      fastElementArrayEqual(elements as Element[], graphElements as Element[]) &&
-      fastElementArrayEqual(links as Link[], graphLinks as Link[])
-    ) {
-      return false;
-    }
-  } else {
-    // Check if graph is already in sync with provided state using fast equality
-    if (
-      fastElementArrayEqual(elements as Element[], graphElements as Element[]) &&
-      fastElementArrayEqual(links as Link[], graphLinks as Link[])
-    ) {
-      return false;
+>(
+  cells: dia.Cell[],
+  graph: Graph,
+  elementSelector: (options: GraphToElementOptions<Element> & { readonly graph: Graph }) => Element,
+  linkSelector: (options: GraphToLinkOptions<Link> & { readonly graph: Graph }) => Link,
+  previousElements?: Record<dia.Cell.ID, Element>,
+  previousLinks?: Record<dia.Cell.ID, Link>
+): { elements: Map<dia.Cell.ID, GraphElement>; links: Map<dia.Cell.ID, GraphLink> } {
+  const elements = new Map<dia.Cell.ID, GraphElement>();
+  const links = new Map<dia.Cell.ID, GraphLink>();
+
+  for (const cell of cells) {
+    if (cell.isElement()) {
+      elements.set(cell.id, mapGraphElement(cell, graph, elementSelector, previousElements?.[cell.id]));
+    } else if (cell.isLink()) {
+      links.set(cell.id, mapGraphLink(cell, graph, linkSelector, previousLinks?.[cell.id]));
     }
   }
 
-  // Build items array using selectors with defaultAttributes injected
-  const elementItems = elements.map((data) => {
-    const defaultAttributes = createDefaultElementMapper(data);
-    return mapDataToElementAttributes({
-      data,
-      graph,
-      defaultAttributes,
-    });
-  });
-  const linkItems = links.map((data) => {
-    const defaultAttributes = createDefaultLinkMapper(data, graph);
-    return mapDataToLinkAttributes({
-      data,
-      graph,
-      defaultAttributes,
-    });
-  });
+  return { elements, links };
+}
 
-  graph.syncCells([...elementItems, ...linkItems], { remove: true });
-  return true;
+/**
+ * Finds IDs to delete by comparing current snapshot with new IDs.
+ * @param currentIds
+ * @param newIds
+ * @param existingDeletes
+ */
+function findIdsToDelete(
+  currentIds: string[],
+  newIds: Set<dia.Cell.ID>,
+  existingDeletes: Map<dia.Cell.ID, true> | undefined
+): Map<dia.Cell.ID, true> {
+  const toDelete = new Map(existingDeletes);
+  for (const id of currentIds) {
+    if (!newIds.has(id)) {
+      toDelete.set(id, true);
+    }
+  }
+  return toDelete;
 }
 
 /**
- * Creates a bidirectional synchronization system between a JointJS graph and an external store.
- *
- * This function handles:
- * - Syncing changes from the graph to the store (when users interact with the graph)
- * - Syncing changes from the store to the graph (when React state updates)
- * - Preventing circular update loops using flags and batch tracking
- * - Handling incremental updates efficiently
- * - Supporting batch operations for performance
- *
- * The synchronization uses several mechanisms to prevent infinite loops:
- * - `isSyncingFromState`: Prevents syncing graph changes back when we're syncing from state
- * - `isUpdatingStateFromGraph`: Prevents syncing state changes to graph when we're updating from graph
- * - Batch tracking: Groups multiple changes together to avoid intermediate syncs
- * @template Graph - The type of JointJS graph instance
- * @template Element - The type of elements in the graph
- * @template Link - The type of links in the graph
- * @param options - Configuration options for state synchronization
- * @returns StateSync instance with subscription and cleanup methods
+ * GOLDEN RULE: This function NEVER calls setState directly.
+ * All state updates are scheduled via the unified scheduler.
+ * @param options
  */
 export function stateSync<
   Graph extends dia.Graph,
   Element extends GraphElement,
   Link extends GraphLink,
->(options: Options<Graph, Element, Link>): StateSync {
+>(options: StateSyncOptions<Graph, Element, Link>): StateSync {
   const {
     graph,
     store,
-    areBatchUpdatesDisabled = false,
-    getIdsSnapshot,
-
+    scheduler,
     mapDataToElementAttributes = defaultMapDataToElementAttributes,
     mapDataToLinkAttributes = defaultMapDataToLinkAttributes,
+    onGraphUpdated,
   } = options;
-  const graphToElementSelector = defaultGraphToElementSelector;
-  const graphToLinkSelector = defaultGraphToLinkSelector;
-
-  // We need to ensure several things:
-  // 1. Graph can update itself, via onCellChange or via onBatchStop - this change is internal and must update the external store - but only if the external store do not trigger the same change.
-  // 2. External store can update the graph via new elements or links - this change is external and must update the internal graph
-  // But issue in the 2. is that the change of graph will re-run internal updates, so it will trigger onCellChange or onBatchStop.
-
-  const changedCellIds = new Set<string>();
-  const pendingChanges = new Map<string, OnChangeOptions>();
-  let hasReset = false;
-  let isSyncingFromState = false;
-  let syncFromStateCounter = 0;
-  let isUpdatingStateFromGraph = false;
-  let updatingStateFromGraphCounter = 0;
-  let batchCounter = 0;
-
-  const onIncrementalChange = () => {
-    // Skip syncing back to React if we're currently syncing from React
-    // This prevents circular updates: React → Graph → React
-    if (isSyncingFromState) {
-      return;
-    }
 
-    // Check if there are any changes to process
-    if (!hasReset && changedCellIds.size === 0) return;
-
-    // Capture current state of changes
-    const isReset = hasReset;
-    const ids = [...changedCellIds];
+  const elementSelector = (options.graphToElementSelector ?? mapElementAttributesToData) as (
+    options: GraphToElementOptions<Element> & { readonly graph: Graph }
+  ) => Element;
 
-    // Clear for next batch
-    hasReset = false;
-    changedCellIds.clear();
+  const linkSelector = (options.graphToLinkSelector ?? mapLinkAttributesToData) as (
+    options: GraphToLinkOptions<Link> & { readonly graph: Graph }
+  ) => Link;
 
-    // Call listeners before isEqual check (layout data might not be in state)
-    if (isReset) {
-      const allCells = graph.getCells();
-      const resetChange: OnChangeOptions = {
-        type: 'reset',
-        cells: allCells,
-      };
-      for (const listener of graphChangeListeners) {
-        listener(resetChange);
-      }
-    } else {
-      // Call listeners for each changed cell
-      for (const id of ids) {
-        const change = pendingChanges.get(id);
-        if (change) {
-          for (const listener of graphChangeListeners) {
-            listener(change);
-          }
-        }
-      }
-    }
-    // Clear pending changes after calling listeners
-    pendingChanges.clear();
+  // --- Scheduling ---
 
-    if (isReset) {
+  const scheduleCellUpdate = (cell: dia.Cell) => {
+    scheduler.scheduleData((data) => {
       const snapshot = store.getSnapshot();
-      const elements = removeDeepReadOnly(snapshot.elements);
-      const links = removeDeepReadOnly(snapshot.links);
-      const idsSnapshot = getIdsSnapshot();
-
-      // Map graph elements with previous state for shape preservation
-      const graphElements = graph.getElements().map((element) => {
-        const previousIndex = idsSnapshot.elementIds[element.id];
-        const previous: Element | undefined =
-          previousIndex != null && previousIndex >= 0 && previousIndex < elements.length
-            ? (elements[previousIndex] as Element)
-            : undefined;
-        const defaultAttributes = createDefaultGraphToElementMapper(element, previous);
-        return graphToElementSelector({
-          cell: element,
-          graph,
-          previous,
-          defaultAttributes,
-        });
-      });
-
-      // Map graph links with previous state for shape preservation
-      const graphLinks = graph.getLinks().map((link) => {
-        const previousIndex = idsSnapshot.linkIds[link.id];
-        const previous: Link | undefined =
-          previousIndex != null && previousIndex >= 0 && previousIndex < links.length
-            ? (links[previousIndex] as Link)
-            : undefined;
-        const defaultAttributes = createDefaultGraphToLinkMapper(link, previous);
-        return graphToLinkSelector({
-          cell: link,
-          graph,
-          previous,
-          defaultAttributes,
-        });
-      });
-
-      // Use fast equality check for better performance
-      const isEqual =
-        fastElementArrayEqual(elements as Element[], graphElements as Element[]) &&
-        fastElementArrayEqual(links as Link[], graphLinks as Link[]);
-      if (isEqual) return;
-
-      // Update state with shape-preserved graph data
-      if (!store.setState) return;
-
-      updatingStateFromGraphCounter++;
-      isUpdatingStateFromGraph = true;
-
-      store.setState(() => ({
-        elements: graphElements as Element[],
-        links: graphLinks as Link[],
-      }));
-
-      isUpdatingStateFromGraph = false;
-      updatingStateFromGraphCounter--;
-      return;
-    }
-    if (!store.setState) {
-      throw new Error('Store does not have setState method');
-    }
-    // Incremental update
-    // Set flag to prevent this state update from triggering another graph sync
-    updatingStateFromGraphCounter++;
-    isUpdatingStateFromGraph = true;
-
-    // Get IDs snapshot for O(1) lookups
-    const idsSnapshot = getIdsSnapshot();
-
-    store.setState((previous: GraphStoreSnapshot<Element, Link>) => {
-      const updates = new Map<string, { type: 'link' | 'element'; data: Element | Link }>();
-      const removals = new Set<string>();
-
-      for (const id of ids) {
-        const cell = graph.getCell(id);
-        if (cell) {
-          if (cell.isLink()) {
-            // Get previous link using O(1) lookup
-            const linkIndex = idsSnapshot.linkIds[id];
-            const previousLink =
-              linkIndex != null && linkIndex >= 0 && linkIndex < previous.links.length
-                ? previous.links[linkIndex]
-                : undefined;
-
-            const defaultAttributes = createDefaultGraphToLinkMapper(cell as dia.Link, previousLink);
-            const updatedLink = graphToLinkSelector({
-              cell: cell as dia.Link,
-              graph,
-              previous: previousLink,
-              defaultAttributes,
-            });
-            updates.set(id, { type: 'link', data: updatedLink as Link });
-          } else {
-            // Get previous element using O(1) lookup
-            const elementIndex = idsSnapshot.elementIds[id];
-            const previousElement =
-              elementIndex != null && elementIndex >= 0 && elementIndex < previous.elements.length
-                ? previous.elements[elementIndex]
-                : undefined;
-
-            const defaultAttributes = createDefaultGraphToElementMapper(cell as dia.Element, previousElement);
-            const updatedElement = graphToElementSelector({
-              cell: cell as dia.Element,
-              graph,
-              previous: previousElement,
-              defaultAttributes,
-            });
-            updates.set(id, { type: 'element', data: updatedElement as Element });
-          }
-        } else {
-          removals.add(id);
-        }
-      }
-
-      // Elements
-      const nextElements: Element[] = [];
-      let elementsChanged = false;
-
-      for (const cellElement of previous.elements) {
-        const id = cellElement.id.toString();
-        if (removals.has(id)) {
-          elementsChanged = true;
-          continue;
-        }
-        if (updates.has(id)) {
-          const update = updates.get(id);
-          if (update?.type === 'element') {
-            if (util.isEqual(cellElement, update.data)) {
-              nextElements.push(cellElement);
-            } else {
-              nextElements.push(update.data as Element);
-              elementsChanged = true;
-            }
-            updates.delete(id);
-          } else {
-            nextElements.push(cellElement);
-          }
-        } else {
-          nextElements.push(cellElement);
-        }
+      if (cell.isElement()) {
+        const previous = snapshot.elements[cell.id] as Element | undefined;
+        return {
+          ...data,
+          elementsToUpdate: mapSet(
+            data.elementsToUpdate,
+            cell.id,
+            mapGraphElement(cell, graph, elementSelector, previous)
+          ),
+        };
       }
-
-      // Add new elements
-      for (const [id, update] of updates) {
-        if (update.type === 'element') {
-          nextElements.push(update.data as Element);
-          elementsChanged = true;
-          updates.delete(id);
-        }
+      if (cell.isLink()) {
+        const previous = snapshot.links[cell.id] as Link | undefined;
+        return {
+          ...data,
+          linksToUpdate: mapSet(
+            data.linksToUpdate,
+            cell.id,
+            mapGraphLink(cell, graph, linkSelector, previous)
+          ),
+        };
       }
+      return data;
+    });
+  };
 
-      // Links
-      const nextLinks: Link[] = [];
-      let linksChanged = false;
-
-      for (const link of previous.links) {
-        const id = link.id.toString();
-        if (removals.has(id)) {
-          linksChanged = true;
-          continue;
-        }
-        if (updates.has(id)) {
-          const update = updates.get(id);
-          if (update?.type === 'link') {
-            if (util.isEqual(link, update.data)) {
-              nextLinks.push(link);
-            } else {
-              nextLinks.push(update.data as Link);
-              linksChanged = true;
-            }
-            updates.delete(id);
-          } else {
-            nextLinks.push(link);
-          }
-        } else {
-          nextLinks.push(link);
-        }
+  const scheduleCellDelete = (cell: dia.Cell) => {
+    scheduler.scheduleData((data) => {
+      if (cell.isElement()) {
+        return {
+          ...data,
+          elementsToUpdate: mapDelete(data.elementsToUpdate, cell.id),
+          elementsToDelete: mapSet(data.elementsToDelete, cell.id, true),
+        };
       }
-
-      // Add new links
-      for (const [, update] of updates) {
-        if (update.type === 'link') {
-          nextLinks.push(update.data as Link);
-          linksChanged = true;
-        }
+      if (cell.isLink()) {
+        return {
+          ...data,
+          linksToUpdate: mapDelete(data.linksToUpdate, cell.id),
+          linksToDelete: mapSet(data.linksToDelete, cell.id, true),
+        };
       }
+      return data;
+    });
+  };
 
-      if (!elementsChanged && !linksChanged) return previous;
+  const scheduleReset = (cells: dia.Cell[]) => {
+    scheduler.scheduleData((data) => {
+      const snapshot = store.getSnapshot();
+      const { elements, links } = mapCellsToData(
+        cells,
+        graph,
+        elementSelector,
+        linkSelector,
+        snapshot.elements as Record<dia.Cell.ID, Element>,
+        snapshot.links as Record<dia.Cell.ID, Link>
+      );
 
-      const newElements = elementsChanged ? nextElements : previous.elements;
-      const newLinks = linksChanged ? nextLinks : previous.links;
       return {
-        ...previous,
-        elements: newElements as Element[],
-        links: newLinks as Link[],
+        ...data,
+        elementsToUpdate: elements,
+        linksToUpdate: links,
+        elementsToDelete: findIdsToDelete(
+          Object.keys(snapshot.elements),
+          new Set(elements.keys()),
+          data.elementsToDelete
+        ),
+        linksToDelete: findIdsToDelete(
+          Object.keys(snapshot.links),
+          new Set(links.keys()),
+          data.linksToDelete
+        ),
       };
     });
-    // Reset the flag after setState completes
-    // The subscription callback runs synchronously within setState (via ReactDOM.unstable_batchedUpdates),
-    // so we can reset the flag immediately after setState returns
-    // If there's a batch, onBatchStop will also handle resetting it as a safety measure
-    updatingStateFromGraphCounter--;
-    if (updatingStateFromGraphCounter === 0) {
-      isUpdatingStateFromGraph = false;
-    }
   };
 
-  const graphChangeListeners = new Set<(change: OnChangeOptions) => () => void>();
-  const cellChangeListeners = new Set<(change: OnChangeOptions) => () => void>();
-
-  /**
-   * Subscribes to cell changes in the graph.
-   * Allows external code to react to changes that occur in the graph.
-   * The callback receives change information and should return a cleanup function that will be called
-   * when the cell is removed or the subscription is cancelled.
-   * @param callback - The callback function that receives change options and returns a cleanup function
-   * @returns A function to unsubscribe from cell changes
-   */
-  function subscribeToGraphChange(callback: (change: OnChangeOptions) => () => void) {
-    graphChangeListeners.add(callback);
-    return () => {
-      graphChangeListeners.delete(callback);
-    };
-  }
-
-  /**
-   * Subscribes to cell change events in the graph.
-   * The callback receives change information and should return a cleanup function.
-   * @param callback - Function that receives change options and returns a cleanup function
-   * @returns Unsubscribe function to remove the listener
-   */
-  function subscribeToCellChange(callback: (change: OnChangeOptions) => () => void) {
-    cellChangeListeners.add(callback);
-    return () => {
-      cellChangeListeners.delete(callback);
-    };
-  }
-  // Here we handle graph internal changes, it's skipped when there is an active batch
-  const destroy = listenToCellChange(graph, (change) => {
-    for (const listener of cellChangeListeners) {
-      listener(change);
-    }
-    // Store change for later processing in onIncrementalChange
-    if (change.type === 'reset') {
-      hasReset = true;
-      changedCellIds.clear();
-      pendingChanges.clear();
-    } else {
-      const id = change.cell.id.toString();
-      changedCellIds.add(id);
-      pendingChanges.set(id, change);
-    }
-
-    // Skip if we're syncing from state to prevent circular updates
-    if (isSyncingFromState) return;
-    if (!areBatchUpdatesDisabled && graph.hasActiveBatch()) return;
-    onIncrementalChange();
-  });
-
-  // Track when batches start
-  const onBatchStart = (event: { batchName?: string }) => {
-    batchCounter++;
-    // If we're syncing from state and this is a sync-cells batch, track it
-    if (isSyncingFromState && event.batchName === 'sync-cells') {
-      // This batch is from our syncCells call, so we should ignore its stop event
-    }
+  const scheduleCellsUpdate = (cells: dia.Cell[]) => {
+    scheduler.scheduleData((data) => {
+      const snapshot = store.getSnapshot();
+      const { elements, links } = mapCellsToData(
+        cells,
+        graph,
+        elementSelector,
+        linkSelector,
+        snapshot.elements as Record<dia.Cell.ID, Element>,
+        snapshot.links as Record<dia.Cell.ID, Link>
+      );
+      return {
+        ...data,
+        elementsToUpdate: new Map([...(data.elementsToUpdate ?? []), ...elements]),
+        linksToUpdate: new Map([...(data.linksToUpdate ?? []), ...links]),
+      };
+    });
   };
 
-  // We only update batch when there is last one.
-  const onBatchStop = (_event: { batchName?: string }) => {
-    batchCounter--;
-    if (batchCounter > 0) return; // Still in a nested batch
-    if (!areBatchUpdatesDisabled && graph.hasActiveBatch()) return;
-
-    // Reset the flag after batch completes
-    const wasSyncingFromState = isSyncingFromState;
-    if (syncFromStateCounter > 0) {
-      syncFromStateCounter--;
-      isSyncingFromState = syncFromStateCounter > 0;
-    }
+  // --- Event Handlers ---
 
-    // Reset the updatingStateFromGraph flag after batch completes
-    // This ensures the flag stays set during the entire batch lifecycle
-    if (updatingStateFromGraphCounter > 0) {
-      updatingStateFromGraphCounter--;
-      if (updatingStateFromGraphCounter === 0) {
-        isUpdatingStateFromGraph = false;
-      }
+  const handleCellChange = (change: OnChangeOptions): void => {
+    if (change.options?.isUpdateFromReact) {
+      return;
     }
 
-    // Skip syncing back to React if we were syncing from React
-    // This prevents circular updates: React → Graph (via syncCells) → batch:stop → React
-    if (wasSyncingFromState) {
-      // Still need to call listeners (e.g., for layout state updates) even when syncing from state
-      // Get current changed cells to notify listeners
-      const currentIds = [...changedCellIds];
-      if (hasReset) {
-        const allCells = graph.getCells();
-        const resetChange: OnChangeOptions = {
-          type: 'reset',
-          cells: allCells,
-        };
-        for (const listener of graphChangeListeners) {
-          listener(resetChange);
-        }
-        hasReset = false;
-        changedCellIds.clear();
-        pendingChanges.clear();
-      } else if (currentIds.length > 0) {
-        for (const id of currentIds) {
-          const change = pendingChanges.get(id);
-          if (change) {
-            for (const listener of graphChangeListeners) {
-              listener(change);
-            }
-          }
-        }
-        changedCellIds.clear();
-        pendingChanges.clear();
-      }
+    if (change.type === 'reset') {
+      scheduleReset(change.cells);
       return;
     }
-    onIncrementalChange();
-  };
 
-  // If graph has existing cells but store is empty, sync those cells to the store first
-  const syncExistingGraphCellsToStore = () => {
-    if (!store.setState) {
+    if (change.type === 'remove') {
+      scheduleCellDelete(change.cell);
       return;
     }
 
-    const snapshot = store.getSnapshot();
-    const storeElements = removeDeepReadOnly(snapshot.elements);
-    const storeLinks = removeDeepReadOnly(snapshot.links);
-
-    // Only sync if store is empty and graph has cells
-    if (storeElements.length === 0 && storeLinks.length === 0) {
-      const existingElements = graph.getElements().map((element) => {
-        const defaultAttributes = createDefaultGraphToElementMapper(element);
-        return graphToElementSelector({
-          cell: element,
-          graph,
-          defaultAttributes,
-        });
-      }) as Element[];
-      const existingLinks = graph.getLinks().map((link) => {
-        const defaultAttributes = createDefaultGraphToLinkMapper(link);
-        return graphToLinkSelector({
-          cell: link,
-          graph,
-          defaultAttributes,
-        });
-      }) as Link[];
-
-      if (existingElements.length > 0 || existingLinks.length > 0) {
-        // Set flag to prevent syncing graph changes back to React during initialization
-        updatingStateFromGraphCounter++;
-        isUpdatingStateFromGraph = true;
-
-        store.setState((previous) => ({
-          ...previous,
-          elements: existingElements,
-          links: existingLinks,
-        }));
-
-        updatingStateFromGraphCounter--;
-        if (updatingStateFromGraphCounter === 0) {
-          isUpdatingStateFromGraph = false;
-        }
-      }
-    }
+    scheduleCellUpdate(change.cell);
   };
 
-  const updateGraphInternal = () => {
-    // Skip if we're updating state from graph changes
-    // This prevents circular updates: Graph → State → Graph
-    if (isUpdatingStateFromGraph) {
-      return;
-    }
+  // --- Store Sync ---
 
+  const updateGraphFromStore = () => {
     const snapshot = store.getSnapshot();
-    const elements = removeDeepReadOnly(snapshot.elements) as Element[];
-    const links = removeDeepReadOnly(snapshot.links) as Link[];
+    const elements = removeDeepReadOnly(snapshot.elements);
+    const links = removeDeepReadOnly(snapshot.links);
 
-    // Set flag to prevent syncing graph changes back to React
-    // This prevents circular updates: React → Graph → React
-    syncFromStateCounter++;
-    isSyncingFromState = true;
+    // Skip sync if store is empty but graph has cells - the scheduler will populate store first
+    const isStoreEmpty = Object.keys(elements).length === 0 && Object.keys(links).length === 0;
+    const graphHasCells = graph.getElements().length > 0 || graph.getLinks().length > 0;
+    if (isStoreEmpty && graphHasCells) {
+      return;
+    }
 
-    const wasSynced = updateGraph({
+    const wasUpdated = updateGraph({
       graph,
-      elements,
-      links,
-      getIdsSnapshot,
-      graphToElementSelector: graphToElementSelector as unknown as (
-        options: GraphToElementOptions<Element> & { readonly graph: Graph }
-      ) => Element,
-      graphToLinkSelector: graphToLinkSelector as (
-        options: GraphToLinkOptions<Link> & { readonly graph: Graph }
-      ) => Link,
+      elements: elements as Record<string, Element>,
+      links: links as Record<string, Link>,
+      graphToElementSelector: elementSelector,
+      graphToLinkSelector: linkSelector,
       mapDataToElementAttributes: mapDataToElementAttributes as (
         options: ElementToGraphOptions<Element> & { readonly graph: Graph }
       ) => dia.Cell.JSON,
       mapDataToLinkAttributes: mapDataToLinkAttributes as (
         options: LinkToGraphOptions<Link> & { readonly graph: Graph }
       ) => dia.Cell.JSON,
+      isUpdateFromReact: true,
     });
 
-    // Only reset the flag if there's no batch (events were processed synchronously)
-    // If there's a batch, onBatchStop will handle resetting it
-    // We need to check after syncCells because it might have started a batch
-    const shouldResetImmediately =
-      !wasSynced || (wasSynced && batchCounter === 0 && !graph.hasActiveBatch());
-    if (shouldResetImmediately) {
-      syncFromStateCounter--;
-      isSyncingFromState = syncFromStateCounter > 0;
+    // Trigger layout update when graph is updated from store (e.g., via useCellActions)
+    if (wasUpdated && onGraphUpdated) {
+      onGraphUpdated();
     }
-    // If wasSynced is true but batch is active, onBatchStop will handle resetting the flag
   };
-  // Here we get the external changes and update the graph
-  const clean = store.subscribe(() => {
-    // Check if we should skip this update (we're updating state from graph)
-    if (isUpdatingStateFromGraph) {
+
+  const syncExistingGraphCellsToStore = () => {
+    const snapshot = store.getSnapshot();
+    const hasStoreData =
+      Object.keys(snapshot.elements).length > 0 || Object.keys(snapshot.links).length > 0;
+    if (hasStoreData) {
       return;
     }
-    updateGraphInternal();
-  });
-  // listen to batch start and stop events to track batch lifecycle
-  graph.on(BATCH_START_EVENT_NAME, onBatchStart);
-  graph.on(BATCH_STOP_EVENT_NAME, onBatchStop);
-  const cleanup = () => {
-    graphChangeListeners.clear();
-    destroy();
-    clean();
-    graph.off(BATCH_START_EVENT_NAME, onBatchStart);
-    graph.off(BATCH_STOP_EVENT_NAME, onBatchStop);
+
+    const allCells = [...graph.getElements(), ...graph.getLinks()];
+    if (allCells.length === 0) {
+      return;
+    }
+
+    scheduleCellsUpdate(allCells);
   };
 
-  // First, sync existing graph cells to store if store is empty
+  // --- Setup & Cleanup ---
+
+  const destroyCellListener = listenToCellChange(graph, handleCellChange);
+  const destroyStoreSubscription = store.subscribe(updateGraphFromStore);
+
   syncExistingGraphCellsToStore();
-  // Then, sync store to graph
-  updateGraphInternal();
+  updateGraphFromStore();
+
   return {
-    subscribeToGraphChange,
-    subscribeToCellChange,
-    cleanup,
+    cleanup: () => {
+      destroyCellListener();
+      destroyStoreSubscription();
+    },
   };
 }
diff --git a/packages/joint-react/src/state/update-graph.ts b/packages/joint-react/src/state/update-graph.ts
new file mode 100644
index 000000000..e78ed99ad
--- /dev/null
+++ b/packages/joint-react/src/state/update-graph.ts
@@ -0,0 +1,179 @@
+import type { dia } from '@joint/core';
+import type { GraphElement } from '../types/element-types';
+import type { GraphLink } from '../types/link-types';
+import type {
+  ElementToGraphOptions,
+  GraphToElementOptions,
+  GraphToLinkOptions,
+  LinkToGraphOptions,
+} from './graph-state-selectors';
+import {
+  createDefaultElementMapper,
+  createDefaultGraphToElementMapper,
+  createDefaultLinkMapper,
+  createDefaultGraphToLinkMapper,
+} from './graph-state-selectors';
+import { fastElementArrayEqual, isPositionOnlyUpdate } from '../utils/fast-equality';
+
+/**
+ * Configuration options for updating a JointJS graph.
+ * @template Graph - The type of JointJS graph instance
+ * @template Element - The type of elements in the graph
+ * @template Link - The type of links in the graph
+ */
+export interface UpdateGraphOptions<
+  Graph extends dia.Graph,
+  Element extends GraphElement,
+  Link extends GraphLink,
+> {
+  /** The JointJS graph instance to update */
+  readonly graph: Graph;
+  /** The elements to sync to the graph (Record keyed by cell ID) */
+  readonly elements: Record<dia.Cell.ID, Element>;
+  /** The links to sync to the graph (Record keyed by cell ID) */
+  readonly links: Record<dia.Cell.ID, Link>;
+  /** Selector to convert graph elements to Element format for comparison */
+  readonly graphToElementSelector: (
+    options: GraphToElementOptions<Element> & { readonly graph: Graph }
+  ) => Element;
+  /** Selector to convert graph links to Link format for comparison */
+  readonly graphToLinkSelector: (
+    options: GraphToLinkOptions<Link> & { readonly graph: Graph }
+  ) => Link;
+  /** Selector to convert Element to JointJS Cell JSON format */
+  readonly mapDataToElementAttributes: (
+    options: ElementToGraphOptions<Element> & { readonly graph: Graph }
+  ) => dia.Cell.JSON;
+  /** Selector to convert Link to JointJS Cell JSON format */
+  readonly mapDataToLinkAttributes: (
+    options: LinkToGraphOptions<Link> & { readonly graph: Graph }
+  ) => dia.Cell.JSON;
+
+  readonly isUpdateFromReact?: boolean;
+}
+
+/**
+ * Maps a JointJS element to its typed representation using the provided selector.
+ * @param cell
+ * @param graph
+ * @param selector
+ * @param previous
+ */
+export function mapGraphElement<Graph extends dia.Graph, Element extends GraphElement>(
+  cell: dia.Element,
+  graph: Graph,
+  selector: (options: GraphToElementOptions<Element> & { readonly graph: Graph }) => Element,
+  previous?: Element
+): Element {
+  const defaultAttributes = createDefaultGraphToElementMapper(cell, previous) as () => Element;
+  return selector({ id: cell.id as string, cell, graph, defaultAttributes, previous });
+}
+
+/**
+ * Maps a JointJS link to its typed representation using the provided selector.
+ * @param cell
+ * @param graph
+ * @param selector
+ * @param previous
+ */
+export function mapGraphLink<Graph extends dia.Graph, Link extends GraphLink>(
+  cell: dia.Link,
+  graph: Graph,
+  selector: (options: GraphToLinkOptions<Link> & { readonly graph: Graph }) => Link,
+  previous?: Link
+): Link {
+  const defaultAttributes = createDefaultGraphToLinkMapper(cell, previous) as () => Link;
+  return selector({ id: cell.id as string, cell, graph, defaultAttributes, previous });
+}
+
+/**
+ * Checks if the graph state matches the provided elements and links.
+ * Uses fast equality checks optimized for position-only updates.
+ * @param graphElements
+ * @param graphLinks
+ * @param elements
+ * @param links
+ */
+function isGraphInSync<Element extends GraphElement, Link extends GraphLink>(
+  graphElements: Element[],
+  graphLinks: Link[],
+  elements: Element[],
+  links: Link[]
+): boolean {
+  // Fast path: Check if arrays have same length first
+  if (elements.length !== graphElements.length || links.length !== graphLinks.length) {
+    return false;
+  }
+
+  // Position-only update: use fast equality check
+  if (isPositionOnlyUpdate(graphElements, elements)) {
+    return (
+      fastElementArrayEqual(elements, graphElements) && fastElementArrayEqual(links, graphLinks)
+    );
+  }
+
+  // General equality check
+  return fastElementArrayEqual(elements, graphElements) && fastElementArrayEqual(links, graphLinks);
+}
+
+/**
+ * Updates a JointJS graph with the provided elements and links.
+ * Compares the current graph state with the provided state and only syncs if they differ.
+ * @template Graph - The type of JointJS graph instance
+ * @template Element - The type of elements in the graph
+ * @template Link - The type of links in the graph
+ * @param options - Configuration options for updating the graph
+ * @returns true if the graph was synced, false if it was already in sync or skipped due to active batch
+ */
+export function updateGraph<
+  Graph extends dia.Graph,
+  Element extends GraphElement,
+  Link extends GraphLink,
+>(options: UpdateGraphOptions<Graph, Element, Link>): boolean {
+  const {
+    graph,
+    elements: elementsRecord,
+    links: linksRecord,
+    graphToElementSelector,
+    graphToLinkSelector,
+    mapDataToElementAttributes,
+    mapDataToLinkAttributes,
+    isUpdateFromReact,
+  } = options;
+
+  if (graph.hasActiveBatch()) {
+    return false;
+  }
+
+  // Convert records to arrays
+  const elements = Object.values(elementsRecord);
+  const links = Object.values(linksRecord);
+
+  // Map current graph state to typed representations
+  // Pass previous state for shape preservation
+  const graphElements = graph
+    .getElements()
+    .map((cell) => mapGraphElement(cell, graph, graphToElementSelector, elementsRecord[cell.id]));
+  const graphLinks = graph
+    .getLinks()
+    .map((cell) => mapGraphLink(cell, graph, graphToLinkSelector, linksRecord[cell.id]));
+
+  // Skip sync if already in sync
+  if (isGraphInSync(graphElements, graphLinks, elements, links)) {
+    return false;
+  }
+
+  // Build items array using selectors with defaultAttributes injected
+  const elementItems = Object.entries(elementsRecord).map(([id, data]) => {
+    const defaultAttributes = createDefaultElementMapper(id, data);
+    return mapDataToElementAttributes({ id, data, graph, defaultAttributes });
+  });
+
+  const linkItems = Object.entries(linksRecord).map(([id, data]) => {
+    const defaultAttributes = createDefaultLinkMapper(id, data, graph);
+    return mapDataToLinkAttributes({ id, data, graph, defaultAttributes });
+  });
+
+  graph.syncCells([...elementItems, ...linkItems], { remove: true, isUpdateFromReact });
+  return true;
+}
diff --git a/packages/joint-react/src/store/__tests__/graph-store.test.ts b/packages/joint-react/src/store/__tests__/graph-store.test.ts
index 6a014948e..323002f98 100644
--- a/packages/joint-react/src/store/__tests__/graph-store.test.ts
+++ b/packages/joint-react/src/store/__tests__/graph-store.test.ts
@@ -1,4 +1,4 @@
-/* eslint-disable no-shadow */
+ 
 /* eslint-disable unicorn/consistent-function-scoping */
 import { dia, shapes } from '@joint/core';
 import { GraphStore } from '../graph-store';
@@ -22,7 +22,6 @@ describe('GraphStore', () => {
       expect(store.graph).toBeInstanceOf(dia.Graph);
       expect(store.publicState).toBeDefined();
       expect(store.internalState).toBeDefined();
-      expect(store.derivedStore).toBeDefined();
     });
 
     it('should create a GraphStore with provided graph instance', () => {
@@ -34,43 +33,55 @@ describe('GraphStore', () => {
     it('should initialize with empty elements and links by default', () => {
       const store = new GraphStore({});
       const snapshot = store.publicState.getSnapshot();
-      expect(snapshot.elements).toEqual([]);
-      expect(snapshot.links).toEqual([]);
+      expect(snapshot.elements).toEqual({});
+      expect(snapshot.links).toEqual({});
     });
 
     it('should initialize with initialElements', () => {
-      const initialElements: GraphElement[] = [
-        { id: 'element-1', x: 10, y: 20, width: 100, height: 50, type: 'ReactElement' },
-        { id: 'element-2', x: 30, y: 40, width: 80, height: 60, type: 'ReactElement' },
-      ];
+      const initialElements: Record<string, GraphElement> = {
+        'element-1': {
+          x: 10,
+          y: 20,
+          width: 100,
+          height: 50,
+          type: 'ReactElement',
+        },
+        'element-2': { x: 30, y: 40, width: 80, height: 60, type: 'ReactElement' },
+      };
       const store = new GraphStore({ initialElements });
       const snapshot = store.publicState.getSnapshot();
-      expect(snapshot.elements).toHaveLength(2);
-      expect(snapshot.elements[0].id).toBe('element-1');
-      expect(snapshot.elements[1].id).toBe('element-2');
+      expect(Object.keys(snapshot.elements)).toHaveLength(2);
+      expect(snapshot.elements['element-1']).toBeDefined();
+      expect(snapshot.elements['element-2']).toBeDefined();
     });
 
     it('should initialize with initialLinks', () => {
-      const initialLinks: GraphLink[] = [
-        { id: 'link-1', source: 'element-1', target: 'element-2', type: 'standard.Link' },
-      ];
+      const initialLinks: Record<string, GraphLink> = {
+        'link-1': { source: 'element-1', target: 'element-2', type: 'standard.Link' },
+      };
       const store = new GraphStore({ initialLinks });
       const snapshot = store.publicState.getSnapshot();
-      expect(snapshot.links).toHaveLength(1);
-      expect(snapshot.links[0].id).toBe('link-1');
+      expect(Object.keys(snapshot.links)).toHaveLength(1);
+      expect(snapshot.links['link-1']).toBeDefined();
     });
 
     it('should initialize with both initialElements and initialLinks', () => {
-      const initialElements: GraphElement[] = [
-        { id: 'element-1', x: 10, y: 20, width: 100, height: 50, type: 'ReactElement' },
-      ];
-      const initialLinks: GraphLink[] = [
-        { id: 'link-1', source: 'element-1', target: 'element-2', type: 'standard.Link' },
-      ];
+      const initialElements: Record<string, GraphElement> = {
+        'element-1': {
+          x: 10,
+          y: 20,
+          width: 100,
+          height: 50,
+          type: 'ReactElement',
+        },
+      };
+      const initialLinks: Record<string, GraphLink> = {
+        'link-1': { source: 'element-1', target: 'element-2', type: 'standard.Link' },
+      };
       const store = new GraphStore({ initialElements, initialLinks });
       const snapshot = store.publicState.getSnapshot();
-      expect(snapshot.elements).toHaveLength(1);
-      expect(snapshot.links).toHaveLength(1);
+      expect(Object.keys(snapshot.elements)).toHaveLength(1);
+      expect(Object.keys(snapshot.links)).toHaveLength(1);
     });
 
     it('should merge custom cellNamespace with default namespace', () => {
@@ -85,7 +96,7 @@ describe('GraphStore', () => {
         // Empty unsubscribe function
       }
       const externalStore = {
-        getSnapshot: () => ({ elements: [], links: [] }),
+        getSnapshot: () => ({ elements: {}, links: {} }),
         subscribe: () => unsubscribe,
         setState: () => {},
       };
@@ -107,8 +118,8 @@ describe('GraphStore', () => {
       });
 
       // Add an element to trigger the selector
+      const id = 'test-element';
       const data: GraphElement = {
-        id: 'test-element',
         x: 10,
         y: 20,
         width: 100,
@@ -117,7 +128,7 @@ describe('GraphStore', () => {
       };
       store.publicState.setState((previous) => ({
         ...previous,
-        elements: [...previous.elements, data],
+        elements: { ...previous.elements, [id]: data },
       }));
 
       // Wait a bit for sync to happen
@@ -126,21 +137,6 @@ describe('GraphStore', () => {
       }, 10);
     });
 
-    it('should default areBatchUpdatesDisabled to false (batch updates enabled)', () => {
-      const store = new GraphStore({});
-      // The store should be created successfully with default batch-based updates
-      expect(store).toBeDefined();
-      expect(store.graph).toBeDefined();
-    });
-
-    it('should use areBatchUpdatesDisabled when provided', () => {
-      const storeWithRealtime = new GraphStore({ areBatchUpdatesDisabled: true });
-      expect(storeWithRealtime).toBeDefined();
-
-      const storeWithBatches = new GraphStore({ areBatchUpdatesDisabled: false });
-      expect(storeWithBatches).toBeDefined();
-    });
-
     it('should handle graph with existing cells', () => {
       const graph = new dia.Graph({}, { cellNamespace: DEFAULT_TEST_NAMESPACE });
       const existingElement = new dia.Element({
@@ -152,9 +148,15 @@ describe('GraphStore', () => {
       graph.addCell(existingElement);
       const cellCountBefore = graph.getCells().length;
 
-      const initialElements: GraphElement[] = [
-        { id: 'new-element', x: 10, y: 20, width: 100, height: 50, type: 'ReactElement' },
-      ];
+      const initialElements: Record<string, GraphElement> = {
+        'new-element': {
+          x: 10,
+          y: 20,
+          width: 100,
+          height: 50,
+          type: 'ReactElement',
+        },
+      };
       const store = new GraphStore({ graph, initialElements });
 
       // Store should be created successfully
@@ -358,8 +360,8 @@ describe('GraphStore', () => {
 
     it('should return true for measured nodes', () => {
       const store = new GraphStore({});
+      const id = 'measured-element';
       const data: GraphElement = {
-        id: 'measured-element',
         x: 10,
         y: 20,
         width: 100,
@@ -369,24 +371,24 @@ describe('GraphStore', () => {
 
       store.publicState.setState((previous) => ({
         ...previous,
-        elements: [...previous.elements, data],
+        elements: { ...previous.elements, [id]: data },
       }));
 
       const domElement = document.createElement('div');
       store.setMeasuredNode({
-        id: 'measured-element',
+        id,
         element: domElement,
       });
 
-      expect(store.hasMeasuredNode('measured-element')).toBe(true);
+      expect(store.hasMeasuredNode(id)).toBe(true);
     });
   });
 
   describe('setMeasuredNode', () => {
     it('should register a node for measurement and return cleanup', () => {
       const store = new GraphStore({});
+      const id = 'measured-element';
       const element: GraphElement = {
-        id: 'measured-element',
         x: 10,
         y: 20,
         width: 100,
@@ -396,22 +398,22 @@ describe('GraphStore', () => {
 
       store.publicState.setState((previous) => ({
         ...previous,
-        elements: [...previous.elements, element],
+        elements: { ...previous.elements, [id]: element },
       }));
 
       const domElement = document.createElement('div');
       const setSize = jest.fn();
       const cleanup = store.setMeasuredNode({
-        id: 'measured-element',
+        id,
         element: domElement,
         transform: setSize,
       });
 
       expect(typeof cleanup).toBe('function');
-      expect(store.hasMeasuredNode('measured-element')).toBe(true);
+      expect(store.hasMeasuredNode(id)).toBe(true);
 
       cleanup();
-      expect(store.hasMeasuredNode('measured-element')).toBe(false);
+      expect(store.hasMeasuredNode(id)).toBe(false);
     });
   });
 
@@ -462,7 +464,7 @@ describe('GraphStore', () => {
         // Empty unsubscribe function
       }
       const newStore = {
-        getSnapshot: () => ({ elements: [], links: [] }),
+        getSnapshot: () => ({ elements: {}, links: {} }),
         subscribe: () => unsubscribe,
         setState: () => {},
       };
@@ -474,41 +476,7 @@ describe('GraphStore', () => {
     });
   });
 
-  describe('derivedStore', () => {
-    it('should create elementIds mapping', () => {
-      const store = new GraphStore({});
-      const elements: GraphElement[] = [
-        { id: 'element-1', x: 10, y: 20, width: 100, height: 50, type: 'ReactElement' },
-        { id: 'element-2', x: 30, y: 40, width: 80, height: 60, type: 'ReactElement' },
-      ];
-
-      store.publicState.setState((previous) => ({
-        ...previous,
-        elements,
-      }));
-
-      const derived = store.derivedStore.getSnapshot();
-      expect(derived.elementIds['element-1']).toBe(0);
-      expect(derived.elementIds['element-2']).toBe(1);
-    });
-
-    it('should create linkIds mapping', () => {
-      const store = new GraphStore({});
-      const links: GraphLink[] = [
-        { id: 'link-1', source: 'element-1', target: 'element-2', type: 'standard.Link' },
-        { id: 'link-2', source: 'element-2', target: 'element-3', type: 'standard.Link' },
-      ];
-
-      store.publicState.setState((previous) => ({
-        ...previous,
-        links,
-      }));
-
-      const derived = store.derivedStore.getSnapshot();
-      expect(derived.linkIds['link-1']).toBe(0);
-      expect(derived.linkIds['link-2']).toBe(1);
-    });
-
+  describe('areElementsMeasuredState', () => {
     it('should track areElementsMeasured correctly', (done) => {
       const store = new GraphStore({});
 
@@ -550,8 +518,8 @@ describe('GraphStore', () => {
   describe('state synchronization', () => {
     it('should sync state changes to graph', (done) => {
       const store = new GraphStore({});
+      const id = 'sync-element';
       const element: GraphElement = {
-        id: 'sync-element',
         x: 10,
         y: 20,
         width: 100,
@@ -561,12 +529,12 @@ describe('GraphStore', () => {
 
       store.publicState.setState((previous) => ({
         ...previous,
-        elements: [...previous.elements, element],
+        elements: { ...previous.elements, [id]: element },
       }));
 
       // Wait for sync
       setTimeout(() => {
-        const graphElement = store.graph.getCell('sync-element');
+        const graphElement = store.graph.getCell(id);
         expect(graphElement).toBeDefined();
         expect(graphElement?.isElement()).toBe(true);
         done();
@@ -587,11 +555,9 @@ describe('GraphStore', () => {
       graph.addCell(element);
 
       // Wait for sync
-      // eslint-disable-next-line @typescript-eslint/no-shadow
-      const findElementById = (element: GraphElement) => element.id === 'graph-element';
       setTimeout(() => {
         const snapshot = store.publicState.getSnapshot();
-        const stateElement = snapshot.elements.find(findElementById);
+        const stateElement = snapshot.elements['graph-element'];
         expect(stateElement).toBeDefined();
         done();
       }, 50);
diff --git a/packages/joint-react/src/store/batch-cache.ts b/packages/joint-react/src/store/batch-cache.ts
new file mode 100644
index 000000000..ba609d0c4
--- /dev/null
+++ b/packages/joint-react/src/store/batch-cache.ts
@@ -0,0 +1,125 @@
+import type { dia } from '@joint/core';
+import type { PortUpdateCacheEntry } from './port-cache';
+import type { ClearViewCacheEntry } from './clear-view';
+
+/**
+ * Generic batch cache for collecting updates before flushing.
+ * Provides a unified pattern for link, port, and other batched updates.
+ * @template K - Key type (usually dia.Cell.ID)
+ * @template V - Value type (cache entry)
+ */
+export class BatchCache<K, V extends object> {
+  private cache = new Map<K, V>();
+  private scheduler: () => void;
+  private defaultEntry: () => V;
+
+  constructor(options: { readonly scheduler: () => void; readonly defaultEntry: () => V }) {
+    this.scheduler = options.scheduler;
+    this.defaultEntry = options.defaultEntry;
+  }
+
+  /**
+   * Gets or creates an entry for the given key.
+   * @param key
+   */
+  getOrCreate(key: K): V {
+    let entry = this.cache.get(key);
+    if (!entry) {
+      entry = this.defaultEntry();
+      this.cache.set(key, entry);
+    }
+    return entry;
+  }
+
+  /**
+   * Updates an entry and schedules a flush.
+   * @param key
+   * @param updater
+   */
+  update(key: K, updater: (entry: V) => void): void {
+    const entry = this.getOrCreate(key);
+    updater(entry);
+    this.scheduler();
+  }
+
+  /**
+   * Gets the current cache size.
+   */
+  get size(): number {
+    return this.cache.size;
+  }
+
+  /**
+   * Checks if the cache is empty.
+   */
+  get isEmpty(): boolean {
+    return this.cache.size === 0;
+  }
+
+  /**
+   * Iterates over cache entries.
+   */
+  entries(): IterableIterator<[K, V]> {
+    return this.cache.entries();
+  }
+
+  /**
+   * Clears the cache.
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Gets an entry by key.
+   * @param key
+   */
+  get(key: K): V | undefined {
+    return this.cache.get(key);
+  }
+
+  /**
+   * Sets an entry by key.
+   * @param key
+   * @param value
+   */
+  set(key: K, value: V): void {
+    this.cache.set(key, value);
+  }
+
+  /**
+   * Checks if a key exists.
+   * @param key
+   */
+  has(key: K): boolean {
+    return this.cache.has(key);
+  }
+}
+
+/**
+ * Creates a typed batch cache for cell ID keyed entries.
+ * @param scheduler - Function to call when updates are scheduled
+ * @returns A new BatchCache instance
+ */
+function createCellCache<V extends object>(scheduler: () => void): BatchCache<dia.Cell.ID, V> {
+  return new BatchCache<dia.Cell.ID, V>({
+    scheduler,
+    defaultEntry: () => ({}) as V,
+  });
+}
+
+/**
+ * Creates a port update cache with the standard entry structure.
+ * @param scheduler
+ */
+export function createPortCache(scheduler: () => void): BatchCache<dia.Cell.ID, PortUpdateCacheEntry> {
+  return createCellCache<PortUpdateCacheEntry>(scheduler);
+}
+
+/**
+ * Creates a clearView cache with the standard entry structure.
+ * @param scheduler
+ */
+export function createClearViewCache(scheduler: () => void): BatchCache<dia.Cell.ID, ClearViewCacheEntry> {
+  return createCellCache<ClearViewCacheEntry>(scheduler);
+}
diff --git a/packages/joint-react/src/store/clear-view.ts b/packages/joint-react/src/store/clear-view.ts
new file mode 100644
index 000000000..f7a8d978b
--- /dev/null
+++ b/packages/joint-react/src/store/clear-view.ts
@@ -0,0 +1,130 @@
+import type { dia } from '@joint/core';
+
+/**
+ * Cache entry for batched clearView updates.
+ */
+export interface ClearViewCacheEntry {
+  /** Callback to validate which links should be cleared */
+  onValidateLink?: (link: dia.Link) => boolean;
+}
+
+/**
+ * Merges two clearView validators.
+ * - If no validator (clear all links), that takes precedence
+ * - If both have validators, creates union validator
+ * @param existing - Existing validator
+ * @param incoming - New validator
+ * @returns Merged validator or undefined
+ */
+export function mergeClearViewValidators(
+  existing: ClearViewCacheEntry | undefined,
+  incoming: ClearViewCacheEntry
+): ClearViewCacheEntry {
+  // No existing entry - use new
+  if (!existing) {
+    return incoming;
+  }
+
+  const { onValidateLink } = incoming;
+
+  // No validator means clear all links - this takes precedence
+  if (!onValidateLink) {
+    return { onValidateLink: undefined };
+  }
+
+  // If existing has validator, create union
+  if (existing.onValidateLink) {
+    const existingValidator = existing.onValidateLink;
+    const newValidator = onValidateLink;
+    return {
+      onValidateLink: (link: dia.Link) => existingValidator(link) || newValidator(link),
+    };
+  }
+
+  // Existing has no validator (clear all) - keep that behavior
+  return existing;
+}
+
+/**
+ * Determines if a link should be cleared based on cell connection.
+ * @param link - The link to check
+ * @param cellId - The cell ID to check against
+ * @param onValidateLink - Optional callback to determine if link should be cleared
+ * @returns True if the link should be cleared
+ */
+export function shouldClearLink(
+  link: dia.Link,
+  cellId: dia.Cell.ID,
+  onValidateLink?: (link: dia.Link) => boolean
+): boolean {
+  const target = link.target();
+  const source = link.source();
+  const isElementLink = target.id === cellId || source.id === cellId;
+  return isElementLink && (!onValidateLink || onValidateLink(link));
+}
+
+/**
+ * Clears connected link views for a cell in a paper.
+ * @param paper - The JointJS Paper instance
+ * @param graph - The JointJS Graph instance
+ * @param cellId - The cell ID whose connected links to clear
+ * @param onValidateLink - Optional callback to determine which links to keep
+ */
+export function clearConnectedLinkViews(
+  paper: dia.Paper,
+  graph: dia.Graph,
+  cellId: dia.Cell.ID,
+  onValidateLink?: (link: dia.Link) => boolean
+): void {
+  const cell = graph.getCell(cellId);
+  if (!cell) {
+    return;
+  }
+
+  for (const link of graph.getConnectedLinks(cell)) {
+    if (!shouldClearLink(link, cellId, onValidateLink)) {
+      continue;
+    }
+
+    const linkView = link.findView(paper);
+    if (!linkView) {
+      continue;
+    }
+
+    // @ts-expect-error we use private jointjs api method
+    linkView._sourceMagnet = null;
+    // @ts-expect-error we use private jointjs api method
+    linkView._targetMagnet = null;
+    // @ts-expect-error we use private jointjs api method
+    linkView.requestConnectionUpdate({ async: false });
+  }
+}
+
+/**
+ * Executes clearView for a single cell across all papers.
+ * @param papers - Iterable of paper stores with paper property
+ * @param graph - The JointJS Graph instance
+ * @param cellId - The cell ID to clear
+ * @param onValidateLink - Optional callback to determine which links to keep
+ */
+export function executeClearViewForCell(
+  papers: Iterable<{ readonly paper?: dia.Paper }>,
+  graph: dia.Graph,
+  cellId: dia.Cell.ID,
+  onValidateLink?: (link: dia.Link) => boolean
+): void {
+  for (const paperStore of papers) {
+    const { paper } = paperStore;
+    if (!paper) {
+      continue;
+    }
+
+    const elementView = paper.findViewByModel(cellId);
+    if (!elementView) {
+      continue;
+    }
+
+    elementView.cleanNodesCache();
+    clearConnectedLinkViews(paper, graph, cellId, onValidateLink);
+  }
+}
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 4e86fbb6e..9acd3cbec 100644
--- a/packages/joint-react/src/store/create-elements-size-observer.ts
+++ b/packages/joint-react/src/store/create-elements-size-observer.ts
@@ -1,7 +1,7 @@
 /* eslint-disable sonarjs/cognitive-complexity */
 import type { dia } from '@joint/core';
 import type { GraphElement } from '../types/element-types';
-import type { GraphStoreDerivedSnapshot, GraphStoreSnapshot, NodeLayout } from './graph-store';
+import type { GraphStoreSnapshot, NodeLayout } from './graph-store';
 import type { MarkDeepReadOnly } from '../utils/create-state';
 
 const DEFAULT_OBSERVER_OPTIONS: ResizeObserverOptions = { box: 'border-box' };
@@ -70,12 +70,10 @@ interface Options {
   readonly resizeObserverOptions?: ResizeObserverOptions;
   /** Function to get the current size of a cell from the graph */
   readonly getCellTransform: (id: dia.Cell.ID) => NodeLayoutOptionalXY & { element: dia.Element; angle: number };
-  /** Function to get the current IDs snapshot for efficient lookups */
-  readonly getIdsSnapshot: () => MarkDeepReadOnly<GraphStoreDerivedSnapshot>;
   /** Function to get the current public snapshot containing all elements */
   readonly getPublicSnapshot: () => MarkDeepReadOnly<GraphStoreSnapshot>;
   /** Callback function called when a batch of elements needs to be updated */
-  readonly onBatchUpdate: (elements: GraphElement[]) => void;
+  readonly onBatchUpdate: (elements: Record<dia.Cell.ID, GraphElement>) => void;
 }
 
 /**
@@ -130,7 +128,6 @@ export function createElementsSizeObserver(options: Options): GraphStoreObserver
   const {
     resizeObserverOptions = DEFAULT_OBSERVER_OPTIONS,
     getCellTransform,
-    getIdsSnapshot,
     onBatchUpdate,
     getPublicSnapshot,
   } = options;
@@ -139,9 +136,10 @@ export function createElementsSizeObserver(options: Options): GraphStoreObserver
   const observer = new ResizeObserver((entries) => {
     // Process all entries as a single batch
     let hasAnySizeChange = false;
-    const idsSnapshot = getIdsSnapshot();
     const publicSnapshot = getPublicSnapshot();
-    const updatedElements: GraphElement[] = [...publicSnapshot.elements] as GraphElement[];
+    // Convert Record to array for batch update (preserving compatibility)
+    const elementsRecord = publicSnapshot.elements as Record<dia.Cell.ID, GraphElement>;
+    const updatedElements: Record<dia.Cell.ID, GraphElement> = { ...elementsRecord };
 
     for (const entry of entries) {
       // We must be careful to not mutate the snapshot data.
@@ -181,12 +179,11 @@ export function createElementsSizeObserver(options: Options): GraphStoreObserver
         continue;
       }
 
-      const elementArrayIndex = idsSnapshot.elementIds[cellId];
-      if (elementArrayIndex == undefined) {
+      const graphElement = updatedElements[cellId];
+      if (!graphElement) {
         throw new Error(`Element with id ${cellId} not found in graph data ref`);
       }
 
-      const graphElement = updatedElements[elementArrayIndex];
       const observedElement = observedElementsByCellId.get(cellId) ?? DEFAULT_OBSERVED_ELEMENT;
       const { transform: sizeTransformFunction = defaultTransform } = observedElement;
 
@@ -204,12 +201,8 @@ export function createElementsSizeObserver(options: Options): GraphStoreObserver
       observedElement.lastWidth = measuredWidth;
       observedElement.lastHeight = measuredHeight;
 
-      if (!graphElement) {
-        throw new Error(`Element with id ${cellId} not found in graph data ref`);
-      }
-
       const { x, y, angle, element: cell } = currentCellTransform;
-      updatedElements[elementArrayIndex] = {
+      updatedElements[cellId] = {
         ...graphElement,
         ...sizeTransformFunction({
           x: x ?? 0,
@@ -229,6 +222,7 @@ export function createElementsSizeObserver(options: Options): GraphStoreObserver
       return;
     }
 
+    // Pass updated elements as Record
     onBatchUpdate(updatedElements);
   });
 
diff --git a/packages/joint-react/src/store/graph-store.ts b/packages/joint-react/src/store/graph-store.ts
index 86201525b..e94d853b9 100644
--- a/packages/joint-react/src/store/graph-store.ts
+++ b/packages/joint-react/src/store/graph-store.ts
@@ -1,5 +1,4 @@
 import { dia, shapes, util } from '@joint/core';
-import { startTransition } from 'react';
 import type { GraphLink } from '../types/link-types';
 import type { GraphElement } from '../types/element-types';
 import type { AddPaperOptions, PaperStoreSnapshot } from './paper-store';
@@ -12,19 +11,34 @@ import {
 import { ReactElement } from '../models/react-element';
 import { ReactLink } from '../models/react-link';
 import type { ExternalStoreLike, State } from '../utils/create-state';
-import { createState, derivedState, getValue } from '../utils/create-state';
-import { stateSync, type StateSync, updateGraph } from '../state/state-sync';
+import { createState, derivedState } from '../utils/create-state';
+import { stateSync, type StateSync } from '../state/state-sync';
 import type { GraphStateSelectors } from '../state/graph-state-selectors';
 import {
-  defaultGraphToElementSelector,
+  mapElementAttributesToData,
   defaultMapDataToElementAttributes,
-  defaultGraphToLinkSelector,
+  mapLinkAttributesToData,
   defaultMapDataToLinkAttributes,
-  createDefaultGraphToLinkMapper,
-  createDefaultLinkMapper,
 } from '../state/graph-state-selectors';
-import type { OnChangeOptions } from '../utils/cell/listen-to-cell-change';
-import { createScheduler } from '../utils/scheduler-old';
+import { listenToCellChange, type OnChangeOptions } from '../utils/cell/listen-to-cell-change';
+import { Scheduler } from '../utils/scheduler';
+import type { GraphSchedulerData } from '../types/scheduler.types';
+import { createPortCache, createClearViewCache, type BatchCache } from './batch-cache';
+import {
+  type PortUpdateCacheEntry,
+  mergePortUpdates,
+  setPort as setPortEntry,
+  removePort as removePortEntry,
+  setPortGroup as setPortGroupEntry,
+  removePortGroup as removePortGroupEntry,
+} from './port-cache';
+import {
+  type ClearViewCacheEntry,
+  mergeClearViewValidators,
+  executeClearViewForCell,
+} from './clear-view';
+import { flushElements, flushLinks, flushLayoutState } from './state-flush';
+import { updateGraph } from '../state/update-graph';
 
 export const DEFAULT_CELL_NAMESPACE: Record<string, unknown> = {
   ...shapes,
@@ -34,274 +48,107 @@ export const DEFAULT_CELL_NAMESPACE: Record<string, unknown> = {
 
 /**
  * External store interface compatible with GraphStore.
- * Used for integrating with external state management libraries (Redux, Zustand, etc.).
  */
 export type ExternalGraphStore = ExternalStoreLike<GraphStoreSnapshot>;
 
 /**
  * Internal state type for GraphStore.
- * Contains the full internal snapshot including paper-specific data.
  */
 export type GraphState = State<GraphStoreInternalSnapshot>;
 
 /**
  * Public snapshot of the graph store containing elements and links.
- * This is the shape of data exposed to React components and external stores.
- * @template Element - The type of elements in the graph
- * @template Link - The type of links in the graph
  */
 export interface GraphStoreSnapshot<
   Element extends GraphElement = GraphElement,
   Link extends GraphLink = GraphLink,
 > {
-  /** Array of all elements (nodes) in the graph */
-  readonly elements: Element[];
-  /** Array of all links (edges) in the graph */
-  readonly links: Link[];
-}
-
-/**
- * Snapshot containing index mappings for elements and links by their IDs.
- * Used for efficient lookups and synchronization.
- */
-export interface GraphStoreDerivedSnapshot {
-  /** Map of element IDs to their index in the elements array */
-  readonly elementIds: Record<dia.Cell.ID, number>;
-  /** Map of link IDs to their index in the links array */
-  readonly linkIds: Record<dia.Cell.ID, number>;
+  readonly elements: Record<dia.Cell.ID, Element>;
+  readonly links: Record<dia.Cell.ID, Link>;
 }
 
 /**
  * Layout data for a single node (element).
  */
 export interface NodeLayout {
-  /** X position of the node */
   readonly x: number;
-  /** Y position of the node */
   readonly y: number;
-  /** Width of the node */
   readonly width: number;
-  /** Height of the node */
   readonly height: number;
-  /** Rotation angle of the node in degrees */
   readonly angle: number;
 }
 
 /**
- * Snapshot containing layout data (geometry) for all nodes by their IDs.
- * Computed from actual graph cell sizes and positions.
+ * Layout data for a single link.
+ */
+export interface LinkLayout {
+  readonly sourceX: number;
+  readonly sourceY: number;
+  readonly targetX: number;
+  readonly targetY: number;
+  readonly d: string;
+}
+
+/**
+ * Snapshot containing layout data for all nodes and links (per paper).
  */
 export interface GraphStoreLayoutSnapshot {
-  /** Map of element IDs to their layout data (x, y, width, height) */
-  readonly layouts: Record<dia.Cell.ID, NodeLayout>;
-  /** Flag indicating if elements have ever been measured (sticky behavior) */
+  readonly elements: Record<dia.Cell.ID, NodeLayout>;
+  readonly links: Record<string, Record<dia.Cell.ID, LinkLayout>>;
   readonly wasEverMeasured: boolean;
 }
 
 /**
  * Full internal snapshot of the graph store.
- * Contains paper-specific data and is not directly exposed to consumers.
  */
 export interface GraphStoreInternalSnapshot {
-  /** Map of paper IDs to their store snapshots */
   readonly papers: Record<string, PaperStoreSnapshot>;
 }
 
-/**
- * Cache entry for batched link updates.
- * @internal
- */
-interface LinkUpdateCacheEntry {
-  /** Line attributes from BaseLink */
-  attrs?: Record<string, unknown>;
-  /** Labels by labelId from LinkLabel */
-  labels?: Map<string, dia.Link.Label>;
-  /** Label IDs to remove */
-  labelsToRemove?: Set<string>;
-  /** Mark entire link for removal */
-  shouldRemove?: boolean;
-}
-
-/**
- * Link label with labelId property for identification.
- * @internal
- */
-interface LinkLabelWithId extends dia.Link.Label {
-  readonly labelId: string;
-}
-
-/**
- * Cache entry for batched port updates.
- * @internal
- */
-interface PortUpdateCacheEntry {
-  /** Ports to add or update by port ID */
-  ports?: Map<string, dia.Element.Port>;
-  /** Port IDs to remove */
-  portsToRemove?: Set<string>;
-  /** Port groups to add or update by group ID */
-  groups?: Map<string, dia.Element.PortGroup>;
-  /** Port group IDs to remove */
-  groupsToRemove?: Set<string>;
-}
-
-/**
- * Cache entry for batched clearView updates.
- * @internal
- */
-interface ClearViewCacheEntry {
-  /** Callback to validate which links should be cleared */
-  onValidateLink?: (link: dia.Link) => boolean;
-}
-
 /**
  * Configuration options for creating a GraphStore instance.
- * @template Element - The type of elements in the graph
- * @template Link - The type of links in the graph
  */
 export interface GraphStoreOptions<
   Element extends GraphElement = GraphElement,
   Link extends GraphLink = GraphLink,
 > extends GraphStateSelectors<Element, Link> {
-  /**
-   * Graph instance to use. If not provided, a new graph instance will be created.
-   * Useful when you need to share a graph instance across multiple stores or integrate with existing JointJS code.
-   * @see https://docs.jointjs.com/api/dia/Graph
-   * @default new dia.Graph({}, { cellNamespace: shapes })
-   */
   readonly graph?: dia.Graph;
-  /**
-   * Namespace for cell models. Defines which cell types are available in the graph.
-   * When provided, it will be merged with the default namespace (shapes + ReactElement).
-   * It's loaded just once during initialization, so it cannot be used as React state.
-   * @default shapes
-   * @see https://docs.jointjs.com/api/shapes
-   */
   readonly cellNamespace?: unknown;
-  /**
-   * Custom cell model to use as the base class for all cells in the graph.
-   * It's loaded just once during initialization, so it cannot be used as React state.
-   * @see https://docs.jointjs.com/api/dia/Cell
-   */
   readonly cellModel?: typeof dia.Cell;
-  /**
-   * Initial elements to be added to the graph on creation.
-   * These are loaded just once during initialization, so they cannot be used as React state.
-   * For dynamic elements, use controlled mode with `elements` and `onElementsChange` props on GraphProvider.
-   */
-  readonly initialElements?: GraphElement[];
-
-  /**
-   * Initial links to be added to the graph on creation.
-   * These are loaded just once during initialization, so they cannot be used as React state.
-   * For dynamic links, use controlled mode with `links` and `onLinksChange` props on GraphProvider.
-   */
-  readonly initialLinks?: GraphLink[];
-
-  /**
-   * External store to use as the source of truth for elements and links.
-   * When provided, GraphStore will treat this as the authoritative source and sync bidirectionally.
-   * Compatible with any store that implements the ExternalStoreLike interface (Redux, Zustand, etc.).
-   * Takes precedence over React-controlled mode (onElementsChange/onLinksChange).
-   */
+  readonly initialElements?: Record<dia.Cell.ID, GraphElement>;
+  readonly initialLinks?: Record<dia.Cell.ID, GraphLink>;
   readonly externalStore?: ExternalGraphStore;
-
-  /**
-   * If true, batch updates are disabled and synchronization will be real-time.
-   * If false (default), batch updates are enabled for better performance.
-   * @default false
-   */
-  readonly areBatchUpdatesDisabled?: boolean;
 }
 
 /**
  * Central store for managing graph state, synchronization, and paper instances.
- * Handles bidirectional synchronization between React state and JointJS graph,
- * manages element size observations, and coordinates multiple paper views.
  */
 export class GraphStore {
-  /**
-   * Internal state containing paper-specific snapshots.
-   * @internal
-   */
   public readonly internalState: State<GraphStoreInternalSnapshot>;
-  /**
-   * Public state containing elements and links, exposed to React components.
-   * Can be replaced with an external store for controlled mode.
-   * @internal
-   */
   public publicState: ExternalStoreLike<GraphStoreSnapshot>;
-  /**
-   * Derived state containing ID-to-index mappings for efficient lookups.
-   * @internal
-   */
-  public readonly derivedStore: State<GraphStoreDerivedSnapshot>;
-  /**
-   * State tracking whether all elements have been measured (have width and height).
-   * Computed based on actual graph cell sizes, not state data.
-   * @internal
-   */
   public readonly areElementsMeasuredState: State<boolean>;
-  /**
-   * State containing layout data (geometry) for all nodes by their IDs.
-   * Computed from actual graph cell sizes and positions.
-   * @internal
-   */
   public readonly layoutState: State<GraphStoreLayoutSnapshot>;
-
-  /** The underlying JointJS graph instance */
   public readonly graph: dia.Graph;
 
-  private unsubscribeFromExternal?: () => void;
-
   private papers = new Map<string, PaperStore>();
   private observer: GraphStoreObserver;
   private stateSync: StateSync;
 
-  /**
-   * Cache for batched link updates (attrs and labels).
-   * Updates are collected here and flushed together via syncCells.
-   * @internal
-   */
-  private linkUpdateCache = new Map<dia.Cell.ID, LinkUpdateCacheEntry>();
-
-  /**
-   * Cache for batched port updates (items and groups).
-   * Updates are collected here and flushed together via syncCells.
-   * @internal
-   */
-  private portUpdateCache = new Map<dia.Cell.ID, PortUpdateCacheEntry>();
-
-  /**
-   * Cache for batched clearView updates.
-   * Updates are collected here and flushed together.
-   * Key is cellId, value contains optional onValidateLink validator.
-   * @internal
-   */
-  private clearViewCache = new Map<dia.Cell.ID, ClearViewCacheEntry>();
-
-  /**
-   * Unified scheduler for batching link, port, and paper snapshot updates.
-   * Triggers flushGraphUpdates when scheduled, which processes all batched updates.
-   * @internal
-   */
-  private graphUpdateScheduler: ReturnType<typeof createScheduler>;
-
-  /**
-   * Registered callbacks for paper snapshot updates.
-   * Each PaperStore registers its update callback here to be batched together.
-   * @internal
-   */
+  private portCache: BatchCache<dia.Cell.ID, PortUpdateCacheEntry>;
+  private clearViewCache: BatchCache<dia.Cell.ID, ClearViewCacheEntry>;
+  private readonly scheduler: Scheduler<GraphSchedulerData>;
   private paperUpdateCallbacks = new Set<() => void>();
+  private isGraphUpdateScheduled = false;
+  private isLayoutUpdateScheduled = false;
 
   private readonly graphToElementSelector: (
-    options: { readonly cell: dia.Element; readonly graph: dia.Graph } & {
+    options: { readonly id: string; readonly cell: dia.Element; readonly graph: dia.Graph } & {
       readonly previous?: GraphElement;
       readonly defaultAttributes: () => GraphElement;
     }
   ) => GraphElement;
   private readonly graphToLinkSelector: (
-    options: { readonly cell: dia.Link; readonly graph: dia.Graph } & {
+    options: { readonly id: string; readonly cell: dia.Link; readonly graph: dia.Graph } & {
       readonly previous?: GraphLink;
       readonly defaultAttributes: () => GraphLink;
     }
@@ -319,40 +166,21 @@ export class GraphStore {
 
   constructor(config: GraphStoreOptions) {
     const {
-      initialElements = [],
-      initialLinks = [],
+      initialElements = {},
+      initialLinks = {},
       cellModel,
       cellNamespace = DEFAULT_CELL_NAMESPACE,
       graph,
-      externalStore: externalState,
+      externalStore,
       mapDataToElementAttributes = defaultMapDataToElementAttributes,
       mapDataToLinkAttributes = defaultMapDataToLinkAttributes,
     } = config;
 
-    // Store selectors as instance variables for use in onBatchUpdate
-    // Always use default implementations for graph-to-state selectors (not configurable)
-    this.graphToElementSelector = defaultGraphToElementSelector as (
-      options: { readonly cell: dia.Element; readonly graph: dia.Graph } & {
-        readonly previous?: GraphElement;
-        readonly defaultAttributes: () => GraphElement;
-      }
-    ) => GraphElement;
-    this.graphToLinkSelector = defaultGraphToLinkSelector as (
-      options: { readonly cell: dia.Link; readonly graph: dia.Graph } & {
-        readonly previous?: GraphLink;
-        readonly defaultAttributes: () => GraphLink;
-      }
-    ) => GraphLink;
-    this.mapDataToElementAttributes = mapDataToElementAttributes as (options: {
-      readonly data: GraphElement;
-      readonly graph: dia.Graph;
-      readonly defaultAttributes: () => dia.Cell.JSON;
-    }) => dia.Cell.JSON;
-    this.mapDataToLinkAttributes = mapDataToLinkAttributes as (options: {
-      readonly data: GraphLink;
-      readonly graph: dia.Graph;
-      readonly defaultAttributes: () => dia.Cell.JSON;
-    }) => dia.Cell.JSON;
+    this.graphToElementSelector = mapElementAttributesToData as typeof this.graphToElementSelector;
+    this.graphToLinkSelector = mapLinkAttributesToData as typeof this.graphToLinkSelector;
+    this.mapDataToElementAttributes =
+      mapDataToElementAttributes as typeof this.mapDataToElementAttributes;
+    this.mapDataToLinkAttributes = mapDataToLinkAttributes as typeof this.mapDataToLinkAttributes;
 
     this.graph =
       graph ??
@@ -361,212 +189,115 @@ export class GraphStore {
         {
           cellNamespace: {
             ...DEFAULT_CELL_NAMESPACE,
-            // @ts-expect-error Shapes is not a valid type for cellNamespace
-            ...cellNamespace,
+            ...(cellNamespace as Record<string, unknown>),
           },
           cellModel,
         }
       );
 
-    if (externalState) {
-      this.publicState = externalState;
-    } else {
-      this.publicState = createState<GraphStoreSnapshot>({
+    this.publicState =
+      externalStore ??
+      createState<GraphStoreSnapshot>({
         name: 'JointJs/Data',
-        newState: () => ({
-          elements: [],
-          links: [],
-        }),
-
+        newState: () => ({ elements: {}, links: {} }),
         isDevToolEnabled: true,
       });
-    }
+
     this.internalState = createState<GraphStoreInternalSnapshot>({
       name: 'Jointjs/Internal',
-      newState: () => ({
-        papers: {},
-      }),
-
+      newState: () => ({ papers: {} }),
       isDevToolEnabled: false,
     });
 
-    this.derivedStore = derivedState({
-      name: 'Jointjs/DataIds',
-      state: this.publicState,
-      selector: (snapshot) => {
-        const elementIds: Record<dia.Cell.ID, number> = {};
-        const linkIds: Record<dia.Cell.ID, number> = {};
-
-        for (const [index, element] of snapshot.elements.entries()) {
-          elementIds[element.id] = index;
-        }
-        for (const [index, link] of snapshot.links.entries()) {
-          linkIds[link.id] = index;
-        }
-        return { elementIds, linkIds };
-      },
-    });
-
-    this.stateSync = stateSync({
-      areBatchUpdatesDisabled: config.areBatchUpdatesDisabled ?? false,
-      graph: this.graph,
-      getIdsSnapshot: () => this.derivedStore.getSnapshot(),
-      mapDataToElementAttributes,
-      mapDataToLinkAttributes,
-      store: {
-        getSnapshot: () => this.publicState.getSnapshot(),
-        subscribe: this.publicState.subscribe,
-        setState: (updater) => {
-          this.publicState.setState((previous) => ({
-            ...previous,
-            ...getValue(previous, updater),
-          }));
-        },
-      },
-    });
-
-    // Create state for tracking node layouts
     this.layoutState = createState<GraphStoreLayoutSnapshot>({
       name: 'Jointjs/Layout',
-      newState: () => ({ layouts: {}, wasEverMeasured: false }),
+      newState: () => ({ elements: {}, links: {}, wasEverMeasured: false }),
       isEqual: util.isEqual,
       isDevToolEnabled: true,
     });
 
-    // Derive areElementsMeasured from layout state
     this.areElementsMeasuredState = derivedState({
       name: 'Jointjs/AreElementsMeasured',
       state: this.layoutState,
       selector: (snapshot) => {
-        // If we've ever been measured, always return true (sticky behavior)
-        if (snapshot.wasEverMeasured) {
-          return true;
-        }
-
-        const { layouts } = snapshot;
-        const layoutEntries = Object.values(layouts);
-
-        if (layoutEntries.length === 0) {
-          return false;
-        }
-
-        for (const layout of layoutEntries) {
-          if (layout.width <= 1 || layout.height <= 1) {
-            return false;
-          }
-        }
-
-        return true;
+        if (snapshot.wasEverMeasured) return true;
+        const layoutEntries = Object.values(snapshot.elements);
+        if (layoutEntries.length === 0) return false;
+        return layoutEntries.every((layout) => layout.width > 1 && layout.height > 1);
       },
     });
 
-    // Function to update layout state from graph
-    // Optimized to only update changed elements and use startTransition for better performance
-    const updateLayoutState = () => {
-      const layouts: Record<dia.Cell.ID, NodeLayout> = {};
-      const elements = this.graph.getElements();
-      const previousLayouts = this.layoutState.getSnapshot().layouts;
-
-      for (const element of elements) {
-        const size = element.get('size');
-        const position = element.get('position') ?? { x: 0, y: 0 };
-        const angle = element.get('angle') ?? 0;
-        // Only track elements that have size (position defaults to 0,0 if not set)
-        if (size) {
-          const newLayout: NodeLayout = {
-            x: position.x ?? 0,
-            y: position.y ?? 0,
-            width: size.width ?? 0,
-            height: size.height ?? 0,
-            angle,
-          };
-
-          // Only update if layout actually changed (optimization)
-          const previousLayout = previousLayouts[element.id];
-          if (
-            previousLayout?.x !== newLayout.x ||
-            previousLayout.y !== newLayout.y ||
-            previousLayout.width !== newLayout.width ||
-            previousLayout.height !== newLayout.height ||
-            previousLayout.angle !== newLayout.angle
-          ) {
-            layouts[element.id] = newLayout;
-          } else {
-            // Reuse previous layout to avoid unnecessary updates
-            layouts[element.id] = previousLayout;
+    // Single scheduler for all updates - GOLDEN RULE: setState ONLY in state-flush.ts
+    this.scheduler = new Scheduler<GraphSchedulerData>({
+      onFlush: (data) => {
+        // Capture flags before resetting them
+        const hadGraphUpdate = this.isGraphUpdateScheduled;
+        const hadLayoutUpdate = this.isLayoutUpdateScheduled;
+
+        // 1. Flush state updates (uses state-flush.ts - GOLDEN RULE compliant)
+        flushElements(this.publicState, data);
+        flushLinks(this.publicState, data);
+
+        // 2. Flush graph updates (link/port/clearView caches)
+        if (hadGraphUpdate) {
+          this.isGraphUpdateScheduled = false;
+          for (const callback of this.paperUpdateCallbacks) {
+            callback();
           }
+          this.flushGraphUpdates();
         }
-      }
 
-      // Compute if all elements are measured
-      const layoutEntries = Object.values(layouts);
-      let areAllMeasured = layoutEntries.length > 0;
-      for (const layout of layoutEntries) {
-        if (layout.width <= 1 || layout.height <= 1) {
-          areAllMeasured = false;
-          break;
+        // 3. Flush layout state when there are changes (uses state-flush.ts)
+        // Also flush after graph updates since papers may have rendered new link views
+        const hasElementChanges = data.elementsToUpdate || data.elementsToDelete;
+        const hasLinkChanges = data.linksToUpdate || data.linksToDelete;
+        const shouldFlushLayout =
+          hadLayoutUpdate || hasElementChanges || hasLinkChanges || hadGraphUpdate;
+        if (shouldFlushLayout) {
+          this.isLayoutUpdateScheduled = false;
+          flushLayoutState({
+            graph: this.graph,
+            layoutState: this.layoutState,
+            papers: this.papers,
+          });
         }
-      }
-
-      // Use startTransition for layout state updates to keep UI responsive
-      startTransition(() => {
-        this.layoutState.setState((previous) => ({
-          layouts,
-          wasEverMeasured: previous.wasEverMeasured || areAllMeasured,
-        }));
-      });
-    };
-
-    // Debounce layout state updates using scheduler to batch multiple changes
-    const scheduleLayoutUpdate = createScheduler(updateLayoutState);
-
-    // Subscribe to cell changes to update layout state
-    // areElementsMeasured will be automatically derived from layout state
-    this.stateSync.subscribeToGraphChange(() => {
-      // Schedule layout state update (batched for performance)
-      scheduleLayoutUpdate();
-
-      // Return cleanup function (no-op since we don't need per-cell cleanup)
-      // eslint-disable-next-line unicorn/consistent-function-scoping
-      return () => {
-        // No cleanup needed
-      };
+      },
     });
 
-    // Initial layout state computation
-    updateLayoutState();
+    // Initial layout update (direct, before scheduler is active)
+    flushLayoutState({ graph: this.graph, layoutState: this.layoutState, papers: this.papers });
 
-    // Initialize unified scheduler for all graph-related updates
-    // Batches link/port updates (syncCells) and paper snapshot updates together
-    this.graphUpdateScheduler = createScheduler(() => {
-      // Execute all registered paper update callbacks
-      for (const callback of this.paperUpdateCallbacks) {
-        callback();
-      }
-      // Then flush graph updates (links and ports)
-      this.flushGraphUpdates();
-    });
+    // BatchCaches use scheduleGraphUpdate which schedules via the single scheduler
+    this.portCache = createPortCache(() => this.scheduleGraphUpdate());
+    this.clearViewCache = createClearViewCache(() => this.scheduleGraphUpdate());
 
-    // Observer for element sizes (uses state.getSnapshot)
+    this.stateSync = stateSync({
+      graph: this.graph,
+      scheduler: this.scheduler,
+      mapDataToElementAttributes,
+      mapDataToLinkAttributes,
+      onGraphUpdated: () => this.scheduleLayoutUpdate(),
+      store: {
+        getSnapshot: () => this.publicState.getSnapshot(),
+        subscribe: this.publicState.subscribe,
+      },
+    });
 
     this.observer = createElementsSizeObserver({
-      getIdsSnapshot: this.derivedStore.getSnapshot,
       getPublicSnapshot: this.publicState.getSnapshot,
       onBatchUpdate: (newElements) => {
-        // Get current links from state
         const snapshot = this.publicState.getSnapshot();
-        const currentLinks = snapshot.links;
 
-        // Update graph directly - this will trigger automatic state sync
+        // 1. Sync new sizes to dia.Graph
         updateGraph({
-          getIdsSnapshot: this.derivedStore.getSnapshot,
           graph: this.graph,
           elements: newElements,
-          links: currentLinks,
+          links: snapshot.links,
           graphToElementSelector: this.graphToElementSelector,
           graphToLinkSelector: this.graphToLinkSelector,
           mapDataToElementAttributes: this.mapDataToElementAttributes,
           mapDataToLinkAttributes: this.mapDataToLinkAttributes,
+          isUpdateFromReact: false,
         });
       },
       getCellTransform: (id) => {
@@ -574,163 +305,111 @@ export class GraphStore {
         if (!cell?.isElement()) throw new Error('Cell not valid');
         const size = cell.get('size');
         const position = cell.get('position');
-        const angle = cell.get('angle') ?? 0;
         if (!size) throw new Error('Size not found');
         return {
           width: size.width,
           height: size.height,
           element: cell,
-          angle,
+          angle: cell.get('angle') ?? 0,
           ...position,
         };
       },
     });
 
-    // Initial sync: either from external store or from constructor elements/links
-    // Only set initial elements/links if graph doesn't have existing cells
-    // (if graph has cells, syncExistingGraphCellsToStore in stateSync will handle it)
+    // Initial sync
     const graphHasCells = this.graph.getElements().length > 0 || this.graph.getLinks().length > 0;
-    if (!graphHasCells || initialElements.length > 0 || initialLinks.length > 0) {
+    if (
+      !graphHasCells ||
+      Object.keys(initialElements).length > 0 ||
+      Object.keys(initialLinks).length > 0
+    ) {
       this.publicState.setState((previous) => ({
         ...previous,
         elements: initialElements,
         links: initialLinks,
       }));
     }
+
+    // Update layout after initial sync (graph now has cells with sizes)
+    flushLayoutState({ graph: this.graph, layoutState: this.layoutState, papers: this.papers });
   }
 
+  // --- Layout State ---
+
   /**
-   * Merges label updates into the current labels array.
-   * @param currentLabels - Current labels from the link
-   * @param entry - Cache entry containing label updates
-   * @returns Merged labels array
-   * @internal
+   * Schedules a layout state update via the single scheduler.
    */
-  private mergeLinkLabels(
-    currentLabels: dia.Link.Label[],
-    entry: LinkUpdateCacheEntry
-  ): dia.Link.Label[] {
-    let mergedLabels = [...currentLabels];
-
-    if (entry.labelsToRemove) {
-      mergedLabels = mergedLabels.filter((l) => {
-        const labelWithId = l as LinkLabelWithId;
-        return !labelWithId.labelId || !entry.labelsToRemove!.has(labelWithId.labelId);
-      });
-    }
-
-    if (entry.labels) {
-      for (const [labelId, labelData] of entry.labels) {
-        const existingIndex = mergedLabels.findIndex(
-          (l) => (l as LinkLabelWithId).labelId === labelId
-        );
-        if (existingIndex === -1) {
-          mergedLabels.push(labelData);
-          continue;
-        }
-        mergedLabels[existingIndex] = labelData;
-      }
-    }
+  private scheduleLayoutUpdate = () => {
+    this.isLayoutUpdateScheduled = true;
+    this.scheduler.scheduleData((data) => data);
+  };
 
-    return mergedLabels;
-  }
+  // --- Port Cache Flush ---
 
-  /**
-   * Flushes all cached link updates and returns cells to sync.
-   * Called automatically by the scheduler when updates are batched.
-   * @returns Array of cell JSON objects to sync
-   * @internal
-   */
-  private flushLinkUpdates = (): dia.Cell.JSON[] => {
-    if (this.linkUpdateCache.size === 0) {
-      return [];
-    }
+  private flushPortUpdates(): dia.Cell.JSON[] {
+    if (this.portCache.isEmpty) return [];
 
-    // Build cells array for syncCells
     const cellsToSync: dia.Cell.JSON[] = [];
 
-    for (const [linkId, entry] of this.linkUpdateCache) {
-      const link = this.graph.getCell(linkId);
-      if (!link?.isLink()) {
-        continue;
-      }
+    for (const [elementId, entry] of this.portCache.entries()) {
+      const element = this.graph.getCell(elementId);
+      if (!element?.isElement()) continue;
 
-      // Convert link from graph to GraphLink format (preserves source/target correctly)
-      const defaultGraphToLinkMapper = createDefaultGraphToLinkMapper(link);
-      const graphLink = this.graphToLinkSelector({
-        cell: link,
-        graph: this.graph,
-        defaultAttributes: defaultGraphToLinkMapper,
-      });
+      const currentPorts = element.get('ports') || {};
+      const { ports, groups } = mergePortUpdates(
+        currentPorts.items || [],
+        currentPorts.groups || {},
+        entry
+      );
 
-      // Merge cached attrs into the link
-      const currentAttributes = graphLink.attrs ?? {};
-      const updatedLink = entry.attrs
-        ? {
-            ...graphLink,
-            attrs: {
-              ...currentAttributes,
-              ...entry.attrs,
-            } as typeof graphLink.attrs,
-          }
-        : graphLink;
-
-      // Convert back to Cell.JSON using mapDataToLinkAttributes (reuses proper source/target handling)
-      const linkMapper = createDefaultLinkMapper(updatedLink as GraphLink, this.graph);
-      const cellJson = this.mapDataToLinkAttributes({
-        data: updatedLink as GraphLink,
-        graph: this.graph,
-        defaultAttributes: linkMapper,
-      });
+      const cellJson = element.toJSON();
+      cellJson.ports = { items: ports, groups };
+      cellsToSync.push(cellJson);
+    }
 
-      // Handle labels separately (labels are on the cell, not in GraphLink)
-      if (entry.labels || entry.labelsToRemove) {
-        const currentLabels = link.labels();
-        cellJson.labels = this.mergeLinkLabels(currentLabels, entry);
-      }
+    this.portCache.clear();
+    return cellsToSync;
+  }
 
-      cellsToSync.push(cellJson);
+  // --- Graph Updates Flush ---
+
+  private flushGraphUpdates = () => {
+    const portCells = this.flushPortUpdates();
+
+    if (portCells.length > 0) {
+      this.graph.syncCells(portCells, { remove: false });
     }
 
-    // Clear cache BEFORE sync to avoid re-triggering
-    this.linkUpdateCache.clear();
+    this.flushClearViewInternal();
+  };
 
-    return cellsToSync;
+  private flushClearViewInternal = () => {
+    for (const [cellId, entry] of this.clearViewCache.entries()) {
+      executeClearViewForCell(this.papers.values(), this.graph, cellId, entry.onValidateLink);
+    }
+    this.clearViewCache.clear();
   };
 
-  /**
-   * Cleans up all resources and subscriptions.
-   * Should be called when the GraphStore is no longer needed.
-   * @param isGraphExternal - Whether the graph instance was provided externally (should not be cleared)
-   */
+  // --- Public API ---
+
   public destroy = (isGraphExternal: boolean) => {
-    // Destroy all paper instances first
     for (const paperStore of this.papers.values()) {
       paperStore.destroy();
     }
     this.papers.clear();
-
     this.internalState.clean();
-    this.derivedStore.clean();
     this.layoutState.clean();
     this.areElementsMeasuredState.clean();
-    // Only clean publicState if it's not an external store (external stores don't have clean method)
     if ('clean' in this.publicState && typeof this.publicState.clean === 'function') {
       this.publicState.clean();
     }
     this.observer.clean();
-    this.unsubscribeFromExternal?.();
     this.stateSync.cleanup();
     if (!isGraphExternal) {
       this.graph.clear();
     }
   };
 
-  /**
-   * Updates the snapshot for a specific paper instance.
-   * @param paperId - The unique identifier of the paper
-   * @param updater - Function that receives the previous snapshot and returns the new one
-   */
   public updatePaperSnapshot(
     paperId: string,
     updater: (previous: PaperStoreSnapshot | undefined) => PaperStoreSnapshot
@@ -738,632 +417,122 @@ export class GraphStore {
     this.internalState.setState((previous) => {
       const currentPaper = previous.papers[paperId];
       const nextPaper = updater(currentPaper);
-
-      if (currentPaper === nextPaper) {
-        return previous;
-      }
-
-      return {
-        ...previous,
-        papers: {
-          ...previous.papers,
-          [paperId]: nextPaper,
-        },
-      };
+      if (currentPaper === nextPaper) return previous;
+      return { ...previous, papers: { ...previous.papers, [paperId]: nextPaper } };
     });
   }
 
-  /**
-   * Updates the element view reference for a specific cell in a paper.
-   * Used internally to track element views for rendering and interaction.
-   * @param paperId - The unique identifier of the paper
-   * @param cellId - The ID of the cell whose view is being updated
-   * @param view - The JointJS element view instance
-   */
   public updatePaperElementView(paperId: string, cellId: dia.Cell.ID, view: dia.ElementView) {
-    // silent update of the data.
     this.updatePaperSnapshot(paperId, (current) => {
       const base = current ?? { paperElementViews: {}, portsData: {} };
-
-      const existingView = base.paperElementViews?.[cellId];
-      if (existingView === view) return base;
-
-      return {
-        paperElementViews: {
-          ...base.paperElementViews,
-          [cellId]: view,
-        },
-      };
+      if (base.paperElementViews?.[cellId] === view) return base;
+      return { paperElementViews: { ...base.paperElementViews, [cellId]: view } };
     });
   }
 
-  /**
-   * Updates the link view reference for a specific link in a paper.
-   * Used internally to track link views for rendering and interaction.
-   * @param paperId - The unique identifier of the paper
-   * @param linkId - The ID of the link whose view is being updated
-   * @param view - The JointJS link view instance
-   */
   public updatePaperLinkView(paperId: string, linkId: dia.Cell.ID, view: dia.LinkView) {
-    // silent update of the data.
     this.updatePaperSnapshot(paperId, (current) => {
       const base = current ?? { linkViews: {}, linksData: {} };
-
-      const existingView = base.linkViews?.[linkId];
-      if (existingView === view) return base;
-
-      return {
-        linkViews: {
-          ...base.linkViews,
-          [linkId]: view,
-        },
-      };
+      if (base.linkViews?.[linkId] === view) return base;
+      return { linkViews: { ...base.linkViews, [linkId]: view } };
     });
   }
 
   private removePaper = (id: string) => {
     const paperStore = this.papers.get(id);
-    // Cleanup paper instance and all its resources
-    if (paperStore) {
-      paperStore.destroy();
-    }
+    paperStore?.destroy();
     this.papers.delete(id);
     this.internalState.setState((previous) => {
       const newPapers: Record<string, PaperStoreSnapshot> = {};
       for (const [key, value] of Object.entries(previous.papers)) {
-        if (key !== id) {
-          newPapers[key] = value;
-        }
+        if (key !== id) newPapers[key] = value;
       }
-      return {
-        ...previous,
-        papers: newPapers,
-      };
+      return { ...previous, papers: newPapers };
     });
   };
-  /**
-   * Adds a new paper instance to the store.
-   * @param id - Unique identifier for the paper
-   * @param paperOptions - Configuration options for the paper
-   * @returns Cleanup function to remove the paper
-   */
+
   public addPaper = (id: string, paperOptions: AddPaperOptions) => {
-    const paperStore = new PaperStore({
-      ...paperOptions,
-      graphStore: this,
-      id,
-    });
+    const paperStore = new PaperStore({ ...paperOptions, graphStore: this, id });
     this.papers.set(id, paperStore);
-    return () => {
-      this.removePaper(id);
-    };
-  };
-
-  /**
-   * Checks if a node is currently being measured for size.
-   * @param id - The ID of the cell to check
-   * @returns True if the node is being observed for size changes
-   */
-  public hasMeasuredNode = (id: dia.Cell.ID) => {
-    return this.observer.has(id);
+    return () => this.removePaper(id);
   };
 
-  /**
-   * Registers a node for size measurement observation.
-   * The observer will automatically update the element's size when the DOM element changes.
-   * @param options - Configuration for the measured node
-   * @returns Cleanup function to stop observing
-   */
-  public setMeasuredNode = (options: SetMeasuredNodeOptions) => {
-    return this.observer.add(options);
-  };
+  public hasMeasuredNode = (id: dia.Cell.ID) => this.observer.has(id);
+  public setMeasuredNode = (options: SetMeasuredNodeOptions) => this.observer.add(options);
+  public getPaperStore = (id: string) => this.papers.get(id);
 
-  /**
-   * Retrieves a paper store instance by its ID.
-   * @param id - The unique identifier of the paper
-   * @returns The PaperStore instance, or undefined if not found
-   */
-  public getPaperStore = (id: string) => {
-    return this.papers.get(id);
-  };
-
-  /**
-   * Subscribes to cell change events in the graph.
-   * Useful for reacting to changes that occur outside of React's control.
-   * @param callback - Function that receives change options and returns a cleanup function
-   * @returns Unsubscribe function
-   */
   public subscribeToCellChange = (callback: (change: OnChangeOptions) => () => void) => {
-    return this.stateSync.subscribeToCellChange(callback);
+    return listenToCellChange(this.graph, (change) => callback(change));
   };
 
-  /**
-   * Updates the external store reference.
-   * Used internally when switching between controlled and uncontrolled modes.
-   * @param newStore - The new external store to use
-   */
   public updateExternalStore = (newStore: ExternalStoreLike<GraphStoreSnapshot>) => {
     this.publicState = newStore;
   };
 
-  /**
-   * Sets link attributes (e.g., line styling from BaseLink).
-   * Updates are batched and applied via syncCells for performance.
-   * @param linkId - The ID of the link to update
-   * @param attributes - Attributes to set on the link
-   */
-  public setLink = (linkId: dia.Cell.ID, attributes: Record<string, unknown>) => {
-    const entry = this.linkUpdateCache.get(linkId) ?? {};
-    entry.attrs = { ...entry.attrs, ...attributes };
-    this.linkUpdateCache.set(linkId, entry);
-    this.graphUpdateScheduler();
-  };
-
-  /**
-   * Marks a link for removal.
-   * Updates are batched and applied via syncCells for performance.
-   * @param linkId - The ID of the link to remove
-   */
-  public removeLink = (linkId: dia.Cell.ID) => {
-    const entry = this.linkUpdateCache.get(linkId) ?? {};
-    entry.shouldRemove = true;
-    this.linkUpdateCache.set(linkId, entry);
-    this.graphUpdateScheduler();
-  };
-
-  /**
-   * Sets or updates a link label (from LinkLabel component).
-   * Updates are batched and applied via syncCells for performance.
-   * @param linkId - The ID of the link
-   * @param labelId - Unique identifier for the label
-   * @param labelData - Label data to set
-   */
-  public setLinkLabel = (linkId: dia.Cell.ID, labelId: string, labelData: dia.Link.Label) => {
-    const entry = this.linkUpdateCache.get(linkId) ?? {};
-    entry.labels = entry.labels ?? new Map();
-    entry.labels.set(labelId, labelData);
-    this.linkUpdateCache.set(linkId, entry);
-    this.graphUpdateScheduler();
-  };
-
-  /**
-   * Removes a link label (from LinkLabel component unmount).
-   * Updates are batched and applied via syncCells for performance.
-   * @param linkId - The ID of the link
-   * @param labelId - Unique identifier for the label to remove
-   */
-  public removeLinkLabel = (linkId: dia.Cell.ID, labelId: string) => {
-    const entry = this.linkUpdateCache.get(linkId) ?? {};
-    entry.labelsToRemove = entry.labelsToRemove ?? new Set();
-    entry.labelsToRemove.add(labelId);
-    this.linkUpdateCache.set(linkId, entry);
-    this.graphUpdateScheduler();
-  };
-
-  /**
-   * Merges port item updates into the current ports array.
-   * @param currentPorts - Current port items array
-   * @param entry - Cache entry containing port updates
-   * @returns Merged port items array
-   * @internal
-   */
-  private mergePortItems(
-    currentPorts: dia.Element.Port[],
-    entry: PortUpdateCacheEntry
-  ): dia.Element.Port[] {
-    // Start with current ports, filter out removed ones
-    const filteredPorts = entry.portsToRemove
-      ? currentPorts.filter((p) => {
-          const portId = p.id;
-          if (!portId) {
-            return true;
-          }
-          return !entry.portsToRemove!.has(portId);
-        })
-      : [...currentPorts];
-
-    // Add/update ports
-    if (!entry.ports) {
-      return filteredPorts;
-    }
-
-    const mergedPorts = [...filteredPorts];
-    for (const [portId, portData] of entry.ports) {
-      const existingIndex = mergedPorts.findIndex((p) => p.id === portId);
-      if (existingIndex === -1) {
-        mergedPorts.push(portData);
-        continue;
-      }
-      mergedPorts[existingIndex] = portData;
-    }
-
-    return mergedPorts;
-  }
-
-  /**
-   * Merges port group updates into the current groups object.
-   * @param currentGroups - Current port groups object
-   * @param entry - Cache entry containing port updates
-   * @returns Merged port groups object
-   * @internal
-   */
-  private mergePortGroups(
-    currentGroups: Record<string, dia.Element.PortGroup> | undefined,
-    entry: PortUpdateCacheEntry
-  ): Record<string, dia.Element.PortGroup> {
-    const mergedGroups = { ...currentGroups };
-
-    // Remove groups
-    if (entry.groupsToRemove) {
-      for (const groupId of entry.groupsToRemove) {
-        if (groupId) {
-          // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
-          delete mergedGroups[groupId];
-        }
-      }
-    }
-
-    // Add/update groups
-    if (entry.groups) {
-      for (const [groupId, groupData] of entry.groups) {
-        mergedGroups[groupId] = groupData;
-      }
-    }
-
-    return mergedGroups;
-  }
-
-  /**
-   * Merges port updates into the current ports structure.
-   * @param currentPorts - Current port items array
-   * @param currentGroups - Current port groups object
-   * @param entry - Cache entry containing port updates
-   * @returns Merged ports and groups
-   * @internal
-   */
-  private mergePortUpdates(
-    currentPorts: dia.Element.Port[],
-    currentGroups: Record<string, dia.Element.PortGroup> | undefined,
-    entry: PortUpdateCacheEntry
-  ): {
-    ports: dia.Element.Port[];
-    groups: Record<string, dia.Element.PortGroup>;
-  } {
-    return {
-      ports: this.mergePortItems(currentPorts, entry),
-      groups: this.mergePortGroups(currentGroups, entry),
-    };
-  }
-
-  /**
-   * Flushes all cached port updates and returns cells to sync.
-   * Called automatically by the scheduler when updates are batched.
-   * @returns Array of cell JSON objects to sync
-   * @internal
-   */
-  private flushPortUpdates = (): dia.Cell.JSON[] => {
-    if (this.portUpdateCache.size === 0) {
-      return [];
-    }
-
-    // Build cells array for syncCells
-    const cellsToSync: dia.Cell.JSON[] = [];
-
-    for (const [elementId, entry] of this.portUpdateCache) {
-      const element = this.graph.getCell(elementId);
-      if (!element?.isElement()) {
-        continue;
-      }
-
-      // Get current ports structure from element
-      const currentPorts = element.get('ports') || {};
-      const currentPortItems = currentPorts.items || [];
-      const currentGroups = currentPorts.groups || {};
-
-      // Merge port updates
-      const { ports, groups } = this.mergePortUpdates(currentPortItems, currentGroups, entry);
-
-      // Build cell JSON with merged ports
-      // Use toJSON to get current state, then update ports
-      const cellJson = element.toJSON();
-
-      // Update ports in cellJson
-      cellJson.ports = {
-        items: ports,
-        groups,
-      };
-
-      cellsToSync.push(cellJson);
-    }
-
-    // Clear cache BEFORE sync to avoid re-triggering
-    this.portUpdateCache.clear();
-
-    return cellsToSync;
-  };
-
-  /**
-   * Flushes all cached graph updates (links, ports, and clearView) in a single pass.
-   * Called automatically by the unified scheduler when updates are batched.
-   * @internal
-   */
-  private flushGraphUpdates = () => {
-    const linkCells = this.flushLinkUpdates();
-    const portCells = this.flushPortUpdates();
-
-    // Combine all updates into single syncCells call for maximum efficiency
-    const allCells = [...linkCells, ...portCells];
-
-    if (allCells.length > 0) {
-      this.graph.syncCells(allCells, { remove: false });
-    }
-
-    // Flush clearView after syncCells to ensure ports are applied first
-    this.flushClearViewInternal();
-  };
-
-  /**
-   * Flushes graph updates immediately (synchronously).
-   * Used during initial render to ensure labels appear immediately with elements/links.
-   * @internal
-   */
-  private flushGraphUpdatesImmediate = () => {
-    // Execute all registered paper update callbacks
-    for (const callback of this.paperUpdateCallbacks) {
-      callback();
-    }
-    // Then flush graph updates (links, ports, and clearView)
-    this.flushGraphUpdates();
-  };
+  // --- Port API (uses BatchCache) ---
 
-  /**
-   * Flushes all pending graph updates synchronously.
-   * Call this from useLayoutEffect to ensure updates are applied before paint.
-   */
-  public flushPendingUpdates = () => {
-    if (
-      this.linkUpdateCache.size === 0 &&
-      this.portUpdateCache.size === 0 &&
-      this.clearViewCache.size === 0
-    ) {
-      return;
-    }
-    this.flushGraphUpdatesImmediate();
-  };
-
-  /**
-   * Sets or updates a port (from Port.Item component).
-   * Updates are batched and applied via syncCells for performance.
-   * @param elementId - The ID of the element containing the port
-   * @param portId - Unique identifier for the port
-   * @param portData - Port data to set
-   */
   public setPort = (elementId: dia.Cell.ID, portId: string, portData: dia.Element.Port) => {
-    const entry = this.portUpdateCache.get(elementId) ?? {};
-    entry.ports = entry.ports ?? new Map();
-    entry.ports.set(portId, portData);
-    this.portUpdateCache.set(elementId, entry);
-    this.graphUpdateScheduler();
+    this.portCache.update(elementId, (entry) => setPortEntry(entry, portId, portData));
   };
 
-  /**
-   * Removes a port (from Port.Item component unmount).
-   * Updates are batched and applied via syncCells for performance.
-   * @param elementId - The ID of the element containing the port
-   * @param portId - Unique identifier for the port to remove
-   */
   public removePort = (elementId: dia.Cell.ID, portId: string) => {
-    const entry = this.portUpdateCache.get(elementId) ?? {};
-    entry.portsToRemove = entry.portsToRemove ?? new Set();
-    entry.portsToRemove.add(portId);
-    this.portUpdateCache.set(elementId, entry);
-    this.graphUpdateScheduler();
+    this.portCache.update(elementId, (entry) => removePortEntry(entry, portId));
   };
 
-  /**
-   * Sets or updates a port group (from Port.Group component).
-   * Updates are batched and applied via syncCells for performance.
-   * @param elementId - The ID of the element containing the port group
-   * @param groupId - Unique identifier for the port group
-   * @param groupData - Port group data to set
-   */
   public setPortGroup = (
     elementId: dia.Cell.ID,
     groupId: string,
     groupData: dia.Element.PortGroup
   ) => {
-    const entry = this.portUpdateCache.get(elementId) ?? {};
-    entry.groups = entry.groups ?? new Map();
-    entry.groups.set(groupId, groupData);
-    this.portUpdateCache.set(elementId, entry);
-    this.graphUpdateScheduler();
+    this.portCache.update(elementId, (entry) => setPortGroupEntry(entry, groupId, groupData));
   };
 
-  /**
-   * Removes a port group (from Port.Group component unmount).
-   * Updates are batched and applied via syncCells for performance.
-   * @param elementId - The ID of the element containing the port group
-   * @param groupId - Unique identifier for the port group to remove
-   */
   public removePortGroup = (elementId: dia.Cell.ID, groupId: string) => {
-    const entry = this.portUpdateCache.get(elementId) ?? {};
-    entry.groupsToRemove = entry.groupsToRemove ?? new Set();
-    entry.groupsToRemove.add(groupId);
-    this.portUpdateCache.set(elementId, entry);
-    this.graphUpdateScheduler();
+    this.portCache.update(elementId, (entry) => removePortGroupEntry(entry, groupId));
   };
 
-  /**
-   * Registers a paper update callback to be executed during batch flush.
-   * Used by PaperStore to batch paper snapshot updates together with graph updates.
-   * @param callback - Callback function to execute during batch flush
-   * @returns Cleanup function to unregister the callback
-   * @internal
-   */
+  // --- Paper API ---
+
   public registerPaperUpdate = (callback: () => void): (() => void) => {
     this.paperUpdateCallbacks.add(callback);
-    return () => {
-      this.paperUpdateCallbacks.delete(callback);
-    };
+    return () => this.paperUpdateCallbacks.delete(callback);
   };
 
   /**
-   * Schedules a paper update to be batched with other updates.
-   * Triggers the unified scheduler which will execute all registered callbacks.
-   * @internal
+   * Schedules graph updates (link/port/clearView) via the single scheduler.
+   * Marks that graph updates need to be flushed in the next onFlush.
    */
-  public schedulePaperUpdate = () => {
-    this.graphUpdateScheduler();
+  private scheduleGraphUpdate = () => {
+    this.isGraphUpdateScheduled = true;
+    // Schedule an empty update to trigger onFlush
+    this.scheduler.scheduleData((data) => data);
   };
 
-  /**
-   * Schedules a clearView operation to be batched.
-   * Multiple calls for the same cell are deduplicated.
-   * If called multiple times for the same cell, the last onValidateLink wins.
-   * If any call has no onValidateLink (meaning "clear all"), that takes precedence.
-   * @param options - Options for the clearView operation
-   * @param options.cellId - The cell ID to clear
-   * @param options.onValidateLink - Optional callback to determine which links to keep
-   */
+  public schedulePaperUpdate = () => this.scheduleGraphUpdate();
+
+  // --- ClearView API ---
+
   public scheduleClearView = (options: {
     readonly cellId: dia.Cell.ID;
     readonly onValidateLink?: (link: dia.Link) => boolean;
   }) => {
-    const { cellId, onValidateLink } = options;
-    const existingEntry = this.clearViewCache.get(cellId);
-
-    // If no existing entry, create new one
-    if (!existingEntry) {
-      this.clearViewCache.set(cellId, { onValidateLink });
-      this.graphUpdateScheduler();
-      return;
-    }
-
-    // Merge strategy:
-    // - If new call has no validator (clear all links), remove any existing validator
-    // - If new call has a validator but existing doesn't, keep clearing all
-    // - If both have validators, the new validator should allow more links (union behavior)
-    if (!onValidateLink) {
-      // No validator means clear all links - this takes precedence
-      this.clearViewCache.set(cellId, { onValidateLink: undefined });
-    } else if (existingEntry.onValidateLink) {
-      // Both have validators - create union validator
-      const existingValidator = existingEntry.onValidateLink;
-      const newValidator = onValidateLink;
-      this.clearViewCache.set(cellId, {
-        onValidateLink: (link: dia.Link) => existingValidator(link) || newValidator(link),
-      });
-    }
-    // If existing has no validator but new does, keep existing (clear all)
-
-    this.graphUpdateScheduler();
+    // check clear-view.ts for more info
+    const existing = this.clearViewCache.get(options.cellId);
+    const merged = mergeClearViewValidators(existing, { onValidateLink: options.onValidateLink });
+    this.clearViewCache.set(options.cellId, merged);
+    this.scheduleGraphUpdate();
   };
 
-  /**
-   * Flushes all pending clearView operations synchronously.
-   * Call this from useLayoutEffect to ensure views are cleared before paint.
-   */
   public flushClearView = () => {
-    if (this.clearViewCache.size === 0) {
-      return;
-    }
+    if (this.clearViewCache.isEmpty) return;
     this.flushClearViewInternal();
   };
 
-  /**
-   * Internal method to flush clearView cache.
-   * @internal
-   */
-  private flushClearViewInternal = () => {
-    // Process each cell in the cache
-    for (const [cellId, entry] of this.clearViewCache) {
-      this.executeClearViewForCell(cellId, entry.onValidateLink);
-    }
-
-    // Clear cache after processing
-    this.clearViewCache.clear();
-  };
-
-  /**
-   * Executes clearView for a single cell.
-   * @internal
-   * @param cellId - The cell ID to clear
-   * @param onValidateLink - Optional callback to determine which links to keep
-   */
-  private executeClearViewForCell = (
-    cellId: dia.Cell.ID,
-    onValidateLink?: (link: dia.Link) => boolean
-  ) => {
-    // Get all papers and execute clearView on each
-    for (const paperStore of this.papers.values()) {
-      const { paper } = paperStore;
-      if (!paper) {
-        continue;
-      }
-
-      const elementView = paper.findViewByModel(cellId);
-      if (!elementView) {
-        continue;
-      }
-
-      elementView.cleanNodesCache();
-      this.clearConnectedLinkViews(paper, cellId, onValidateLink);
-    }
-  };
-
-  /**
-   * Clears the connected link views for a cell.
-   * @internal
-   * @param paper - The JointJS Paper instance
-   * @param cellId - The cell ID whose connected links to clear
-   * @param onValidateLink - Optional callback to determine which links to keep
-   */
-  private clearConnectedLinkViews = (
-    paper: dia.Paper,
-    cellId: dia.Cell.ID,
-    onValidateLink?: (link: dia.Link) => boolean
-  ) => {
-    const cell = this.graph.getCell(cellId);
-    if (!cell) {
-      return;
-    }
-
-    for (const link of this.graph.getConnectedLinks(cell)) {
-      if (!this.shouldClearLink(link, cellId, onValidateLink)) {
-        continue;
-      }
-
-      const linkView = link.findView(paper);
-      if (!linkView) {
-        continue;
-      }
-
-      // @ts-expect-error we use private jointjs api method
-      linkView._sourceMagnet = null;
-      // @ts-expect-error we use private jointjs api method
-      linkView._targetMagnet = null;
-      // @ts-expect-error we use private jointjs api method
-      linkView.requestConnectionUpdate({ async: false });
+  public flushPendingUpdates = () => {
+    if (this.portCache.isEmpty && this.clearViewCache.isEmpty) return;
+    for (const callback of this.paperUpdateCallbacks) {
+      callback();
     }
-  };
-
-  /**
-   * Determines if a link should be cleared.
-   * @internal
-   * @param link - The link to check
-   * @param cellId - The cell ID to check against
-   * @param onValidateLink - Optional callback to determine if link should be cleared
-   * @returns True if the link should be cleared
-   */
-  private shouldClearLink = (
-    link: dia.Link,
-    cellId: dia.Cell.ID,
-    onValidateLink?: (link: dia.Link) => boolean
-  ): boolean => {
-    const target = link.target();
-    const source = link.source();
-    const isElementLink = target.id === cellId || source.id === cellId;
-
-    return isElementLink && (!onValidateLink || onValidateLink(link));
+    this.flushGraphUpdates();
   };
 }
diff --git a/packages/joint-react/src/store/paper-store.ts b/packages/joint-react/src/store/paper-store.ts
index d5f5b0a54..5a33bbfa4 100644
--- a/packages/joint-react/src/store/paper-store.ts
+++ b/packages/joint-react/src/store/paper-store.ts
@@ -3,12 +3,9 @@ import type { OverWriteResult } from '../context';
 import type { RenderElement, RenderLink } from '../components';
 import type { GraphElement } from '../types/element-types';
 import type { GraphLink } from '../types/link-types';
-import type { ReactPaper } from '../types/paper.types';
+import type { ReactPaper as ReactPaperType } from '../types/paper.types';
 import type { GraphState, GraphStore } from './graph-store';
-import { REACT_TYPE } from '../models/react-element';
-import { ReactElementView } from '../models/react-element-view';
-import { ReactLinkView } from '../models/react-link-view';
-import { REACT_LINK_TYPE } from '../models/react-link';
+import { ReactPaper } from '../models/react-paper';
 
 const DEFAULT_CLICK_THRESHOLD = 10;
 export const PORTAL_SELECTOR = 'react-port-portal';
@@ -87,7 +84,7 @@ export interface PaperStoreSnapshot {
  */
 export class PaperStore {
   /** The underlying JointJS Paper instance with React-specific properties */
-  public paper: ReactPaper;
+  public paper: ReactPaper & ReactPaperType;
   /** Unique identifier for this paper instance */
   public paperId: string;
   /** Reference to the overwrite result if custom rendering is used */
@@ -147,40 +144,68 @@ export class PaperStore {
     // eslint-disable-next-line unicorn/no-this-assignment, @typescript-eslint/no-this-alias
     const store = this;
 
-    const reactCellVieOptions: Partial<dia.Paper.Options> = {};
-    if (renderElement !== undefined) {
-      reactCellVieOptions.elementView = (element) => {
-        if (element.get('type') === REACT_TYPE) {
-          return ReactElementView;
-        }
-        return null;
-      };
-    }
-    if (renderLink !== undefined) {
-      reactCellVieOptions.linkView = (link) => {
-        if (link.get('type') === REACT_LINK_TYPE) {
-          return ReactLinkView;
-        }
-        return null;
-      };
-    }
-
-    // Create a new JointJS Paper with the provided options
-    const paper = new dia.Paper({
+    // Create a new ReactPaper instance
+    // ReactPaper handles view lifecycle internally via insertView/removeView
+    const paper = new ReactPaper({
       async: true,
       sorting: dia.Paper.sorting.APPROX,
       preventDefaultBlankAction: false,
       frozen: true,
       model: graph,
-      ...reactCellVieOptions,
       // 👇 override to always allow connection
       validateConnection: () => true,
       // 👇 also, allow links to start or end on empty space
       validateMagnet: () => true,
+      // 👇 capture port elements after render for React portals
+      afterRender: (() => {
+        // Re-entrancy guard to prevent infinite loops
+        let isProcessing = false;
+        return () => {
+          if (isProcessing) {
+            return;
+          }
+          isProcessing = true;
+          try {
+            // Iterate through all element views and capture port elements
+            let hasPortsChanged = false;
+            for (const view of Object.values(cache.elementViews)) {
+              const portElementsCache = (
+                view as dia.ElementView & {
+                  _portElementsCache?: Record<string, PortElementsCacheEntry>;
+                }
+              )._portElementsCache;
+              if (!portElementsCache) {
+                continue;
+              }
+              const newPorts = store.getNewPorts({
+                state: graphStore.internalState,
+                cellId: view.model.id as dia.Cell.ID,
+                portElementsCache,
+                portsData: cache.portsData,
+              });
+              if (newPorts && newPorts !== cache.portsData) {
+                cache.portsData = newPorts;
+                hasPortsChanged = true;
+              }
+            }
+            // Only schedule update if ports actually changed
+            if (hasPortsChanged) {
+              graphStore.schedulePaperUpdate();
+            }
+          } finally {
+            isProcessing = false;
+          }
+        };
+      })(),
       ...paperOptions,
-      viewManagement: paperOptions.viewManagement ?? true,
       clickThreshold: paperOptions.clickThreshold ?? DEFAULT_CLICK_THRESHOLD,
-    }) as ReactPaper;
+      autoFreeze: true,
+      viewManagement: {
+        disposeHidden: true,
+        lazyInitialize: true,
+      },
+      graphStore,
+    }) as ReactPaper & ReactPaperType;
 
     // Attach React-specific properties to the paper for view access
     paper.reactElementCache = {
diff --git a/packages/joint-react/src/store/port-cache.ts b/packages/joint-react/src/store/port-cache.ts
new file mode 100644
index 000000000..463f25390
--- /dev/null
+++ b/packages/joint-react/src/store/port-cache.ts
@@ -0,0 +1,149 @@
+import type { dia } from '@joint/core';
+
+/**
+ * Cache entry for batched port updates.
+ */
+export interface PortUpdateCacheEntry {
+  /** Ports to add or update by port ID */
+  ports?: Map<string, dia.Element.Port>;
+  /** Port IDs to remove */
+  portsToRemove?: Set<string>;
+  /** Port groups to add or update by group ID */
+  groups?: Map<string, dia.Element.PortGroup>;
+  /** Port group IDs to remove */
+  groupsToRemove?: Set<string>;
+}
+
+/**
+ * Merges port item updates into the current ports array.
+ * @param currentPorts - Current port items array
+ * @param entry - Cache entry containing port updates
+ * @returns Merged port items array
+ */
+export function mergePortItems(
+  currentPorts: dia.Element.Port[],
+  entry: PortUpdateCacheEntry
+): dia.Element.Port[] {
+  // Start with current ports, filter out removed ones
+  const filteredPorts = entry.portsToRemove
+    ? currentPorts.filter((port) => {
+        const portId = port.id;
+        if (!portId) {
+          return true;
+        }
+        return !entry.portsToRemove!.has(portId);
+      })
+    : [...currentPorts];
+
+  // Add/update ports
+  if (!entry.ports) {
+    return filteredPorts;
+  }
+
+  const mergedPorts = [...filteredPorts];
+  for (const [portId, portData] of entry.ports) {
+    const existingIndex = mergedPorts.findIndex((port) => port.id === portId);
+    if (existingIndex === -1) {
+      mergedPorts.push(portData);
+      continue;
+    }
+    mergedPorts[existingIndex] = portData;
+  }
+
+  return mergedPorts;
+}
+
+/**
+ * Merges port group updates into the current groups object.
+ * @param currentGroups - Current port groups object
+ * @param entry - Cache entry containing port updates
+ * @returns Merged port groups object
+ */
+export function mergePortGroups(
+  currentGroups: Record<string, dia.Element.PortGroup> | undefined,
+  entry: PortUpdateCacheEntry
+): Record<string, dia.Element.PortGroup> {
+  const mergedGroups = { ...currentGroups };
+
+  // Remove groups
+  if (entry.groupsToRemove) {
+    for (const groupId of entry.groupsToRemove) {
+      if (groupId) {
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        delete mergedGroups[groupId];
+      }
+    }
+  }
+
+  // Add/update groups
+  if (entry.groups) {
+    for (const [groupId, groupData] of entry.groups) {
+      mergedGroups[groupId] = groupData;
+    }
+  }
+
+  return mergedGroups;
+}
+
+/**
+ * Merges port updates into the current ports structure.
+ * @param currentPorts - Current port items array
+ * @param currentGroups - Current port groups object
+ * @param entry - Cache entry containing port updates
+ * @returns Merged ports and groups
+ */
+export function mergePortUpdates(
+  currentPorts: dia.Element.Port[],
+  currentGroups: Record<string, dia.Element.PortGroup> | undefined,
+  entry: PortUpdateCacheEntry
+): {
+  readonly ports: dia.Element.Port[];
+  readonly groups: Record<string, dia.Element.PortGroup>;
+} {
+  return {
+    ports: mergePortItems(currentPorts, entry),
+    groups: mergePortGroups(currentGroups, entry),
+  };
+}
+
+/**
+ * Sets a port on a port cache entry.
+ * @param entry
+ * @param portId
+ * @param portData
+ */
+export function setPort(entry: PortUpdateCacheEntry, portId: string, portData: dia.Element.Port): void {
+  entry.ports = entry.ports ?? new Map();
+  entry.ports.set(portId, portData);
+}
+
+/**
+ * Marks a port for removal on a port cache entry.
+ * @param entry
+ * @param portId
+ */
+export function removePort(entry: PortUpdateCacheEntry, portId: string): void {
+  entry.portsToRemove = entry.portsToRemove ?? new Set();
+  entry.portsToRemove.add(portId);
+}
+
+/**
+ * Sets a port group on a port cache entry.
+ * @param entry
+ * @param groupId
+ * @param groupData
+ */
+export function setPortGroup(entry: PortUpdateCacheEntry, groupId: string, groupData: dia.Element.PortGroup): void {
+  entry.groups = entry.groups ?? new Map();
+  entry.groups.set(groupId, groupData);
+}
+
+/**
+ * Marks a port group for removal on a port cache entry.
+ * @param entry
+ * @param groupId
+ */
+export function removePortGroup(entry: PortUpdateCacheEntry, groupId: string): void {
+  entry.groupsToRemove = entry.groupsToRemove ?? new Set();
+  entry.groupsToRemove.add(groupId);
+}
diff --git a/packages/joint-react/src/store/state-flush.ts b/packages/joint-react/src/store/state-flush.ts
new file mode 100644
index 000000000..a69e89f63
--- /dev/null
+++ b/packages/joint-react/src/store/state-flush.ts
@@ -0,0 +1,193 @@
+/* eslint-disable sonarjs/cognitive-complexity */
+import type { dia } from '@joint/core';
+import { startTransition } from 'react';
+import type { GraphSchedulerData } from '../types/scheduler.types';
+import type { ExternalStoreLike, State } from '../utils/create-state';
+import type {
+  GraphStoreSnapshot,
+  GraphStoreLayoutSnapshot,
+  NodeLayout,
+  LinkLayout,
+} from './graph-store';
+import type { PaperStore } from './paper-store';
+
+/**
+ * GOLDEN RULE: All setState calls must happen through these flush functions.
+ * This module isolates state mutations to ensure they only happen in scheduler's onFlush.
+ *
+ * DO NOT call setState directly in graph-store.ts - use these functions instead.
+ */
+
+/**
+ * Flushes element updates to public state.
+ * Called from scheduler's onFlush callback.
+ * @param publicState - The public state store
+ * @param data - The scheduler data containing updates
+ */
+export function flushElements(
+  publicState: ExternalStoreLike<GraphStoreSnapshot>,
+  data: GraphSchedulerData
+): void {
+  if (!data.elementsToUpdate && !data.elementsToDelete) return;
+
+  publicState.setState((previous) => {
+    const elements = { ...previous.elements };
+    if (data.elementsToUpdate) {
+      for (const [id, element] of data.elementsToUpdate) {
+        elements[id] = element;
+      }
+    }
+    if (data.elementsToDelete) {
+      for (const id of data.elementsToDelete.keys()) {
+        Reflect.deleteProperty(elements, id);
+      }
+    }
+    return { ...previous, elements };
+  });
+}
+
+/**
+ * Flushes link updates to public state.
+ * Called from scheduler's onFlush callback.
+ * @param publicState - The public state store
+ * @param data - The scheduler data containing updates
+ */
+export function flushLinks(
+  publicState: ExternalStoreLike<GraphStoreSnapshot>,
+  data: GraphSchedulerData
+): void {
+  if (!data.linksToUpdate && !data.linksToDelete) return;
+
+  publicState.setState((previous) => {
+    const links = { ...previous.links };
+    if (data.linksToUpdate) {
+      for (const [id, link] of data.linksToUpdate) {
+        links[id] = link;
+      }
+    }
+    if (data.linksToDelete) {
+      for (const id of data.linksToDelete.keys()) {
+        Reflect.deleteProperty(links, id);
+      }
+    }
+    return { ...previous, links };
+  });
+}
+
+/**
+ * Options for flushing layout state.
+ */
+export interface FlushLayoutStateOptions {
+  readonly graph: dia.Graph;
+  readonly layoutState: State<GraphStoreLayoutSnapshot>;
+  readonly papers?: Map<string, PaperStore>;
+}
+
+/**
+ * Checks if two link layouts are equal.
+ * @param a - First link layout
+ * @param b - Second link layout
+ * @returns True if layouts are equal
+ */
+function isLinkLayoutEqual(a: LinkLayout | undefined, b: LinkLayout): boolean {
+  if (!a) return false;
+  return (
+    a.sourceX === b.sourceX &&
+    a.sourceY === b.sourceY &&
+    a.targetX === b.targetX &&
+    a.targetY === b.targetY &&
+    a.d === b.d
+  );
+}
+
+/**
+ * Flushes layout state updates (element layouts and per-paper link layouts).
+ * Called from scheduler's onFlush callback.
+ * @param options - The flush options
+ */
+export function flushLayoutState(options: FlushLayoutStateOptions): void {
+  const { graph, layoutState, papers } = options;
+  const elementLayouts: Record<dia.Cell.ID, NodeLayout> = {};
+  const linkLayoutsPerPaper: Record<string, Record<dia.Cell.ID, LinkLayout>> = {};
+  const elements = graph.getElements();
+  const previousSnapshot = layoutState.getSnapshot();
+  const previousElementLayouts = previousSnapshot.elements;
+  const previousLinkLayouts = previousSnapshot.links;
+
+  for (const element of elements) {
+    const size = element.get('size');
+    const position = element.get('position') ?? { x: 0, y: 0 };
+    const angle = element.get('angle') ?? 0;
+    if (!size) continue;
+
+    const newLayout: NodeLayout = {
+      x: position.x ?? 0,
+      y: position.y ?? 0,
+      width: size.width ?? 0,
+      height: size.height ?? 0,
+      angle,
+    };
+
+    const previousLayout = previousElementLayouts[element.id];
+    elementLayouts[element.id] =
+      previousLayout?.x === newLayout.x &&
+      previousLayout.y === newLayout.y &&
+      previousLayout.width === newLayout.width &&
+      previousLayout.height === newLayout.height &&
+      previousLayout.angle === newLayout.angle
+        ? previousLayout
+        : newLayout;
+  }
+
+  // Flush link layouts from each paper
+  if (papers) {
+    const links = graph.getLinks();
+    for (const paperStore of papers.values()) {
+      const { paper, paperId } = paperStore;
+      if (!paper) continue;
+
+      const paperLinkLayouts: Record<dia.Cell.ID, LinkLayout> = {};
+      const previousPaperLinkLayouts = previousLinkLayouts[paperId] ?? {};
+
+      for (const link of links) {
+        const linkView = paper.findViewByModel(link) as dia.LinkView | null;
+        if (!linkView) continue;
+
+        const sourcePoint = linkView.sourcePoint ?? { x: 0, y: 0 };
+        const targetPoint = linkView.targetPoint ?? { x: 0, y: 0 };
+        const d = linkView.getSerializedConnection?.() ?? '';
+
+        const newLinkLayout: LinkLayout = {
+          sourceX: sourcePoint.x,
+          sourceY: sourcePoint.y,
+          targetX: targetPoint.x,
+          targetY: targetPoint.y,
+          d,
+        };
+
+        const previousLinkLayout = previousPaperLinkLayouts[link.id];
+        paperLinkLayouts[link.id] = isLinkLayoutEqual(previousLinkLayout, newLinkLayout)
+          ? previousLinkLayout
+          : newLinkLayout;
+      }
+
+      linkLayoutsPerPaper[paperId] = paperLinkLayouts;
+    }
+  }
+
+  let areAllMeasured = Object.keys(elementLayouts).length > 0;
+  for (const layout of Object.values(elementLayouts)) {
+    if (layout.width <= 1 || layout.height <= 1) {
+      areAllMeasured = false;
+      break;
+    }
+  }
+
+  startTransition(() => {
+    layoutState.setState((previous) => ({
+      elements: elementLayouts,
+      links: linkLayoutsPerPaper,
+      wasEverMeasured: previous.wasEverMeasured || areAllMeasured,
+    }));
+  });
+}
diff --git a/packages/joint-react/src/stories/demos/flowchart/code.tsx b/packages/joint-react/src/stories/demos/flowchart/code.tsx
index 7904fed9c..07aa1d8e2 100644
--- a/packages/joint-react/src/stories/demos/flowchart/code.tsx
+++ b/packages/joint-react/src/stories/demos/flowchart/code.tsx
@@ -2,12 +2,7 @@
 /* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import './index.css';
 import type { GraphLink, RenderElement, TransformOptions } from '@joint/react';
-import {
-  GraphProvider,
-  Highlighter,
-  Paper,
-  useNodeSize,
-} from '@joint/react';
+import { GraphProvider, Highlighter, Paper, useNodeSize } from '@joint/react';
 import { PAPER_CLASSNAME, PRIMARY, SECONDARY } from 'storybook-config/theme';
 import { dia, linkTools } from '@joint/core';
 import { forwardRef, useRef, useState, type FC } from 'react';
@@ -15,86 +10,75 @@ import { forwardRef, useRef, useState, type FC } from 'react';
 const unit = 4;
 
 type NodeElement = {
-  id: string;
   label: string;
   type: 'start' | 'step' | 'decision';
   cx: number;
   cy: number;
 };
 
-const flowchartNodes: NodeElement[] = [
-  { id: 'start', label: 'Start', type: 'start', cx: 50, cy: 40 },
-  {
-    id: 'addToCart',
+const flowchartNodes: Record<string, NodeElement> = {
+  start: { label: 'Start', type: 'start', cx: 50, cy: 40 },
+  addToCart: {
     label: 'Add to Cart',
     type: 'step',
     cx: 200,
     cy: 40,
   },
-  {
-    id: 'checkoutItems',
+  checkoutItems: {
     label: 'Checkout Items',
     type: 'step',
     cx: 350,
     cy: 40,
   },
-  {
-    id: 'addShippingInfo',
+  addShippingInfo: {
     label: 'Add Shipping Info',
     type: 'step',
     cx: 500,
     cy: 40,
   },
-  {
-    id: 'addPaymentInfo',
+  addPaymentInfo: {
     label: 'Add Payment Info',
     type: 'step',
     cx: 500,
     cy: 140,
   },
-  {
-    id: 'validPayment',
+  validPayment: {
     label: 'Valid Payment?',
     type: 'decision',
     cx: 500,
     cy: 250,
   },
-  {
-    id: 'presentErrorMessage',
+  presentErrorMessage: {
     label: 'Present Error Message',
     type: 'step',
     cx: 750,
     cy: 350,
   },
-  {
-    id: 'sendOrder',
+  sendOrder: {
     label: 'Send Order to Warehouse',
     type: 'step',
     cx: 200,
     cy: 250,
   },
-  {
-    id: 'packOrder',
+  packOrder: {
     label: 'Pack Order',
     type: 'step',
     cx: 40,
     cy: 350,
   },
-  {
-    id: 'qualityCheck',
+  qualityCheck: {
     label: 'Quality Check?',
     type: 'decision',
     cx: 200,
     cy: 460,
   },
-  {
-    id: 'shipItems',
+  shipItems: {
     label: 'Ship Items to Customer',
     type: 'step',
     cx: 500,
     cy: 460,
   },
-];
+};
 const LINK_OPTIONS: Partial<GraphLink> = {
   z: 2,
   attrs: {
@@ -139,56 +123,51 @@ const LINK_OPTIONS: Partial<GraphLink> = {
 };
 type FlowchartLink = GraphLink & { label?: string };
 
-const flowchartLinks: FlowchartLink[] = [
-  { ...LINK_OPTIONS, id: 'flow1', source: 'start', target: 'addToCart' },
-  { ...LINK_OPTIONS, id: 'flow2', source: 'addToCart', target: 'checkoutItems' },
-  { ...LINK_OPTIONS, id: 'flow3', source: 'checkoutItems', target: 'addShippingInfo' },
-  { ...LINK_OPTIONS, id: 'flow4', source: 'addShippingInfo', target: 'addPaymentInfo' },
-  { ...LINK_OPTIONS, id: 'flow5', source: 'addPaymentInfo', target: 'validPayment' },
-  {
+const flowchartLinks: Record<string, FlowchartLink> = {
+  flow1: { ...LINK_OPTIONS, source: 'start', target: 'addToCart' },
+  flow2: { ...LINK_OPTIONS, source: 'addToCart', target: 'checkoutItems' },
+  flow3: { ...LINK_OPTIONS, source: 'checkoutItems', target: 'addShippingInfo' },
+  flow4: { ...LINK_OPTIONS, source: 'addShippingInfo', target: 'addPaymentInfo' },
+  flow5: { ...LINK_OPTIONS, source: 'addPaymentInfo', target: 'validPayment' },
+  flow6: {
     ...LINK_OPTIONS,
-    id: 'flow6',
     source: 'validPayment',
     target: 'presentErrorMessage',
     label: 'No',
   },
-  {
+  flow7: {
     ...LINK_OPTIONS,
-    id: 'flow7',
     source: 'presentErrorMessage',
     target: 'addPaymentInfo',
   },
-  {
+  flow8: {
     ...LINK_OPTIONS,
-    id: 'flow8',
     source: 'validPayment',
     target: 'sendOrder',
     label: 'Yes',
   },
-  { ...LINK_OPTIONS, id: 'flow9', source: 'sendOrder', target: 'packOrder' },
-  { ...LINK_OPTIONS, id: 'flow10', source: 'packOrder', target: 'qualityCheck' },
-  {
+  flow9: { ...LINK_OPTIONS, source: 'sendOrder', target: 'packOrder' },
+  flow10: { ...LINK_OPTIONS, source: 'packOrder', target: 'qualityCheck' },
+  flow11: {
     ...LINK_OPTIONS,
-    id: 'flow11',
     source: 'qualityCheck',
     target: 'shipItems',
     label: 'Ok',
   },
-  {
+  flow12: {
     ...LINK_OPTIONS,
-    id: 'flow12',
     source: 'qualityCheck',
     target: 'sendOrder',
     label: 'Not Ok',
   },
-];
+};
 
 interface PropsWithClick {
   readonly onMouseEnter?: () => void;
   readonly onMouseLeave?: () => void;
   readonly isToolActive?: boolean;
 }
-type FlowchartNodeProps = (typeof flowchartNodes)[number] & PropsWithClick;
+type FlowchartNodeProps = (typeof flowchartNodes)[string] & PropsWithClick;
 
 function transform(options: TransformOptions & { padding: number; cx: number; cy: number }) {
   const { width: nodeWidth, height: nodeHeight, padding, cx, cy } = options;
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 636324d32..e837ec349 100644
--- a/packages/joint-react/src/stories/demos/introduction-demo/code.tsx
+++ b/packages/joint-react/src/stories/demos/introduction-demo/code.tsx
@@ -1,4 +1,4 @@
-/* eslint-disable prefer-destructuring */
+ 
 /* eslint-disable @typescript-eslint/no-shadow */
 /* eslint-disable no-shadow */
 /* eslint-disable @eslint-react/no-array-index-key */
@@ -76,10 +76,9 @@ const PAPER_PROPS: PaperProps<Element> = {
   onLinkMouseLeave: ({ linkView }) => linkView.removeTools(),
 };
 
-// Create initial elements and links with typing support
-const elements: Element[] = [
-  {
-    id: '1',
+// Create initial elements and links with typing support as Records
+const elements: Record<string, Element> = {
+  '1': {
     x: 50,
     y: 110,
     elementType: 'alert',
@@ -87,8 +86,7 @@ const elements: Element[] = [
     description: 'This is longer text, it can be any message provided by the user',
     inputText: 'Node Text',
   },
-  {
-    id: '2',
+  '2': {
     x: 550,
     y: 110,
     elementType: 'info',
@@ -96,8 +94,7 @@ const elements: Element[] = [
     description: 'This is longer text, it can be any message provided by the user',
     inputText: '',
   },
-  {
-    id: '3',
+  '3': {
     x: 50,
     y: 370,
     elementType: 'table',
@@ -115,12 +112,11 @@ const elements: Element[] = [
       },
     },
   },
-];
+};
 
-// Create initial links from table element port to another element
-const links: GraphLink[] = [
-  {
-    id: 'link2',
+// Create initial links from table element port to another element as Record
+const links: Record<string, GraphLink> = {
+  'link2': {
     source: { id: '3', port: 'out-3-0' }, // Port from table element
     target: { id: '1' },
     attrs: {
@@ -135,7 +131,7 @@ const links: GraphLink[] = [
       },
     },
   },
-];
+};
 
 // Define the message component
 function MessageComponent({
@@ -485,7 +481,7 @@ function Main() {
           {...PAPER_PROPS}
           defaultLink={() => {
             // eslint-disable-next-line @typescript-eslint/no-unused-vars
-            const { id, ...rest } = links[0];
+            const { id, ...rest } = links['link2'];
             return new shapes.standard.Link(rest as shapes.standard.LinkAttributes);
           }}
           width="100%"
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 1868bfd3b..60d9e3cfd 100644
--- a/packages/joint-react/src/stories/demos/pulsing-port/code.tsx
+++ b/packages/joint-react/src/stories/demos/pulsing-port/code.tsx
@@ -14,6 +14,7 @@ import {
   TextNode,
   useLinks,
   useNodeSize,
+  useCellId,
 } from '@joint/react';
 
 const NODE_WIDTH = 150;
@@ -68,9 +69,8 @@ type Element = GraphElement & {
   };
 };
 
-const elements: Element[] = [
-  {
-    id: '1',
+const elements: Record<string, Element> = {
+  '1': {
     x: 50,
     y: 50,
     attrs: {
@@ -79,8 +79,7 @@ const elements: Element[] = [
       },
     },
   },
-  {
-    id: '2',
+  '2': {
     x: 350,
     y: 50,
     attrs: {
@@ -89,8 +88,7 @@ const elements: Element[] = [
       },
     },
   },
-  {
-    id: '3',
+  '3': {
     x: 150,
     y: 250,
     attrs: {
@@ -99,20 +97,19 @@ const elements: Element[] = [
       },
     },
   },
-];
+};
 
-function NodeElement({ id }: Element) {
+function NodeElement(_props: Element) {
+  const id = useCellId();
   const rectRef = useRef<SVGRectElement>(null);
   const { width, height } = useNodeSize(rectRef);
 
   const isConnected = useLinks((links) =>
-    links
-      .map((link) => {
-        const sourceId = getCellId(link.source);
-        const targetId = getCellId(link.target);
-        return sourceId === id || targetId === id;
-      })
-      .includes(true)
+    Object.values(links).some((link) => {
+      const sourceId = getCellId(link.source);
+      const targetId = getCellId(link.target);
+      return sourceId === id || targetId === id;
+    })
   );
 
   return (
diff --git a/packages/joint-react/src/stories/demos/user-flow/code.tsx b/packages/joint-react/src/stories/demos/user-flow/code.tsx
index 72fb48957..dc92f87a5 100644
--- a/packages/joint-react/src/stories/demos/user-flow/code.tsx
+++ b/packages/joint-react/src/stories/demos/user-flow/code.tsx
@@ -8,12 +8,12 @@ import { useCallback, useState } from 'react';
 import { HTMLNode } from 'storybook-config/decorators/with-simple-data';
 
 type NodeType = {
-  id: string;
   title: string;
   description: string;
   nodeType: 'user-action' | 'entity' | 'confirm' | 'message';
   x: number;
   y: number;
+
   attrs?: {
     root?: {
       magnet?: boolean;
@@ -21,35 +21,34 @@ type NodeType = {
   };
 };
 
-const nodes: NodeType[] = [
-  {
-    id: '1',
+const nodes: Record<string, NodeType> = {
+  '1': {
     title: 'User Action',
     description: 'Transfer funds',
     nodeType: 'user-action',
     x: 50,
     y: 50,
+
     attrs: {
       root: {
         magnet: false,
       },
     },
   },
-  {
-    id: '2',
+  '2': {
     title: 'Entity',
     description: 'Transfer funds',
     nodeType: 'entity',
     x: 120,
     y: 200,
+
     attrs: {
       root: {
         magnet: false,
       },
     },
   },
-  {
-    id: '3',
+  '3': {
     title: 'User Action',
     description: 'Get account balance',
     nodeType: 'user-action',
@@ -61,25 +60,22 @@ const nodes: NodeType[] = [
     x: 190,
     y: 350,
   },
-];
+};
 
-const links: GraphLink[] = [
-  {
-    id: 'link1',
+const links: Record<string, GraphLink> = {
+  link1: {
     source: { id: '1', port: '1' },
     target: { id: '2', port: 'in' },
   },
-  {
-    id: 'link2',
+  link2: {
     source: { id: '2', port: '1' },
     target: { id: '3', port: 'in' },
   },
-  {
-    id: 'link3',
+  link3: {
     source: { id: '3', port: '2' },
     target: { id: '1', port: 'in' },
   },
-];
+};
 
 interface PortProps {
   id: string;
diff --git a/packages/joint-react/src/stories/examples/stress/code.tsx b/packages/joint-react/src/stories/examples/stress/code.tsx
index dbdd76dad..b3039c60f 100644
--- a/packages/joint-react/src/stories/examples/stress/code.tsx
+++ b/packages/joint-react/src/stories/examples/stress/code.tsx
@@ -1,22 +1,39 @@
-/* eslint-disable sonarjs/no-nested-functions */
 /* eslint-disable sonarjs/pseudo-random */
 /* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import {
   GraphProvider,
-  Link,
   Paper,
+  useLinkLayout,
   type GraphElement,
   type GraphLink,
   type RenderLink,
 } from '@joint/react';
 import '../index.css';
 import React, { useCallback, useRef, useState, startTransition, memo } from 'react';
-import { PAPER_CLASSNAME, PRIMARY, LIGHT, SECONDARY } from 'storybook-config/theme';
+import { PAPER_CLASSNAME, PRIMARY, LIGHT } from 'storybook-config/theme';
 import { REACT_LINK_TYPE } from '../../../models/react-link';
 
 function initialElements(xNodes = 15, yNodes = 30) {
-  const nodes = [];
-  const edges = [];
+  const nodes: Record<
+    string,
+    {
+      width: number;
+      height: number;
+      fontSize: number;
+      label: string;
+      x: number;
+      y: number;
+    }
+  > = {};
+  const edges: Record<
+    string,
+    {
+      type: string;
+      source: string;
+      target: string;
+      z: number;
+    }
+  > = {};
   let nodeId = 1;
   let edgeId = 1;
   let recentNodeId: number | null = null;
@@ -25,24 +42,24 @@ function initialElements(xNodes = 15, yNodes = 30) {
     for (let x = 0; x < xNodes; x++) {
       const position = { x: x * 100, y: y * 50 };
       const data = { label: `Node ${nodeId}` };
+      const id = `stress-${nodeId.toString()}`;
       const node = {
-        id: `stress-${nodeId.toString()}`,
         width: 50,
         height: 20,
         fontSize: 11,
         ...data,
         ...position,
       };
-      nodes.push(node);
+      nodes[id] = node;
 
       if (recentNodeId !== null && nodeId <= xNodes * yNodes) {
-        edges.push({
-          id: `edge-${edgeId.toString()}`,
+        const edgeIdString = `edge-${edgeId.toString()}`;
+        edges[edgeIdString] = {
           type: REACT_LINK_TYPE,
           source: `stress-${recentNodeId.toString()}`,
           target: `stress-${nodeId.toString()}`,
           z: -1,
-        });
+        };
         edgeId++;
       }
 
@@ -56,7 +73,7 @@ function initialElements(xNodes = 15, yNodes = 30) {
 
 const { nodes: initialNodes, edges: initialEdges } = initialElements(15, 30);
 
-type BaseElementWithData = (typeof initialNodes)[number];
+type BaseElementWithData = (typeof initialNodes)[string];
 
 const RenderElement = memo(function RenderElement({
   width,
@@ -77,10 +94,16 @@ const RenderElement = memo(function RenderElement({
   );
 });
 
+function StressLinkPath() {
+  const layout = useLinkLayout();
+  if (!layout) return null;
+  return <path d={layout.d} stroke={LIGHT} strokeWidth={0.5} fill="none" />;
+}
+
 function Main({
   setElements,
 }: Readonly<{
-  setElements: React.Dispatch<React.SetStateAction<GraphElement[]>>;
+  setElements: React.Dispatch<React.SetStateAction<Record<string, GraphElement>>>;
 }>) {
   // Memoize the renderElement function to prevent unnecessary re-renders
   const renderElement = useCallback(
@@ -88,41 +111,21 @@ function Main({
     []
   );
 
-  const renderLink: RenderLink = useCallback(
-    (link) => (
-      <>
-        <Link.Base stroke={LIGHT} strokeWidth={0.5} />
-        <Link.Label position={{ distance: 0.5 }}>
-          <foreignObject x={-20} y={-8} width={40} height={16}>
-            <div
-              className="flex items-center justify-center rounded text-xs"
-              style={{
-                background: SECONDARY,
-                color: '#ffffff',
-                fontSize: 9,
-                width: 40,
-                height: 16,
-              }}
-            >
-              {link.id.toString().split('-')[1]}
-            </div>
-          </foreignObject>
-        </Link.Label>
-      </>
-    ),
-    []
-  );
+  const renderLink: RenderLink = useCallback(() => <StressLinkPath />, []);
 
   const updatePos = useCallback(() => {
     // Use startTransition to mark this as a non-urgent update
     // This allows React to keep the UI responsive during the update
     startTransition(() => {
       setElements((previousElements) => {
-        const newElements = previousElements.map((node) => ({
-          ...node,
-          x: Math.random() * 1500,
-          y: Math.random() * 1500,
-        }));
+        const newElements: Record<string, GraphElement> = {};
+        for (const [id, node] of Object.entries(previousElements)) {
+          newElements[id] = {
+            ...node,
+            x: Math.random() * 1500,
+            y: Math.random() * 1500,
+          };
+        }
 
         return newElements;
       });
@@ -153,8 +156,8 @@ function Main({
 }
 
 export default function App() {
-  const [elements, setElements] = useState<GraphElement[]>(initialNodes);
-  const [links, setLinks] = useState<GraphLink[]>(initialEdges);
+  const [elements, setElements] = useState<Record<string, GraphElement>>(initialNodes);
+  const [links, setLinks] = useState<Record<string, GraphLink>>(initialEdges);
 
   return (
     <GraphProvider
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 7926ed0f2..bb7f5990b 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
@@ -17,19 +17,19 @@ import type { dia } from '@joint/core';
 import { PAPER_CLASSNAME } from 'storybook-config/theme';
 import { useCellActions } from '../../../hooks/use-cell-actions';
 
-const initialElements = [
-  { id: '1', label: 'Node 1', width: 100, height: 50 },
-  { id: '2', label: 'Node 2', width: 100, height: 50 },
-  { id: '3', label: 'Node 3', width: 100, height: 50 },
-  { id: '4', label: 'Node 4', width: 100, height: 50 },
-  { id: '5', label: 'Node 5', width: 100, height: 50 },
-  { id: '6', label: 'Node 6', width: 100, height: 50 },
-  { id: '7', label: 'Node 7', width: 100, height: 50 },
-  { id: '8', label: 'Node 8', width: 100, height: 50 },
-  { id: '9', label: 'Node 9', width: 100, height: 50 },
-];
+const initialElements: Record<string, { label: string; width: number; height: number }> = {
+  '1': { label: 'Node 1', width: 100, height: 50 },
+  '2': { label: 'Node 2', width: 100, height: 50 },
+  '3': { label: 'Node 3', width: 100, height: 50 },
+  '4': { label: 'Node 4', width: 100, height: 50 },
+  '5': { label: 'Node 5', width: 100, height: 50 },
+  '6': { label: 'Node 6', width: 100, height: 50 },
+  '7': { label: 'Node 7', width: 100, height: 50 },
+  '8': { label: 'Node 8', width: 100, height: 50 },
+  '9': { label: 'Node 9', width: 100, height: 50 },
+};
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
 const INPUT_CLASSNAME =
   'block w-15 mr-2 p-2 text-gray-900 border border-gray-300 rounded-lg bg-gray-50 text-xs focus:ring-blue-500 focus:border-blue-500 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-blue-500 dark:focus:border-blue-500';
@@ -84,7 +84,7 @@ function Main() {
     [makeLayoutWithGrid, gridXSize]
   );
 
-  const elementsLength = useElements((items) => items.length);
+  const elementsLength = useElements((items) => Object.keys(items).length);
   return (
     <div className="flex flex-col">
       <div className="mb-8 flex flex-row items-center">
@@ -106,8 +106,8 @@ function Main() {
 
         <button
           onClick={() => {
-            set({
-              id: `${Math.random()}`,
+            const newId = `${Math.random()}`;
+            set(newId, {
               label: `Node ${elementsLength + 1}`,
               height: 0, // we recompute the size after the element is added
               width: 0, // we recompute the size after the element is added
diff --git a/packages/joint-react/src/stories/examples/with-build-in-shapes/code.tsx b/packages/joint-react/src/stories/examples/with-build-in-shapes/code.tsx
index 306e740f3..eb81ad444 100644
--- a/packages/joint-react/src/stories/examples/with-build-in-shapes/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-build-in-shapes/code.tsx
@@ -41,10 +41,9 @@ const mapDataToLinkAttributes = ({
 
 const SECONDARY = '#6366f1';
 
-const initialElements: NativeElement[] = [
+const initialElements: Record<string, NativeElement> = {
   // Row 1: Basic shapes
-  {
-    id: 'rectangle',
+  'rectangle': {
     x: 20,
     y: 20,
     width: 100,
@@ -55,8 +54,7 @@ const initialElements: NativeElement[] = [
       label: { text: 'Rectangle', fill: 'white' },
     },
   },
-  {
-    id: 'circle',
+  'circle': {
     x: 150,
     y: 20,
     width: 60,
@@ -67,8 +65,7 @@ const initialElements: NativeElement[] = [
       label: { text: 'Circle', fill: 'white' },
     },
   },
-  {
-    id: 'ellipse',
+  'ellipse': {
     x: 240,
     y: 20,
     width: 100,
@@ -79,8 +76,7 @@ const initialElements: NativeElement[] = [
       label: { text: 'Ellipse', fill: 'white' },
     },
   },
-  {
-    id: 'cylinder',
+  'cylinder': {
     x: 370,
     y: 10,
     width: 60,
@@ -92,8 +88,7 @@ const initialElements: NativeElement[] = [
     },
   },
   // Row 2: Path shapes
-  {
-    id: 'path',
+  'path': {
     x: 20,
     y: 110,
     width: 80,
@@ -107,8 +102,7 @@ const initialElements: NativeElement[] = [
       label: { text: 'Path', fill: 'white' },
     },
   },
-  {
-    id: 'polygon',
+  'polygon': {
     x: 130,
     y: 110,
     width: 80,
@@ -122,8 +116,7 @@ const initialElements: NativeElement[] = [
       label: { text: 'Polygon', fill: 'white' },
     },
   },
-  {
-    id: 'polyline',
+  'polyline': {
     x: 240,
     y: 110,
     width: 100,
@@ -139,8 +132,7 @@ const initialElements: NativeElement[] = [
       label: { text: 'Polyline', y: 70, fill: 'white' },
     },
   },
-  {
-    id: 'textblock',
+  'textblock': {
     x: 370,
     y: 110,
     width: 100,
@@ -152,8 +144,7 @@ const initialElements: NativeElement[] = [
     },
   },
   // Row 3: Headered and Image shapes
-  {
-    id: 'headered',
+  'headered': {
     x: 20,
     y: 220,
     width: 120,
@@ -166,8 +157,7 @@ const initialElements: NativeElement[] = [
       bodyText: { text: 'Body', fill: '#374151' },
     },
   },
-  {
-    id: 'image',
+  'image': {
     x: 170,
     y: 220,
     width: 60,
@@ -180,8 +170,7 @@ const initialElements: NativeElement[] = [
       label: { text: 'Image', fill: 'white' },
     },
   },
-  {
-    id: 'bordered-image',
+  'bordered-image': {
     x: 260,
     y: 220,
     width: 70,
@@ -195,8 +184,7 @@ const initialElements: NativeElement[] = [
       label: { text: 'Bordered', fill: 'white' },
     },
   },
-  {
-    id: 'embedded-image',
+  'embedded-image': {
     x: 360,
     y: 220,
     width: 100,
@@ -211,8 +199,7 @@ const initialElements: NativeElement[] = [
     },
   },
   // Row 4: More shapes and link targets
-  {
-    id: 'inscribed-image',
+  'inscribed-image': {
     x: 20,
     y: 330,
     width: 70,
@@ -227,8 +214,7 @@ const initialElements: NativeElement[] = [
       label: { text: 'Inscribed', fill: 'white' },
     },
   },
-  {
-    id: 'link-source',
+  'link-source': {
     x: 150,
     y: 350,
     width: 80,
@@ -239,8 +225,7 @@ const initialElements: NativeElement[] = [
       label: { text: 'Source', fill: 'white' },
     },
   },
-  {
-    id: 'link-target-1',
+  'link-target-1': {
     x: 350,
     y: 320,
     width: 80,
@@ -251,8 +236,7 @@ const initialElements: NativeElement[] = [
       label: { text: 'Target 1', fill: 'white' },
     },
   },
-  {
-    id: 'link-target-2',
+  'link-target-2': {
     x: 350,
     y: 420,
     width: 80,
@@ -263,8 +247,7 @@ const initialElements: NativeElement[] = [
       label: { text: 'Target 2', fill: 'white' },
     },
   },
-  {
-    id: 'link-target-3',
+  'link-target-3': {
     x: 520,
     y: 320,
     width: 80,
@@ -275,11 +258,10 @@ const initialElements: NativeElement[] = [
       label: { text: 'Target 3', fill: 'white' },
     },
   },
-];
+};
 
-const initialLinks: NativeLink[] = [
-  {
-    id: 'link-standard',
+const initialLinks: Record<string, NativeLink> = {
+  'link-standard': {
     source: 'link-source',
     target: 'link-target-1',
     type: 'standard.Link',
@@ -288,8 +270,7 @@ const initialLinks: NativeLink[] = [
     },
     labels: [{ attrs: { text: { text: 'Link' } } }],
   },
-  {
-    id: 'link-double',
+  'link-double': {
     source: 'link-source',
     target: 'link-target-2',
     type: 'standard.DoubleLink',
@@ -299,8 +280,7 @@ const initialLinks: NativeLink[] = [
     },
     labels: [{ attrs: { text: { text: 'DoubleLink' } } }],
   },
-  {
-    id: 'link-shadow',
+  'link-shadow': {
     source: 'link-target-1',
     target: 'link-target-3',
     type: 'standard.ShadowLink',
@@ -310,7 +290,7 @@ const initialLinks: NativeLink[] = [
     },
     labels: [{ attrs: { text: { text: 'ShadowLink' } } }],
   },
-];
+};
 
 function Main() {
   return (
diff --git a/packages/joint-react/src/stories/examples/with-card/code.tsx b/packages/joint-react/src/stories/examples/with-card/code.tsx
index 5ccdb4c0a..5896a485f 100644
--- a/packages/joint-react/src/stories/examples/with-card/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-card/code.tsx
@@ -11,14 +11,13 @@ import {
 } from '@joint/react';
 import { PAPER_CLASSNAME, PRIMARY } from 'storybook-config/theme';
 
-const initialElements = [
-  { id: '1', label: 'Node 1', x: 100, y: 0 },
-  { id: '2', label: 'Node 2 with longer text', x: 250, y: 150 },
-];
+const initialElements: Record<string, { label: string; x: number; y: number }> = {
+  '1': { label: 'Node 1', x: 100, y: 0 },
+  '2': { label: 'Node 2 with longer text', x: 250, y: 150 },
+};
 
-const initialEdges: GraphLink[] = [
-  {
-    id: 'e1-2',
+const initialEdges: Record<string, GraphLink> = {
+  'e1-2': {
     source: '1',
     target: '2',
     attrs: {
@@ -27,9 +26,9 @@ const initialEdges: GraphLink[] = [
       },
     },
   },
-];
+};
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
 function Card({ label }: Readonly<Partial<BaseElementWithData>>) {
   const contentRef = useRef<HTMLDivElement>(null);
diff --git a/packages/joint-react/src/stories/examples/with-cell-actions/code.tsx b/packages/joint-react/src/stories/examples/with-cell-actions/code.tsx
new file mode 100644
index 000000000..9c491e9be
--- /dev/null
+++ b/packages/joint-react/src/stories/examples/with-cell-actions/code.tsx
@@ -0,0 +1,533 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
+/* eslint-disable react-perf/jsx-no-new-function-as-prop */
+import { useRef, useState } from 'react';
+import {
+  GraphProvider,
+  Paper,
+  useCellActions,
+  useElements,
+  useLinks,
+  useNodeLayout,
+  useNodeSize,
+  type GraphElement,
+  type GraphLink,
+} from '@joint/react';
+import '../index.css';
+import { PAPER_CLASSNAME, PRIMARY, LIGHT } from 'storybook-config/theme';
+
+const SECONDARY = '#6366f1';
+
+interface NodeData extends GraphElement {
+  readonly label: string;
+  readonly color: string;
+}
+
+const initialElements: Record<string, NodeData> = {
+  '1': { label: 'Node A', color: PRIMARY, x: 50, y: 50, width: 120, height: 60 },
+  '2': { label: 'Node B', color: SECONDARY, x: 250, y: 50, width: 120, height: 60 },
+  '3': { label: 'Node C', color: PRIMARY, x: 150, y: 180, width: 120, height: 60 },
+};
+
+const initialLinks: Record<string, GraphLink> = {
+  'link-1-2': {
+    source: '1',
+    target: '2',
+    attrs: { line: { stroke: LIGHT } },
+  },
+  'link-1-3': {
+    source: '1',
+    target: '3',
+    attrs: { line: { stroke: LIGHT } },
+  },
+};
+
+// --- Node Component ---
+
+function RenderElement({ label, color }: Readonly<NodeData>) {
+  const elementRef = useRef<HTMLDivElement>(null);
+  const { width, height } = useNodeSize(elementRef);
+
+  return (
+    <foreignObject width={width} height={height}>
+      <div
+        ref={elementRef}
+        style={{
+          backgroundColor: color,
+          borderRadius: 8,
+          padding: '12px 16px',
+          color: 'white',
+          fontWeight: 500,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          boxShadow: '0 2px 8px rgba(0,0,0,0.15)',
+          minWidth: 80,
+          minHeight: 40,
+        }}
+      >
+        {label}
+      </div>
+    </foreignObject>
+  );
+}
+
+// --- Control Panel Components ---
+
+interface ElementControlsProps {
+  readonly id: string;
+  readonly element: NodeData;
+}
+
+function ElementControls({ id, element }: Readonly<ElementControlsProps>) {
+  const { set, remove } = useCellActions<NodeData>();
+  const layout = useNodeLayout(id);
+
+  const inputStyle = {
+    padding: '6px 10px',
+    border: '1px solid rgba(0, 0, 0, 0.15)',
+    borderRadius: 8,
+    fontSize: 12,
+    backgroundColor: 'rgba(255, 255, 255, 0.9)',
+    color: '#1f2937',
+    outline: 'none',
+    transition: 'border-color 0.15s, box-shadow 0.15s',
+  };
+
+  return (
+    <div
+      style={{
+        padding: '12px 16px',
+        borderBottom: '1px solid rgba(0, 0, 0, 0.06)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 10,
+      }}
+    >
+      <div style={{ fontWeight: 600, color: '#1f2937', fontSize: 13 }}>
+        {element.label}
+        <span style={{ fontWeight: 400, color: '#9ca3af', marginLeft: 6, fontSize: 11 }}>#{id}</span>
+      </div>
+
+      {/* Label */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+        <label style={{ width: 45, fontSize: 11, color: '#6b7280', fontWeight: 500 }}>Label</label>
+        <input
+          type="text"
+          value={element.label}
+          onChange={(event) => set(id, (previous) => ({ ...previous, label: event.target.value }))}
+          style={{ ...inputStyle, flex: 1 }}
+        />
+      </div>
+
+      {/* Color */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+        <label style={{ width: 45, fontSize: 11, color: '#6b7280', fontWeight: 500 }}>Color</label>
+        <input
+          type="color"
+          value={element.color}
+          onChange={(event) => set(id, (previous) => ({ ...previous, color: event.target.value }))}
+          style={{ width: 36, height: 28, border: 'none', cursor: 'pointer', borderRadius: 6, padding: 0 }}
+        />
+      </div>
+
+      {/* Position */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+        <label style={{ width: 45, fontSize: 11, color: '#6b7280', fontWeight: 500 }}>Pos</label>
+        <input
+          type="number"
+          value={layout?.x ?? element.x}
+          onChange={(event) => set(id, (previous) => ({ ...previous, x: Number(event.target.value) }))}
+          style={{ ...inputStyle, width: 65 }}
+          placeholder="X"
+        />
+        <input
+          type="number"
+          value={layout?.y ?? element.y}
+          onChange={(event) => set(id, (previous) => ({ ...previous, y: Number(event.target.value) }))}
+          style={{ ...inputStyle, width: 65 }}
+          placeholder="Y"
+        />
+      </div>
+
+      {/* Size */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+        <label style={{ width: 45, fontSize: 11, color: '#6b7280', fontWeight: 500 }}>Size</label>
+        <input
+          type="number"
+          value={layout?.width ?? element.width}
+          onChange={(event) => set(id, (previous) => ({ ...previous, width: Number(event.target.value) }))}
+          style={{ ...inputStyle, width: 65 }}
+          placeholder="W"
+        />
+        <input
+          type="number"
+          value={layout?.height ?? element.height}
+          onChange={(event) => set(id, (previous) => ({ ...previous, height: Number(event.target.value) }))}
+          style={{ ...inputStyle, width: 65 }}
+          placeholder="H"
+        />
+      </div>
+
+      {/* Angle */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+        <label style={{ width: 45, fontSize: 11, color: '#6b7280', fontWeight: 500 }}>Angle</label>
+        <input
+          type="range"
+          min="0"
+          max="360"
+          value={layout?.angle ?? 0}
+          onChange={(event) => set(id, (previous) => ({ ...previous, angle: Number(event.target.value) }))}
+          style={{ flex: 1, accentColor: PRIMARY }}
+        />
+        <span style={{ fontSize: 11, width: 32, color: '#6b7280' }}>{layout?.angle ?? 0}°</span>
+      </div>
+
+      {/* Remove */}
+      <button
+        onClick={() => remove(id)}
+        style={{
+          marginTop: 4,
+          padding: '8px 12px',
+          backgroundColor: 'rgba(239, 68, 68, 0.1)',
+          color: '#dc2626',
+          border: '1px solid rgba(239, 68, 68, 0.2)',
+          borderRadius: 8,
+          cursor: 'pointer',
+          fontSize: 11,
+          fontWeight: 500,
+          transition: 'background-color 0.15s',
+        }}
+      >
+        Remove
+      </button>
+    </div>
+  );
+}
+
+function getLinkEndpointId(endpoint: GraphLink['source']): string {
+  if (typeof endpoint === 'string') return endpoint;
+  if (typeof endpoint === 'object' && 'id' in endpoint) {
+    return String(endpoint.id);
+  }
+  return 'unknown';
+}
+
+interface LinkControlsProps {
+  readonly id: string;
+  readonly link: GraphLink;
+}
+
+function LinkControls({ id, link }: Readonly<LinkControlsProps>) {
+  const { set, remove } = useCellActions<GraphLink>();
+  const sourceId = getLinkEndpointId(link.source);
+  const targetId = getLinkEndpointId(link.target);
+
+  return (
+    <div
+      style={{
+        padding: '12px 16px',
+        borderBottom: '1px solid rgba(0, 0, 0, 0.06)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 10,
+      }}
+    >
+      <div style={{ fontWeight: 600, color: '#1f2937', fontSize: 13 }}>
+        {sourceId} <span style={{ color: '#9ca3af', margin: '0 4px' }}>→</span> {targetId}
+      </div>
+
+      {/* Stroke Color */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+        <label style={{ width: 45, fontSize: 11, color: '#6b7280', fontWeight: 500 }}>Color</label>
+        <input
+          type="color"
+          value={(link.attrs?.line as { stroke?: string })?.stroke ?? '#000000'}
+          onChange={(event) =>
+            set(id, (previous) => ({
+              ...previous,
+              attrs: { ...previous.attrs, line: { ...previous.attrs?.line, stroke: event.target.value } },
+            }))
+          }
+          style={{ width: 36, height: 28, border: 'none', cursor: 'pointer', borderRadius: 6, padding: 0 }}
+        />
+      </div>
+
+      {/* Remove */}
+      <button
+        onClick={() => remove(id)}
+        style={{
+          marginTop: 4,
+          padding: '8px 12px',
+          backgroundColor: 'rgba(239, 68, 68, 0.1)',
+          color: '#dc2626',
+          border: '1px solid rgba(239, 68, 68, 0.2)',
+          borderRadius: 8,
+          cursor: 'pointer',
+          fontSize: 11,
+          fontWeight: 500,
+          transition: 'background-color 0.15s',
+        }}
+      >
+        Remove
+      </button>
+    </div>
+  );
+}
+
+function AddElementForm() {
+  const { set } = useCellActions<NodeData>();
+  const elements = useElements<NodeData>();
+  const [label, setLabel] = useState('');
+
+  const handleAdd = () => {
+    if (!label.trim()) return;
+
+    const existingIds = Object.keys(elements).map(Number).filter((numberValue) => !Number.isNaN(numberValue));
+    const newId = String(Math.max(0, ...existingIds) + 1);
+
+    // eslint-disable-next-line sonarjs/pseudo-random -- Random position for demo purposes
+    const randomX = 50 + Math.random() * 200;
+    // eslint-disable-next-line sonarjs/pseudo-random -- Random position for demo purposes
+    const randomY = 50 + Math.random() * 150;
+
+    set(newId, {
+      label: label.trim(),
+      color: PRIMARY,
+      x: randomX,
+      y: randomY,
+      width: 120,
+      height: 60,
+    });
+    setLabel('');
+  };
+
+  return (
+    <div
+      style={{
+        padding: '12px 16px',
+        borderBottom: '1px solid rgba(0, 0, 0, 0.06)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 10,
+      }}
+    >
+      <div style={{ fontWeight: 600, color: '#1f2937', fontSize: 12 }}>Add Node</div>
+      <div style={{ display: 'flex', gap: 8 }}>
+        <input
+          type="text"
+          value={label}
+          onChange={(event) => setLabel(event.target.value)}
+          placeholder="Label..."
+          style={{
+            flex: 1,
+            padding: '8px 12px',
+            border: '1px solid rgba(0, 0, 0, 0.15)',
+            borderRadius: 8,
+            fontSize: 12,
+            backgroundColor: 'rgba(255, 255, 255, 0.9)',
+            color: '#1f2937',
+            outline: 'none',
+          }}
+          onKeyDown={(event) => event.key === 'Enter' && handleAdd()}
+        />
+        <button
+          onClick={handleAdd}
+          style={{
+            padding: '8px 14px',
+            backgroundColor: PRIMARY,
+            color: 'white',
+            border: 'none',
+            borderRadius: 8,
+            cursor: 'pointer',
+            fontSize: 11,
+            fontWeight: 600,
+          }}
+        >
+          +
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function AddLinkForm() {
+  const { set } = useCellActions<GraphLink>();
+  const elements = useElements<NodeData>();
+  const [source, setSource] = useState('');
+  const [target, setTarget] = useState('');
+
+  const elementIds = Object.keys(elements);
+
+  const selectStyle = {
+    flex: 1,
+    padding: '8px 10px',
+    border: '1px solid rgba(0, 0, 0, 0.15)',
+    borderRadius: 8,
+    fontSize: 12,
+    backgroundColor: 'rgba(255, 255, 255, 0.9)',
+    color: '#1f2937',
+    outline: 'none',
+    cursor: 'pointer',
+  };
+
+  const handleAdd = () => {
+    if (!source || !target || source === target) return;
+
+    const newId = `link-${source}-${target}-${Date.now()}`;
+    set(newId, {
+      source,
+      target,
+      attrs: { line: { stroke: LIGHT } },
+    });
+    setSource('');
+    setTarget('');
+  };
+
+  return (
+    <div
+      style={{
+        padding: '12px 16px',
+        borderBottom: '1px solid rgba(0, 0, 0, 0.06)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 10,
+      }}
+    >
+      <div style={{ fontWeight: 600, color: '#1f2937', fontSize: 12 }}>Add Link</div>
+      <div style={{ display: 'flex', gap: 8 }}>
+        <select value={source} onChange={(event) => setSource(event.target.value)} style={selectStyle}>
+          <option value="">From...</option>
+          {elementIds.map((id) => (
+            <option key={id} value={id}>
+              {elements[id].label}
+            </option>
+          ))}
+        </select>
+        <select value={target} onChange={(event) => setTarget(event.target.value)} style={selectStyle}>
+          <option value="">To...</option>
+          {elementIds.map((id) => (
+            <option key={id} value={id}>
+              {elements[id].label}
+            </option>
+          ))}
+        </select>
+        <button
+          onClick={handleAdd}
+          style={{
+            padding: '8px 14px',
+            backgroundColor: PRIMARY,
+            color: 'white',
+            border: 'none',
+            borderRadius: 8,
+            cursor: 'pointer',
+            fontSize: 11,
+            fontWeight: 600,
+          }}
+        >
+          +
+        </button>
+      </div>
+    </div>
+  );
+}
+
+// --- Main Component ---
+
+function Main() {
+  const elements = useElements<NodeData>();
+  const links = useLinks();
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'row', height: 500, position: 'relative' }}>
+      {/* Canvas */}
+      <Paper
+        width="100%"
+        className={PAPER_CLASSNAME}
+        height={500}
+        renderElement={RenderElement}
+        defaultRouter={{ name: 'normal' }}
+        defaultConnector={{ name: 'rounded', args: { radius: 10 } }}
+      />
+
+      {/* Control Panel - Glassmorphism Style */}
+      <div
+        style={{
+          position: 'absolute',
+          right: 16,
+          top: 16,
+          bottom: 16,
+          width: 260,
+          backgroundColor: 'rgba(255, 255, 255, 0.85)',
+          backdropFilter: 'blur(12px)',
+          WebkitBackdropFilter: 'blur(12px)',
+          borderRadius: 16,
+          boxShadow: '0 8px 32px rgba(0, 0, 0, 0.12)',
+          border: '1px solid rgba(255, 255, 255, 0.3)',
+          overflowY: 'auto',
+          overflowX: 'hidden',
+        }}
+      >
+        <div
+          style={{
+            padding: '16px 16px 12px',
+            borderBottom: '1px solid rgba(0, 0, 0, 0.06)',
+            fontSize: 13,
+            fontWeight: 700,
+            color: '#1f2937',
+            letterSpacing: '-0.01em',
+          }}
+        >
+          Cell Actions
+        </div>
+
+        {/* Add forms */}
+        <AddElementForm />
+        <AddLinkForm />
+
+        {/* Element Controls */}
+        <div
+          style={{
+            padding: '10px 16px',
+            backgroundColor: 'rgba(0, 0, 0, 0.03)',
+            fontSize: 11,
+            fontWeight: 600,
+            color: '#6b7280',
+            textTransform: 'uppercase',
+            letterSpacing: '0.05em',
+          }}
+        >
+          Nodes ({Object.keys(elements).length})
+        </div>
+        {Object.entries(elements).map(([id, element]) => (
+          <ElementControls key={id} id={id} element={element} />
+        ))}
+
+        {/* Link Controls */}
+        <div
+          style={{
+            padding: '10px 16px',
+            backgroundColor: 'rgba(0, 0, 0, 0.03)',
+            fontSize: 11,
+            fontWeight: 600,
+            color: '#6b7280',
+            textTransform: 'uppercase',
+            letterSpacing: '0.05em',
+          }}
+        >
+          Links ({Object.keys(links).length})
+        </div>
+        {Object.entries(links).map(([id, link]) => (
+          <LinkControls key={id} id={id} link={link} />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <GraphProvider elements={initialElements} links={initialLinks}>
+      <Main />
+    </GraphProvider>
+  );
+}
diff --git a/packages/joint-react/src/stories/examples/with-cell-actions/story.tsx b/packages/joint-react/src/stories/examples/with-cell-actions/story.tsx
new file mode 100644
index 000000000..67dc1e97c
--- /dev/null
+++ b/packages/joint-react/src/stories/examples/with-cell-actions/story.tsx
@@ -0,0 +1,20 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index.css';
+import Code from './code';
+
+export type Story = StoryObj<typeof Code>;
+
+import { makeRootDocumentation } from '../../utils/make-story';
+
+import CodeRaw from './code?raw';
+
+export default {
+  title: 'Examples/Cell Actions',
+  tags: ['example'],
+  component: Code,
+  parameters: makeRootDocumentation({
+    code: CodeRaw,
+  }),
+} satisfies Meta<typeof Code>;
+
+export const Default: Story = {};
diff --git a/packages/joint-react/src/stories/examples/with-custom-link/code-with-create-links-classname.tsx b/packages/joint-react/src/stories/examples/with-custom-link/code-with-create-links-classname.tsx
index b169d79bc..01fcd0f30 100644
--- a/packages/joint-react/src/stories/examples/with-custom-link/code-with-create-links-classname.tsx
+++ b/packages/joint-react/src/stories/examples/with-custom-link/code-with-create-links-classname.tsx
@@ -12,14 +12,13 @@ import { HTMLNode } from 'storybook-config/decorators/with-simple-data';
 import './code-with-create-links-classname.css';
 import { PAPER_CLASSNAME, PRIMARY } from 'storybook-config/theme';
 
-const initialElements = [
-  { id: '1', label: 'Node 1', x: 100, y: 0 },
-  { id: '2', label: 'Node 2', x: 100, y: 200 },
-];
+const initialElements: Record<string, { label: string; x: number; y: number }> = {
+  '1': { label: 'Node 1', x: 100, y: 0 },
+  '2': { label: 'Node 2', x: 100, y: 200 },
+};
 
-const initialEdges: GraphLink[] = [
-  {
-    id: 'e1-2',
+const initialEdges: Record<string, GraphLink> = {
+  'e1-2': {
     source: '1',
     target: '2',
     attrs: {
@@ -29,9 +28,9 @@ const initialEdges: GraphLink[] = [
       },
     },
   },
-];
+};
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
 function Main() {
   const renderElement: RenderElement<BaseElementWithData> = useCallback(
diff --git a/packages/joint-react/src/stories/examples/with-custom-link/code-with-create-links.tsx b/packages/joint-react/src/stories/examples/with-custom-link/code-with-create-links.tsx
index 3950c8eec..ea448e607 100644
--- a/packages/joint-react/src/stories/examples/with-custom-link/code-with-create-links.tsx
+++ b/packages/joint-react/src/stories/examples/with-custom-link/code-with-create-links.tsx
@@ -10,14 +10,13 @@ import {
 import { useCallback } from 'react';
 import { HTMLNode } from 'storybook-config/decorators/with-simple-data';
 
-const initialElements = [
-  { id: '1', label: 'Node 1', x: 100, y: 0 },
-  { id: '2', label: 'Node 2', x: 100, y: 200 },
-];
+const initialElements: Record<string, { label: string; x: number; y: number }> = {
+  '1': { label: 'Node 1', x: 100, y: 0 },
+  '2': { label: 'Node 2', x: 100, y: 200 },
+};
 
-const initialEdges: GraphLink[] = [
-  {
-    id: 'e1-2',
+const initialEdges: Record<string, GraphLink> = {
+  'e1-2': {
     source: '1',
     target: '2',
     attrs: {
@@ -28,9 +27,9 @@ const initialEdges: GraphLink[] = [
       },
     },
   },
-];
+};
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
 function Main() {
   const renderElement: RenderElement<BaseElementWithData> = useCallback(
diff --git a/packages/joint-react/src/stories/examples/with-custom-link/code-with-dia-links.tsx b/packages/joint-react/src/stories/examples/with-custom-link/code-with-dia-links.tsx
index 748a35df4..c2c955bbb 100644
--- a/packages/joint-react/src/stories/examples/with-custom-link/code-with-dia-links.tsx
+++ b/packages/joint-react/src/stories/examples/with-custom-link/code-with-dia-links.tsx
@@ -7,10 +7,10 @@ import { useCallback } from 'react';
 import { HTMLNode } from 'storybook-config/decorators/with-simple-data';
 import { Paper } from '../../../components/paper/paper';
 
-const initialElements = [
-  { id: '1', label: 'Node 1', x: 100, y: 0 },
-  { id: '2', label: 'Node 2', x: 100, y: 200 },
-];
+const initialElements: Record<string, { label: string; x: number; y: number }> = {
+  '1': { label: 'Node 1', x: 100, y: 0 },
+  '2': { label: 'Node 2', x: 100, y: 200 },
+};
 
 class LinkModel extends shapes.standard.Link {
   defaults() {
@@ -27,7 +27,7 @@ class LinkModel extends shapes.standard.Link {
   }
 }
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
 function Main() {
   const renderElement: RenderElement<BaseElementWithData> = useCallback(
@@ -47,15 +47,14 @@ function Main() {
   );
 }
 
-const links = [
-  {
+const links: Record<string, { source: string; target: string; type: string; attrs: { line: { stroke: string } } }> = {
+  '1123': {
     source: '1',
     target: '2',
     type: 'LinkModel',
-    id: '1123',
     attrs: { line: { stroke: PRIMARY } },
   },
-];
+};
 
 export default function App(props: Readonly<GraphProps>) {
   return (
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 2452634ac..a953c415c 100644
--- a/packages/joint-react/src/stories/examples/with-highlighter/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-highlighter/code.tsx
@@ -5,28 +5,25 @@ import '../index.css';
 import { useState } from 'react';
 import { PAPER_CLASSNAME, PRIMARY, SECONDARY } from 'storybook-config/theme';
 
-const initialElements = [
-  {
-    id: '1',
+const initialElements: Record<string, GraphElement & { label: string }> = {
+  '1': {
     label: 'Node 1',
     x: 100,
     y: 50,
     width: 125,
     height: 25,
   },
-  {
-    id: '2',
+  '2': {
     label: 'Node 2',
     x: 100,
     y: 200,
     width: 120,
     height: 25,
   },
-] satisfies GraphElement[];
+};
 
-const initialEdges = [
-  {
-    id: 'e1-2',
+const initialEdges: Record<string, GraphLink> = {
+  'e1-2': {
     source: '1',
     target: '2',
     attrs: {
@@ -35,11 +32,11 @@ const initialEdges = [
       },
     },
   },
-] satisfies GraphLink[];
+};
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
-function RenderItemWithChildren({ height, width, label }: Readonly<BaseElementWithData>) {
+function RenderItemWithChildren({ height = 0, width = 0, label }: Readonly<BaseElementWithData>) {
   const [isHighlighted, setIsHighlighted] = useState(false);
   return (
     <g
diff --git a/packages/joint-react/src/stories/examples/with-intersection/code.tsx b/packages/joint-react/src/stories/examples/with-intersection/code.tsx
index 8036efd1e..e72a24087 100644
--- a/packages/joint-react/src/stories/examples/with-intersection/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-intersection/code.tsx
@@ -1,22 +1,23 @@
 /* eslint-disable react-perf/jsx-no-new-object-as-prop */
-import { GraphProvider, useElements, useGraph, Paper, useNodeSize } from '@joint/react';
+import { GraphProvider, useElements, useGraph, Paper, useNodeSize, useCellId } from '@joint/react';
 import '../index.css';
 import { useRef } from 'react';
 import type { dia } from '@joint/core';
 import { PAPER_CLASSNAME } from 'storybook-config/theme';
 
-const initialElements = [
-  { id: '1', label: 'Node 1', x: 100, y: 0 },
-  { id: '2', label: 'Node 2', x: 100, y: 200 },
-  { id: '3', label: 'Node 3', x: 200, y: 100 },
-  { id: '4', label: 'Node 4', x: 0, y: 100 },
-];
+const initialElements: Record<string, { label: string; x: number; y: number }> = {
+  '1': { label: 'Node 1', x: 100, y: 0 },
+  '2': { label: 'Node 2', x: 100, y: 200 },
+  '3': { label: 'Node 3', x: 200, y: 100 },
+  '4': { label: 'Node 4', x: 0, y: 100 },
+};
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
-function ResizableNode({ id, label }: Readonly<BaseElementWithData>) {
+function ResizableNode({ label }: Readonly<BaseElementWithData>) {
   const nodeRef = useRef<HTMLDivElement>(null);
   const graph = useGraph();
+  const id = useCellId();
   const element = graph.getCell(id) as dia.Element;
 
   const isIntersected = useElements(() => {
@@ -44,7 +45,7 @@ function Main() {
 
 export default function App() {
   return (
-    <GraphProvider areBatchUpdatesDisabled elements={initialElements}>
+    <GraphProvider elements={initialElements}>
       <Main />
     </GraphProvider>
   );
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 899cb4ad4..1887d281c 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
@@ -6,9 +6,8 @@ import { GraphProvider, jsx, Paper, type RenderElement } from '@joint/react';
 import { useCallback } from 'react';
 import { PRIMARY, BG, SECONDARY, PAPER_CLASSNAME } from 'storybook-config/theme';
 
-const initialEdges = [
-  {
-    id: 'e1-2',
+const initialEdges: Record<string, { source: string; target: string; attrs: { line: { stroke: string; strokeDasharray: string } } }> = {
+  'e1-2': {
     source: '1',
     target: '2',
     attrs: {
@@ -18,12 +17,12 @@ const initialEdges = [
       },
     },
   },
-];
+};
 
-const initialElements = [
-  { id: '1', label: 'Node 1', x: 100, y: 10, width: 120, height: 30 },
-  { id: '2', label: 'Node 2', x: 100, y: 200, width: 120, height: 30 },
-];
+const initialElements: Record<string, { label: string; x: number; y: number; width: number; height: number }> = {
+  '1': { label: 'Node 1', x: 100, y: 10, width: 120, height: 30 },
+  '2': { label: 'Node 2', x: 100, y: 200, width: 120, height: 30 },
+};
 
 // 1) creating link tools
 const verticesTool = new linkTools.Vertices({
@@ -66,7 +65,7 @@ const toolsView = new dia.ToolsView({
   tools: [boundaryTool, verticesTool, infoButton],
 });
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
 function RectElement({ width, height }: Readonly<BaseElementWithData>) {
   return (
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 03b5d02e8..67d6296e8 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
@@ -3,17 +3,16 @@
 
 import '../index.css';
 import React, { useCallback, useRef, type PropsWithChildren } from 'react';
-import { GraphProvider, Paper, useNodeSize, type OnTransformElement } from '@joint/react';
+import { GraphProvider, Paper, useNodeSize, type OnTransformElement, useCellId } from '@joint/react';
 import { PAPER_CLASSNAME, PRIMARY } from 'storybook-config/theme';
 import { useCellActions } from '../../../hooks/use-cell-actions';
 
-const initialElements = [
-  { id: '1', label: 'Node 1', inputs: [] as string[], x: 100, y: 0 },
-  { id: '2', label: 'Node 2', inputs: [] as string[], x: 500, y: 200 },
-];
-const initialEdges = [
-  {
-    id: 'e1-2',
+const initialElements: Record<string, { label: string; inputs: string[]; x: number; y: number }> = {
+  '1': { label: 'Node 1', inputs: [] as string[], x: 100, y: 0 },
+  '2': { label: 'Node 2', inputs: [] as string[], x: 500, y: 200 },
+};
+const initialEdges: Record<string, { source: string; target: string; attrs: { line: { stroke: string } } }> = {
+  'e1-2': {
     source: '1',
     target: '2',
     attrs: {
@@ -22,11 +21,12 @@ const initialEdges = [
       },
     },
   },
-];
+};
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
-function ListElement({ id, children, inputs }: PropsWithChildren<BaseElementWithData>) {
+function ListElement({ children, inputs }: PropsWithChildren<BaseElementWithData>) {
+  const id = useCellId();
   const padding = 10;
   const headerHeight = 50;
   const elementRef = useRef<HTMLDivElement>(null);
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 460656916..aa16ae7c3 100644
--- a/packages/joint-react/src/stories/examples/with-minimap/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-minimap/code.tsx
@@ -4,13 +4,12 @@ import { useCallback, useRef } from 'react';
 import { GraphProvider, Paper, useNodeSize, type RenderElement } from '@joint/react';
 import { PRIMARY, SECONDARY, LIGHT, PAPER_CLASSNAME } from 'storybook-config/theme';
 
-const initialElements = [
-  { id: '1', label: 'Node 1', color: PRIMARY, x: 100, y: 10, width: 100, height: 50 },
-  { id: '2', label: 'Node 2', color: SECONDARY, x: 100, y: 200, width: 100, height: 50 },
-];
-const initialEdges = [
-  {
-    id: 'e1-2',
+const initialElements: Record<string, { label: string; color: string; x: number; y: number; width: number; height: number }> = {
+  '1': { label: 'Node 1', color: PRIMARY, x: 100, y: 10, width: 100, height: 50 },
+  '2': { label: 'Node 2', color: SECONDARY, x: 100, y: 200, width: 100, height: 50 },
+};
+const initialEdges: Record<string, { source: string; target: string; attrs: { line: { stroke: string } } }> = {
+  'e1-2': {
     source: '1',
     target: '2',
     attrs: {
@@ -19,9 +18,9 @@ const initialEdges = [
       },
     },
   },
-];
+};
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
 function MiniMap() {
   const renderElement: RenderElement<BaseElementWithData> = useCallback(
diff --git a/packages/joint-react/src/stories/examples/with-node-update/code-add-remove-node.tsx b/packages/joint-react/src/stories/examples/with-node-update/code-add-remove-node.tsx
index 38bb0c9f1..28a2514d2 100644
--- a/packages/joint-react/src/stories/examples/with-node-update/code-add-remove-node.tsx
+++ b/packages/joint-react/src/stories/examples/with-node-update/code-add-remove-node.tsx
@@ -14,15 +14,14 @@ import { useRef } from 'react';
 import { PAPER_CLASSNAME, PRIMARY } from 'storybook-config/theme';
 import { useCellActions } from '../../../hooks/use-cell-actions';
 
-const initialElements = [
-  { id: '1', label: 'Node 1', color: '#ffffff', x: 40, y: 70 },
-  { id: '2', label: 'Node 2', color: '#ffffff', x: 170, y: 120 },
-  { id: '3', label: 'Node 2', color: '#ffffff', x: 30, y: 180 },
-];
+const initialElements: Record<string, { label: string; color: string; x: number; y: number; width: number; height: number }> = {
+  '1': { label: 'Node 1', color: '#ffffff', x: 40, y: 70, width: 120, height: 80 },
+  '2': { label: 'Node 2', color: '#ffffff', x: 170, y: 120, width: 120, height: 80 },
+  '3': { label: 'Node 2', color: '#ffffff', x: 30, y: 180, width: 120, height: 80 },
+};
 
-const initialEdges: GraphLink[] = [
-  {
-    id: 'e1-1',
+const initialEdges: Record<string, GraphLink> = {
+  'e1-1': {
     source: '1',
     target: '2',
     attrs: {
@@ -31,11 +30,15 @@ const initialEdges: GraphLink[] = [
       },
     },
   },
-];
+};
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
-function ElementInput({ id, label }: Readonly<BaseElementWithData>) {
+interface ElementInputProps extends BaseElementWithData {
+  readonly id: string;
+}
+
+function ElementInput({ id, label }: Readonly<ElementInputProps>) {
   const { set } = useCellActions<BaseElementWithData>();
   return (
     <input
@@ -97,8 +100,8 @@ function Main() {
         renderElement={RenderElement}
       />
       <div style={{ display: 'flex', flexDirection: 'column' }}>
-        {elements.map((item) => {
-          return <ElementInput key={item.id} {...item} />;
+        {Object.entries(elements).map(([id, item]) => {
+          return <ElementInput key={id} id={id} {...item} />;
         })}
       </div>
     </div>
diff --git a/packages/joint-react/src/stories/examples/with-node-update/code-with-color.tsx b/packages/joint-react/src/stories/examples/with-node-update/code-with-color.tsx
index ee0fb6e99..405e5e34e 100644
--- a/packages/joint-react/src/stories/examples/with-node-update/code-with-color.tsx
+++ b/packages/joint-react/src/stories/examples/with-node-update/code-with-color.tsx
@@ -6,13 +6,13 @@ import { PRIMARY, LIGHT, PAPER_CLASSNAME } from 'storybook-config/theme';
 import { HTMLNode } from 'storybook-config/decorators/with-simple-data';
 import { useCellActions } from '../../../hooks/use-cell-actions';
 
-const initialElements = [
-  { id: '1', label: 'Node 1', color: PRIMARY, x: 100, y: 0 },
-  { id: '2', label: 'Node 2', color: PRIMARY, x: 100, y: 200 },
-];
+const initialElements: Record<string, { id: string; label: string; color: string; x: number; y: number; width: number; height: number }> = {
+  '1': { id: '1', label: 'Node 1', color: PRIMARY, x: 100, y: 0, width: 100, height: 50 },
+  '2': { id: '2', label: 'Node 2', color: PRIMARY, x: 100, y: 200, width: 100, height: 50 },
+};
 
-const initialEdges: GraphLink[] = [
-  {
+const initialEdges: Record<string, GraphLink> = {
+  'e1-2': {
     id: 'e1-2',
     source: '1',
     target: '2',
@@ -22,9 +22,9 @@ const initialEdges: GraphLink[] = [
       },
     },
   },
-];
+};
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
 function RenderElement({ color, id }: Readonly<BaseElementWithData>) {
   const { set } = useCellActions<BaseElementWithData>();
diff --git a/packages/joint-react/src/stories/examples/with-node-update/code-with-svg.tsx b/packages/joint-react/src/stories/examples/with-node-update/code-with-svg.tsx
index a907bb4f0..f3ecb7bc2 100644
--- a/packages/joint-react/src/stories/examples/with-node-update/code-with-svg.tsx
+++ b/packages/joint-react/src/stories/examples/with-node-update/code-with-svg.tsx
@@ -5,14 +5,13 @@ import '../index.css';
 import { LIGHT, PAPER_CLASSNAME, PRIMARY } from 'storybook-config/theme';
 import { useCellActions } from '../../../hooks/use-cell-actions';
 
-const initialElements = [
-  { id: '1', color: PRIMARY, x: 100, y: 0, width: 130, height: 35 },
-  { id: '2', color: PRIMARY, x: 100, y: 200, width: 130, height: 35 },
-];
+const initialElements: Record<string, { color: string; x: number; y: number; width: number; height: number }> = {
+  '1': { color: PRIMARY, x: 100, y: 0, width: 130, height: 35 },
+  '2': { color: PRIMARY, x: 100, y: 200, width: 130, height: 35 },
+};
 
-const initialEdges: GraphLink[] = [
-  {
-    id: 'e1-2',
+const initialEdges: Record<string, GraphLink> = {
+  'e1-2': {
     source: '1',
     target: '2',
     attrs: {
@@ -21,11 +20,15 @@ const initialEdges: GraphLink[] = [
       },
     },
   },
-];
+};
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
-function ElementInput({ id, color }: Readonly<BaseElementWithData>) {
+interface ElementInputProps extends BaseElementWithData {
+  readonly id: string;
+}
+
+function ElementInput({ id, color }: Readonly<ElementInputProps>) {
   const { set } = useCellActions<BaseElementWithData>();
   return (
     <input
@@ -47,8 +50,8 @@ function Main() {
     <div style={{ display: 'flex', flexDirection: 'row' }}>
       <Paper width="100%" className={PAPER_CLASSNAME} height={280} renderElement={RenderElement} />
       <div style={{ display: 'flex', flexDirection: 'column' }}>
-        {elements.map((item) => {
-          return <ElementInput key={item.id} {...item} />;
+        {Object.entries(elements).map(([id, item]) => {
+          return <ElementInput key={id} id={id} {...item} />;
         })}
       </div>
     </div>
diff --git a/packages/joint-react/src/stories/examples/with-node-update/code.tsx b/packages/joint-react/src/stories/examples/with-node-update/code.tsx
index 6ef26c58d..c55ec7519 100644
--- a/packages/joint-react/src/stories/examples/with-node-update/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-node-update/code.tsx
@@ -6,13 +6,13 @@ import { useRef } from 'react';
 import { PAPER_CLASSNAME, PRIMARY } from 'storybook-config/theme';
 import { useCellActions } from '../../../hooks/use-cell-actions';
 
-const initialElements = [
-  { id: '1', label: 'Node 1', color: '#ffffff', x: 100, y: 0 },
-  { id: '2', label: 'Node 2', color: '#ffffff', x: 100, y: 200 },
-];
+const initialElements: Record<string, { id: string; label: string; color: string; x: number; y: number; width: number; height: number }> = {
+  '1': { id: '1', label: 'Node 1', color: '#ffffff', x: 100, y: 0, width: 100, height: 50 },
+  '2': { id: '2', label: 'Node 2', color: '#ffffff', x: 100, y: 200, width: 100, height: 50 },
+};
 
-const initialEdges: GraphLink[] = [
-  {
+const initialEdges: Record<string, GraphLink> = {
+  'e1-2': {
     id: 'e1-2',
     source: '1',
     target: '2',
@@ -22,9 +22,9 @@ const initialEdges: GraphLink[] = [
       },
     },
   },
-];
+};
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
 function ElementInput({ id, label }: Readonly<BaseElementWithData>) {
   const { set } = useCellActions<BaseElementWithData>();
@@ -56,7 +56,7 @@ function Main() {
     <div style={{ display: 'flex', flexDirection: 'row' }}>
       <Paper width="100%" className={PAPER_CLASSNAME} height={280} renderElement={RenderElement} />
       <div style={{ display: 'flex', flexDirection: 'column' }}>
-        {elements.map((item) => {
+        {Object.values(elements).map((item) => {
           return <ElementInput key={item.id} {...item} />;
         })}
       </div>
diff --git a/packages/joint-react/src/stories/examples/with-proximity-link/code.tsx b/packages/joint-react/src/stories/examples/with-proximity-link/code.tsx
index dce5457d7..d78db8e46 100644
--- a/packages/joint-react/src/stories/examples/with-proximity-link/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-proximity-link/code.tsx
@@ -1,5 +1,5 @@
 /* eslint-disable react-perf/jsx-no-new-object-as-prop */
-import { GraphProvider, Paper, useNodeSize } from '@joint/react';
+import { GraphProvider, Paper, useNodeSize, useCellId } from '@joint/react';
 import '../index.css';
 import { useRef } from 'react';
 import { shapes, util } from '@joint/core';
@@ -7,14 +7,14 @@ import { PAPER_CLASSNAME, SECONDARY } from 'storybook-config/theme';
 import type { dia } from '../../../../../joint-core/types';
 import { useCellChangeEffect } from '../../../hooks/use-cell-change-effect';
 
-const initialElements = [
-  { id: '1', label: 'Node 1', x: 100, y: 0 },
-  { id: '2', label: 'Node 2', x: 100, y: 200 },
-  { id: '3', label: 'Node 3', x: 280, y: 100 },
-  { id: '4', label: 'Node 4', x: 0, y: 100 },
-];
+const initialElements: Record<string, { label: string; x: number; y: number }> = {
+  '1': { label: 'Node 1', x: 100, y: 0 },
+  '2': { label: 'Node 2', x: 100, y: 200 },
+  '3': { label: 'Node 3', x: 280, y: 100 },
+  '4': { label: 'Node 4', x: 0, y: 100 },
+};
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
 class DashedLink extends shapes.standard.Link {
   defaults() {
@@ -106,7 +106,8 @@ function createProximityLinks(
   }
 }
 
-function ResizableNode({ id, label }: Readonly<BaseElementWithData>) {
+function ResizableNode({ label }: Readonly<BaseElementWithData>) {
+  const id = useCellId();
   const nodeRef = useRef<HTMLDivElement>(null);
   const managedLinksRef = useRef<Set<string>>(new Set());
 
diff --git a/packages/joint-react/src/stories/examples/with-render-link/code.tsx b/packages/joint-react/src/stories/examples/with-render-link/code.tsx
index 776bba12a..29eed2dad 100644
--- a/packages/joint-react/src/stories/examples/with-render-link/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-render-link/code.tsx
@@ -1,58 +1,60 @@
- 
 /* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { PAPER_CLASSNAME, PRIMARY } from 'storybook-config/theme';
 import '../index.css';
 
-import { GraphProvider, Link, Paper, type RenderLink } from '@joint/react';
+import { GraphProvider, Paper, type RenderLink, useCellId, useLinkLayout } from '@joint/react';
 import { useCallback } from 'react';
 import { HTMLNode } from 'storybook-config/decorators/with-simple-data';
 import { REACT_LINK_TYPE } from '../../../models/react-link';
 
-const initialElements = [
-  { id: '1', label: 'Node 1', x: 100, y: 0 },
-  { id: '2', label: 'Node 2', x: 100, y: 200 },
-  { id: '3', label: 'Node 3', x: 300, y: 100 },
-];
+const initialElements: Record<string, { label: string; x: number; y: number }> = {
+  '1': { label: 'Node 1', x: 100, y: 0 },
+  '2': { label: 'Node 2', x: 100, y: 200 },
+  '3': { label: 'Node 3', x: 300, y: 100 },
+};
 
-const initialLinks = [
-  {
-    id: 'link-1',
+const initialLinks: Record<string, { type: string; source: string; target: string }> = {
+  'link-1': {
     type: REACT_LINK_TYPE,
     source: '1',
     target: '2',
   },
-  {
-    id: 'link-2',
+  'link-2': {
     type: REACT_LINK_TYPE,
     source: '2',
     target: '3',
   },
-];
+};
+
+function LinkPath() {
+  const layout = useLinkLayout();
+  const id = useCellId();
+
+  if (!layout) {
+    return null;
+  }
+
+  // Calculate midpoint for label
+  const midX = (layout.sourceX + layout.targetX) / 2;
+  const midY = (layout.sourceY + layout.targetY) / 2;
+
+  return (
+    <g>
+      <path d={layout.d} stroke={PRIMARY} strokeWidth={2} fill="none" />
+      <foreignObject x={midX - 30} y={midY - 10} width={60} height={20}>
+        <div className="bg-blue-100 rounded px-2 py-1 text-xs text-center">Link {id}</div>
+      </foreignObject>
+    </g>
+  );
+}
 
 function Main() {
   const renderElement = useCallback(
-    (element: { id: string; label: string }) => <HTMLNode className="node">{element.label}</HTMLNode>,
+    (element: { label: string }) => <HTMLNode className="node">{element.label}</HTMLNode>,
     []
   );
 
-  const renderLink: RenderLink = useCallback(
-    (link) => (
-      <>
-        <Link.Base
-          stroke={PRIMARY}
-          strokeWidth={2}
-        />
-        <Link.Label position={{ distance: 0.5 }}>
-          <foreignObject width={60} height={20}>
-            <div className="bg-blue-100 rounded px-2 py-1 text-xs text-center">
-              Link {link.id}
-            </div>
-          </foreignObject>
-        </Link.Label>
-      </>
-    ),
-    []
-  );
+  const renderLink: RenderLink = useCallback(() => <LinkPath />, []);
 
   return (
     <div style={{ display: 'flex', flexDirection: 'row' }}>
diff --git a/packages/joint-react/src/stories/examples/with-resizable-node/code.tsx b/packages/joint-react/src/stories/examples/with-resizable-node/code.tsx
index eedf3ef94..2df600f9d 100644
--- a/packages/joint-react/src/stories/examples/with-resizable-node/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-resizable-node/code.tsx
@@ -4,14 +4,13 @@ import '../index.css';
 import { useCallback, useRef } from 'react';
 import { PAPER_CLASSNAME, PRIMARY } from 'storybook-config/theme';
 
-const initialElements = [
-  { id: '1', label: 'Node 1', x: 100, y: 0 },
-  { id: '2', label: 'Node 2', x: 100, y: 200 },
-];
+const initialElements: Record<string, { label: string; x: number; y: number }> = {
+  '1': { label: 'Node 1', x: 100, y: 0 },
+  '2': { label: 'Node 2', x: 100, y: 200 },
+};
 
-const initialEdges = [
-  {
-    id: 'e1-2',
+const initialEdges: Record<string, { source: string; target: string; attrs: { line: { stroke: string } } }> = {
+  'e1-2': {
     source: '1',
     target: '2',
     attrs: {
@@ -20,9 +19,9 @@ const initialEdges = [
       },
     },
   },
-];
+};
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
 function ResizableNode({ label }: Readonly<BaseElementWithData>) {
   const nodeRef = useRef<HTMLDivElement>(null);
@@ -30,7 +29,7 @@ function ResizableNode({ label }: Readonly<BaseElementWithData>) {
     const node = nodeRef.current;
     if (!node) return;
 
-    // Get the node’s bounding rectangle
+    // Get the node's bounding rectangle
     const rect = node.getBoundingClientRect();
     const threshold = 20; // pixels from the bottom-right corner considered as resize area
 
@@ -61,7 +60,7 @@ function ResizableNode({ label }: Readonly<BaseElementWithData>) {
 
 function Main() {
   const elementsSize = useElements((items) =>
-    items.map(({ width, height }) => `${width} x ${height}`)
+    Object.values(items).map(({ width, height }) => `${width} x ${height}`)
   );
 
   return (
diff --git a/packages/joint-react/src/stories/examples/with-rotable-node/code.tsx b/packages/joint-react/src/stories/examples/with-rotable-node/code.tsx
index 04e92ad7e..b6e7b6ac5 100644
--- a/packages/joint-react/src/stories/examples/with-rotable-node/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-rotable-node/code.tsx
@@ -5,13 +5,13 @@ import { useCallback, useRef } from 'react';
 import { PAPER_CLASSNAME, PRIMARY } from 'storybook-config/theme';
 import { useCellActions } from '../../../hooks/use-cell-actions';
 
-const initialElements = [
-  { id: '1', label: 'Node 1', x: 20, y: 100 },
-  { id: '2', label: 'Node 2', x: 200, y: 100 },
-];
+const initialElements: Record<string, { id: string; label: string; x: number; y: number }> = {
+  '1': { id: '1', label: 'Node 1', x: 20, y: 100 },
+  '2': { id: '2', label: 'Node 2', x: 200, y: 100 },
+};
 
-const initialEdges = [
-  {
+const initialEdges: Record<string, { id: string; source: string; target: string; attrs: { line: { stroke: string } } }> = {
+  'e1-2': {
     id: 'e1-2',
     source: '1',
     target: '2',
@@ -21,9 +21,9 @@ const initialEdges = [
       },
     },
   },
-];
+};
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
 function RotatableNode({ label, id }: Readonly<BaseElementWithData>) {
   const paper = usePaper();
@@ -85,7 +85,7 @@ function RotatableNode({ label, id }: Readonly<BaseElementWithData>) {
 
 function Main() {
   const elementRotation = useElements((items) =>
-    items.map(({ angle }) => `${angle?.toString().padStart(3, '0')} deg`)
+    Object.values(items).map(({ angle }) => `${angle?.toString().padStart(3, '0')} deg`)
   );
 
   return (
diff --git a/packages/joint-react/src/stories/examples/with-svg-node/code.tsx b/packages/joint-react/src/stories/examples/with-svg-node/code.tsx
index ff640af49..375d6a563 100644
--- a/packages/joint-react/src/stories/examples/with-svg-node/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-svg-node/code.tsx
@@ -10,9 +10,8 @@ import {
 } from '@joint/react';
 import { useCallback, useRef } from 'react';
 
-const initialEdges = [
-  {
-    id: 'e1-2',
+const initialEdges: Record<string, { source: string; target: string; attrs: { line: { stroke: string } } }> = {
+  'e1-2': {
     source: '1',
     target: '2',
     attrs: {
@@ -21,14 +20,14 @@ const initialEdges = [
       },
     },
   },
-];
+};
 
-const initialElements = [
-  { id: '1', label: 'Node 1', x: 100, y: 0 },
-  { id: '2', label: 'Node 2', x: 100, y: 200 },
-];
+const initialElements: Record<string, { label: string; x: number; y: number }> = {
+  '1': { label: 'Node 1', x: 100, y: 0 },
+  '2': { label: 'Node 2', x: 100, y: 200 },
+};
 
-type BaseElementWithData = (typeof initialElements)[number];
+type BaseElementWithData = (typeof initialElements)[string];
 
 function RenderedRect({ label }: Readonly<BaseElementWithData>) {
   const textMargin = 20;
diff --git a/packages/joint-react/src/stories/introduction.mdx b/packages/joint-react/src/stories/introduction.mdx
index 9c3d4d314..50209d2e1 100644
--- a/packages/joint-react/src/stories/introduction.mdx
+++ b/packages/joint-react/src/stories/introduction.mdx
@@ -69,16 +69,16 @@ Use the graph APIs to update state. Hooks provide convenient access:
 - {getAPIDocumentationLink('usePaper')}: Access the JointJS [Paper](https://docs.jointjs.com/learn/quickstart/paper/)
 
 ### 🔹 Creating Nodes and Links
-Elements and links are plain objects with at least an `id` field and geometry properties.
+Elements and links are plain objects with geometry properties. They are stored as Records keyed by their ID.
 
 ```ts
-const initialElements = [
-  { id: '1', type: 'rect', x: 10, y: 10, width: 100, height: 100 },
-];
+const initialElements = {
+  '1': { type: 'rect', x: 10, y: 10, width: 100, height: 100 },
+};
 
-const initialLinks = [
-  { id: '1-2', source: '1', target: '2' },
-];
+const initialLinks = {
+  '1-2': { source: '1', target: '2' },
+};
 ```
 
 ---
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 4239a4d45..8d38779c2 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
@@ -56,14 +56,13 @@ import type { Update } from '../../../utils/create-state';
  */
 type CustomElement = GraphElement & { label: string };
 
-const defaultElements: CustomElement[] = [
-  { id: '1', label: 'Hello', x: 100, y: 0, width: 100, height: 50 },
-  { id: '2', label: 'World', x: 100, y: 200, width: 100, height: 50 },
-];
-
-const defaultLinks: GraphLink[] = [
-  {
-    id: 'e1-2',
+const defaultElements: Record<string, CustomElement> = {
+  '1': { label: 'Hello', x: 100, y: 0, width: 100, height: 50 },
+  '2': { label: 'World', x: 100, y: 200, width: 100, height: 50 },
+};
+
+const defaultLinks: Record<string, GraphLink> = {
+  'e1-2': {
     source: '1',
     target: '2',
     attrs: {
@@ -72,7 +71,7 @@ const defaultLinks: GraphLink[] = [
       },
     },
   },
-];
+};
 
 // ============================================================================
 // STEP 2: Custom Element Renderer
@@ -101,12 +100,14 @@ const jotaiStore = createStore();
  * Jotai atom for graph elements.
  * Atoms are the building blocks of Jotai - they hold state.
  */
-const elementsAtom = atom<GraphElement[]>(defaultElements as GraphElement[]);
+const elementsAtom = atom<Record<string, GraphElement>>(
+  defaultElements as Record<string, GraphElement>
+);
 
 /**
  * Jotai atom for graph links.
  */
-const linksAtom = atom<GraphLink[]>(defaultLinks as GraphLink[]);
+const linksAtom = atom<Record<string, GraphLink>>(defaultLinks as Record<string, GraphLink>);
 
 // ============================================================================
 // STEP 4: Create Jotai Adapter Hook
@@ -230,8 +231,9 @@ function PaperApp({ store }: Readonly<PaperAppProps>) {
             const currentState = store.getSnapshot();
 
             // Create a new element
+            const newId = Math.random().toString(36).slice(7);
             const newElement: CustomElement = {
-              id: Math.random().toString(36).slice(7),
+              id: newId,
               label: 'New Node',
               x: Math.random() * 200,
               y: Math.random() * 200,
@@ -242,8 +244,8 @@ function PaperApp({ store }: Readonly<PaperAppProps>) {
             // Update the store with the new element
             // This will automatically sync to the graph and update Jotai atoms
             store.setState({
-              elements: [...currentState.elements, newElement],
-              links: currentState.links as GraphLink[],
+              elements: { ...currentState.elements, [newId]: newElement },
+              links: currentState.links as Record<string, GraphLink>,
             });
           }}
         >
@@ -256,26 +258,33 @@ function PaperApp({ store }: Readonly<PaperAppProps>) {
             // Get current state from the store
             const currentState = store.getSnapshot();
 
-            if (currentState.elements.length === 0) {
+            const elementIds = Object.keys(currentState.elements);
+            if (elementIds.length === 0) {
               return;
             }
 
             // Remove the last element
-            const newElements = currentState.elements.slice(0, -1);
-            const removedElementId = currentState.elements.at(-1)?.id;
+            const removedElementId = elementIds.at(-1);
+            if (!removedElementId) {
+              return;
+            }
+
+            // eslint-disable-next-line sonarjs/no-unused-vars
+            const { [removedElementId]: _removed, ...newElements } = currentState.elements;
 
             // Remove links connected to the removed element
-            const newLinks = removedElementId
-              ? currentState.links.filter(
-                  (link) => link.source !== removedElementId && link.target !== removedElementId
-                )
-              : currentState.links;
+            const newLinks: Record<string, GraphLink> = {};
+            for (const [id, link] of Object.entries(currentState.links)) {
+              if (link.source !== removedElementId && link.target !== removedElementId) {
+                newLinks[id] = link;
+              }
+            }
 
             // Update the store
             // This will automatically sync to the graph and update Jotai atoms
             store.setState({
               elements: newElements,
-              links: newLinks as GraphLink[],
+              links: newLinks,
             });
           }}
         >
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 e7cc8ea9a..9989a5395 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
@@ -47,7 +47,7 @@ import {
 } from '@joint/react';
 import '../../examples/index.css';
 import { PAPER_CLASSNAME, PRIMARY } from 'storybook-config/theme';
-import { useState, useEffect, useRef } from 'react';
+import { useState } from 'react';
 import Peer, { type DataConnection } from 'peerjs';
 import type { GraphStoreSnapshot } from '../../../store/graph-store';
 import type { Update } from '../../../utils/create-state';
@@ -61,14 +61,13 @@ import type { Update } from '../../../utils/create-state';
  */
 type CustomElement = GraphElement & { label: string };
 
-const defaultElements: CustomElement[] = [
-  { id: '1', label: 'Hello', x: 100, y: 0, width: 100, height: 50 },
-  { id: '2', label: 'World', x: 100, y: 200, width: 100, height: 50 },
-];
+const defaultElements: Record<string, CustomElement> = {
+  '1': { label: 'Hello', x: 100, y: 0, width: 100, height: 50 },
+  '2': { label: 'World', x: 100, y: 200, width: 100, height: 50 },
+};
 
-const defaultLinks: GraphLink[] = [
-  {
-    id: 'e1-2',
+const defaultLinks: Record<string, GraphLink> = {
+  'e1-2': {
     source: '1',
     target: '2',
     attrs: {
@@ -77,7 +76,7 @@ const defaultLinks: GraphLink[] = [
       },
     },
   },
-];
+};
 
 // ============================================================================
 // STEP 2: Custom Element Renderer
@@ -102,8 +101,8 @@ function RenderItem(props: CustomElement) {
  */
 interface StateSyncMessage {
   type: 'state-update';
-  elements: GraphElement[];
-  links: GraphLink[];
+  elements: Record<string, GraphElement>;
+  links: Record<string, GraphLink>;
 }
 
 /**
@@ -122,19 +121,19 @@ interface StateSyncMessage {
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected';
 
 function createPeerJSStore(
-  initialElements: GraphElement[],
-  initialLinks: GraphLink[]
+  initialElements: Record<string, GraphElement>,
+  initialLinks: Record<string, GraphLink>,
+  callbacks: {
+    onPeerIdChange: (id: string | null) => void;
+    onConnectionStatusChange: (status: ConnectionStatus) => void;
+    onConnectedPeerIdChange: (id: string | null) => void;
+  }
 ): {
   store: ExternalGraphStore;
   peerId: string | null;
   connectedPeerId: string | null;
   connectionStatus: ConnectionStatus;
   connectToPeer: (remotePeerId: string) => void;
-  setCallbacks: (
-    peerIdCb: (id: string | null) => void,
-    statusCb: (status: ConnectionStatus) => void,
-    connectedIdCb: (id: string | null) => void
-  ) => void;
 } {
   // Local state
   let currentState: GraphStoreSnapshot = {
@@ -218,6 +217,9 @@ function createPeerJSStore(
       // Notify subscribers
       notifySubscribers();
 
+      // eslint-disable-next-line no-console
+      console.log('[PeerJS] setState called, connectionStatus:', connectionStatus, 'connections:', connectionsRef.length);
+
       // Send to peers (if connected and not receiving an update)
       if (connectionStatus === 'connected' && !isReceivingUpdateRef.current) {
         sendStateUpdate(newState);
@@ -225,10 +227,8 @@ function createPeerJSStore(
     },
   };
 
-  // Callbacks for React state updates
-  let onPeerIdChange: ((id: string | null) => void) | null = null;
-  let onConnectionStatusChange: ((status: ConnectionStatus) => void) | null = null;
-  let onConnectedPeerIdChange: ((id: string | null) => void) | null = null;
+  // Callbacks for React state updates (provided at creation time to avoid race conditions)
+  const { onPeerIdChange, onConnectionStatusChange, onConnectedPeerIdChange } = callbacks;
 
   // Initialize PeerJS peer
   const initializePeer = () => {
@@ -237,9 +237,7 @@ function createPeerJSStore(
 
     peer.on('open', (id) => {
       peerId = id;
-      if (onPeerIdChange) {
-        onPeerIdChange(id);
-      }
+      onPeerIdChange(id);
     });
 
     // Handle incoming connections
@@ -247,12 +245,8 @@ function createPeerJSStore(
       connectionStatus = 'connected';
       connectedPeerId = conn.peer;
       connectionsRef.push(conn);
-      if (onConnectionStatusChange) {
-        onConnectionStatusChange('connected');
-      }
-      if (onConnectedPeerIdChange) {
-        onConnectedPeerIdChange(conn.peer);
-      }
+      onConnectionStatusChange('connected');
+      onConnectedPeerIdChange(conn.peer);
 
       // Handle incoming data
       conn.on('data', (data) => {
@@ -268,12 +262,8 @@ function createPeerJSStore(
         if (connectionsRef.length === 0) {
           connectionStatus = 'disconnected';
           connectedPeerId = null;
-          if (onConnectionStatusChange) {
-            onConnectionStatusChange('disconnected');
-          }
-          if (onConnectedPeerIdChange) {
-            onConnectedPeerIdChange(null);
-          }
+          onConnectionStatusChange('disconnected');
+          onConnectedPeerIdChange(null);
         }
       });
     });
@@ -283,9 +273,7 @@ function createPeerJSStore(
       console.error('PeerJS error:', error);
       if (error.type === 'peer-unavailable') {
         connectionStatus = 'disconnected';
-        if (onConnectionStatusChange) {
-          onConnectionStatusChange('disconnected');
-        }
+        onConnectionStatusChange('disconnected');
         alert('Peer not found. Make sure the peer ID is correct and the peer is online.');
       }
     });
@@ -298,32 +286,85 @@ function createPeerJSStore(
     }
 
     connectionStatus = 'connecting';
-    if (onConnectionStatusChange) {
-      onConnectionStatusChange('connecting');
-    }
+    onConnectionStatusChange('connecting');
+
+    // eslint-disable-next-line no-console
+    console.log('[PeerJS] Attempting to connect to:', remotePeerId, 'peerRef.open:', peerRef.open);
 
     const conn = peerRef.connect(remotePeerId);
 
-    conn.on('open', () => {
+    // eslint-disable-next-line no-console
+    console.log('[PeerJS] Connection object created, conn.open:', conn.open);
+
+    // Check underlying WebRTC connection state
+    if (conn.peerConnection) {
+      // eslint-disable-next-line no-console
+      console.log('[PeerJS] RTCPeerConnection state:', conn.peerConnection.connectionState);
+      conn.peerConnection.onconnectionstatechange = () => {
+        // eslint-disable-next-line no-console
+        console.log('[PeerJS] RTCPeerConnection state changed:', conn.peerConnection?.connectionState);
+      };
+      conn.peerConnection.oniceconnectionstatechange = () => {
+        // eslint-disable-next-line no-console
+        console.log('[PeerJS] ICE connection state:', conn.peerConnection?.iceConnectionState);
+      };
+    } else {
+      // eslint-disable-next-line no-console
+      console.log('[PeerJS] peerConnection not yet available');
+    }
+
+    const handleConnectionOpen = () => {
+      // eslint-disable-next-line no-console
+      console.log('[PeerJS] Connection opened to:', remotePeerId);
       connectionStatus = 'connected';
       connectedPeerId = remotePeerId;
       connectionsRef.push(conn);
-      if (onConnectionStatusChange) {
-        onConnectionStatusChange('connected');
-      }
-      if (onConnectedPeerIdChange) {
-        onConnectedPeerIdChange(remotePeerId);
-      }
+      onConnectionStatusChange('connected');
+      onConnectedPeerIdChange(remotePeerId);
 
       // Send current state to the newly connected peer
       sendStateUpdate(currentState);
-    });
+    };
+
+    // Check if connection is already open (can happen before listener is attached)
+    if (conn.open) {
+      // eslint-disable-next-line no-console
+      console.log('[PeerJS] Connection already open, calling handler immediately');
+      handleConnectionOpen();
+    } else {
+      // eslint-disable-next-line no-console
+      console.log('[PeerJS] Connection not yet open, waiting for open event');
+      conn.on('open', handleConnectionOpen);
+
+      // Workaround: PeerJS sometimes doesn't fire 'open' event - poll connection state
+      let connectionHandled = false;
+      const pollInterval = setInterval(() => {
+        // eslint-disable-next-line no-console
+        console.log('[PeerJS] Polling connection state, conn.open:', conn.open);
+        if (conn.open && !connectionHandled) {
+          connectionHandled = true;
+          clearInterval(pollInterval);
+          // eslint-disable-next-line no-console
+          console.log('[PeerJS] Connection opened via polling');
+          handleConnectionOpen();
+        }
+      }, 500);
+
+      // Clear polling after 10 seconds to avoid memory leak
+      setTimeout(() => {
+        clearInterval(pollInterval);
+      }, 10_000);
+    }
 
     conn.on('data', (data) => {
+      // eslint-disable-next-line no-console
+      console.log('[PeerJS] Received data from peer:', data);
       handlePeerUpdate(data as StateSyncMessage);
     });
 
     conn.on('close', () => {
+      // eslint-disable-next-line no-console
+      console.log('[PeerJS] Connection closed');
       const index = connectionsRef.indexOf(conn);
       if (index !== -1) {
         connectionsRef.splice(index, 1);
@@ -331,12 +372,8 @@ function createPeerJSStore(
       if (connectionsRef.length === 0) {
         connectionStatus = 'disconnected';
         connectedPeerId = null;
-        if (onConnectionStatusChange) {
-          onConnectionStatusChange('disconnected');
-        }
-        if (onConnectedPeerIdChange) {
-          onConnectedPeerIdChange(null);
-        }
+        onConnectionStatusChange('disconnected');
+        onConnectedPeerIdChange(null);
       }
     });
 
@@ -344,9 +381,7 @@ function createPeerJSStore(
       // eslint-disable-next-line no-console
       console.error('Connection error:', error);
       connectionStatus = 'disconnected';
-      if (onConnectionStatusChange) {
-        onConnectionStatusChange('disconnected');
-      }
+      onConnectionStatusChange('disconnected');
     });
   };
 
@@ -365,15 +400,6 @@ function createPeerJSStore(
       return connectionStatus;
     },
     connectToPeer,
-    setCallbacks: (
-      peerIdCb: (id: string | null) => void,
-      statusCb: (status: ConnectionStatus) => void,
-      connectedIdCb: (id: string | null) => void
-    ) => {
-      onPeerIdChange = peerIdCb;
-      onConnectionStatusChange = statusCb;
-      onConnectedPeerIdChange = connectedIdCb;
-    },
   };
 }
 
@@ -399,8 +425,9 @@ function PaperApp({ store }: Readonly<PaperAppProps>) {
             const currentState = store.getSnapshot();
 
             // Create a new element
+            const newId = Math.random().toString(36).slice(7);
             const newElement: CustomElement = {
-              id: Math.random().toString(36).slice(7),
+              id: newId,
               label: 'New Node',
               x: Math.random() * 200,
               y: Math.random() * 200,
@@ -411,8 +438,8 @@ function PaperApp({ store }: Readonly<PaperAppProps>) {
             // Update the store with the new element
             // This will automatically sync to peers via PeerJS
             store.setState({
-              elements: [...currentState.elements, newElement],
-              links: [...currentState.links],
+              elements: { ...currentState.elements, [newId]: newElement },
+              links: { ...currentState.links },
             });
           }}
         >
@@ -425,26 +452,32 @@ function PaperApp({ store }: Readonly<PaperAppProps>) {
             // Get current state from the store
             const currentState = store.getSnapshot();
 
-            if (currentState.elements.length === 0) {
+            const elementIds = Object.keys(currentState.elements);
+            if (elementIds.length === 0) {
               return;
             }
 
             // Remove the last element
-            const newElements = currentState.elements.slice(0, -1);
-            const removedElementId = currentState.elements.at(-1)?.id;
+            const removedElementId = elementIds.at(-1);
+            if (!removedElementId) {
+              return;
+            }
+            // eslint-disable-next-line sonarjs/no-unused-vars
+            const { [removedElementId]: _removed, ...newElements } = currentState.elements;
 
             // Remove links connected to the removed element
-            const newLinks = removedElementId
-              ? currentState.links.filter(
-                  (link) => link.source !== removedElementId && link.target !== removedElementId
-                )
-              : currentState.links;
+            const newLinks: Record<string, GraphLink> = {};
+            for (const [id, link] of Object.entries(currentState.links)) {
+              if (link.source !== removedElementId && link.target !== removedElementId) {
+                newLinks[id] = link;
+              }
+            }
 
             // Update the store
             // This will automatically sync to peers via PeerJS
             store.setState({
               elements: newElements,
-              links: [...newLinks],
+              links: newLinks,
             });
           }}
         >
@@ -466,17 +499,19 @@ function Main(props: Readonly<GraphProps>) {
   const [connectionStatus, setConnectionStatus] = useState<ConnectionStatus>('disconnected');
   const [copyFeedback, setCopyFeedback] = useState(false);
 
-  // Create PeerJS store (only once)
-  const peerJSStoreRef = useRef(createPeerJSStore(defaultElements, defaultLinks));
-
-  // Set up callbacks for React state updates
-  useEffect(() => {
-    peerJSStoreRef.current.setCallbacks(setPeerId, setConnectionStatus, setConnectedPeerId);
-  }, []);
+  // Create PeerJS store (only once) with callbacks passed at creation time
+  // This avoids the race condition where peer.on('open') fires before useEffect runs
+  const [peerJSStore] = useState(() =>
+    createPeerJSStore(defaultElements, defaultLinks, {
+      onPeerIdChange: setPeerId,
+      onConnectionStatusChange: setConnectionStatus,
+      onConnectedPeerIdChange: setConnectedPeerId,
+    })
+  );
 
   const handleConnect = () => {
     if (remotePeerId.trim()) {
-      peerJSStoreRef.current.connectToPeer(remotePeerId.trim());
+      peerJSStore.connectToPeer(remotePeerId.trim());
       setConnectionStatus('connecting');
     }
   };
@@ -573,8 +608,8 @@ function Main(props: Readonly<GraphProps>) {
       </div>
 
       {/* Graph */}
-      <GraphProvider {...props} externalStore={peerJSStoreRef.current.store}>
-        <PaperApp store={peerJSStoreRef.current.store} />
+      <GraphProvider {...props} externalStore={peerJSStore.store}>
+        <PaperApp store={peerJSStore.store} />
       </GraphProvider>
     </div>
   );
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 018c490f1..8e3d7f9c6 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,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-dynamic-delete */
 /* 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 */
@@ -71,10 +72,10 @@ import type { Update } from '../../../utils/create-state';
  * History is managed automatically by redux-undo, so we don't need to include it here.
  */
 interface GraphState {
-  /** Array of all elements (nodes) in the graph */
-  readonly elements: GraphElement[];
-  /** Array of all links (edges) in the graph */
-  readonly links: GraphLink[];
+  /** Record of all elements (nodes) in the graph keyed by ID */
+  readonly elements: Record<string, GraphElement>;
+  /** Record of all links (edges) in the graph keyed by ID */
+  readonly links: Record<string, GraphLink>;
 }
 
 // ============================================================================
@@ -89,17 +90,16 @@ type CustomElement = GraphElement & { label: string };
 /**
  * Initial elements for the graph.
  */
-const defaultElements: CustomElement[] = [
-  { id: '1', label: 'Hello', x: 100, y: 0, width: 100, height: 50 },
-  { id: '2', label: 'World', x: 100, y: 200, width: 100, height: 50 },
-];
+const defaultElements: Record<string, CustomElement> = {
+  '1': { label: 'Hello', x: 100, y: 0, width: 100, height: 50 },
+  '2': { label: 'World', x: 100, y: 200, width: 100, height: 50 },
+};
 
 /**
  * Initial links for the graph.
  */
-const defaultLinks: GraphLink[] = [
-  {
-    id: 'e1-2',
+const defaultLinks: Record<string, GraphLink> = {
+  'e1-2': {
     source: '1',
     target: '2',
     attrs: {
@@ -108,7 +108,7 @@ const defaultLinks: GraphLink[] = [
       },
     },
   },
-];
+};
 
 /**
  * Redux slice for managing graph state.
@@ -118,32 +118,40 @@ const defaultLinks: GraphLink[] = [
 const graphSlice = createSlice({
   name: 'graph',
   initialState: {
-    elements: defaultElements as GraphElement[],
-    links: defaultLinks as GraphLink[],
+    elements: defaultElements as Record<string, GraphElement>,
+    links: defaultLinks as Record<string, GraphLink>,
   } satisfies GraphState,
   reducers: {
     /**
      * Adds a new element to the graph.
+     * The element must include an 'id' property that will be used as the key.
      */
-    addElement: (state, action: PayloadAction<GraphElement>) => {
-      state.elements.push(action.payload);
+    addElement: (state, action: PayloadAction<{ id: string } & GraphElement>) => {
+      const { id, ...element } = action.payload;
+      state.elements[id] = element;
     },
     /**
      * Removes the last element from the graph.
      * Also removes all links connected to that element.
      */
     removeLastElement: (state) => {
-      if (state.elements.length === 0) {
+      const elementIds = Object.keys(state.elements);
+      if (elementIds.length === 0) {
         return;
       }
       // Remove the last element
-      const removedElementId = state.elements.at(-1)?.id;
-      state.elements.pop();
+      const removedElementId = elementIds.at(-1);
+      if (!removedElementId) {
+        return;
+      }
+      delete state.elements[removedElementId];
       // Remove all links connected to the removed element
       if (removedElementId) {
-        state.links = state.links.filter(
-          (link) => link.source !== removedElementId && link.target !== removedElementId
-        );
+        for (const [id, link] of Object.entries(state.links)) {
+          if (link.source === removedElementId || link.target === removedElementId) {
+            delete state.links[id];
+          }
+        }
       }
     },
     /**
@@ -414,15 +422,15 @@ function ReduxConnectedPaperApp() {
           onClick={() => {
             // Dispatch Redux action to add a new element
             // redux-undo automatically saves the current state to history
+            const newId = Math.random().toString(36).slice(7);
             const newElement: CustomElement = {
-              id: Math.random().toString(36).slice(7),
               label: 'New Node',
               x: Math.random() * 200,
               y: Math.random() * 200,
               width: 100,
               height: 50,
-            } as CustomElement;
-            dispatch(addElement(newElement));
+            };
+            dispatch(addElement({ id: newId, ...newElement }));
           }}
         >
           Add Element
@@ -495,6 +503,3 @@ function ReduxConnectedPaperApp() {
 export default function App(props: Readonly<GraphProps>) {
   return <Main {...props} />;
 }
-
-
-
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 e414e069a..af2bb6f00 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
@@ -56,14 +56,13 @@ import type { Update } from '../../../utils/create-state';
  */
 type CustomElement = GraphElement & { label: string };
 
-const defaultElements: CustomElement[] = [
-  { id: '1', label: 'Hello', x: 100, y: 0, width: 100, height: 50 },
-  { id: '2', label: 'World', x: 100, y: 200, width: 100, height: 50 },
-];
-
-const defaultLinks: GraphLink[] = [
-  {
-    id: 'e1-2',
+const defaultElements: Record<string, CustomElement> = {
+  '1': { label: 'Hello', x: 100, y: 0, width: 100, height: 50 },
+  '2': { label: 'World', x: 100, y: 200, width: 100, height: 50 },
+};
+
+const defaultLinks: Record<string, GraphLink> = {
+  'e1-2': {
     source: '1',
     target: '2',
     attrs: {
@@ -72,7 +71,7 @@ const defaultLinks: GraphLink[] = [
       },
     },
   },
-];
+};
 
 // ============================================================================
 // STEP 2: Custom Element Renderer
@@ -95,12 +94,12 @@ function RenderItem(props: CustomElement) {
  * Zustand store interface for graph state.
  */
 interface GraphStore {
-  /** Array of all elements (nodes) in the graph */
-  elements: GraphElement[];
-  /** Array of all links (edges) in the graph */
-  links: GraphLink[];
+  /** Record of all elements (nodes) in the graph keyed by ID */
+  elements: Record<string, GraphElement>;
+  /** Record of all links (edges) in the graph keyed by ID */
+  links: Record<string, GraphLink>;
   /** Action to add a new element */
-  addElement: (data: GraphElement) => void;
+  addElement: (id: string, data: GraphElement) => void;
   /** Action to remove the last element */
   removeLastElement: () => void;
   /** Action to update the graph state (used by adapter) */
@@ -112,27 +111,34 @@ interface GraphStore {
  * Zustand stores are simple - just define state and actions in one place.
  */
 const useGraphStore = create<GraphStore>((set) => ({
-  elements: defaultElements as GraphElement[],
-  links: defaultLinks as GraphLink[],
+  elements: defaultElements as Record<string, GraphElement>,
+  links: defaultLinks as Record<string, GraphLink>,
 
-  addElement: (element) => {
+  addElement: (id: string, element: GraphElement) => {
     set((state) => ({
-      elements: [...state.elements, element],
+      elements: { ...state.elements, [id]: element },
     }));
   },
 
   removeLastElement: () => {
     set((state) => {
-      if (state.elements.length === 0) {
+      const elementIds = Object.keys(state.elements);
+      if (elementIds.length === 0) {
+        return state;
+      }
+      const removedElementId = elementIds.at(-1);
+      if (!removedElementId) {
         return state;
       }
-      const removedElementId = state.elements.at(-1)?.id;
-      const newElements = state.elements.slice(0, -1);
-      const newLinks = removedElementId
-        ? state.links.filter(
-            (link) => link.source !== removedElementId && link.target !== removedElementId
-          )
-        : state.links;
+      // eslint-disable-next-line sonarjs/no-unused-vars
+      const { [removedElementId]: _removed, ...newElements } = state.elements;
+
+      const newLinks: Record<string, GraphLink> = {};
+      for (const [id, link] of Object.entries(state.links)) {
+        if (link.source !== removedElementId && link.target !== removedElementId) {
+          newLinks[id] = link;
+        }
+      }
 
       return {
         elements: newElements,
@@ -249,15 +255,15 @@ function PaperApp() {
           className="px-4 py-2 bg-blue-600 hover:bg-blue-700 text-white rounded font-medium transition-colors"
           onClick={() => {
             // Use Zustand action to add a new element
+            const newId = Math.random().toString(36).slice(7);
             const newElement: CustomElement = {
-              id: Math.random().toString(36).slice(7),
               label: 'New Node',
               x: Math.random() * 200,
               y: Math.random() * 200,
               width: 100,
               height: 50,
-            } as CustomElement;
-            addElement(newElement);
+            };
+            addElement(newId, newElement);
           }}
         >
           Add Element
diff --git a/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode.tsx b/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode.tsx
index 7a5c92d21..37f741b1e 100644
--- a/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode.tsx
+++ b/packages/joint-react/src/stories/tutorials/step-by-step/code-controlled-mode.tsx
@@ -1,3 +1,4 @@
+/* eslint-disable sonarjs/no-unused-vars */
 /* eslint-disable sonarjs/pseudo-random */
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
 
@@ -71,10 +72,10 @@ type CustomLink = GraphLink;
  * - x, y: position on the canvas
  * - width, height: dimensions
  */
-const defaultElements: CustomElement[] = [
-  { id: '1', label: 'Hello', x: 100, y: 0, width: 100, height: 50 },
-  { id: '2', label: 'World', x: 100, y: 200, width: 100, height: 50 },
-];
+const defaultElements: Record<string, CustomElement> = {
+  '1': { label: 'Hello', x: 100, y: 0, width: 100, height: 50 },
+  '2': { label: 'World', x: 100, y: 200, width: 100, height: 50 },
+};
 
 /**
  * Initial links (edges) for the graph.
@@ -84,9 +85,8 @@ const defaultElements: CustomElement[] = [
  * - target: id of the target element
  * - attrs: visual attributes (colors, stroke width, etc.)
  */
-const defaultLinks: CustomLink[] = [
-  {
-    id: 'e1-2',
+const defaultLinks: Record<string, CustomLink> = {
+  'e1-2': {
     source: '1',
     target: '2',
     attrs: {
@@ -95,7 +95,7 @@ const defaultLinks: CustomLink[] = [
       },
     },
   },
-];
+};
 
 // ============================================================================
 // STEP 3: Custom Element Renderer
@@ -132,10 +132,10 @@ function RenderItem(props: CustomElement) {
  * In controlled mode, all state changes must go through these setters.
  */
 interface PaperAppProps {
-  /** Function to update the elements array */
-  readonly onElementsChange: Dispatch<SetStateAction<CustomElement[]>>;
-  /** Function to update the links array */
-  readonly onLinksChange: Dispatch<SetStateAction<CustomLink[]>>;
+  /** Function to update the elements Record */
+  readonly onElementsChange: Dispatch<SetStateAction<Record<string, CustomElement>>>;
+  /** Function to update the links Record */
+  readonly onLinksChange: Dispatch<SetStateAction<Record<string, CustomLink>>>;
 }
 
 /**
@@ -230,28 +230,30 @@ function PaperApp({ onElementsChange, onLinksChange }: Readonly<PaperAppProps>)
           type="button"
           className="px-4 py-2 bg-blue-600 hover:bg-blue-700 text-white rounded font-medium transition-colors"
           onClick={() => {
-            // Step 1: Create a new element object
+            // Step 1: Generate a unique ID for the new element
+            // Math.random().toString(36) creates a base-36 string
+            // .slice(7) removes the "0." prefix
+            const newId = Math.random().toString(36).slice(7);
+
+            // Step 2: Create a new element object (without id - id is the Record key)
             // This is just a plain JavaScript object - not a JointJS element yet
             const newElement: CustomElement = {
-              // Generate a unique ID using random string
-              // Math.random().toString(36) creates a base-36 string
-              // .slice(7) removes the "0." prefix
-              id: Math.random().toString(36).slice(7),
               label: 'New Node',
               // Random position to spread elements across the canvas
               x: Math.random() * 200,
               y: Math.random() * 200,
               width: 100,
               height: 50,
-            } as CustomElement;
+            };
 
-            // Step 2: Update React state using functional update
+            // Step 3: Update React state using functional update
             // This is the KEY to controlled mode - we update state, not the graph
             // The functional form (prev) => newValue ensures we use the latest state
             onElementsChange((elements) => {
-              // Create a new array with all existing elements plus the new one
-              // We use spread operator to create a new array (immutability)
-              return [...elements, newElement];
+              // Create a new Record with all existing elements plus the new one
+              // We use spread operator to create a new object (immutability)
+              // The id is the key, not a property of the element
+              return { ...elements, [newId]: newElement };
             });
 
             // Step 3: That's it! GraphProvider will handle the rest:
@@ -306,24 +308,28 @@ function PaperApp({ onElementsChange, onLinksChange }: Readonly<PaperAppProps>)
             // Step 1: Update elements state by removing the last element
             onElementsChange((elements) => {
               // Check if there are any elements to remove
-              if (elements.length === 0) {
+              const elementIds = Object.keys(elements);
+              if (elementIds.length === 0) {
                 // No elements to remove, return current state unchanged
                 return elements;
               }
 
-              // Create a new array without the last element
-              // slice(0, -1) returns all elements except the last one
-              const newElements = elements.slice(0, -1);
+              // Create a new Record without the last element
+              const removedElementId = elementIds.at(-1);
+              if (!removedElementId) {
+                return elements;
+              }
+              const { [removedElementId]: _, ...newElements } = elements;
 
               // Step 2: If no elements remain, clear all links
               // Links require source and target elements to exist
               // If we remove all elements, links become invalid
-              if (newElements.length === 0) {
+              if (Object.keys(newElements).length === 0) {
                 // Clear all links since there are no elements left
-                onLinksChange([]);
+                onLinksChange({});
               }
 
-              // Return the new elements array
+              // Return the new elements Record
               return newElements;
             });
 
@@ -381,8 +387,8 @@ function PaperApp({ onElementsChange, onLinksChange }: Readonly<PaperAppProps>)
 function Main(props: Readonly<GraphProps>) {
   // Create React state for elements and links
   // These are the single source of truth for the graph
-  const [elements, setElements] = useState<GraphElement[]>(defaultElements);
-  const [links, setLinks] = useState<GraphLink[]>(defaultLinks);
+  const [elements, setElements] = useState<Record<string, GraphElement>>(defaultElements);
+  const [links, setLinks] = useState<Record<string, GraphLink>>(defaultLinks);
 
   return (
     <GraphProvider
@@ -395,14 +401,14 @@ function Main(props: Readonly<GraphProps>) {
       onElementsChange={setElements}
       onLinksChange={setLinks}
     >
-      {/* 
+      {/*
         Pass state setters to child component so it can update the graph
         by updating React state. The type assertions are needed because
         GraphElement/GraphLink are more generic than CustomElement/CustomLink.
       */}
       <PaperApp
-        onElementsChange={setElements as Dispatch<SetStateAction<CustomElement[]>>}
-        onLinksChange={setLinks as Dispatch<SetStateAction<CustomLink[]>>}
+        onElementsChange={setElements as Dispatch<SetStateAction<Record<string, CustomElement>>>}
+        onLinksChange={setLinks as Dispatch<SetStateAction<Record<string, CustomLink>>>}
       />
     </GraphProvider>
   );
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 e00cc65a3..bacdb65b0 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
@@ -14,16 +14,15 @@ import { BUTTON_CLASSNAME } from 'storybook-config/theme';
 // Define element type with custom properties
 type CustomElement = GraphElement & { data: { label: string } };
 
-// Define initial elements
-const initialElements: CustomElement[] = [
-  { id: '1', data: { label: 'Hello' }, x: 100, y: 0, width: 100, height: 25 },
-  { id: '2', data: { label: 'World' }, x: 100, y: 200, width: 100, height: 25 },
-];
+// Define initial elements as Record
+const initialElements: Record<string, CustomElement> = {
+  '1': { data: { label: 'Hello' }, x: 100, y: 0, width: 100, height: 25 },
+  '2': { data: { label: 'World' }, x: 100, y: 200, width: 100, height: 25 },
+};
 
-// Define initial edges
-const initialEdges: GraphLink[] = [
-  {
-    id: 'e1-2',
+// Define initial edges as Record
+const initialEdges: Record<string, GraphLink> = {
+  'e1-2': {
     source: '1',
     target: '2',
     type: 'standard.Link', // If you define type, it provides intellisense support
@@ -34,7 +33,7 @@ const initialEdges: GraphLink[] = [
       },
     },
   },
-];
+};
 
 let zoomLevel = 1;
 
@@ -114,7 +113,6 @@ function Main() {
 export default function App(props: Readonly<GraphProps>) {
   return (
     <GraphProvider
-      areBatchUpdatesDisabled
       {...props}
       links={initialEdges}
       elements={initialElements}
diff --git a/packages/joint-react/src/stories/tutorials/step-by-step/code-html.tsx b/packages/joint-react/src/stories/tutorials/step-by-step/code-html.tsx
index ee143f8e4..de2b199ba 100644
--- a/packages/joint-react/src/stories/tutorials/step-by-step/code-html.tsx
+++ b/packages/joint-react/src/stories/tutorials/step-by-step/code-html.tsx
@@ -14,16 +14,15 @@ import { PAPER_CLASSNAME, PRIMARY } from 'storybook-config/theme';
 // define element type with custom properties
 type CustomElement = GraphElement & { label: string };
 
-// define initial elements
-const initialElements: CustomElement[] = [
-  { id: '1', label: 'Hello', x: 100, y: 0, width: 100, height: 50 },
-  { id: '2', label: 'World', x: 100, y: 200, width: 100, height: 50 },
-];
+// define initial elements as Record
+const initialElements: Record<string, CustomElement> = {
+  '1': { label: 'Hello', x: 100, y: 0, width: 100, height: 50 },
+  '2': { label: 'World', x: 100, y: 200, width: 100, height: 50 },
+};
 
-// define initial edges
-const initialEdges: GraphLink[] = [
-  {
-    id: 'e1-2',
+// define initial edges as Record
+const initialEdges: Record<string, GraphLink> = {
+  'e1-2': {
     source: '1',
     target: '2',
     type: 'standard.Link', // if define type, it provide intellisense support
@@ -34,7 +33,7 @@ const initialEdges: GraphLink[] = [
       },
     },
   },
-];
+};
 function RenderItem(props: CustomElement) {
   const { label, width, height } = props;
   const elementRef = React.useRef<HTMLDivElement>(null);
diff --git a/packages/joint-react/src/stories/tutorials/step-by-step/code-svg.tsx b/packages/joint-react/src/stories/tutorials/step-by-step/code-svg.tsx
index 69ccfc3e6..7ffeb764c 100644
--- a/packages/joint-react/src/stories/tutorials/step-by-step/code-svg.tsx
+++ b/packages/joint-react/src/stories/tutorials/step-by-step/code-svg.tsx
@@ -12,16 +12,15 @@ import {
 // define element type with custom properties
 type CustomElement = GraphElement & { color: string };
 
-// define initial elements
-const initialElements: CustomElement[] = [
-  { id: '1', color: PRIMARY, x: 100, y: 0, width: 100, height: 25 },
-  { id: '2', color: PRIMARY, x: 100, y: 200, width: 100, height: 25 },
-];
+// define initial elements as Record
+const initialElements: Record<string, CustomElement> = {
+  '1': { color: PRIMARY, x: 100, y: 0, width: 100, height: 25 },
+  '2': { color: PRIMARY, x: 100, y: 200, width: 100, height: 25 },
+};
 
-// define initial edges
-const initialEdges: GraphLink[] = [
-  {
-    id: 'e1-2',
+// define initial edges as Record
+const initialEdges: Record<string, GraphLink> = {
+  'e1-2': {
     source: '1',
     target: '2',
     type: 'standard.Link', // if define type, it provide intellisense support
@@ -32,7 +31,7 @@ const initialEdges: GraphLink[] = [
       },
     },
   },
-];
+};
 
 function RenderItem({ width, height, color }: CustomElement) {
   return <rect rx={10} ry={10} width={width} height={height} fill={color} />;
diff --git a/packages/joint-react/src/stories/tutorials/step-by-step/docs.mdx b/packages/joint-react/src/stories/tutorials/step-by-step/docs.mdx
index 48f6f8182..7f6e6dd27 100644
--- a/packages/joint-react/src/stories/tutorials/step-by-step/docs.mdx
+++ b/packages/joint-react/src/stories/tutorials/step-by-step/docs.mdx
@@ -42,23 +42,23 @@ Welcome! This guide will help you get started with the new `@joint/react` librar
 
 ### a. Elements (Nodes)
 
-Elements are plain objects with at least an `id` and geometry properties (`x`, `y`, `width`, `height`).
+Elements are plain objects with geometry properties (`x`, `y`, `width`, `height`). They are stored as Records keyed by their ID.
 
 ```tsx
-const elements = [
-  { id: '1', label: 'Node 1', x: 100, y: 0, width: 100, height: 25 },
-  { id: '2', label: 'Node 2', x: 100, y: 200, width: 100, height: 25 },
-];
+const elements = {
+  '1': { label: 'Node 1', x: 100, y: 0, width: 100, height: 25 },
+  '2': { label: 'Node 2', x: 100, y: 200, width: 100, height: 25 },
+};
 ```
 
 ### b. Links (Edges)
 
-Links are plain objects with `id`, `source`, and `target` properties.
+Links are plain objects with `source` and `target` properties. They are stored as Records keyed by their ID.
 
 ```tsx
-const links = [
-  { id: 'l1', source: '1', target: '2' },
-];
+const links = {
+  'l1': { source: '1', target: '2' },
+};
 ```
 
 ---
@@ -207,10 +207,10 @@ ${CodeControlledMode}
 
 #### How It Works:
 
-1. **State Management**: Use `useState` to manage elements and links:
+1. **State Management**: Use `useState` to manage elements and links as Records:
    ```tsx
-   const [elements, setElements] = useState<GraphElement[]>(defaultElements);
-   const [links, setLinks] = useState<GraphLink[]>(defaultLinks);
+   const [elements, setElements] = useState<Record<string, GraphElement>>(defaultElements);
+   const [links, setLinks] = useState<Record<string, GraphLink>>(defaultLinks);
    ```
 
 2. **Controlled Mode**: Pass state and change handlers to `GraphProvider`:
@@ -489,10 +489,10 @@ You can render multiple `Paper` instances inside one `GraphProvider` to create f
 ```tsx
 import { GraphProvider } from '@joint/react';
 
-const elements = [
-  { id: '1', label: 'A', x: 50, y: 50, width: 80, height: 40 },
-  { id: '2', label: 'B', x: 250, y: 180, width: 80, height: 40 },
-];
+const elements = {
+  '1': { label: 'A', x: 50, y: 50, width: 80, height: 40 },
+  '2': { label: 'B', x: 250, y: 180, width: 80, height: 40 },
+};
 
 export function MultiViews() {
   return (
diff --git a/packages/joint-react/src/types/cell.types.ts b/packages/joint-react/src/types/cell.types.ts
deleted file mode 100644
index bd3729e42..000000000
--- a/packages/joint-react/src/types/cell.types.ts
+++ /dev/null
@@ -1,4 +0,0 @@
-import type { dia } from '@joint/core';
-export interface CellWithId {
-  readonly id: dia.Cell.ID;
-}
diff --git a/packages/joint-react/src/types/element-types.ts b/packages/joint-react/src/types/element-types.ts
index 8dcfe8d50..5b5cef451 100644
--- a/packages/joint-react/src/types/element-types.ts
+++ b/packages/joint-react/src/types/element-types.ts
@@ -25,10 +25,6 @@ export interface StandardShapesTypeMapper {
 export type StandardShapesType = keyof StandardShapesTypeMapper;
 
 export interface GraphElement extends Record<string, unknown> {
-  /**
-   * Unique identifier of the element.
-   */
-  id: dia.Cell.ID;
   /**
    * Ports of the element.
    */
diff --git a/packages/joint-react/src/types/link-types.ts b/packages/joint-react/src/types/link-types.ts
index 41dc9dab2..31f3c2b10 100644
--- a/packages/joint-react/src/types/link-types.ts
+++ b/packages/joint-react/src/types/link-types.ts
@@ -14,10 +14,6 @@ export type StandardLinkShapesType = keyof StandardLinkShapesTypeMapper;
  * @see @see https://docs.jointjs.com/learn/features/shapes/links/#dialink
  */
 export interface GraphLink extends Record<string, unknown> {
-  /**
-   * Unique identifier of the link.
-   */
-  readonly id: dia.Cell.ID;
   /**
    * Source element id or endpoint definition.
    */
diff --git a/packages/joint-react/src/types/scheduler.types.ts b/packages/joint-react/src/types/scheduler.types.ts
new file mode 100644
index 000000000..39b1dcadf
--- /dev/null
+++ b/packages/joint-react/src/types/scheduler.types.ts
@@ -0,0 +1,40 @@
+import type { dia } from '@joint/core';
+import type { GraphElement } from './element-types';
+import type { GraphLink } from './link-types';
+
+/**
+ * Unified scheduler data structure for batching all JointJS to React updates.
+ * Uses Maps for efficient add/update and delete operations.
+ * All fields are optional - only include what needs updating.
+ */
+export interface GraphSchedulerData {
+  // Elements
+  readonly elementsToUpdate?: Map<dia.Cell.ID, GraphElement>;
+  readonly elementsToDelete?: Map<dia.Cell.ID, true>;
+
+  // Links
+  readonly linksToUpdate?: Map<dia.Cell.ID, GraphLink>;
+  readonly linksToDelete?: Map<dia.Cell.ID, true>;
+
+  // Ports (nested by element ID)
+  readonly portsToUpdate?: Map<dia.Cell.ID, Map<string, dia.Element.Port>>;
+  readonly portsToDelete?: Map<dia.Cell.ID, Set<string>>;
+
+  // Port Groups (nested by element ID)
+  readonly portGroupsToUpdate?: Map<dia.Cell.ID, Map<string, dia.Element.PortGroup>>;
+  readonly portGroupsToDelete?: Map<dia.Cell.ID, Set<string>>;
+
+  // Link attributes
+  readonly linkAttrsToUpdate?: Map<dia.Cell.ID, Record<string, unknown>>;
+
+  // Labels (nested by link ID)
+  readonly labelsToUpdate?: Map<dia.Cell.ID, Map<string, dia.Link.Label>>;
+  readonly labelsToDelete?: Map<dia.Cell.ID, Set<string>>;
+
+  // Views (for React paper updates)
+  readonly viewsToUpdate?: Map<dia.Cell.ID, dia.CellView>;
+  readonly viewsToDelete?: Map<dia.Cell.ID, true>;
+
+  // Paper update trigger
+  readonly shouldUpdatePaper?: boolean;
+}
diff --git a/packages/joint-react/src/utils/__tests__/get-cell.test.ts b/packages/joint-react/src/utils/__tests__/get-cell.test.ts
index 787bd0119..2a5aa3be6 100644
--- a/packages/joint-react/src/utils/__tests__/get-cell.test.ts
+++ b/packages/joint-react/src/utils/__tests__/get-cell.test.ts
@@ -1,18 +1,15 @@
-import { mapLinkFromGraph } from '../cell/cell-utilities';
+import { createDefaultGraphToLinkMapper } from '../../state/graph-state-selectors';
 import type { dia } from '@joint/core';
 
-describe('cell utilities', () => {
-  let mockCell: dia.Cell;
+describe('graph-state-selectors link mapping', () => {
+  let mockCell: dia.Link;
 
   beforeEach(() => {
     mockCell = {
       id: 'mock-id',
       attributes: {
-        size: { width: 100, height: 50 },
-        position: { x: 10, y: 20 },
         data: { key: 'value' },
         type: 'mock-type',
-        ports: { items: [] },
       },
       get: jest.fn((key) => {
         const mockData: Record<string, unknown> = {
@@ -21,29 +18,27 @@ describe('cell utilities', () => {
           z: 1,
           markup: '<markup>',
           defaultLabel: 'default-label',
-          ports: { items: [] },
         };
         return mockData[key];
       }),
-    } as unknown as dia.Cell;
+    } as unknown as dia.Link;
   });
 
-  describe('linkFromGraph', () => {
+  describe('createDefaultGraphToLinkMapper', () => {
     it('should extract link attributes correctly', () => {
-      const link = mapLinkFromGraph(mockCell);
+      const mapper = createDefaultGraphToLinkMapper(mockCell);
+      const link = mapper();
+      // id is no longer part of GraphLink - it's the Record key
       expect(link).toMatchObject({
-        id: 'mock-id',
         source: 'source-id',
         target: 'target-id',
         type: 'mock-type',
         z: 1,
         markup: '<markup>',
         defaultLabel: 'default-label',
-        data: { key: 'value' },
-        size: { width: 100, height: 50 },
-        position: { x: 10, y: 20 },
-        ports: { items: [] },
+        key: 'value', // data properties are spread to top level
       });
+      expect(link).not.toHaveProperty('id');
     });
   });
 });
diff --git a/packages/joint-react/src/utils/cell/cell-utilities.ts b/packages/joint-react/src/utils/cell/cell-utilities.ts
deleted file mode 100644
index 55f39e364..000000000
--- a/packages/joint-react/src/utils/cell/cell-utilities.ts
+++ /dev/null
@@ -1,100 +0,0 @@
-import { util, type dia } from '@joint/core';
-import { REACT_TYPE } from '../../models/react-element';
-import type { GraphLink } from '../../types/link-types';
-import type { GraphElement } from '../../types/element-types';
-import { getTargetOrSource } from './get-link-targe-and-source-ids';
-
-export type CellOrJsonCell = dia.Cell | dia.Cell.JSON;
-
-/**
- * Converts a link to a graph cell.
- * @param link - The link to convert.
- * @param graph - The graph instance.
- * @returns The cell or JSON cell representation.
- */
-export function mapLinkToGraph(link: GraphLink, graph: dia.Graph): CellOrJsonCell {
-  const source = getTargetOrSource(link.source);
-  const target = getTargetOrSource(link.target);
-  const { attrs, type = 'standard.Link', ...rest } = link;
-
-  // Note: Accessing prototype defaults directly. Consider caching defaults for performance.
-  const defaults = util.result(
-    util.getByPath(graph.layerCollection.cellNamespace, type, '.').prototype,
-    'defaults',
-    {}
-  );
-
-  const mergedLink = {
-    ...rest,
-    type,
-    attrs: util.defaultsDeep({}, attrs as never, defaults.attrs),
-  };
-
-  return {
-    ...mergedLink,
-    type: link.type ?? 'standard.Link',
-    source,
-    target,
-  } as dia.Cell.JSON;
-}
-
-/**
- * Maps a GraphElement to a JointJS Cell or JSON representation.
- * @param element - The element to process.
- * @returns A standard JointJS element or a JSON representation of the element.
- * @group utils
- * @description
- * This function is used to process an element and convert it to a standard JointJS element if needed.
- * It extracts position and size information from the element and creates the appropriate cell representation.
- * @private
- * @example
- * ```ts
- * import { mapElementToGraph } from '@joint/react';
- *
- * const element = { id: '1', x: 10, y: 20, width: 100, height: 50 };
- * const processed = mapElementToGraph(element);
- * ```
- */
-export function mapElementToGraph<T extends GraphElement>(element: T): CellOrJsonCell {
-  const { type = REACT_TYPE, x, y, width, height } = element;
-
-  return {
-    type,
-    position: { x, y },
-    size: { width, height },
-    ...element,
-  } as dia.Cell.JSON;
-}
-
-export type GraphCell<Element extends GraphElement = GraphElement> = Element | GraphLink;
-
-/**
- * Get link via cell
- * @param cell - The cell to get the link from.
- * @returns - The link.
- * @group utils
- * @private
- * @description
- * This function is used to get a link from a cell.
- * It extracts the source, target, and attributes from the cell and returns them as a link.
- * It also adds the id, isElement, isLink, type, z, markup, and defaultLabel to the link.
- * @example
- * ```ts
- * const link = getLink(cell);
- * console.log(link);
- * ```
- */
-export function mapLinkFromGraph<Link extends dia.Link | GraphLink = GraphLink>(
-  cell: dia.Cell<dia.Cell.Attributes>
-): Link {
-  return {
-    ...cell.attributes,
-    id: cell.id,
-    source: cell.get('source') as dia.Cell.ID,
-    target: cell.get('target') as dia.Cell.ID,
-    type: cell.attributes.type,
-    z: cell.get('z'),
-    markup: cell.get('markup'),
-    defaultLabel: cell.get('defaultLabel'),
-  } as Link;
-}
diff --git a/packages/joint-react/src/utils/cell/listen-to-cell-change.ts b/packages/joint-react/src/utils/cell/listen-to-cell-change.ts
index 38813a30c..af7fc8f5f 100644
--- a/packages/joint-react/src/utils/cell/listen-to-cell-change.ts
+++ b/packages/joint-react/src/utils/cell/listen-to-cell-change.ts
@@ -2,10 +2,20 @@ import { mvc, type dia } from '@joint/core';
 
 export type ChangeEvent = 'change' | 'add' | 'remove' | 'reset';
 
+/**
+ * JointJS options object passed through events.
+ * Contains flags like `isUpdateFromReact` to detect update sources.
+ */
+export interface JointJSEventOptions {
+  readonly isUpdateFromReact?: boolean;
+  readonly [key: string]: unknown;
+}
+
 interface OnChangeOptionsBase {
   readonly type: ChangeEvent;
   readonly cells?: dia.Cell[];
   readonly cell?: dia.Cell;
+  readonly options?: JointJSEventOptions;
 }
 interface OnChangeOptionsUpdate extends OnChangeOptionsBase {
   readonly type: 'change' | 'add' | 'remove';
@@ -31,15 +41,26 @@ export function listenToCellChange(
   handleCellsChange: OnChangeHandler
 ): () => void {
   const controller = new mvc.Listener();
-  controller.listenTo(graph, 'change', (cell: dia.Cell) =>
-    handleCellsChange({ type: 'change', cell })
+  controller.listenTo(graph, 'change', (cell: dia.Cell, options: JointJSEventOptions) =>
+    handleCellsChange({ type: 'change', cell, options })
+  );
+  controller.listenTo(
+    graph,
+    'add',
+    (cell: dia.Cell, _collection: mvc.Collection<dia.Cell>, options: JointJSEventOptions) =>
+      handleCellsChange({ type: 'add', cell, options })
   );
-  controller.listenTo(graph, 'add', (cell: dia.Cell) => handleCellsChange({ type: 'add', cell }));
-  controller.listenTo(graph, 'remove', (cell: dia.Cell) =>
-    handleCellsChange({ type: 'remove', cell })
+  controller.listenTo(
+    graph,
+    'remove',
+    (cell: dia.Cell, _collection: mvc.Collection<dia.Cell>, options: JointJSEventOptions) =>
+      handleCellsChange({ type: 'remove', cell, options })
   );
-  controller.listenTo(graph, 'reset', (cells: dia.Cell[]) =>
-    handleCellsChange({ type: 'reset', cells })
+  controller.listenTo(
+    graph,
+    'reset',
+    (collection: mvc.Collection<dia.Cell>, options: JointJSEventOptions) =>
+      handleCellsChange({ type: 'reset', cells: collection.models, options })
   );
 
   return () => controller.stopListening();
diff --git a/packages/joint-react/src/utils/clear-view.ts b/packages/joint-react/src/utils/clear-view.ts
index 32825043a..7a2579145 100644
--- a/packages/joint-react/src/utils/clear-view.ts
+++ b/packages/joint-react/src/utils/clear-view.ts
@@ -4,9 +4,7 @@ interface Options {
   readonly graph: dia.Graph;
   readonly paper: dia.Paper;
   readonly cellId: dia.Cell.ID;
-  readonly onValidateLink?: (link: dia.Link) => boolean;
 }
-const DEFAULT_ON_VALIDATE_LINK = () => true;
 
 /**
  * Clear the view of the cell and the links connected to it.
@@ -21,7 +19,7 @@ const DEFAULT_ON_VALIDATE_LINK = () => true;
  * @param options - The options for the clear view.
  */
 export function clearView(options: Options) {
-  const { graph, paper, cellId, onValidateLink = DEFAULT_ON_VALIDATE_LINK } = options;
+  const { graph, paper, cellId } = options;
   const elementView = paper.findViewByModel(cellId);
   elementView.cleanNodesCache();
   for (const link of graph.getConnectedLinks(elementView.model)) {
@@ -32,11 +30,6 @@ export function clearView(options: Options) {
       continue;
     }
 
-    const isValid = onValidateLink(link);
-    if (!isValid) {
-      continue;
-    }
-
     const linkView = link.findView(paper);
     // @ts-expect-error we use private jointjs api method, it throw error here.
     linkView._sourceMagnet = null;
diff --git a/packages/joint-react/src/utils/is.ts b/packages/joint-react/src/utils/is.ts
index 0335d551d..f7fff5df4 100644
--- a/packages/joint-react/src/utils/is.ts
+++ b/packages/joint-react/src/utils/is.ts
@@ -2,7 +2,12 @@
 import { dia, util } from '@joint/core';
 import type { GraphElement } from '../types/element-types';
 import type { FunctionComponent, JSX } from 'react';
-import type { GraphCell } from './cell/cell-utilities';
+import type { GraphLink } from '../types/link-types';
+
+/**
+ * Represents a cell in the graph (either element or link).
+ */
+export type GraphCell<Element extends GraphElement = GraphElement> = Element | GraphLink;
 
 export type Setter<Value> = (item: Value) => Value;
 
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 3b4737e4a..1bfdf9b63 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-array-as-prop */
+ 
 /* eslint-disable react-perf/jsx-no-new-object-as-prop */
 import { dia } from '@joint/core';
 import '../../stories/examples/index.css';
@@ -40,18 +40,23 @@ const CustomRect = dia.Element.define(
   }
 );
 
-const initialElements = [
-  {
+const initialElements: Record<string, {
+  type: string;
+  id: string;
+  x: number;
+  y: number;
+}> = {
+  'rect1': {
     type: 'CustomRect',
     id: 'rect1',
     x: 80,
     y: 80,
   },
-];
+};
 
 function App() {
   return (
-    <GraphProvider cellNamespace={{ CustomRect }} elements={initialElements} links={[]}>
+    <GraphProvider cellNamespace={{ CustomRect }} elements={initialElements} links={{}}>
       <Paper width={320} height={220} className={PAPER_CLASSNAME} />
     </GraphProvider>
   );
diff --git a/packages/joint-react/src/utils/scheduler-old.ts b/packages/joint-react/src/utils/scheduler-old.ts
deleted file mode 100644
index 5ec990378..000000000
--- a/packages/joint-react/src/utils/scheduler-old.ts
+++ /dev/null
@@ -1,57 +0,0 @@
-// eslint-disable-next-line camelcase
-import { unstable_getCurrentPriorityLevel, unstable_scheduleCallback } from 'scheduler';
-/**
- * Creates a debounced function that uses React's internal scheduler for timing.
- * Multiple calls within the same synchronous execution cycle are batched into a single
- * execution in the next available event loop tick. All callbacks stored by id will be
- * executed when the scheduled work flushes.
- * @param userCallback The function to be debounced and scheduled.
- * @param priorityLevel The priority level to run the task at.
- * @returns A function you call to schedule your work with an optional callback and id.
- */
-export function createScheduler(userCallback: () => void, priorityLevel?: number) {
-  let callbackId: unknown | null = null;
-  const callbacks = new Map<string, (id: string) => void>();
-
-  const effectivePriority =
-    priorityLevel === undefined ? unstable_getCurrentPriorityLevel() : priorityLevel;
-
-  /**
-   * The actual function that processes the batched callbacks.
-   * This runs asynchronously via the scheduler.
-   */
-  const flushScheduledWork = () => {
-    callbackId = null;
-
-    // Collect all ids before clearing
-
-    // Execute all stored callbacks with their respective ids
-    for (const [id, callback] of callbacks) {
-      callback(id);
-    }
-
-    // Execute the main callback for each id after stored callbacks
-    userCallback();
-
-    // Clear all stored callbacks after execution
-    callbacks.clear();
-  };
-
-  /**
-   * This is the function the user calls to schedule a task.
-   * It stores the callback with its id and ensures the flush function is scheduled once.
-   * @param id Optional id string to pass to the callback.
-   * @param callback Optional callback function that receives an id parameter.
-   */
-  return (id?: string, callback?: (id: string) => void) => {
-    if (id !== undefined && callback !== undefined) {
-      // Store callback in map with id as key
-      callbacks.set(id, callback);
-    }
-
-    if (callbackId === null) {
-      // Schedule the flush function if it hasn't been scheduled already
-      callbackId = unstable_scheduleCallback(effectivePriority, flushScheduledWork);
-    }
-  };
-}
diff --git a/packages/joint-react/src/utils/scheduler.ts b/packages/joint-react/src/utils/scheduler.ts
index 5156ff45d..1fded1ac0 100644
--- a/packages/joint-react/src/utils/scheduler.ts
+++ b/packages/joint-react/src/utils/scheduler.ts
@@ -1,7 +1,7 @@
 import {
   unstable_getCurrentPriorityLevel as getCurrentPriorityLevel,
   unstable_scheduleCallback as scheduleCallback,
-} from "scheduler";
+} from 'scheduler';
 
 /**
  * Options for creating a graph updates scheduler.
@@ -28,20 +28,22 @@ export interface GraphUpdatesSchedulerOptions<Data extends object> {
  * @example
  * ```ts
  * interface MyData {
- *   elements?: string[];
- *   links?: string[];
+ *   elementsToUpdate?: Map<string, { id: string; label: string }>;
+ *   elementsToDelete?: Map<string, true>;
  * }
  *
- * const scheduler = new GraphUpdatesScheduler<MyData>({
+ * const scheduler = new Scheduler<MyData>({
  *   onFlush: (data) => {
- *     console.log(data.elements, data.links);
+ *     console.log(data.elementsToUpdate, data.elementsToDelete);
  *   },
  * });
  *
  * // Multiple calls are batched
- * scheduler.scheduleData((prev) => ({ ...prev, elements: ['el1'] }));
- * scheduler.scheduleData((prev) => ({ ...prev, links: ['link1'] }));
- * // onFlush called once with combined result: { elements: ['el1'], links: ['link1'] }
+ * const updateMap = new Map([['el1', { id: 'el1', label: 'Element 1' }]]);
+ * scheduler.scheduleData((prev) => ({ ...prev, elementsToUpdate: updateMap }));
+ * const deleteMap = new Map([['el2', true as const]]);
+ * scheduler.scheduleData((prev) => ({ ...prev, elementsToDelete: deleteMap }));
+ * // onFlush called once with combined result
  * ```
  */
 export class Scheduler<Data extends object> {
@@ -66,10 +68,7 @@ export class Scheduler<Data extends object> {
     this.currentData = updater(this.currentData);
 
     if (this.callbackId === null) {
-      this.callbackId = scheduleCallback(
-        this.effectivePriority,
-        this.flushScheduledWork,
-      );
+      this.callbackId = scheduleCallback(this.effectivePriority, this.flushScheduledWork);
     }
   };
 
diff --git a/packages/joint-react/src/utils/test-wrappers.tsx b/packages/joint-react/src/utils/test-wrappers.tsx
index 1070407c2..00bfd0f38 100644
--- a/packages/joint-react/src/utils/test-wrappers.tsx
+++ b/packages/joint-react/src/utils/test-wrappers.tsx
@@ -58,20 +58,20 @@ export function paperRenderElementWrapper(options: Options): React.JSXElementCon
 
 export const simpleRenderElementWrapper = paperRenderElementWrapper({
   graphProviderProps: {
-    elements: [
-      {
+    elements: {
+      '1': {
         id: '1',
         width: 97,
         height: 99,
       },
-    ],
-    links: [
-      {
+    },
+    links: {
+      '3': {
         id: '3',
         source: '1',
         target: '2',
       },
-    ],
+    },
   },
 });
 
diff --git a/yarn.lock b/yarn.lock
index ff9a99992..62415cb4d 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2751,6 +2751,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@jest/create-cache-key-function@npm:^30.0.0":
+  version: 30.2.0
+  resolution: "@jest/create-cache-key-function@npm:30.2.0"
+  dependencies:
+    "@jest/types": "npm:30.2.0"
+  checksum: 10/7a2dd0efe747c1b2e61825e51ace11e42f278203fae37a3b9462c8d2132394978682ed7094f5ce3d9f5a9e5f2855e6d1d933e5f3ac5165b127c36591f3d98d85
+  languageName: node
+  linkType: hard
+
 "@jest/diff-sequences@npm:30.0.1":
   version: 30.0.1
   resolution: "@jest/diff-sequences@npm:30.0.1"
@@ -3477,6 +3486,8 @@ __metadata:
     "@storybook/react": "npm:8.6.12"
     "@storybook/react-vite": "npm:8.6.12"
     "@storybook/test": "npm:8.6.12"
+    "@swc/core": "npm:^1.15.11"
+    "@swc/jest": "npm:^0.2.39"
     "@testing-library/jest-dom": "npm:^6.6.3"
     "@testing-library/react": "npm:^16.0.1"
     "@testing-library/react-hooks": "npm:^8.0.1"
@@ -3511,7 +3522,6 @@ __metadata:
     storybook: "npm:^8.6.14"
     storybook-addon-performance: "npm:0.17.3"
     storybook-multilevel-sort: "npm:2.1.0"
-    ts-jest: "npm:^29.2.5"
     ts-node: "npm:^10.9.2"
     typedoc: "npm:^0.28.5"
     typedoc-github-theme: "npm:^0.3.0"
@@ -5575,6 +5585,151 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@swc/core-darwin-arm64@npm:1.15.11":
+  version: 1.15.11
+  resolution: "@swc/core-darwin-arm64@npm:1.15.11"
+  conditions: os=darwin & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@swc/core-darwin-x64@npm:1.15.11":
+  version: 1.15.11
+  resolution: "@swc/core-darwin-x64@npm:1.15.11"
+  conditions: os=darwin & cpu=x64
+  languageName: node
+  linkType: hard
+
+"@swc/core-linux-arm-gnueabihf@npm:1.15.11":
+  version: 1.15.11
+  resolution: "@swc/core-linux-arm-gnueabihf@npm:1.15.11"
+  conditions: os=linux & cpu=arm
+  languageName: node
+  linkType: hard
+
+"@swc/core-linux-arm64-gnu@npm:1.15.11":
+  version: 1.15.11
+  resolution: "@swc/core-linux-arm64-gnu@npm:1.15.11"
+  conditions: os=linux & cpu=arm64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@swc/core-linux-arm64-musl@npm:1.15.11":
+  version: 1.15.11
+  resolution: "@swc/core-linux-arm64-musl@npm:1.15.11"
+  conditions: os=linux & cpu=arm64 & libc=musl
+  languageName: node
+  linkType: hard
+
+"@swc/core-linux-x64-gnu@npm:1.15.11":
+  version: 1.15.11
+  resolution: "@swc/core-linux-x64-gnu@npm:1.15.11"
+  conditions: os=linux & cpu=x64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@swc/core-linux-x64-musl@npm:1.15.11":
+  version: 1.15.11
+  resolution: "@swc/core-linux-x64-musl@npm:1.15.11"
+  conditions: os=linux & cpu=x64 & libc=musl
+  languageName: node
+  linkType: hard
+
+"@swc/core-win32-arm64-msvc@npm:1.15.11":
+  version: 1.15.11
+  resolution: "@swc/core-win32-arm64-msvc@npm:1.15.11"
+  conditions: os=win32 & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@swc/core-win32-ia32-msvc@npm:1.15.11":
+  version: 1.15.11
+  resolution: "@swc/core-win32-ia32-msvc@npm:1.15.11"
+  conditions: os=win32 & cpu=ia32
+  languageName: node
+  linkType: hard
+
+"@swc/core-win32-x64-msvc@npm:1.15.11":
+  version: 1.15.11
+  resolution: "@swc/core-win32-x64-msvc@npm:1.15.11"
+  conditions: os=win32 & cpu=x64
+  languageName: node
+  linkType: hard
+
+"@swc/core@npm:^1.15.11":
+  version: 1.15.11
+  resolution: "@swc/core@npm:1.15.11"
+  dependencies:
+    "@swc/core-darwin-arm64": "npm:1.15.11"
+    "@swc/core-darwin-x64": "npm:1.15.11"
+    "@swc/core-linux-arm-gnueabihf": "npm:1.15.11"
+    "@swc/core-linux-arm64-gnu": "npm:1.15.11"
+    "@swc/core-linux-arm64-musl": "npm:1.15.11"
+    "@swc/core-linux-x64-gnu": "npm:1.15.11"
+    "@swc/core-linux-x64-musl": "npm:1.15.11"
+    "@swc/core-win32-arm64-msvc": "npm:1.15.11"
+    "@swc/core-win32-ia32-msvc": "npm:1.15.11"
+    "@swc/core-win32-x64-msvc": "npm:1.15.11"
+    "@swc/counter": "npm:^0.1.3"
+    "@swc/types": "npm:^0.1.25"
+  peerDependencies:
+    "@swc/helpers": ">=0.5.17"
+  dependenciesMeta:
+    "@swc/core-darwin-arm64":
+      optional: true
+    "@swc/core-darwin-x64":
+      optional: true
+    "@swc/core-linux-arm-gnueabihf":
+      optional: true
+    "@swc/core-linux-arm64-gnu":
+      optional: true
+    "@swc/core-linux-arm64-musl":
+      optional: true
+    "@swc/core-linux-x64-gnu":
+      optional: true
+    "@swc/core-linux-x64-musl":
+      optional: true
+    "@swc/core-win32-arm64-msvc":
+      optional: true
+    "@swc/core-win32-ia32-msvc":
+      optional: true
+    "@swc/core-win32-x64-msvc":
+      optional: true
+  peerDependenciesMeta:
+    "@swc/helpers":
+      optional: true
+  checksum: 10/2ee702f6ee39fc68f1e4d03a19191eaa3762d54ab917d5617741196bbe3beba9fb50b1e878af2735f8a42ecdef3632f44acc090611ebf01a0df4dc533a71f5d2
+  languageName: node
+  linkType: hard
+
+"@swc/counter@npm:^0.1.3":
+  version: 0.1.3
+  resolution: "@swc/counter@npm:0.1.3"
+  checksum: 10/df8f9cfba9904d3d60f511664c70d23bb323b3a0803ec9890f60133954173047ba9bdeabce28cd70ba89ccd3fd6c71c7b0bd58be85f611e1ffbe5d5c18616598
+  languageName: node
+  linkType: hard
+
+"@swc/jest@npm:^0.2.39":
+  version: 0.2.39
+  resolution: "@swc/jest@npm:0.2.39"
+  dependencies:
+    "@jest/create-cache-key-function": "npm:^30.0.0"
+    "@swc/counter": "npm:^0.1.3"
+    jsonc-parser: "npm:^3.2.0"
+  peerDependencies:
+    "@swc/core": "*"
+  checksum: 10/a2b7ed6fbb908867e673d1bbff9efde7eee225a57ad75735216ce2005e40c5cfb92285bd807d2058f1c0317e3d48ed71f5577fe85b28bebc80c1bc2c3a03306e
+  languageName: node
+  linkType: hard
+
+"@swc/types@npm:^0.1.25":
+  version: 0.1.25
+  resolution: "@swc/types@npm:0.1.25"
+  dependencies:
+    "@swc/counter": "npm:^0.1.3"
+  checksum: 10/f6741450224892d12df43e5ca7f3cc0287df644dcd672626eb0cc2a3a8e3e875f4b29eb11336f37c7240cf6e010ba59eb3a79f4fb8bee5cbd168dfc1326ff369
+  languageName: node
+  linkType: hard
+
 "@szmarczak/http-timer@npm:^4.0.5":
   version: 4.0.6
   resolution: "@szmarczak/http-timer@npm:4.0.6"
@@ -8956,15 +9111,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"bs-logger@npm:^0.2.6":
-  version: 0.2.6
-  resolution: "bs-logger@npm:0.2.6"
-  dependencies:
-    fast-json-stable-stringify: "npm:2.x"
-  checksum: 10/e6d3ff82698bb3f20ce64fb85355c5716a3cf267f3977abe93bf9c32a2e46186b253f48a028ae5b96ab42bacd2c826766d9ae8cf6892f9b944656be9113cf212
-  languageName: node
-  linkType: hard
-
 "bser@npm:2.1.1":
   version: 2.1.1
   resolution: "bser@npm:2.1.1"
@@ -12884,7 +13030,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"fast-json-stable-stringify@npm:2.x, fast-json-stable-stringify@npm:^2.0.0, fast-json-stable-stringify@npm:^2.1.0":
+"fast-json-stable-stringify@npm:^2.0.0, fast-json-stable-stringify@npm:^2.1.0":
   version: 2.1.0
   resolution: "fast-json-stable-stringify@npm:2.1.0"
   checksum: 10/2c20055c1fa43c922428f16ca8bb29f2807de63e5c851f665f7ac9790176c01c3b40335257736b299764a8d383388dabc73c8083b8e1bc3d99f0a941444ec60e
@@ -14300,24 +14446,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"handlebars@npm:^4.7.8":
-  version: 4.7.8
-  resolution: "handlebars@npm:4.7.8"
-  dependencies:
-    minimist: "npm:^1.2.5"
-    neo-async: "npm:^2.6.2"
-    source-map: "npm:^0.6.1"
-    uglify-js: "npm:^3.1.4"
-    wordwrap: "npm:^1.0.0"
-  dependenciesMeta:
-    uglify-js:
-      optional: true
-  bin:
-    handlebars: bin/handlebars
-  checksum: 10/bd528f4dd150adf67f3f857118ef0fa43ff79a153b1d943fa0a770f2599e38b25a7a0dbac1a3611a4ec86970fd2325a81310fb788b5c892308c9f8743bd02e11
-  languageName: node
-  linkType: hard
-
 "happy-dom@npm:^8.1.0":
   version: 8.9.0
   resolution: "happy-dom@npm:8.9.0"
@@ -16595,6 +16723,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"jsonc-parser@npm:^3.2.0":
+  version: 3.3.1
+  resolution: "jsonc-parser@npm:3.3.1"
+  checksum: 10/9b0dc391f20b47378f843ef1e877e73ec652a5bdc3c5fa1f36af0f119a55091d147a86c1ee86a232296f55c929bba174538c2bf0312610e0817a22de131cc3f4
+  languageName: node
+  linkType: hard
+
 "jsonfile@npm:^4.0.0":
   version: 4.0.0
   resolution: "jsonfile@npm:4.0.0"
@@ -17080,13 +17215,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"lodash.memoize@npm:^4.1.2":
-  version: 4.1.2
-  resolution: "lodash.memoize@npm:4.1.2"
-  checksum: 10/192b2168f310c86f303580b53acf81ab029761b9bd9caa9506a019ffea5f3363ea98d7e39e7e11e6b9917066c9d36a09a11f6fe16f812326390d8f3a54a1a6da
-  languageName: node
-  linkType: hard
-
 "lodash.memoize@npm:~3.0.3":
   version: 3.0.4
   resolution: "lodash.memoize@npm:3.0.4"
@@ -17328,7 +17456,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"make-error@npm:^1.1.1, make-error@npm:^1.3.6":
+"make-error@npm:^1.1.1":
   version: 1.3.6
   resolution: "make-error@npm:1.3.6"
   checksum: 10/b86e5e0e25f7f777b77fabd8e2cbf15737972869d852a22b7e73c17623928fccb826d8e46b9951501d3f20e51ad74ba8c59ed584f610526a48f8ccf88aaec402
@@ -23548,46 +23676,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ts-jest@npm:^29.2.5":
-  version: 29.4.6
-  resolution: "ts-jest@npm:29.4.6"
-  dependencies:
-    bs-logger: "npm:^0.2.6"
-    fast-json-stable-stringify: "npm:^2.1.0"
-    handlebars: "npm:^4.7.8"
-    json5: "npm:^2.2.3"
-    lodash.memoize: "npm:^4.1.2"
-    make-error: "npm:^1.3.6"
-    semver: "npm:^7.7.3"
-    type-fest: "npm:^4.41.0"
-    yargs-parser: "npm:^21.1.1"
-  peerDependencies:
-    "@babel/core": ">=7.0.0-beta.0 <8"
-    "@jest/transform": ^29.0.0 || ^30.0.0
-    "@jest/types": ^29.0.0 || ^30.0.0
-    babel-jest: ^29.0.0 || ^30.0.0
-    jest: ^29.0.0 || ^30.0.0
-    jest-util: ^29.0.0 || ^30.0.0
-    typescript: ">=4.3 <6"
-  peerDependenciesMeta:
-    "@babel/core":
-      optional: true
-    "@jest/transform":
-      optional: true
-    "@jest/types":
-      optional: true
-    babel-jest:
-      optional: true
-    esbuild:
-      optional: true
-    jest-util:
-      optional: true
-  bin:
-    ts-jest: cli.js
-  checksum: 10/e0ff9e13f684166d5331808b288043b8054f49a1c2970480a92ba3caec8d0ff20edd092f2a4e7a3ad8fcb9ba4d674bee10ec7ee75046d8066bbe43a7d16cf72e
-  languageName: node
-  linkType: hard
-
 "ts-loader@npm:^9.2.5":
   version: 9.5.4
   resolution: "ts-loader@npm:9.5.4"
@@ -23776,13 +23864,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"type-fest@npm:^4.41.0":
-  version: 4.41.0
-  resolution: "type-fest@npm:4.41.0"
-  checksum: 10/617ace794ac0893c2986912d28b3065ad1afb484cad59297835a0807dc63286c39e8675d65f7de08fafa339afcb8fe06a36e9a188b9857756ae1e92ee8bda212
-  languageName: node
-  linkType: hard
-
 "type-is@npm:~1.6.18":
   version: 1.6.18
   resolution: "type-is@npm:1.6.18"
@@ -24028,7 +24109,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"uglify-js@npm:^3.1.4, uglify-js@npm:^3.5.0":
+"uglify-js@npm:^3.5.0":
   version: 3.19.3
   resolution: "uglify-js@npm:3.19.3"
   bin:
@@ -25610,13 +25691,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"wordwrap@npm:^1.0.0":
-  version: 1.0.0
-  resolution: "wordwrap@npm:1.0.0"
-  checksum: 10/497d40beb2bdb08e6d38754faa17ce20b0bf1306327f80cb777927edb23f461ee1f6bc659b3c3c93f26b08e1cf4b46acc5bae8fda1f0be3b5ab9a1a0211034cd
-  languageName: node
-  linkType: hard
-
 "workerpool@npm:^6.5.1":
   version: 6.5.1
   resolution: "workerpool@npm:6.5.1"

From df4a3a6daf52bd751006c41dbd0f3dd3f771dde3 Mon Sep 17 00:00:00 2001
From: samuelgja <samuel.gjabel@gmail.com>
Date: Fri, 30 Jan 2026 15:37:31 +0700
Subject: [PATCH 3/5] refactor: remove unnecessary 'id' properties from
 elements and links in various components and tests

- Updated GraphProvider stories to remove 'id' from elements and links.
- Cleaned up highlighter tests by removing 'id' from element definitions.
- Adjusted stroke highlighter tests to eliminate 'id' from elements.
- Modified paper tests to remove 'id' from elements and links.
- Refactored port tests to exclude 'id' from elements.
- Updated hooks tests to remove 'id' from elements.
- Cleaned up model tests by removing 'id' from ReactElement and ReactLink instances.
- Adjusted example stories to remove 'id' from elements and links.
---
 .../decorators/with-simple-data.tsx           | 35 ++++++-----
 .../decorators/with-strict-mode.tsx           |  4 +-
 packages/joint-react/README.md                | 23 +++----
 packages/joint-react/eslint.config.mjs        | 18 +++++-
 .../graph/graph-provider.stories.tsx          |  6 +-
 .../__tests__/highlighter-cleanup.test.tsx    |  1 -
 .../highlighters/__tests__/stroke.test.tsx    |  1 -
 .../paper-html-overlay-links.test.tsx         |  9 ++-
 .../components/paper/__tests__/paper.test.tsx | 12 ++--
 .../src/components/paper/paper.stories.tsx    |  8 +--
 .../port/__tests__/port-group.test.tsx        |  1 -
 .../port/__tests__/port-item.test.tsx         |  1 -
 .../components/port/__tests__/port.test.tsx   | 11 +---
 .../components/port/port-group.stories.tsx    |  5 --
 .../src/components/port/port-item.stories.tsx |  5 --
 .../src/hooks/__tests__/use-cell-id.test.tsx  |  1 -
 .../src/hooks/__tests__/use-element.test.tsx  |  2 -
 .../src/hooks/__tests__/use-elements.test.ts  |  3 -
 .../src/hooks/__tests__/use-graph.test.ts     |  1 -
 .../src/hooks/__tests__/use-links.test.ts     |  6 +-
 .../__tests__/use-paper-context.test.tsx      |  1 -
 .../src/hooks/use-cell-actions.stories.tsx    | 23 ++++---
 .../models/__tests__/react-element.test.ts    |  8 +--
 .../src/models/__tests__/react-link.test.ts   | 10 +--
 .../src/models/__tests__/react-paper.test.ts  | 63 +++++++------------
 .../store/create-elements-size-observer.ts    |  4 +-
 .../with-node-update/code-with-color.tsx      | 12 ++--
 .../examples/with-node-update/code.tsx        | 13 ++--
 .../examples/with-rotable-node/code.tsx       | 14 ++---
 .../utils/joint-jsx/jsx-to-markup.stories.tsx |  2 -
 .../joint-react/src/utils/test-wrappers.tsx   |  2 -
 packages/joint-react/tsconfig.json            | 14 ++---
 32 files changed, 137 insertions(+), 182 deletions(-)

diff --git a/packages/joint-react/.storybook/decorators/with-simple-data.tsx b/packages/joint-react/.storybook/decorators/with-simple-data.tsx
index 684ee4ae2..2849d36f5 100644
--- a/packages/joint-react/.storybook/decorators/with-simple-data.tsx
+++ b/packages/joint-react/.storybook/decorators/with-simple-data.tsx
@@ -4,7 +4,7 @@
 // @ts-expect-error do not provide typings.
 import JsonViewer from '@andypf/json-viewer/dist/esm/react/JsonViewer';
 import { useCallback, useRef, type HTMLProps, type JSX, type PropsWithChildren } from 'react';
-import { GraphProvider, useNodeSize, type GraphLink } from '@joint/react';
+import { GraphProvider, useCellId, useNodeSize, type GraphLink } from '@joint/react';
 import { PAPER_CLASSNAME, PRIMARY } from '../theme';
 import type { PartialStoryFn, StoryContext } from 'storybook/internal/types';
 import { Paper } from '../../src/components/paper/paper';
@@ -12,19 +12,20 @@ import { Paper } from '../../src/components/paper/paper';
 export type StoryFunction = PartialStoryFn<any, any>;
 export type StoryCtx = StoryContext<any, any>;
 
-export const testElements: Record<string, {
-  id: string;
-  label: string;
-  color: string;
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-  hoverColor: string;
-  angle: number;
-}> = {
+export const testElements: Record<
+  string,
+  {
+    label: string;
+    color: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    hoverColor: string;
+    angle: number;
+  }
+> = {
   '1': {
-    id: '1',
     label: 'Node 1',
     color: PRIMARY,
     x: 100,
@@ -35,7 +36,6 @@ export const testElements: Record<string, {
     angle: 0,
   },
   '2': {
-    id: '2',
     label: 'Node 2',
     color: PRIMARY,
     x: 200,
@@ -50,7 +50,6 @@ export const testElements: Record<string, {
 export type SimpleElement = (typeof testElements)[string];
 export const testLinks: Record<string, GraphLink> = {
   'l-1': {
-    id: 'l-1',
     source: '1',
     target: '2',
     attrs: {
@@ -138,7 +137,11 @@ export function SimpleRenderLinkDecorator(Story: StoryFunction, { args }: StoryC
     <RenderItemDecorator
       renderLink={component}
       // eslint-disable-next-line react-perf/jsx-no-new-function-as-prop
-      renderElement={({ id }) => <HTMLNode className="node">{id}</HTMLNode>}
+      renderElement={() => {
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        const id = useCellId();
+        return <HTMLNode className="node">{id}</HTMLNode>;
+      }}
     />
   );
 }
diff --git a/packages/joint-react/.storybook/decorators/with-strict-mode.tsx b/packages/joint-react/.storybook/decorators/with-strict-mode.tsx
index 02068bd7f..890501326 100644
--- a/packages/joint-react/.storybook/decorators/with-strict-mode.tsx
+++ b/packages/joint-react/.storybook/decorators/with-strict-mode.tsx
@@ -1,6 +1,4 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import React from 'react';
-
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function withStrictMode(Story: any) {
   return (
     //  <React.StrictMode>
diff --git a/packages/joint-react/README.md b/packages/joint-react/README.md
index 7b767bccf..4f2a49d03 100644
--- a/packages/joint-react/README.md
+++ b/packages/joint-react/README.md
@@ -41,8 +41,7 @@ bun add @joint/react
 
 ## 🧭 Core Ideas
 
-- **Elements (nodes)** and **links (edges)** are plain objects.
-- Define **`id` explicitly** and mark it as a literal (`'foo' as const`) so TypeScript keeps it precise.
+- **Elements (nodes)** and **links (edges)** are plain objects stored in a `Record<string, Data>` where the key is the ID.
 - The **`GraphProvider`** component provides the graph context; **`Paper`** renders it.
 - Use hooks like `useElements`, `useLinks`, `useGraph`, `usePaper` for reading/updating state.
 
@@ -50,19 +49,19 @@ bun add @joint/react
 
 ## 🚀 Quick Start (TypeScript)
 
-`id` must be present for every element and link.
+Elements and links are stored in a `Record<string, Data>` where the key is the ID.
 
 ```tsx
 import React from 'react'
 import { GraphProvider } from '@joint/react'
 
 const elements = {
-  'node1': { id: 'node1', label: 'Start', x: 100, y: 50, width: 120, height: 60 },
-  'node2': { id: 'node2', label: 'End',   x: 100, y: 200, width: 120, height: 60 },
+  'node1': { label: 'Start', x: 100, y: 50, width: 120, height: 60 },
+  'node2': { label: 'End',   x: 100, y: 200, width: 120, height: 60 },
 } as const
 
 const links = {
-  'link1': { id: 'link1', source: 'node1', target: 'node2' },
+  'link1': { source: 'node1', target: 'node2' },
 } as const
 
 // Narrow element type straight from the record:
@@ -103,12 +102,12 @@ import React from 'react'
 import { GraphProvider } from '@joint/react'
 
 const elements = {
-  'a': { id: 'a' as const, label: 'A', x: 40,  y: 60,  width: 80, height: 40 },
-  'b': { id: 'b' as const, label: 'B', x: 260, y: 180, width: 80, height: 40 },
+  'a': { label: 'A', x: 40,  y: 60,  width: 80, height: 40 },
+  'b': { label: 'B', x: 260, y: 180, width: 80, height: 40 },
 } as const
 
 const links = {
-  'a-b': { id: 'a-b' as const, source: 'a', target: 'b' },
+  'a-b': { source: 'a', target: 'b' },
 } as const
 
 export function MultiView() {
@@ -169,7 +168,7 @@ import React, { useState } from 'react'
 import { GraphProvider } from '@joint/react'
 
 const initialElements = {
-  'n1': { id: 'n1' as const, label: 'Item', x: 60, y: 60, width: 100, height: 40 },
+  'n1': { label: 'Item', x: 60, y: 60, width: 100, height: 40 },
 } as const
 
 const initialLinks = {} as const
@@ -231,8 +230,7 @@ function MyComponent() {
   const { set, remove } = useCellActions()
 
   const addNode = () => {
-    set({
-      id: 'new-node',
+    set('new-node', {
       x: 100,
       y: 100,
       width: 120,
@@ -288,7 +286,6 @@ export function FitOnMount() {
 
 ## 🧠 Best Practices
 
-- **Define ids as literals**: `id: 'node1' as const` — enables exact typing and prevents mismatches.
 - **Type elements from data**: `type Element = typeof elements[keyof typeof elements]` — reuse data as your source of truth.
 - **Memoize renderers & handlers**: `useCallback` to minimize re-renders.
 - **Keep overlay HTML lightweight**: Prefer simple layout; avoid heavy transforms/animations in `<foreignObject>` (Safari can be picky).
diff --git a/packages/joint-react/eslint.config.mjs b/packages/joint-react/eslint.config.mjs
index 8fabb3401..c822b0ba6 100644
--- a/packages/joint-react/eslint.config.mjs
+++ b/packages/joint-react/eslint.config.mjs
@@ -2,7 +2,19 @@ import { tsConfig, jsConfig, reactTsConfig } from '@joint/eslint-config';
 import { defineConfig } from 'eslint/config';
 
 export default defineConfig([
-    ...jsConfig,
-    ...tsConfig,
-    ...reactTsConfig,
+  {
+    ignores: ['**/*.snap'],
+  },
+  {
+    files: ['src/**/*.{js,jsx,ts,tsx}', '.storybook/**/*.{js,jsx,ts,tsx}'],
+  },
+  ...jsConfig,
+  ...tsConfig,
+  ...reactTsConfig,
+  {
+    files: ['src/stories/tutorials/step-by-step/code-controlled-mode-jotai.tsx'],
+    rules: {
+      'jsdoc/escape-inline-tags': ['warn', { allowedInlineTags: ['joint'] }],
+    },
+  },
 ]);
diff --git a/packages/joint-react/src/components/graph/graph-provider.stories.tsx b/packages/joint-react/src/components/graph/graph-provider.stories.tsx
index 8e7fc33d6..9071b12ba 100644
--- a/packages/joint-react/src/components/graph/graph-provider.stories.tsx
+++ b/packages/joint-react/src/components/graph/graph-provider.stories.tsx
@@ -36,12 +36,12 @@ The **GraphProvider** component provides a shared Graph context for all its desc
 import { GraphProvider, Paper } from '@joint/react';
 
 const elements = {
-  '1': { id: '1', x: 100, y: 100, width: 100, height: 50 },
-  '2': { id: '2', x: 250, y: 200, width: 100, height: 50 },
+  '1': { x: 100, y: 100, width: 100, height: 50 },
+  '2': { x: 250, y: 200, width: 100, height: 50 },
 };
 
 const links = {
-  'l1': { id: 'l1', source: '1', target: '2' },
+  'l1': { source: '1', target: '2' },
 };
 
 function MyDiagram() {
diff --git a/packages/joint-react/src/components/highlighters/__tests__/highlighter-cleanup.test.tsx b/packages/joint-react/src/components/highlighters/__tests__/highlighter-cleanup.test.tsx
index a87012761..526996c5a 100644
--- a/packages/joint-react/src/components/highlighters/__tests__/highlighter-cleanup.test.tsx
+++ b/packages/joint-react/src/components/highlighters/__tests__/highlighter-cleanup.test.tsx
@@ -16,7 +16,6 @@ describe('Highlighter cleanup', () => {
           graph,
           elements: {
             'element-1': {
-              id: 'element-1',
               x: 0,
               y: 0,
               width: 100,
diff --git a/packages/joint-react/src/components/highlighters/__tests__/stroke.test.tsx b/packages/joint-react/src/components/highlighters/__tests__/stroke.test.tsx
index 7ffc6ca0a..43bbaeeba 100644
--- a/packages/joint-react/src/components/highlighters/__tests__/stroke.test.tsx
+++ b/packages/joint-react/src/components/highlighters/__tests__/stroke.test.tsx
@@ -7,7 +7,6 @@ describe('Stroke highlighter', () => {
     graphProviderProps: {
       elements: {
         '1': {
-          id: '1',
           width: 100,
           height: 100,
         },
diff --git a/packages/joint-react/src/components/paper/__tests__/paper-html-overlay-links.test.tsx b/packages/joint-react/src/components/paper/__tests__/paper-html-overlay-links.test.tsx
index 88c2f7d12..4b0f9179d 100644
--- a/packages/joint-react/src/components/paper/__tests__/paper-html-overlay-links.test.tsx
+++ b/packages/joint-react/src/components/paper/__tests__/paper-html-overlay-links.test.tsx
@@ -10,13 +10,12 @@ interface TestElement extends GraphElement {
 }
 
 const elements: Record<string, TestElement> = {
-  '1': { id: '1', label: 'Hello', x: 100, y: 0, width: 100, height: 50 },
-  '2': { id: '2', label: 'World', x: 100, y: 200, width: 100, height: 50 },
+  '1': { label: 'Hello', x: 100, y: 0, width: 100, height: 50 },
+  '2': { label: 'World', x: 100, y: 200, width: 100, height: 50 },
 };
 
 const links: Record<string, GraphLink> = {
   'link-1': {
-    id: 'link-1',
     source: '1',
     target: '2',
   },
@@ -107,8 +106,8 @@ describe('Paper with useHTMLOverlay and links', () => {
     }
 
     const initialElements: Record<string, TestElement> = {
-      '1': { id: '1', label: 'Element1', x: 100, y: 0, width: 100, height: 50 },
-      '2': { id: '2', label: 'Element2', x: 100, y: 200, width: 100, height: 50 },
+      '1': { label: 'Element1', x: 100, y: 0, width: 100, height: 50 },
+      '2': { label: 'Element2', x: 100, y: 200, width: 100, height: 50 },
     };
 
     const { container } = render(
diff --git a/packages/joint-react/src/components/paper/__tests__/paper.test.tsx b/packages/joint-react/src/components/paper/__tests__/paper.test.tsx
index 440fc3b6a..bd16fce35 100644
--- a/packages/joint-react/src/components/paper/__tests__/paper.test.tsx
+++ b/packages/joint-react/src/components/paper/__tests__/paper.test.tsx
@@ -109,9 +109,9 @@ describe('Paper Component', () => {
 
   it('calls onElementsSizeChange when element sizes change', async () => {
     const onElementsSizeChangeMock = jest.fn();
-    const updatedElements: Record<string, { id: string; label: string; width: number; height: number }> = {
-      '1': { id: '1', label: 'Node 1', width: 100, height: 50 },
-      '2': { id: '2', label: 'Node 2', width: 150, height: 75 },
+    const updatedElements: Record<string, { label: string; width: number; height: number }> = {
+      '1': { label: 'Node 1', width: 100, height: 50 },
+      '2': { label: 'Node 2', width: 150, height: 75 },
     };
 
     const { rerender } = render(
@@ -332,9 +332,9 @@ describe('Paper Component', () => {
 
   it('should set elements and positions via react state, when change it via paper api', async () => {
     // Create elements with initial x/y so they can be synced back
-    const elementsWithPosition: Record<string, { id: string; label: string; x: number; y: number; width: number; height: number }> = {
-      '1': { id: '1', label: 'Node 1', x: 0, y: 0, width: 10, height: 10 },
-      '2': { id: '2', label: 'Node 2', x: 0, y: 0, width: 10, height: 10 },
+    const elementsWithPosition: Record<string, { label: string; x: number; y: number; width: number; height: number }> = {
+      '1': { label: 'Node 1', x: 0, y: 0, width: 10, height: 10 },
+      '2': { label: 'Node 2', x: 0, y: 0, width: 10, height: 10 },
     };
     // eslint-disable-next-line unicorn/consistent-function-scoping
     function UpdatePosition() {
diff --git a/packages/joint-react/src/components/paper/paper.stories.tsx b/packages/joint-react/src/components/paper/paper.stories.tsx
index 6f6245287..35c521355 100644
--- a/packages/joint-react/src/components/paper/paper.stories.tsx
+++ b/packages/joint-react/src/components/paper/paper.stories.tsx
@@ -17,6 +17,7 @@ import { getAPILink } from '../../stories/utils/get-api-documentation-link';
 import { makeRootDocumentation } from '../../stories/utils/make-story';
 import { jsx } from '../../utils/joint-jsx/jsx-to-markup';
 import { useCellActions } from '../../hooks/use-cell-actions';
+import { useCellId } from '../../hooks/use-cell-id';
 import { Paper } from './paper';
 import type { RenderElement } from './paper.types';
 import type { GraphElement } from '../../types/element-types';
@@ -345,7 +346,8 @@ export const WithOnClickColorChange: Story = {
     },
   },
   render: () => {
-    const renderElement: RenderElement<SimpleElement> = ({ width, height, hoverColor, id }) => {
+    const renderElement: RenderElement<SimpleElement> = ({ width, height, hoverColor }) => {
+      const id = useCellId();
       const { set } = useCellActions();
       return (
         <div
@@ -363,7 +365,6 @@ export const WithOnClickColorChange: Story = {
           '1': {
             width: 100,
             height: 40,
-            id: '1',
             label: 'Element 1',
             x: 50,
             y: 50,
@@ -372,7 +373,6 @@ export const WithOnClickColorChange: Story = {
           '2': {
             width: 100,
             height: 40,
-            id: '2',
             label: 'Element 1',
             x: 100,
             y: 250,
@@ -381,7 +381,6 @@ export const WithOnClickColorChange: Story = {
         }}
         links={{
           'l1': {
-            id: 'l1',
             source: '1',
             target: '2',
             attrs: {
@@ -458,7 +457,6 @@ export const WithDataWithoutWidthAndHeightAndXAndY: Story = {
         }}
         links={{
           'l1': {
-            id: 'l1',
             source: '1',
             target: '2',
             attrs: {
diff --git a/packages/joint-react/src/components/port/__tests__/port-group.test.tsx b/packages/joint-react/src/components/port/__tests__/port-group.test.tsx
index 477881067..eda9b7c3c 100644
--- a/packages/joint-react/src/components/port/__tests__/port-group.test.tsx
+++ b/packages/joint-react/src/components/port/__tests__/port-group.test.tsx
@@ -23,7 +23,6 @@ describe('PortGroup cleanup', () => {
           graph,
           elements: {
             'element-1': {
-              id: 'element-1',
               x: 0,
               y: 0,
               width: 100,
diff --git a/packages/joint-react/src/components/port/__tests__/port-item.test.tsx b/packages/joint-react/src/components/port/__tests__/port-item.test.tsx
index 958a68a57..c3910b0a7 100644
--- a/packages/joint-react/src/components/port/__tests__/port-item.test.tsx
+++ b/packages/joint-react/src/components/port/__tests__/port-item.test.tsx
@@ -24,7 +24,6 @@ describe('PortItem cleanup', () => {
           graph,
           elements: {
             'element-1': {
-              id: 'element-1',
               x: 0,
               y: 0,
               width: 100,
diff --git a/packages/joint-react/src/components/port/__tests__/port.test.tsx b/packages/joint-react/src/components/port/__tests__/port.test.tsx
index 6c28f5b27..c9dc1a52e 100644
--- a/packages/joint-react/src/components/port/__tests__/port.test.tsx
+++ b/packages/joint-react/src/components/port/__tests__/port.test.tsx
@@ -20,7 +20,6 @@ describe('port', () => {
             graph,
             elements: {
               'element-1': {
-                id: 'element-1',
                 width: 100,
                 height: 100,
               },
@@ -53,9 +52,7 @@ describe('port', () => {
       graphProviderProps: {
         graph,
         elements: {
-          'element-1': {
-            id: 'element-1',
-          },
+          'element-1': {},
         },
       },
     });
@@ -92,9 +89,7 @@ describe('port', () => {
       graphProviderProps: {
         graph,
         elements: {
-          'element-1': {
-            id: 'element-1',
-          },
+          'element-1': {},
         },
       },
     });
@@ -158,7 +153,6 @@ describe('port', () => {
         graph,
         elements: {
           'element-1': {
-            id: 'element-1',
             width: 200,
             height: 100,
           },
@@ -236,7 +230,6 @@ describe('port', () => {
         graph,
         elements: {
           'element-1': {
-            id: 'element-1',
             width: 200,
             height: 100,
             x: 0,
diff --git a/packages/joint-react/src/components/port/port-group.stories.tsx b/packages/joint-react/src/components/port/port-group.stories.tsx
index 7d8e84d2b..c70d007a9 100644
--- a/packages/joint-react/src/components/port/port-group.stories.tsx
+++ b/packages/joint-react/src/components/port/port-group.stories.tsx
@@ -11,21 +11,18 @@ import { makeRootDocumentation, makeStory } from '../../stories/utils/make-story
 import { Paper } from '../paper/paper';
 
 const initialElements: Record<string, {
-  id: string;
   x: number;
   y: number;
   width: number;
   height: number;
 }> = {
   '1': {
-    id: '1',
     x: 100,
     y: 20,
     width: 100,
     height: 50,
   },
   '2': {
-    id: '2',
     x: 200,
     y: 250,
     width: 100,
@@ -34,13 +31,11 @@ const initialElements: Record<string, {
 };
 
 const initialLinks: Record<string, {
-  id: string;
   target: { id: string; port: string };
   source: { id: string; port: string };
   attrs: { line: { stroke: string } };
 }> = {
   'e1-2': {
-    id: 'e1-2',
     target: {
       id: '2',
       port: 'port-one',
diff --git a/packages/joint-react/src/components/port/port-item.stories.tsx b/packages/joint-react/src/components/port/port-item.stories.tsx
index 3e51c1bd7..6ff6e2e16 100644
--- a/packages/joint-react/src/components/port/port-item.stories.tsx
+++ b/packages/joint-react/src/components/port/port-item.stories.tsx
@@ -10,30 +10,25 @@ import { makeRootDocumentation, makeStory } from '../../stories/utils/make-story
 import { Paper } from '../paper/paper';
 
 const initialElements: Record<string, {
-  id: string;
   x: number;
   y: number;
 }> = {
   '1': {
-    id: '1',
     x: 100,
     y: 20,
   },
   '2': {
-    id: '2',
     x: 200,
     y: 250,
   },
 };
 
 const initialLinks: Record<string, {
-  id: string;
   source: { id: string; port: string };
   target: { id: string; port: string };
   attrs: { line: { stroke: string } };
 }> = {
   'link-1': {
-    id: 'link-1',
     source: {
       id: '1',
       port: 'port-one',
diff --git a/packages/joint-react/src/hooks/__tests__/use-cell-id.test.tsx b/packages/joint-react/src/hooks/__tests__/use-cell-id.test.tsx
index 2a82252ac..c2c974503 100644
--- a/packages/joint-react/src/hooks/__tests__/use-cell-id.test.tsx
+++ b/packages/joint-react/src/hooks/__tests__/use-cell-id.test.tsx
@@ -8,7 +8,6 @@ describe('use-cell-id', () => {
       graphProviderProps: {
         elements: {
           'test-cell-id': {
-            id: 'test-cell-id',
             width: 100,
             height: 100,
           },
diff --git a/packages/joint-react/src/hooks/__tests__/use-element.test.tsx b/packages/joint-react/src/hooks/__tests__/use-element.test.tsx
index 8ab1b24ea..dce81f895 100644
--- a/packages/joint-react/src/hooks/__tests__/use-element.test.tsx
+++ b/packages/joint-react/src/hooks/__tests__/use-element.test.tsx
@@ -7,7 +7,6 @@ describe('use-element', () => {
     graphProviderProps: {
       elements: {
         '1': {
-          id: '1',
           width: 100,
           height: 100,
           x: 10,
@@ -32,7 +31,6 @@ describe('use-element', () => {
 
     await waitFor(() => {
       expect(result.current).toBeDefined();
-      expect(result.current.id).toBe('1');
       expect(result.current.width).toBe(100);
       expect(result.current.height).toBe(100);
     });
diff --git a/packages/joint-react/src/hooks/__tests__/use-elements.test.ts b/packages/joint-react/src/hooks/__tests__/use-elements.test.ts
index cfd1de22c..e299797b8 100644
--- a/packages/joint-react/src/hooks/__tests__/use-elements.test.ts
+++ b/packages/joint-react/src/hooks/__tests__/use-elements.test.ts
@@ -6,19 +6,16 @@ describe('use-elements', () => {
   const wrapper = graphProviderWrapper({
     elements: {
       '1': {
-        id: '1',
         width: 97,
         height: 99,
       },
       '2': {
-        id: '2',
         width: 97,
         height: 99,
       },
     },
     links: {
       '3': {
-        id: '3',
         source: '1',
         target: '2',
       },
diff --git a/packages/joint-react/src/hooks/__tests__/use-graph.test.ts b/packages/joint-react/src/hooks/__tests__/use-graph.test.ts
index 9d4828988..ec5fd30ae 100644
--- a/packages/joint-react/src/hooks/__tests__/use-graph.test.ts
+++ b/packages/joint-react/src/hooks/__tests__/use-graph.test.ts
@@ -6,7 +6,6 @@ describe('use-graph', () => {
   const wrapper = graphProviderWrapper({
     elements: {
       '1': {
-        id: '1',
         width: 100,
         height: 100,
       },
diff --git a/packages/joint-react/src/hooks/__tests__/use-links.test.ts b/packages/joint-react/src/hooks/__tests__/use-links.test.ts
index 70670d5b3..29b1aac4b 100644
--- a/packages/joint-react/src/hooks/__tests__/use-links.test.ts
+++ b/packages/joint-react/src/hooks/__tests__/use-links.test.ts
@@ -16,19 +16,16 @@ describe('use-links', () => {
   const wrapper = graphProviderWrapper({
     elements: {
       '1': {
-        id: '1',
         width: 97,
         height: 99,
       },
       '2': {
-        id: '2',
         width: 97,
         height: 99,
       },
     },
     links: {
       '3': {
-        id: '3',
         source: '1',
         target: '2',
       },
@@ -50,7 +47,8 @@ describe('use-links', () => {
     await waitFor(() => {
       expect(renders).toHaveBeenCalledTimes(1);
       expect(Object.keys(result.current).length).toBe(1);
-      expect(result.current['3'].id).toBe('3');
+      expect(result.current['3']).toBeDefined();
+      expect(result.current['3'].source).toBe('1');
     });
   });
 
diff --git a/packages/joint-react/src/hooks/__tests__/use-paper-context.test.tsx b/packages/joint-react/src/hooks/__tests__/use-paper-context.test.tsx
index ea188628f..fc2a86cb7 100644
--- a/packages/joint-react/src/hooks/__tests__/use-paper-context.test.tsx
+++ b/packages/joint-react/src/hooks/__tests__/use-paper-context.test.tsx
@@ -7,7 +7,6 @@ describe('use-paper-context', () => {
     graphProviderProps: {
       elements: {
         '1': {
-          id: '1',
           width: 100,
           height: 100,
         },
diff --git a/packages/joint-react/src/hooks/use-cell-actions.stories.tsx b/packages/joint-react/src/hooks/use-cell-actions.stories.tsx
index 7814bd5fb..efe907a92 100644
--- a/packages/joint-react/src/hooks/use-cell-actions.stories.tsx
+++ b/packages/joint-react/src/hooks/use-cell-actions.stories.tsx
@@ -7,6 +7,7 @@ import { BUTTON_CLASSNAME, PRIMARY } from 'storybook-config/theme';
 import { makeRootDocumentation, makeStory } from '../stories/utils/make-story';
 import { getAPILink } from '../stories/utils/get-api-documentation-link';
 import { useCellActions } from './use-cell-actions';
+import { useCellId } from './use-cell-id';
 
 const API_URL = getAPILink('useCellActions');
 
@@ -97,7 +98,8 @@ function Component() {
 
 export default meta;
 
-function Hook({ label, id }: Readonly<SimpleElement>) {
+function Hook({ label }: Readonly<SimpleElement>) {
+  const id = useCellId();
   const { set } = useCellActions<SimpleElement>();
 
   return (
@@ -116,7 +118,6 @@ export const SetLabel: Story = makeStory<Story>({
   args: {
     label: 'default',
     color: 'red',
-    id: 'default-id',
   },
   apiURL: API_URL,
   code: `import { useCellActions } from '@joint/react'
@@ -139,7 +140,8 @@ export const SetLabel: Story = makeStory<Story>({
   description: 'Set new data for the element.',
 });
 
-function HookSetPosition({ label, id }: Readonly<SimpleElement>) {
+function HookSetPosition({ label }: Readonly<SimpleElement>) {
+  const id = useCellId();
   const { set } = useCellActions<SimpleElement>();
 
   return (
@@ -179,7 +181,8 @@ function HookSetPosition({  label , id }: SimpleElement) {
   description: 'Set the position of the element.',
 });
 
-function HookSetSize({ label, id }: Readonly<SimpleElement>) {
+function HookSetSize({ label }: Readonly<SimpleElement>) {
+  const id = useCellId();
   const { set } = useCellActions<SimpleElement>();
   return (
     <HTMLNode className="node">
@@ -216,7 +219,8 @@ function HookSetSize({  label , id }: SimpleElement) {
   description: 'Set the size of the element.',
 });
 
-function HookSetAngle({ label, id }: Readonly<SimpleElement>) {
+function HookSetAngle({ label }: Readonly<SimpleElement>) {
+  const id = useCellId();
   const { set } = useCellActions<SimpleElement>();
 
   return (
@@ -262,7 +266,8 @@ function HookSetAngle({  label , id }: SimpleElement) {
   description: 'Set the angle of the element.',
 });
 
-function HookSetAny({ label, id }: Readonly<SimpleElement>) {
+function HookSetAny({ label }: Readonly<SimpleElement>) {
+  const id = useCellId();
   const { set } = useCellActions();
 
   return (
@@ -342,7 +347,8 @@ function HookSetAny({  label , id }: SimpleElement) {
 });
 
 // remove elements
-function HookRemoveElement({ label, id }: Readonly<SimpleElement>) {
+function HookRemoveElement({ label }: Readonly<SimpleElement>) {
+  const id = useCellId();
   const { remove } = useCellActions();
 
   return (
@@ -376,7 +382,8 @@ function HookRemoveElement({  label , id }: SimpleElement) {
 });
 
 // set link example
-function HookSetAndRemoveLink({ label, id }: Readonly<SimpleElement>) {
+function HookSetAndRemoveLink({ label }: Readonly<SimpleElement>) {
+  const id = useCellId();
   const { remove, set } = useCellActions();
 
   return (
diff --git a/packages/joint-react/src/models/__tests__/react-element.test.ts b/packages/joint-react/src/models/__tests__/react-element.test.ts
index 83ace4218..93e64ca77 100644
--- a/packages/joint-react/src/models/__tests__/react-element.test.ts
+++ b/packages/joint-react/src/models/__tests__/react-element.test.ts
@@ -11,7 +11,6 @@ describe('react-element', () => {
   describe('ReactElement', () => {
     it('should create a ReactElement instance', () => {
       const element = new ReactElement({
-        id: '1',
         position: { x: 10, y: 20 },
         size: { width: 100, height: 50 },
       });
@@ -23,7 +22,6 @@ describe('react-element', () => {
 
     it('should have default attributes', () => {
       const element = new ReactElement({
-        id: '1',
         position: { x: 10, y: 20 },
         size: { width: 100, height: 50 },
       });
@@ -34,7 +32,6 @@ describe('react-element', () => {
 
     it('should accept custom attributes', () => {
       const element = new ReactElement({
-        id: '1',
         position: { x: 10, y: 20 },
         size: { width: 100, height: 50 },
         data: { custom: 'value' },
@@ -49,7 +46,6 @@ describe('react-element', () => {
       }
 
       const element = new ReactElement<CustomAttributes>({
-        id: '1',
         position: { x: 10, y: 20 },
         size: { width: 100, height: 50 },
       });
@@ -59,7 +55,7 @@ describe('react-element', () => {
 
     describe('markup', () => {
       it('should have empty markup array', () => {
-        const element = new ReactElement({ id: 'test' });
+        const element = new ReactElement();
         expect(element.markup).toEqual([]);
       });
     });
@@ -68,7 +64,6 @@ describe('react-element', () => {
   describe('createElement', () => {
     it('should create a ReactElement instance', () => {
       const element = createElement({
-        id: '1',
         position: { x: 10, y: 20 },
         size: { width: 100, height: 50 },
       });
@@ -86,7 +81,6 @@ describe('react-element', () => {
 
     it('should accept custom attributes', () => {
       const element = createElement({
-        id: '1',
         position: { x: 10, y: 20 },
         size: { width: 100, height: 50 },
         data: { label: 'Test' },
diff --git a/packages/joint-react/src/models/__tests__/react-link.test.ts b/packages/joint-react/src/models/__tests__/react-link.test.ts
index d5bd6dde3..406353395 100644
--- a/packages/joint-react/src/models/__tests__/react-link.test.ts
+++ b/packages/joint-react/src/models/__tests__/react-link.test.ts
@@ -3,7 +3,7 @@ import { ReactLink, REACT_LINK_TYPE } from '../react-link';
 describe('ReactLink', () => {
   describe('markup', () => {
     it('should have wrapper and line path markup for link rendering', () => {
-      const link = new ReactLink({ id: 'test' });
+      const link = new ReactLink();
       expect(link.markup).toEqual([
         {
           tagName: 'path',
@@ -29,14 +29,14 @@ describe('ReactLink', () => {
 
   describe('defaults', () => {
     it('should have REACT_LINK_TYPE as type', () => {
-      const link = new ReactLink({ id: 'test' });
+      const link = new ReactLink();
       expect(link.get('type')).toBe(REACT_LINK_TYPE);
     });
 
     it('should have connection: true attrs for path computation', () => {
       // This is critical for JointJS to compute the link path (d attribute)
       // Without connection: true, the path d attribute will be empty/null
-      const link = new ReactLink({ id: 'test' });
+      const link = new ReactLink();
       const attributes = link.get('attrs');
 
       expect(attributes?.wrapper?.connection).toBe(true);
@@ -44,7 +44,7 @@ describe('ReactLink', () => {
     });
 
     it('should have default stroke and strokeWidth for line', () => {
-      const link = new ReactLink({ id: 'test' });
+      const link = new ReactLink();
       const attributes = link.get('attrs');
 
       expect(attributes?.line?.stroke).toBe('#333333');
@@ -53,7 +53,7 @@ describe('ReactLink', () => {
     });
 
     it('should have default strokeWidth for wrapper (click target)', () => {
-      const link = new ReactLink({ id: 'test' });
+      const link = new ReactLink();
       const attributes = link.get('attrs');
 
       expect(attributes?.wrapper?.strokeWidth).toBe(10);
diff --git a/packages/joint-react/src/models/__tests__/react-paper.test.ts b/packages/joint-react/src/models/__tests__/react-paper.test.ts
index d1fc7d281..c8da6458e 100644
--- a/packages/joint-react/src/models/__tests__/react-paper.test.ts
+++ b/packages/joint-react/src/models/__tests__/react-paper.test.ts
@@ -71,52 +71,47 @@ describe('ReactPaper', () => {
       paper = createPaper();
 
       const element = new shapes.standard.Rectangle({
-        id: 'el1',
         position: { x: 0, y: 0 },
         size: { width: 100, height: 100 },
       });
       graphStore.graph.addCell(element);
 
       // After adding cell, view should be in elementCache
-      expect(elementCache.elementViews['el1']).toBeDefined();
-      expect(elementCache.elementViews['el1'].model).toBe(element);
+      expect(elementCache.elementViews[element.id]).toBeDefined();
+      expect(elementCache.elementViews[element.id].model).toBe(element);
     });
 
     it('should add link view to reactLinkCache when inserted', () => {
       paper = createPaper();
 
       const element1 = new shapes.standard.Rectangle({
-        id: 'el1',
         position: { x: 0, y: 0 },
         size: { width: 100, height: 100 },
       });
       const element2 = new shapes.standard.Rectangle({
-        id: 'el2',
         position: { x: 200, y: 0 },
         size: { width: 100, height: 100 },
       });
       const link = new shapes.standard.Link({
-        id: 'link1',
-        source: { id: 'el1' },
-        target: { id: 'el2' },
+        source: { id: element1.id },
+        target: { id: element2.id },
       });
       graphStore.graph.addCells([element1, element2, link]);
 
-      expect(linkCache.linkViews['link1']).toBeDefined();
-      expect(linkCache.linkViews['link1'].model).toBe(link);
+      expect(linkCache.linkViews[link.id]).toBeDefined();
+      expect(linkCache.linkViews[link.id].model).toBe(link);
     });
 
     it('should set magnet=false on element views', () => {
       paper = createPaper();
 
       const element = new shapes.standard.Rectangle({
-        id: 'el1',
         position: { x: 0, y: 0 },
         size: { width: 100, height: 100 },
       });
       graphStore.graph.addCell(element);
 
-      const view = elementCache.elementViews['el1'];
+      const view = elementCache.elementViews[element.id];
       expect(view.el.getAttribute('magnet')).toBe('false');
     });
 
@@ -124,23 +119,20 @@ describe('ReactPaper', () => {
       paper = createPaper();
 
       const element1 = new shapes.standard.Rectangle({
-        id: 'el1',
         position: { x: 0, y: 0 },
         size: { width: 100, height: 100 },
       });
       const element2 = new shapes.standard.Rectangle({
-        id: 'el2',
         position: { x: 200, y: 0 },
         size: { width: 100, height: 100 },
       });
       const link = new shapes.standard.Link({
-        id: 'link1',
-        source: { id: 'el1' },
-        target: { id: 'el2' },
+        source: { id: element1.id },
+        target: { id: element2.id },
       });
       graphStore.graph.addCells([element1, element2, link]);
 
-      const linkView = linkCache.linkViews['link1'];
+      const linkView = linkCache.linkViews[link.id];
       expect(linkView.el.getAttribute('magnet')).not.toBe('false');
     });
 
@@ -150,7 +142,6 @@ describe('ReactPaper', () => {
       paper = createPaper();
 
       const element = new shapes.standard.Rectangle({
-        id: 'el1',
         position: { x: 0, y: 0 },
         size: { width: 100, height: 100 },
       });
@@ -165,47 +156,42 @@ describe('ReactPaper', () => {
       paper = createPaper();
 
       const element = new shapes.standard.Rectangle({
-        id: 'el1',
         position: { x: 0, y: 0 },
         size: { width: 100, height: 100 },
       });
       graphStore.graph.addCell(element);
-      expect(elementCache.elementViews['el1']).toBeDefined();
+      expect(elementCache.elementViews[element.id]).toBeDefined();
 
       graphStore.graph.removeCells([element]);
-      expect(elementCache.elementViews['el1']).toBeUndefined();
+      expect(elementCache.elementViews[element.id]).toBeUndefined();
     });
 
     it('should remove view from reactLinkCache when link is removed', () => {
       paper = createPaper();
 
       const element1 = new shapes.standard.Rectangle({
-        id: 'el1',
         position: { x: 0, y: 0 },
         size: { width: 100, height: 100 },
       });
       const element2 = new shapes.standard.Rectangle({
-        id: 'el2',
         position: { x: 200, y: 0 },
         size: { width: 100, height: 100 },
       });
       const link = new shapes.standard.Link({
-        id: 'link1',
-        source: { id: 'el1' },
-        target: { id: 'el2' },
+        source: { id: element1.id },
+        target: { id: element2.id },
       });
       graphStore.graph.addCells([element1, element2, link]);
-      expect(linkCache.linkViews['link1']).toBeDefined();
+      expect(linkCache.linkViews[link.id]).toBeDefined();
 
       graphStore.graph.removeCells([link]);
-      expect(linkCache.linkViews['link1']).toBeUndefined();
+      expect(linkCache.linkViews[link.id]).toBeUndefined();
     });
 
     it('should call schedulePaperUpdate when view is removed', () => {
       paper = createPaper();
 
       const element = new shapes.standard.Rectangle({
-        id: 'el1',
         position: { x: 0, y: 0 },
         size: { width: 100, height: 100 },
       });
@@ -227,18 +213,17 @@ describe('ReactPaper', () => {
       });
 
       const element = new shapes.standard.Rectangle({
-        id: 'el1',
         position: { x: 0, y: 0 },
         size: { width: 50, height: 50 },
       });
       graphStore.graph.addCell(element);
-      expect(elementCache.elementViews['el1']).toBeDefined();
+      expect(elementCache.elementViews[element.id]).toBeDefined();
 
       // Get the view and call _hideCellView directly
       const view = paper.findViewByModel(element);
       paper._hideCellView(view);
 
-      expect(elementCache.elementViews['el1']).toBeUndefined();
+      expect(elementCache.elementViews[element.id]).toBeUndefined();
     });
 
     it('should remove link view from reactLinkCache when hidden', () => {
@@ -248,35 +233,31 @@ describe('ReactPaper', () => {
       });
 
       const element1 = new shapes.standard.Rectangle({
-        id: 'el1',
         position: { x: 0, y: 0 },
         size: { width: 50, height: 50 },
       });
       const element2 = new shapes.standard.Rectangle({
-        id: 'el2',
         position: { x: 200, y: 0 },
         size: { width: 50, height: 50 },
       });
       const link = new shapes.standard.Link({
-        id: 'link1',
-        source: { id: 'el1' },
-        target: { id: 'el2' },
+        source: { id: element1.id },
+        target: { id: element2.id },
       });
       graphStore.graph.addCells([element1, element2, link]);
-      expect(linkCache.linkViews['link1']).toBeDefined();
+      expect(linkCache.linkViews[link.id]).toBeDefined();
 
       // Get the link view and call _hideCellView directly
       const linkView = paper.findViewByModel(link);
       paper._hideCellView(linkView);
 
-      expect(linkCache.linkViews['link1']).toBeUndefined();
+      expect(linkCache.linkViews[link.id]).toBeUndefined();
     });
 
     it('should call schedulePaperUpdate when view is hidden', () => {
       paper = createPaper();
 
       const element = new shapes.standard.Rectangle({
-        id: 'el1',
         position: { x: 0, y: 0 },
         size: { width: 100, height: 100 },
       });
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 9acd3cbec..a84ba5534 100644
--- a/packages/joint-react/src/store/create-elements-size-observer.ts
+++ b/packages/joint-react/src/store/create-elements-size-observer.ts
@@ -69,7 +69,9 @@ interface Options {
   /** Options to pass to the ResizeObserver constructor */
   readonly resizeObserverOptions?: ResizeObserverOptions;
   /** Function to get the current size of a cell from the graph */
-  readonly getCellTransform: (id: dia.Cell.ID) => NodeLayoutOptionalXY & { element: dia.Element; angle: number };
+  readonly getCellTransform: (
+    id: dia.Cell.ID
+  ) => NodeLayoutOptionalXY & { element: dia.Element; angle: number };
   /** Function to get the current public snapshot containing all elements */
   readonly getPublicSnapshot: () => MarkDeepReadOnly<GraphStoreSnapshot>;
   /** Callback function called when a batch of elements needs to be updated */
diff --git a/packages/joint-react/src/stories/examples/with-node-update/code-with-color.tsx b/packages/joint-react/src/stories/examples/with-node-update/code-with-color.tsx
index 405e5e34e..536305097 100644
--- a/packages/joint-react/src/stories/examples/with-node-update/code-with-color.tsx
+++ b/packages/joint-react/src/stories/examples/with-node-update/code-with-color.tsx
@@ -1,19 +1,18 @@
 /* eslint-disable react-perf/jsx-no-new-object-as-prop */
 /* eslint-disable react-perf/jsx-no-new-function-as-prop */
-import { GraphProvider, Paper, type GraphLink } from '@joint/react';
+import { GraphProvider, Paper, useCellId, type GraphLink } from '@joint/react';
 import '../index.css';
 import { PRIMARY, LIGHT, PAPER_CLASSNAME } from 'storybook-config/theme';
 import { HTMLNode } from 'storybook-config/decorators/with-simple-data';
 import { useCellActions } from '../../../hooks/use-cell-actions';
 
-const initialElements: Record<string, { id: string; label: string; color: string; x: number; y: number; width: number; height: number }> = {
-  '1': { id: '1', label: 'Node 1', color: PRIMARY, x: 100, y: 0, width: 100, height: 50 },
-  '2': { id: '2', label: 'Node 2', color: PRIMARY, x: 100, y: 200, width: 100, height: 50 },
+const initialElements: Record<string, { label: string; color: string; x: number; y: number; width: number; height: number }> = {
+  '1': { label: 'Node 1', color: PRIMARY, x: 100, y: 0, width: 100, height: 50 },
+  '2': { label: 'Node 2', color: PRIMARY, x: 100, y: 200, width: 100, height: 50 },
 };
 
 const initialEdges: Record<string, GraphLink> = {
   'e1-2': {
-    id: 'e1-2',
     source: '1',
     target: '2',
     attrs: {
@@ -26,7 +25,8 @@ const initialEdges: Record<string, GraphLink> = {
 
 type BaseElementWithData = (typeof initialElements)[string];
 
-function RenderElement({ color, id }: Readonly<BaseElementWithData>) {
+function RenderElement({ color }: Readonly<BaseElementWithData>) {
+  const id = useCellId();
   const { set } = useCellActions<BaseElementWithData>();
   return (
     <HTMLNode
diff --git a/packages/joint-react/src/stories/examples/with-node-update/code.tsx b/packages/joint-react/src/stories/examples/with-node-update/code.tsx
index c55ec7519..b54996b9d 100644
--- a/packages/joint-react/src/stories/examples/with-node-update/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-node-update/code.tsx
@@ -6,14 +6,13 @@ import { useRef } from 'react';
 import { PAPER_CLASSNAME, PRIMARY } from 'storybook-config/theme';
 import { useCellActions } from '../../../hooks/use-cell-actions';
 
-const initialElements: Record<string, { id: string; label: string; color: string; x: number; y: number; width: number; height: number }> = {
-  '1': { id: '1', label: 'Node 1', color: '#ffffff', x: 100, y: 0, width: 100, height: 50 },
-  '2': { id: '2', label: 'Node 2', color: '#ffffff', x: 100, y: 200, width: 100, height: 50 },
+const initialElements: Record<string, { label: string; color: string; x: number; y: number; width: number; height: number }> = {
+  '1': { label: 'Node 1', color: '#ffffff', x: 100, y: 0, width: 100, height: 50 },
+  '2': { label: 'Node 2', color: '#ffffff', x: 100, y: 200, width: 100, height: 50 },
 };
 
 const initialEdges: Record<string, GraphLink> = {
   'e1-2': {
-    id: 'e1-2',
     source: '1',
     target: '2',
     attrs: {
@@ -26,7 +25,7 @@ const initialEdges: Record<string, GraphLink> = {
 
 type BaseElementWithData = (typeof initialElements)[string];
 
-function ElementInput({ id, label }: Readonly<BaseElementWithData>) {
+function ElementInput({ id, label }: Readonly<BaseElementWithData & { id: string }>) {
   const { set } = useCellActions<BaseElementWithData>();
   return (
     <input
@@ -56,8 +55,8 @@ function Main() {
     <div style={{ display: 'flex', flexDirection: 'row' }}>
       <Paper width="100%" className={PAPER_CLASSNAME} height={280} renderElement={RenderElement} />
       <div style={{ display: 'flex', flexDirection: 'column' }}>
-        {Object.values(elements).map((item) => {
-          return <ElementInput key={item.id} {...item} />;
+        {Object.entries(elements).map(([id, item]) => {
+          return <ElementInput key={id} id={id} {...item} />;
         })}
       </div>
     </div>
diff --git a/packages/joint-react/src/stories/examples/with-rotable-node/code.tsx b/packages/joint-react/src/stories/examples/with-rotable-node/code.tsx
index b6e7b6ac5..0f1711d7f 100644
--- a/packages/joint-react/src/stories/examples/with-rotable-node/code.tsx
+++ b/packages/joint-react/src/stories/examples/with-rotable-node/code.tsx
@@ -1,18 +1,17 @@
 /* eslint-disable react-perf/jsx-no-new-object-as-prop */
-import { GraphProvider, Paper, useElements, usePaper, useNodeSize } from '@joint/react';
+import { GraphProvider, Paper, useElements, usePaper, useNodeSize, useCellId } from '@joint/react';
 import '../index.css';
 import { useCallback, useRef } from 'react';
 import { PAPER_CLASSNAME, PRIMARY } from 'storybook-config/theme';
 import { useCellActions } from '../../../hooks/use-cell-actions';
 
-const initialElements: Record<string, { id: string; label: string; x: number; y: number }> = {
-  '1': { id: '1', label: 'Node 1', x: 20, y: 100 },
-  '2': { id: '2', label: 'Node 2', x: 200, y: 100 },
+const initialElements: Record<string, { label: string; x: number; y: number }> = {
+  '1': { label: 'Node 1', x: 20, y: 100 },
+  '2': { label: 'Node 2', x: 200, y: 100 },
 };
 
-const initialEdges: Record<string, { id: string; source: string; target: string; attrs: { line: { stroke: string } } }> = {
+const initialEdges: Record<string, { source: string; target: string; attrs: { line: { stroke: string } } }> = {
   'e1-2': {
-    id: 'e1-2',
     source: '1',
     target: '2',
     attrs: {
@@ -25,7 +24,8 @@ const initialEdges: Record<string, { id: string; source: string; target: string;
 
 type BaseElementWithData = (typeof initialElements)[string];
 
-function RotatableNode({ label, id }: Readonly<BaseElementWithData>) {
+function RotatableNode({ label }: Readonly<BaseElementWithData>) {
+  const id = useCellId();
   const paper = usePaper();
   const { set } = useCellActions();
 
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 1bfdf9b63..72855b8ed 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
@@ -42,13 +42,11 @@ const CustomRect = dia.Element.define(
 
 const initialElements: Record<string, {
   type: string;
-  id: string;
   x: number;
   y: number;
 }> = {
   'rect1': {
     type: 'CustomRect',
-    id: 'rect1',
     x: 80,
     y: 80,
   },
diff --git a/packages/joint-react/src/utils/test-wrappers.tsx b/packages/joint-react/src/utils/test-wrappers.tsx
index 00bfd0f38..1b90db7fe 100644
--- a/packages/joint-react/src/utils/test-wrappers.tsx
+++ b/packages/joint-react/src/utils/test-wrappers.tsx
@@ -60,14 +60,12 @@ export const simpleRenderElementWrapper = paperRenderElementWrapper({
   graphProviderProps: {
     elements: {
       '1': {
-        id: '1',
         width: 97,
         height: 99,
       },
     },
     links: {
       '3': {
-        id: '3',
         source: '1',
         target: '2',
       },
diff --git a/packages/joint-react/tsconfig.json b/packages/joint-react/tsconfig.json
index 891648614..ca1279aa1 100644
--- a/packages/joint-react/tsconfig.json
+++ b/packages/joint-react/tsconfig.json
@@ -1,17 +1,17 @@
 {
   "compilerOptions": {
-    "target": "ES2020",                          // stable JS output
+    "target": "ES2020", // stable JS output
     "lib": ["DOM", "DOM.Iterable", "ESNext"],
-    "module": "ESNext",                          // let Vite handle bundling
-    "moduleResolution": "bundler",               // <- **important**
-    "jsx": "react-jsx",                          // modern JSX transform
-    "declaration": true,                         // emit types for consumers
-    "declarationMap": true,                      // useful if publishing
+    "module": "ESNext", // let Vite handle bundling
+    "moduleResolution": "bundler", // <- **important**
+    "jsx": "react-jsx", // modern JSX transform
+    "declaration": true, // emit types for consumers
+    "declarationMap": true, // useful if publishing
     "emitDeclarationOnly": false,
     "outDir": "lib",
     "esModuleInterop": true,
     "allowSyntheticDefaultImports": true,
-    "isolatedModules": true,                     // good for Vite
+    "isolatedModules": true, // good for Vite
     "strict": true,
     "noFallthroughCasesInSwitch": true,
     "forceConsistentCasingInFileNames": true,

From 33b456ba0dfc7961955948ebe39ba0e46963d4c8 Mon Sep 17 00:00:00 2001
From: samuelgja <samuel.gjabel@gmail.com>
Date: Fri, 30 Jan 2026 21:27:11 +0700
Subject: [PATCH 4/5] fix(joint-react): fix links flickering

---
 .../__tests__/paper-link-flickering.test.tsx  | 363 ++++++++++++++++++
 .../src/components/paper/paper.types.ts       |   2 +-
 .../joint-react/src/hooks/use-node-size.tsx   |   2 +-
 .../src/models/__tests__/react-paper.test.ts  | 282 +++++++++++++-
 .../joint-react/src/models/react-paper.ts     | 125 ++++--
 .../create-elements-size-observer.test.ts     | 288 ++++++++++++++
 .../store/create-elements-size-observer.ts    | 218 ++++++++---
 packages/joint-react/src/store/paper-store.ts |  60 +--
 packages/joint-react/src/store/state-flush.ts |  11 +-
 9 files changed, 1232 insertions(+), 119 deletions(-)
 create mode 100644 packages/joint-react/src/components/paper/__tests__/paper-link-flickering.test.tsx
 create mode 100644 packages/joint-react/src/store/__tests__/create-elements-size-observer.test.ts

diff --git a/packages/joint-react/src/components/paper/__tests__/paper-link-flickering.test.tsx b/packages/joint-react/src/components/paper/__tests__/paper-link-flickering.test.tsx
new file mode 100644
index 000000000..dfad57f5d
--- /dev/null
+++ b/packages/joint-react/src/components/paper/__tests__/paper-link-flickering.test.tsx
@@ -0,0 +1,363 @@
+/* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
+/**
+ * Test suite to catch the "link flickering" bug.
+ *
+ * THE BUG:
+ * When rendering a Paper with elements and links, the visual sequence is:
+ * - Frame 1: Empty screen
+ * - Frame 2: Only links visible (pointing to positions, but no element content)
+ * - Frame 3: Correct render with both elements and links
+ *
+ * This happens because:
+ * - JointJS renders link SVG paths synchronously
+ * - React portals render element content via microtask (later)
+ *
+ * These tests verify the INVARIANT:
+ * "If links are visible with rendered paths, elements must also have their content rendered"
+ */
+import { render, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { GraphProvider, Paper, type GraphElement, type GraphLink } from '../../../index';
+
+/**
+ * Flushes the microtask queue by waiting for a microtask to complete.
+ */
+async function flushMicrotasks(): Promise<void> {
+  await new Promise<void>((resolve) => {
+    queueMicrotask(resolve);
+  });
+}
+
+interface TestElement extends GraphElement {
+  readonly label: string;
+}
+
+const TEST_ELEMENTS: Record<string, TestElement> = {
+  '1': { label: 'Element1', x: 100, y: 0, width: 100, height: 50 },
+  '2': { label: 'Element2', x: 100, y: 200, width: 100, height: 50 },
+};
+
+const TEST_LINKS: Record<string, GraphLink> = {
+  'link-1': {
+    source: '1',
+    target: '2',
+  },
+};
+
+/**
+ * Helper to check the consistency invariant:
+ * If links have rendered paths, elements must have their React content.
+ */
+function checkLinkElementConsistency(container: HTMLElement): {
+  readonly linksHavePaths: boolean;
+  readonly elementsHaveContent: boolean;
+  readonly isConsistent: boolean;
+} {
+  // Check if any link has a rendered path (not empty)
+  const linkPaths = container.querySelectorAll('.joint-link path[joint-selector="line"]');
+  const linksHavePaths = [...linkPaths].some((path) => {
+    const d = path.getAttribute('d');
+    return d && d.length > 0 && d.startsWith('M');
+  });
+
+  // Check if elements have their React content rendered
+  const elementContents = container.querySelectorAll('.element-content');
+  const elementsHaveContent = elementContents.length === Object.keys(TEST_ELEMENTS).length;
+
+  // Consistency: if links are visible, elements must be visible too
+  const isConsistent = !linksHavePaths || elementsHaveContent;
+
+  return { linksHavePaths, elementsHaveContent, isConsistent };
+}
+
+/**
+ * Helper to check that link paths don't point to origin (0,0).
+ * If links render before elements are positioned, they might have M0,0 paths.
+ */
+function checkLinkPathsNotAtOrigin(container: HTMLElement): boolean {
+  const linkPaths = container.querySelectorAll('.joint-link path[joint-selector="line"]');
+
+  for (const path of linkPaths) {
+    const d = path.getAttribute('d');
+    // A path starting with M0,0 or M 0 0 indicates link rendered at origin
+    // This happens when elements haven't been positioned yet
+    if (d && /^M\s*0[,\s]+0/.test(d)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+describe('Paper link flickering prevention', () => {
+  it('INVARIANT: links should not have paths before element content is rendered (SVG mode)', async () => {
+    const { container } = render(
+      <GraphProvider elements={TEST_ELEMENTS} links={TEST_LINKS}>
+        <Paper<TestElement>
+          renderElement={({ label }) => (
+            <foreignObject width="100" height="50">
+              <div className="element-content">{label}</div>
+            </foreignObject>
+          )}
+        />
+      </GraphProvider>
+    );
+
+    // Check consistency at multiple timing points
+    const timingPoints = [
+      'immediate',
+      'microtask-1',
+      'microtask-2',
+      'microtask-3',
+      'microtask-4',
+      'microtask-5',
+    ];
+
+    // Immediate check (before any microtasks)
+    let result = checkLinkElementConsistency(container);
+    if (!result.isConsistent) {
+      throw new Error(
+        `FLICKERING BUG DETECTED at ${timingPoints[0]}: ` +
+          `Links have paths (${result.linksHavePaths}) but elements have no content (${result.elementsHaveContent})`
+      );
+    }
+
+    // Check after each microtask flush
+    for (let index = 1; index <= 5; index++) {
+      await flushMicrotasks();
+      result = checkLinkElementConsistency(container);
+      if (!result.isConsistent) {
+        throw new Error(
+          `FLICKERING BUG DETECTED at ${timingPoints[index]}: ` +
+            `Links have paths (${result.linksHavePaths}) but elements have no content (${result.elementsHaveContent})`
+        );
+      }
+    }
+
+    // Final state should have both links and elements
+    await waitFor(() => {
+      const finalResult = checkLinkElementConsistency(container);
+      expect(finalResult.linksHavePaths).toBe(true);
+      expect(finalResult.elementsHaveContent).toBe(true);
+      expect(finalResult.isConsistent).toBe(true);
+    });
+  });
+
+  it('INVARIANT: links should not have paths before element content is rendered (HTML overlay mode)', async () => {
+    const { container } = render(
+      <GraphProvider elements={TEST_ELEMENTS} links={TEST_LINKS}>
+        <Paper<TestElement>
+          useHTMLOverlay
+          renderElement={({ label }) => <div className="element-content">{label}</div>}
+        />
+      </GraphProvider>
+    );
+
+    // Immediate check
+    let result = checkLinkElementConsistency(container);
+    if (!result.isConsistent) {
+      throw new Error(
+        'FLICKERING BUG DETECTED (immediate): ' +
+          `Links have paths (${result.linksHavePaths}) but elements have no content (${result.elementsHaveContent})`
+      );
+    }
+
+    // Check after microtask flushes
+    for (let index = 0; index < 5; index++) {
+      await flushMicrotasks();
+      result = checkLinkElementConsistency(container);
+      if (!result.isConsistent) {
+        throw new Error(
+          `FLICKERING BUG DETECTED (microtask ${index + 1}): ` +
+            `Links have paths (${result.linksHavePaths}) but elements have no content (${result.elementsHaveContent})`
+        );
+      }
+    }
+
+    // Final state check
+    await waitFor(() => {
+      const finalResult = checkLinkElementConsistency(container);
+      expect(finalResult.linksHavePaths).toBe(true);
+      expect(finalResult.elementsHaveContent).toBe(true);
+    });
+  });
+
+  it('measureNode returns correct model size for ReactElement', async () => {
+    // This test verifies that the measureNode callback is set up correctly.
+    // Note: In jsdom, SVG transform calculations don't work properly, so we can't
+    // verify the final link path coordinates. But we can verify that:
+    // 1. Links render (not blocked)
+    // 2. The link path exists and has valid format
+    // 3. The measureNode fix is applied (verified by other passing tests)
+
+    const { container } = render(
+      <GraphProvider elements={TEST_ELEMENTS} links={TEST_LINKS}>
+        <Paper<TestElement>
+          useHTMLOverlay
+          renderElement={({ label }) => <div className="element-content">{label}</div>}
+        />
+      </GraphProvider>
+    );
+
+    // Wait for link to render
+    await waitFor(
+      () => {
+        const linkPath = container.querySelector('.joint-link path[joint-selector="line"]');
+        expect(linkPath).toBeInTheDocument();
+      },
+      { timeout: 2000 }
+    );
+
+    const linkPath = container.querySelector('.joint-link path[joint-selector="line"]');
+    const d = linkPath?.getAttribute('d');
+
+    // Verify path exists and has valid SVG path format (starts with M)
+    expect(d).toBeTruthy();
+    expect(d?.startsWith('M')).toBe(true);
+
+    // Verify it's not an empty path (M and L should have coordinates)
+    const pathMatch = d?.match(/^M\s*([\d.]+)[,\s]+([\d.]+)\s*L\s*([\d.]+)[,\s]+([\d.]+)/);
+    expect(pathMatch).toBeTruthy();
+
+    // Note: We can't verify exact coordinates in jsdom because SVG transforms
+    // don't work correctly. The real browser will show correct coordinates
+    // because the measureNode callback returns the model's size, which is then
+    // transformed by getRootTranslateMatrix() with the element's position.
+  });
+
+  it('link paths should have correct coordinates (not at origin 0,0)', async () => {
+    const { container } = render(
+      <GraphProvider elements={TEST_ELEMENTS} links={TEST_LINKS}>
+        <Paper<TestElement>
+          useHTMLOverlay
+          renderElement={({ label }) => <div className="element-content">{label}</div>}
+        />
+      </GraphProvider>
+    );
+
+    // Wait for links to render
+    await waitFor(
+      () => {
+        const linkPath = container.querySelector('.joint-link path[joint-selector="line"]');
+        expect(linkPath).toBeInTheDocument();
+        expect(linkPath?.getAttribute('d')).toBeTruthy();
+      },
+      { timeout: 2000 }
+    );
+
+    // Verify paths don't point to origin
+    const pathsValid = checkLinkPathsNotAtOrigin(container);
+    expect(pathsValid).toBe(true);
+
+    // Additionally, verify the path has reasonable coordinates
+    const linkPath = container.querySelector('.joint-link path[joint-selector="line"]');
+    const d = linkPath?.getAttribute('d');
+
+    // Parse first coordinate from path (M x,y ...)
+    const match = d?.match(/^M\s*([\d.]+)[,\s]+([\d.]+)/);
+    if (match) {
+      const x = Number.parseFloat(match[1]);
+      const y = Number.parseFloat(match[2]);
+
+      // The path should start near element 1's position (x: 100, y: 0, width: 100, height: 50)
+      // So the link source point should be around x: 100-200, y: 0-50
+      expect(x).toBeGreaterThan(0);
+      expect(y).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  it('should maintain consistency during initial render (no state changes)', async () => {
+    const { container } = render(
+      <GraphProvider elements={TEST_ELEMENTS} links={TEST_LINKS}>
+        <Paper<TestElement>
+          useHTMLOverlay
+          renderElement={({ label }) => <div className="element-content">{label}</div>}
+        />
+      </GraphProvider>
+    );
+
+    // Check consistency at every microtask boundary
+    for (let index = 0; index < 10; index++) {
+      const result = checkLinkElementConsistency(container);
+      // Log any inconsistency for debugging
+      if (!result.isConsistent) {
+        // eslint-disable-next-line no-console
+        console.warn(`Inconsistency at microtask ${index}: links=${result.linksHavePaths}, elements=${result.elementsHaveContent}`);
+      }
+      await flushMicrotasks();
+    }
+
+    // Final state must have both elements and links
+    await waitFor(() => {
+      const elementContents = container.querySelectorAll('.element-content');
+      expect(elementContents.length).toBe(2);
+
+      const linkPaths = container.querySelectorAll('.joint-link path[joint-selector="line"]');
+      expect(linkPaths.length).toBe(1);
+    });
+  });
+
+  it('records timing of link vs element rendering for debugging', async () => {
+    const timingLog: Array<{
+      readonly timestamp: number;
+      readonly phase: string;
+      readonly linksHavePaths: boolean;
+      readonly elementsHaveContent: boolean;
+    }> = [];
+
+    const startTime = performance.now();
+
+    const { container } = render(
+      <GraphProvider elements={TEST_ELEMENTS} links={TEST_LINKS}>
+        <Paper<TestElement>
+          useHTMLOverlay
+          renderElement={({ label }) => <div className="element-content">{label}</div>}
+        />
+      </GraphProvider>
+    );
+
+    // Log immediately
+    const logState = (phase: string) => {
+      const result = checkLinkElementConsistency(container);
+      timingLog.push({
+        timestamp: performance.now() - startTime,
+        phase,
+        linksHavePaths: result.linksHavePaths,
+        elementsHaveContent: result.elementsHaveContent,
+      });
+    };
+
+    logState('immediate');
+
+    for (let index = 1; index <= 10; index++) {
+      await flushMicrotasks();
+      logState(`microtask-${index}`);
+    }
+
+    // Wait for final state
+    await waitFor(() => {
+      expect(container.querySelector('.element-content')).toBeInTheDocument();
+    });
+
+    logState('final');
+
+    // Find if there was ever a state where links existed but elements didn't
+    const flickeringOccurred = timingLog.some(
+      (entry) => entry.linksHavePaths && !entry.elementsHaveContent
+    );
+
+    if (flickeringOccurred) {
+      // eslint-disable-next-line no-console
+      console.warn('FLICKERING DETECTED! Links rendered before elements.');
+      const flickeringEntries = timingLog.filter(
+        (entry) => entry.linksHavePaths && !entry.elementsHaveContent
+      );
+      // eslint-disable-next-line no-console
+      console.warn('Flickering entries:', flickeringEntries);
+    }
+
+    // This is the actual test assertion
+    expect(flickeringOccurred).toBe(false);
+  });
+});
diff --git a/packages/joint-react/src/components/paper/paper.types.ts b/packages/joint-react/src/components/paper/paper.types.ts
index 379140753..651aecd08 100644
--- a/packages/joint-react/src/components/paper/paper.types.ts
+++ b/packages/joint-react/src/components/paper/paper.types.ts
@@ -13,7 +13,7 @@ export interface OnLoadOptions {
 
 type ReactPaperOptionsBase = OmitWithoutIndexSignature<
   dia.Paper.Options,
-  'frozen' | 'defaultLink' | 'autoFreeze' | 'viewManagement'
+  'frozen' | 'defaultLink' | 'autoFreeze' | 'viewManagement' | 'measureNode'
 >;
 export interface ReactPaperOptions extends ReactPaperOptionsBase {
   /**
diff --git a/packages/joint-react/src/hooks/use-node-size.tsx b/packages/joint-react/src/hooks/use-node-size.tsx
index 1f92ab890..d5f449380 100644
--- a/packages/joint-react/src/hooks/use-node-size.tsx
+++ b/packages/joint-react/src/hooks/use-node-size.tsx
@@ -149,7 +149,7 @@ export function useNodeSize(
     const cell = graph.getCell(id);
     if (!cell?.isElement()) throw new Error('Cell not valid');
     // Check if another useNodeSize hook is already measuring this element
-    if (hasMeasuredNode(id)) {
+    if (hasMeasuredNode(id) && process.env.NODE_ENV !== 'production') {
       const errorMessage =
         process.env.NODE_ENV === 'production'
           ? `Multiple useNodeSize hooks detected for element "${id}". Only one useNodeSize hook can be used per element.`
diff --git a/packages/joint-react/src/models/__tests__/react-paper.test.ts b/packages/joint-react/src/models/__tests__/react-paper.test.ts
index c8da6458e..780d3a58e 100644
--- a/packages/joint-react/src/models/__tests__/react-paper.test.ts
+++ b/packages/joint-react/src/models/__tests__/react-paper.test.ts
@@ -1,9 +1,10 @@
 import { dia, shapes } from '@joint/core';
 import { ReactPaper } from '../react-paper';
+import { ReactElement } from '../react-element';
 import { GraphStore } from '../../store/graph-store';
 import type { ReactElementViewCache, ReactLinkViewCache } from '../../types/paper.types';
 
-const DEFAULT_CELL_NAMESPACE = shapes;
+const DEFAULT_CELL_NAMESPACE = { ...shapes, ReactElement };
 
 describe('ReactPaper', () => {
   let graphStore: GraphStore;
@@ -51,6 +52,13 @@ describe('ReactPaper', () => {
     return p;
   }
 
+  /**
+   * Helper to access private pendingLinks for testing
+   */
+  function getPendingLinks(p: ReactPaper): Set<string> {
+    return (p as unknown as { pendingLinks: Set<string> }).pendingLinks;
+  }
+
   describe('constructor', () => {
     it('should create a paper instance', () => {
       paper = createPaper();
@@ -271,5 +279,277 @@ describe('ReactPaper', () => {
 
       expect(scheduleSpy).toHaveBeenCalled();
     });
+
+    it('should remove link from pendingLinks when hidden', () => {
+      paper = createPaper();
+
+      // Use ReactElement which has empty markup (like real React usage)
+      const element1 = new ReactElement({
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const element2 = new ReactElement({
+        position: { x: 200, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const link = new shapes.standard.Link({
+        source: { id: element1.id },
+        target: { id: element2.id },
+      });
+      graphStore.graph.addCells([element1, element2, link]);
+
+      const pendingLinks = getPendingLinks(paper);
+
+      // Link should be in pending (source/target have no children - ReactElement has empty markup)
+      expect(pendingLinks.has(link.id as string)).toBe(true);
+
+      // Hide the link
+      const linkView = paper.findViewByModel(link);
+      paper._hideCellView(linkView);
+
+      // Should be removed from pending
+      expect(pendingLinks.has(link.id as string)).toBe(false);
+    });
+  });
+
+  describe('pending links visibility', () => {
+    it('should hide link when source element has no children (ReactElement)', () => {
+      paper = createPaper();
+
+      // Use ReactElement which has empty markup (like real React usage)
+      const element1 = new ReactElement({
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const element2 = new ReactElement({
+        position: { x: 200, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const link = new shapes.standard.Link({
+        source: { id: element1.id },
+        target: { id: element2.id },
+      });
+      graphStore.graph.addCells([element1, element2, link]);
+
+      const linkView = linkCache.linkViews[link.id];
+
+      // Link should be hidden (ReactElement has empty markup, no children)
+      expect(linkView.el.style.visibility).toBe('hidden');
+    });
+
+    it('should NOT hide link when using standard shapes with default markup', () => {
+      paper = createPaper();
+
+      // Standard shapes have default markup with children
+      const element1 = new shapes.standard.Rectangle({
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const element2 = new shapes.standard.Rectangle({
+        position: { x: 200, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const link = new shapes.standard.Link({
+        source: { id: element1.id },
+        target: { id: element2.id },
+      });
+      graphStore.graph.addCells([element1, element2, link]);
+
+      const linkView = linkCache.linkViews[link.id];
+      const pendingLinks = getPendingLinks(paper);
+
+      // Standard shapes have children, so link should NOT be hidden or pending
+      expect(linkView.el.style.visibility).toBe('');
+      expect(pendingLinks.has(link.id as string)).toBe(false);
+    });
+
+    it('should add link to pendingLinks when source/target not ready (ReactElement)', () => {
+      paper = createPaper();
+
+      // Use ReactElement which has empty markup
+      const element1 = new ReactElement({
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const element2 = new ReactElement({
+        position: { x: 200, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const link = new shapes.standard.Link({
+        source: { id: element1.id },
+        target: { id: element2.id },
+      });
+      graphStore.graph.addCells([element1, element2, link]);
+
+      const pendingLinks = getPendingLinks(paper);
+
+      expect(pendingLinks.has(link.id as string)).toBe(true);
+    });
+
+    it('should show link when source and target elements have children', () => {
+      paper = createPaper();
+
+      // Use ReactElement which has empty markup
+      const element1 = new ReactElement({
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const element2 = new ReactElement({
+        position: { x: 200, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const link = new shapes.standard.Link({
+        source: { id: element1.id },
+        target: { id: element2.id },
+      });
+      graphStore.graph.addCells([element1, element2, link]);
+
+      const linkView = linkCache.linkViews[link.id];
+      const element1View = elementCache.elementViews[element1.id];
+      const element2View = elementCache.elementViews[element2.id];
+
+      // Initially hidden
+      expect(linkView.el.style.visibility).toBe('hidden');
+
+      // Simulate React rendering children by adding child elements
+      const child1 = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
+      const child2 = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
+      element1View.el.append(child1);
+      element2View.el.append(child2);
+
+      // Call checkPendingLinks to process
+      paper.checkPendingLinks();
+
+      // Link should now be visible
+      expect(linkView.el.style.visibility).toBe('');
+    });
+
+    it('should remove link from pendingLinks after showing', () => {
+      paper = createPaper();
+
+      // Use ReactElement which has empty markup
+      const element1 = new ReactElement({
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const element2 = new ReactElement({
+        position: { x: 200, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const link = new shapes.standard.Link({
+        source: { id: element1.id },
+        target: { id: element2.id },
+      });
+      graphStore.graph.addCells([element1, element2, link]);
+
+      const pendingLinks = getPendingLinks(paper);
+      const element1View = elementCache.elementViews[element1.id];
+      const element2View = elementCache.elementViews[element2.id];
+
+      // Initially in pending
+      expect(pendingLinks.has(link.id as string)).toBe(true);
+
+      // Simulate React rendering children
+      element1View.el.append(document.createElementNS('http://www.w3.org/2000/svg', 'rect'));
+      element2View.el.append(document.createElementNS('http://www.w3.org/2000/svg', 'rect'));
+
+      paper.checkPendingLinks();
+
+      // Should be removed from pending
+      expect(pendingLinks.has(link.id as string)).toBe(false);
+    });
+
+    it('should not show link if only source is ready', () => {
+      paper = createPaper();
+
+      // Use ReactElement which has empty markup
+      const element1 = new ReactElement({
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const element2 = new ReactElement({
+        position: { x: 200, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const link = new shapes.standard.Link({
+        source: { id: element1.id },
+        target: { id: element2.id },
+      });
+      graphStore.graph.addCells([element1, element2, link]);
+
+      const linkView = linkCache.linkViews[link.id];
+      const element1View = elementCache.elementViews[element1.id];
+
+      // Only add children to source element
+      element1View.el.append(document.createElementNS('http://www.w3.org/2000/svg', 'rect'));
+
+      paper.checkPendingLinks();
+
+      // Link should still be hidden (target has no children)
+      expect(linkView.el.style.visibility).toBe('hidden');
+    });
+
+    it('should clean up pendingLinks when link is removed', () => {
+      paper = createPaper();
+
+      // Use ReactElement which has empty markup
+      const element1 = new ReactElement({
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const element2 = new ReactElement({
+        position: { x: 200, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const link = new shapes.standard.Link({
+        source: { id: element1.id },
+        target: { id: element2.id },
+      });
+      graphStore.graph.addCells([element1, element2, link]);
+
+      const pendingLinks = getPendingLinks(paper);
+
+      // Link should be in pending
+      expect(pendingLinks.has(link.id as string)).toBe(true);
+
+      // Remove the link
+      graphStore.graph.removeCells([link]);
+
+      // Should be cleaned up
+      expect(pendingLinks.has(link.id as string)).toBe(false);
+    });
+
+    it('should handle checkPendingLinks when link view was removed', () => {
+      paper = createPaper();
+
+      // Use ReactElement which has empty markup
+      const element1 = new ReactElement({
+        position: { x: 0, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const element2 = new ReactElement({
+        position: { x: 200, y: 0 },
+        size: { width: 100, height: 100 },
+      });
+      const link = new shapes.standard.Link({
+        source: { id: element1.id },
+        target: { id: element2.id },
+      });
+      graphStore.graph.addCells([element1, element2, link]);
+
+      const pendingLinks = getPendingLinks(paper);
+
+      // Link should be in pending
+      expect(pendingLinks.has(link.id as string)).toBe(true);
+
+      // Manually remove from linkCache but keep in pendingLinks (simulating race condition)
+      Reflect.deleteProperty(linkCache.linkViews, link.id);
+
+      // Should not throw
+      expect(() => paper.checkPendingLinks()).not.toThrow();
+
+      // Should clean up the orphaned pending link
+      expect(pendingLinks.has(link.id as string)).toBe(false);
+    });
   });
 });
diff --git a/packages/joint-react/src/models/react-paper.ts b/packages/joint-react/src/models/react-paper.ts
index 59c0bdc54..be7e6f13c 100644
--- a/packages/joint-react/src/models/react-paper.ts
+++ b/packages/joint-react/src/models/react-paper.ts
@@ -10,6 +10,7 @@ import type { ReactElementViewCache, ReactLinkViewCache } from '../types/paper.t
  * - Tracking mounted views in React caches for portal rendering
  * - Scheduling React updates when views mount/unmount
  * - Disabling magnets on React elements
+ * - Hiding links until their source/target elements have rendered
  * @example
  * ```typescript
  * const paper = new ReactPaper({
@@ -29,14 +30,86 @@ export class ReactPaper extends dia.Paper {
   /** Cache for link views - set by PaperStore */
   public reactLinkCache!: ReactLinkViewCache;
 
+  /** Links waiting for source/target elements to render */
+  private pendingLinks: Set<dia.Cell.ID> = new Set();
+
   constructor(options: ReactPaperOptions) {
     super(options);
     this.graphStore = options.graphStore;
   }
 
+  /**
+   * Check if an element view has rendered its React content.
+   * @param elementId - The element ID to check
+   * @returns true if element view exists and has children
+   */
+  private isElementReady(elementId: dia.Cell.ID | undefined): boolean {
+    if (!elementId) return false;
+    const elementView = this.reactElementCache.elementViews[elementId];
+    return !!elementView?.el && elementView.el.children.length > 0;
+  }
+
+  /**
+   * Check pending links and show them if their source/target are ready.
+   * Called after React renders element content.
+   */
+  public checkPendingLinks(): void {
+    if (this.pendingLinks.size === 0) return;
+
+    const linksToShow: dia.Cell.ID[] = [];
+
+    for (const linkId of this.pendingLinks) {
+      const linkView = this.reactLinkCache.linkViews[linkId];
+      if (!linkView) {
+        // Link was removed, clean up
+        this.pendingLinks.delete(linkId);
+        continue;
+      }
+
+      const link = linkView.model;
+      const sourceId = link.source().id as dia.Cell.ID;
+      const targetId = link.target().id as dia.Cell.ID;
+
+      if (this.isElementReady(sourceId) && this.isElementReady(targetId)) {
+        linksToShow.push(linkId);
+      }
+    }
+
+    // Show ready links
+    for (const linkId of linksToShow) {
+      this.pendingLinks.delete(linkId);
+      const linkView = this.reactLinkCache.linkViews[linkId];
+      if (linkView?.el) {
+        linkView.el.style.visibility = '';
+      }
+    }
+  }
+
+  /**
+   * Remove a cell from the appropriate cache.
+   * Uses Reflect.deleteProperty to satisfy `@typescript-eslint/no-dynamic-delete` rule.
+   * Performance is identical to `delete` operator.
+   * @param cell - The cell to remove from cache
+   */
+  private removeFromCache(cell: dia.Cell): void {
+    const cellId = cell.id;
+
+    if (cell.isElement()) {
+      const newElementViews = { ...this.reactElementCache.elementViews };
+      Reflect.deleteProperty(newElementViews, cellId);
+      this.reactElementCache.elementViews = newElementViews;
+    } else if (cell.isLink()) {
+      const newLinkViews = { ...this.reactLinkCache.linkViews };
+      Reflect.deleteProperty(newLinkViews, cellId);
+      this.reactLinkCache.linkViews = newLinkViews;
+      this.pendingLinks.delete(cellId);
+    }
+  }
+
   /**
    * Called when a view is mounted into the DOM.
    * Adds view to appropriate cache and schedules React update.
+   * For links, hides them until source/target elements have rendered.
    * @param view - The cell view being inserted
    * @param isInitialInsert - Whether this is the initial insert
    */
@@ -55,8 +128,24 @@ export class ReactPaper extends dia.Paper {
         ...this.reactElementCache.elementViews,
         [cellId]: view as dia.ElementView,
       };
+
+      // Check if any pending links can now be shown
+      this.checkPendingLinks();
     } else if (view.model.isLink()) {
       const linkView = view as dia.LinkView;
+      const link = linkView.model;
+      const sourceId = link.source().id as dia.Cell.ID;
+      const targetId = link.target().id as dia.Cell.ID;
+
+      // Check if source/target elements have rendered their React content
+      const isSourceReady = this.isElementReady(sourceId);
+      const isTargetReady = this.isElementReady(targetId);
+
+      if (!isSourceReady || !isTargetReady) {
+        // Hide link until source/target are ready
+        view.el.style.visibility = 'hidden';
+        this.pendingLinks.add(cellId);
+      }
 
       // Add to link views cache
       this.reactLinkCache.linkViews = {
@@ -76,24 +165,8 @@ export class ReactPaper extends dia.Paper {
    * @returns The removed cell view
    */
   removeView(cell: dia.Cell): dia.CellView {
-    const cellId = cell.id;
-
-    if (cell.isElement()) {
-      // Remove from element views cache
-      const newElementViews = { ...this.reactElementCache.elementViews };
-      Reflect.deleteProperty(newElementViews, cellId);
-      this.reactElementCache.elementViews = newElementViews;
-    } else if (cell.isLink()) {
-      // Remove from link views cache
-      const newLinkViews = { ...this.reactLinkCache.linkViews };
-      Reflect.deleteProperty(newLinkViews, cellId);
-      this.reactLinkCache.linkViews = newLinkViews;
-    }
-
-    // Schedule React update
+    this.removeFromCache(cell);
     this.graphStore.schedulePaperUpdate();
-
-    // Call parent implementation
     return super.removeView(cell);
   }
 
@@ -104,24 +177,8 @@ export class ReactPaper extends dia.Paper {
    * @internal
    */
   _hideCellView(cellView: dia.CellView): void {
-    const cellId = cellView.model.id;
-
-    if (cellView.model.isElement()) {
-      // Remove from element views cache
-      const newElementViews = { ...this.reactElementCache.elementViews };
-      Reflect.deleteProperty(newElementViews, cellId);
-      this.reactElementCache.elementViews = newElementViews;
-    } else if (cellView.model.isLink()) {
-      // Remove from link views cache
-      const newLinkViews = { ...this.reactLinkCache.linkViews };
-      Reflect.deleteProperty(newLinkViews, cellId);
-      this.reactLinkCache.linkViews = newLinkViews;
-    }
-
-    // Schedule React update
+    this.removeFromCache(cellView.model);
     this.graphStore.schedulePaperUpdate();
-
-    // Call parent implementation
     super._hideCellView(cellView);
   }
 }
diff --git a/packages/joint-react/src/store/__tests__/create-elements-size-observer.test.ts b/packages/joint-react/src/store/__tests__/create-elements-size-observer.test.ts
new file mode 100644
index 000000000..efb1eed89
--- /dev/null
+++ b/packages/joint-react/src/store/__tests__/create-elements-size-observer.test.ts
@@ -0,0 +1,288 @@
+/* eslint-disable prefer-destructuring */
+/* eslint-disable sonarjs/no-nested-functions */
+/* eslint-disable @typescript-eslint/no-require-imports */
+import type { dia } from '@joint/core';
+import type { GraphStoreSnapshot } from '../graph-store';
+import type { GraphElement } from '../../types/element-types';
+import type { GraphStoreObserver } from '../create-elements-size-observer';
+
+// Mock ResizeObserver for testing
+// eslint-disable-next-line sonarjs/public-static-readonly
+let mockResizeObserverInstances: MockResizeObserver[] = [];
+
+class MockResizeObserver {
+  private callback: ResizeObserverCallback;
+  private observedElements = new Map<Element, ResizeObserverEntry>();
+
+  constructor(callback: ResizeObserverCallback) {
+    this.callback = callback;
+    mockResizeObserverInstances.push(this);
+  }
+
+  observe(target: Element) {
+    // Simulate an entry with initial size
+    const entry = this.createEntry(target, 100, 50);
+    this.observedElements.set(target, entry);
+  }
+
+  unobserve(target: Element) {
+    this.observedElements.delete(target);
+  }
+
+  disconnect() {
+    this.observedElements.clear();
+  }
+
+  // Test helper to simulate resize
+  triggerResize(target: Element, width: number, height: number) {
+    const entry = this.createEntry(target, width, height);
+    this.observedElements.set(target, entry);
+    this.callback([entry], this as unknown as ResizeObserver);
+  }
+
+  // Test helper to trigger callback for all observed elements
+  triggerAllCallbacks() {
+    const entries = [...this.observedElements.values()];
+    if (entries.length > 0) {
+      this.callback(entries, this as unknown as ResizeObserver);
+    }
+  }
+
+  private createEntry(target: Element, width: number, height: number): ResizeObserverEntry {
+    return {
+      target,
+      contentRect: {
+        width,
+        height,
+        top: 0,
+        left: 0,
+        bottom: height,
+        right: width,
+        x: 0,
+        y: 0,
+        toJSON: () => ({}),
+      },
+      borderBoxSize: [{ inlineSize: width, blockSize: height }],
+      contentBoxSize: [{ inlineSize: width, blockSize: height }],
+      devicePixelContentBoxSize: [{ inlineSize: width, blockSize: height }],
+    } as ResizeObserverEntry;
+  }
+
+  static getLastInstance(): MockResizeObserver | undefined {
+    return mockResizeObserverInstances.at(-1);
+  }
+
+  static clearInstances() {
+    mockResizeObserverInstances = [];
+  }
+}
+
+// Replace global ResizeObserver with mock
+globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+
+describe('createElementsSizeObserver', () => {
+  let observer: GraphStoreObserver;
+  let mockOnBatchUpdate: jest.Mock;
+  let mockGetCellTransform: jest.Mock;
+  let mockGetPublicSnapshot: jest.Mock;
+  let mockElements: Record<dia.Cell.ID, GraphElement>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let createElementsSizeObserver: any;
+
+  beforeEach(() => {
+    MockResizeObserver.clearInstances();
+
+    // Reset modules and reimport to ensure the mock is used
+    jest.resetModules();
+    // Re-assign the mock after reset to ensure it's used
+    globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+    // eslint-disable-next-line unicorn/prefer-module
+    createElementsSizeObserver = require('../create-elements-size-observer').createElementsSizeObserver;
+
+    mockElements = {
+      'element-1': { x: 0, y: 0, width: 1, height: 1, type: 'ReactElement' },
+      'element-2': { x: 100, y: 100, width: 1, height: 1, type: 'ReactElement' },
+    };
+
+    mockOnBatchUpdate = jest.fn();
+    mockGetCellTransform = jest.fn((id: dia.Cell.ID) => ({
+      width: 1,
+      height: 1,
+      x: 0,
+      y: 0,
+      angle: 0,
+      element: { id } as dia.Element,
+    }));
+    mockGetPublicSnapshot = jest.fn(
+      () =>
+        ({
+          elements: mockElements,
+          links: {},
+        }) as GraphStoreSnapshot
+    );
+
+    observer = createElementsSizeObserver({
+      onBatchUpdate: mockOnBatchUpdate,
+      getCellTransform: mockGetCellTransform,
+      getPublicSnapshot: mockGetPublicSnapshot,
+    });
+  });
+
+  afterEach(() => {
+    observer.clean();
+  });
+
+  describe('add', () => {
+    it('should register element with ResizeObserver', () => {
+      const element = document.createElement('div');
+
+      observer.add({ id: 'element-1', element });
+
+      expect(observer.has('element-1')).toBe(true);
+    });
+
+    it('should return cleanup function that unregisters element', () => {
+      const element = document.createElement('div');
+
+      const cleanup = observer.add({ id: 'element-1', element });
+      expect(observer.has('element-1')).toBe(true);
+
+      cleanup();
+      expect(observer.has('element-1')).toBe(false);
+    });
+
+    it('should handle multiple elements', () => {
+      const element1 = document.createElement('div');
+      const element2 = document.createElement('div');
+
+      observer.add({ id: 'element-1', element: element1 });
+      observer.add({ id: 'element-2', element: element2 });
+
+      expect(observer.has('element-1')).toBe(true);
+      expect(observer.has('element-2')).toBe(true);
+    });
+
+    it('should process ResizeObserver callback when element is added', () => {
+      const element = document.createElement('div');
+
+      observer.add({ id: 'element-1', element });
+
+      // Trigger resize via ResizeObserver (simulates browser behavior)
+      const resizeObserver = MockResizeObserver.getLastInstance();
+      expect(resizeObserver).toBeDefined();
+      resizeObserver?.triggerResize(element, 100, 50);
+
+      expect(mockOnBatchUpdate).toHaveBeenCalledTimes(1);
+
+      const updateCall = mockOnBatchUpdate.mock.calls[0][0];
+      expect(updateCall['element-1']).toBeDefined();
+      expect(updateCall['element-1'].width).toBe(100);
+      expect(updateCall['element-1'].height).toBe(50);
+    });
+
+    it('should handle multiple elements with ResizeObserver', () => {
+      const element1 = document.createElement('div');
+      const element2 = document.createElement('div');
+
+      observer.add({ id: 'element-1', element: element1 });
+      observer.add({ id: 'element-2', element: element2 });
+
+      // Trigger resize for both elements
+      const resizeObserver = MockResizeObserver.getLastInstance();
+      resizeObserver?.triggerResize(element1, 100, 50);
+      resizeObserver?.triggerResize(element2, 200, 100);
+
+      expect(mockOnBatchUpdate).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('ResizeObserver callback', () => {
+    it('should process size changes from ResizeObserver', () => {
+      const element = document.createElement('div');
+
+      observer.add({ id: 'element-1', element });
+
+      const resizeObserver = MockResizeObserver.getLastInstance();
+      expect(resizeObserver).toBeDefined();
+
+      // Trigger initial resize
+      resizeObserver?.triggerResize(element, 100, 50);
+      expect(mockOnBatchUpdate).toHaveBeenCalledTimes(1);
+
+      // Trigger resize to a different size
+      resizeObserver?.triggerResize(element, 200, 100);
+
+      // Should be called again for the resize
+      expect(mockOnBatchUpdate).toHaveBeenCalledTimes(2);
+    });
+
+    it('should not update if size has not changed significantly', () => {
+      const element = document.createElement('div');
+
+      observer.add({ id: 'element-1', element });
+
+      const resizeObserver = MockResizeObserver.getLastInstance();
+
+      // Trigger initial resize
+      resizeObserver?.triggerResize(element, 100, 50);
+      expect(mockOnBatchUpdate).toHaveBeenCalledTimes(1);
+      mockOnBatchUpdate.mockClear();
+
+      // Trigger resize with same size (within epsilon of 0.5)
+      resizeObserver?.triggerResize(element, 100.1, 50.1);
+
+      // Should not trigger update because change is within epsilon
+      expect(mockOnBatchUpdate).not.toHaveBeenCalled();
+    });
+
+    it('should use transform function when provided', () => {
+      const element = document.createElement('div');
+      const transform = jest.fn(({ width, height }) => ({
+        width: width + 20,
+        height: height + 20,
+      }));
+
+      observer.add({ id: 'element-1', element, transform });
+
+      const resizeObserver = MockResizeObserver.getLastInstance();
+      resizeObserver?.triggerResize(element, 100, 50);
+
+      expect(transform).toHaveBeenCalled();
+
+      const updateCall = mockOnBatchUpdate.mock.calls[0][0];
+      expect(updateCall['element-1'].width).toBe(120); // 100 + 20
+      expect(updateCall['element-1'].height).toBe(70); // 50 + 20
+    });
+  });
+
+  describe('clean', () => {
+    it('should remove all observed elements', () => {
+      const element1 = document.createElement('div');
+      const element2 = document.createElement('div');
+
+      observer.add({ id: 'element-1', element: element1 });
+      observer.add({ id: 'element-2', element: element2 });
+
+      expect(observer.has('element-1')).toBe(true);
+      expect(observer.has('element-2')).toBe(true);
+
+      observer.clean();
+
+      expect(observer.has('element-1')).toBe(false);
+      expect(observer.has('element-2')).toBe(false);
+    });
+  });
+
+  describe('has', () => {
+    it('should return true for registered elements', () => {
+      const element = document.createElement('div');
+      observer.add({ id: 'element-1', element });
+
+      expect(observer.has('element-1')).toBe(true);
+    });
+
+    it('should return false for unregistered elements', () => {
+      expect(observer.has('non-existent')).toBe(false);
+    });
+  });
+});
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 a84ba5534..7064ea44f 100644
--- a/packages/joint-react/src/store/create-elements-size-observer.ts
+++ b/packages/joint-react/src/store/create-elements-size-observer.ts
@@ -111,6 +111,89 @@ function roundToTwoDecimals(value: number) {
   return Math.round(value * 100) / 100;
 }
 
+/**
+ * Options for processing a single element's size change.
+ */
+interface ProcessSizeChangeOptions {
+  readonly cellId: dia.Cell.ID;
+  readonly measuredWidth: number;
+  readonly measuredHeight: number;
+  readonly observedElement: ObservedElement | Partial<ObservedElement>;
+  readonly getCellTransform: Options['getCellTransform'];
+  readonly updatedElements: Record<dia.Cell.ID, GraphElement>;
+}
+
+/**
+ * Processes a size change for a single element.
+ * Returns true if the element was updated, false otherwise.
+ */
+function processSizeChange(options: ProcessSizeChangeOptions): boolean {
+  const {
+    cellId,
+    measuredWidth,
+    measuredHeight,
+    observedElement,
+    getCellTransform,
+    updatedElements,
+  } = options;
+
+  const currentCellTransform = getCellTransform(cellId);
+
+  // Compare the measured size with the current cell size using epsilon to avoid jitter
+  const hasSizeChanged =
+    Math.abs(currentCellTransform.width - measuredWidth) > EPSILON ||
+    Math.abs(currentCellTransform.height - measuredHeight) > EPSILON;
+
+  if (!hasSizeChanged) {
+    return false;
+  }
+
+  // We observe just width and height, not x and y
+  if (
+    currentCellTransform.width === measuredWidth &&
+    currentCellTransform.height === measuredHeight
+  ) {
+    return false;
+  }
+
+  const graphElement = updatedElements[cellId];
+  if (!graphElement) {
+    return false;
+  }
+
+  const { transform: sizeTransformFunction = defaultTransform } = observedElement;
+
+  const lastWidth = roundToTwoDecimals(observedElement.lastWidth ?? 0);
+  const lastHeight = roundToTwoDecimals(observedElement.lastHeight ?? 0);
+
+  // Check if the change is significant compared to the last observed size
+  const widthDifference = Math.abs(lastWidth - measuredWidth);
+  const heightDifference = Math.abs(lastHeight - measuredHeight);
+  if (widthDifference <= EPSILON && heightDifference <= EPSILON) {
+    return false;
+  }
+
+  // Update cached size values
+  observedElement.lastWidth = measuredWidth;
+  observedElement.lastHeight = measuredHeight;
+
+  const { x, y, angle, element: cell } = currentCellTransform;
+  updatedElements[cellId] = {
+    ...graphElement,
+    ...sizeTransformFunction({
+      x: x ?? 0,
+      y: y ?? 0,
+      angle: angle ?? 0,
+      element: cell,
+      width: measuredWidth,
+      height: measuredHeight,
+      id: cellId,
+    }),
+  };
+
+  return true;
+}
+
 /**
  * Creates an observer for element size changes using the ResizeObserver API.
  *
@@ -123,6 +206,7 @@ function roundToTwoDecimals(value: number) {
  * - Batches multiple size changes together for performance
  * - Compares sizes with epsilon to avoid jitter from sub-pixel rendering
  * - Supports custom size update handlers
+ * - Performs immediate synchronous measurement on add to prevent flickering
  * @param options - The options for creating the size observer
  * @returns A GraphStoreObserver instance with methods to add/remove observers
  */
@@ -135,6 +219,66 @@ export function createElementsSizeObserver(options: Options): GraphStoreObserver
   } = options;
   const observedElementsByCellId = new Map<dia.Cell.ID, ObservedElement>();
   const cellIdByDomElement = new Map<HTMLElement | SVGElement, dia.Cell.ID>();
+
+  // Pending immediate measurements to batch
+  const pendingImmediateMeasurements = new Map<dia.Cell.ID, { width: number; height: number }>();
+  let isImmediateBatchScheduled = false;
+
+  /**
+   * Flushes all pending immediate measurements in a single batch update.
+   */
+  function flushImmediateMeasurements() {
+    if (pendingImmediateMeasurements.size === 0) {
+      isImmediateBatchScheduled = false;
+      return;
+    }
+
+    const publicSnapshot = getPublicSnapshot();
+    const elementsRecord = publicSnapshot.elements as Record<dia.Cell.ID, GraphElement>;
+    const updatedElements: Record<dia.Cell.ID, GraphElement> = { ...elementsRecord };
+    let hasAnySizeChange = false;
+
+    for (const [cellId, { width, height }] of pendingImmediateMeasurements) {
+      const observedElement = observedElementsByCellId.get(cellId) ?? DEFAULT_OBSERVED_ELEMENT;
+
+      const measuredWidth = roundToTwoDecimals(width);
+      const measuredHeight = roundToTwoDecimals(height);
+
+      const wasUpdated = processSizeChange({
+        cellId,
+        measuredWidth,
+        measuredHeight,
+        observedElement,
+        getCellTransform,
+        updatedElements,
+      });
+
+      if (wasUpdated) {
+        hasAnySizeChange = true;
+      }
+    }
+
+    pendingImmediateMeasurements.clear();
+    isImmediateBatchScheduled = false;
+
+    if (hasAnySizeChange) {
+      onBatchUpdate(updatedElements);
+    }
+  }
+
+  /**
+   * Schedules an immediate measurement to be processed in the current microtask batch.
+   */
+  function scheduleImmediateMeasurement(cellId: dia.Cell.ID, width: number, height: number) {
+    pendingImmediateMeasurements.set(cellId, { width, height });
+
+    if (!isImmediateBatchScheduled) {
+      isImmediateBatchScheduled = true;
+      // Use queueMicrotask for synchronous-like batching within the same execution context
+      queueMicrotask(flushImmediateMeasurements);
+    }
+  }
+
   const observer = new ResizeObserver((entries) => {
     // Process all entries as a single batch
     let hasAnySizeChange = false;
@@ -162,62 +306,20 @@ export function createElementsSizeObserver(options: Options): GraphStoreObserver
 
       const measuredWidth = roundToTwoDecimals(inlineSize);
       const measuredHeight = roundToTwoDecimals(blockSize);
-      const currentCellTransform = getCellTransform(cellId);
-
-      // Compare the measured size with the current cell size using epsilon to avoid jitter
-      const hasSizeChanged =
-        Math.abs(currentCellTransform.width - measuredWidth) > EPSILON ||
-        Math.abs(currentCellTransform.height - measuredHeight) > EPSILON;
-
-      if (!hasSizeChanged) {
-        continue;
-      }
-
-      // We observe just width and height, not x and y
-      if (
-        currentCellTransform.width === measuredWidth &&
-        currentCellTransform.height === measuredHeight
-      ) {
-        continue;
-      }
-
-      const graphElement = updatedElements[cellId];
-      if (!graphElement) {
-        throw new Error(`Element with id ${cellId} not found in graph data ref`);
-      }
-
       const observedElement = observedElementsByCellId.get(cellId) ?? DEFAULT_OBSERVED_ELEMENT;
-      const { transform: sizeTransformFunction = defaultTransform } = observedElement;
 
-      const lastWidth = roundToTwoDecimals(observedElement.lastWidth ?? 0);
-      const lastHeight = roundToTwoDecimals(observedElement.lastHeight ?? 0);
+      const wasUpdated = processSizeChange({
+        cellId,
+        measuredWidth,
+        measuredHeight,
+        observedElement,
+        getCellTransform,
+        updatedElements,
+      });
 
-      // Check if the change is significant compared to the last observed size
-      const widthDifference = Math.abs(lastWidth - measuredWidth);
-      const heightDifference = Math.abs(lastHeight - measuredHeight);
-      if (widthDifference <= EPSILON && heightDifference <= EPSILON) {
-        continue;
+      if (wasUpdated) {
+        hasAnySizeChange = true;
       }
-
-      // Update cached size values
-      observedElement.lastWidth = measuredWidth;
-      observedElement.lastHeight = measuredHeight;
-
-      const { x, y, angle, element: cell } = currentCellTransform;
-      updatedElements[cellId] = {
-        ...graphElement,
-        ...sizeTransformFunction({
-          x: x ?? 0,
-          y: y ?? 0,
-          angle: angle ?? 0,
-          element: cell,
-          width: measuredWidth,
-          height: measuredHeight,
-          id: cellId,
-        }),
-      };
-
-      hasAnySizeChange = true;
     }
 
     if (!hasAnySizeChange) {
@@ -230,13 +332,23 @@ export function createElementsSizeObserver(options: Options): GraphStoreObserver
 
   return {
     add({ id, element, transform }: SetMeasuredNodeOptions) {
+      // Register with ResizeObserver for future changes
       observer.observe(element, resizeObserverOptions);
       observedElementsByCellId.set(id, { element, transform });
       cellIdByDomElement.set(element, id);
+
+      // Perform immediate synchronous measurement to prevent flickering
+      // This eliminates the 2ms delay from ResizeObserver callback
+      const rect = element.getBoundingClientRect();
+      if (rect.width > 0 && rect.height > 0) {
+        scheduleImmediateMeasurement(id, rect.width, rect.height);
+      }
+
       return () => {
         observer.unobserve(element);
         observedElementsByCellId.delete(id);
         cellIdByDomElement.delete(element);
+        pendingImmediateMeasurements.delete(id);
       };
     },
     clean() {
@@ -245,6 +357,8 @@ export function createElementsSizeObserver(options: Options): GraphStoreObserver
       }
       observedElementsByCellId.clear();
       cellIdByDomElement.clear();
+      pendingImmediateMeasurements.clear();
+      isImmediateBatchScheduled = false;
       observer.disconnect();
     },
     has(id: dia.Cell.ID) {
diff --git a/packages/joint-react/src/store/paper-store.ts b/packages/joint-react/src/store/paper-store.ts
index 5a33bbfa4..0c421013e 100644
--- a/packages/joint-react/src/store/paper-store.ts
+++ b/packages/joint-react/src/store/paper-store.ts
@@ -146,6 +146,9 @@ export class PaperStore {
 
     // Create a new ReactPaper instance
     // ReactPaper handles view lifecycle internally via insertView/removeView
+    // NOTE: We don't use cellVisibility to hide links because JointJS's
+    // unmountedList.rotate() causes O(n) checks per frame when returning false.
+    // Link visibility should be handled in React layer instead.
     const paper = new ReactPaper({
       async: true,
       sorting: dia.Paper.sorting.APPROX,
@@ -160,41 +163,44 @@ export class PaperStore {
       afterRender: (() => {
         // Re-entrancy guard to prevent infinite loops
         let isProcessing = false;
-        return () => {
+        return function (this: ReactPaper) {
           if (isProcessing) {
             return;
           }
           isProcessing = true;
-          try {
-            // Iterate through all element views and capture port elements
-            let hasPortsChanged = false;
-            for (const view of Object.values(cache.elementViews)) {
-              const portElementsCache = (
-                view as dia.ElementView & {
-                  _portElementsCache?: Record<string, PortElementsCacheEntry>;
-                }
-              )._portElementsCache;
-              if (!portElementsCache) {
-                continue;
-              }
-              const newPorts = store.getNewPorts({
-                state: graphStore.internalState,
-                cellId: view.model.id as dia.Cell.ID,
-                portElementsCache,
-                portsData: cache.portsData,
-              });
-              if (newPorts && newPorts !== cache.portsData) {
-                cache.portsData = newPorts;
-                hasPortsChanged = true;
+
+          // Check if any pending links can now be shown
+          this.checkPendingLinks();
+
+          // Iterate through all element views and capture port elements
+          let hasPortsChanged = false;
+          for (const view of Object.values(cache.elementViews)) {
+            const portElementsCache = (
+              view as dia.ElementView & {
+                _portElementsCache?: Record<string, PortElementsCacheEntry>;
               }
+            )._portElementsCache;
+            if (!portElementsCache) {
+              continue;
             }
-            // Only schedule update if ports actually changed
-            if (hasPortsChanged) {
-              graphStore.schedulePaperUpdate();
+            const newPorts = store.getNewPorts({
+              state: graphStore.internalState,
+              cellId: view.model.id as dia.Cell.ID,
+              portElementsCache,
+              portsData: cache.portsData,
+            });
+            if (newPorts && newPorts !== cache.portsData) {
+              cache.portsData = newPorts;
+              hasPortsChanged = true;
             }
-          } finally {
-            isProcessing = false;
           }
+
+          // Only schedule update if ports actually changed
+          if (hasPortsChanged) {
+            graphStore.schedulePaperUpdate();
+          }
+
+          isProcessing = false;
         };
       })(),
       ...paperOptions,
diff --git a/packages/joint-react/src/store/state-flush.ts b/packages/joint-react/src/store/state-flush.ts
index a69e89f63..ec510d069 100644
--- a/packages/joint-react/src/store/state-flush.ts
+++ b/packages/joint-react/src/store/state-flush.ts
@@ -11,6 +11,11 @@ import type {
 } from './graph-store';
 import type { PaperStore } from './paper-store';
 
+/**
+ * Default point used as fallback when position is not available.
+ */
+const DEFAULT_POINT = { x: 0, y: 0 } as const;
+
 /**
  * GOLDEN RULE: All setState calls must happen through these flush functions.
  * This module isolates state mutations to ensure they only happen in scheduler's onFlush.
@@ -116,7 +121,7 @@ export function flushLayoutState(options: FlushLayoutStateOptions): void {
 
   for (const element of elements) {
     const size = element.get('size');
-    const position = element.get('position') ?? { x: 0, y: 0 };
+    const position = element.get('position') ?? DEFAULT_POINT;
     const angle = element.get('angle') ?? 0;
     if (!size) continue;
 
@@ -153,8 +158,8 @@ export function flushLayoutState(options: FlushLayoutStateOptions): void {
         const linkView = paper.findViewByModel(link) as dia.LinkView | null;
         if (!linkView) continue;
 
-        const sourcePoint = linkView.sourcePoint ?? { x: 0, y: 0 };
-        const targetPoint = linkView.targetPoint ?? { x: 0, y: 0 };
+        const sourcePoint = linkView.sourcePoint ?? DEFAULT_POINT;
+        const targetPoint = linkView.targetPoint ?? DEFAULT_POINT;
         const d = linkView.getSerializedConnection?.() ?? '';
 
         const newLinkLayout: LinkLayout = {

From 26e2ff974cbb5d8368f20463a40b06acbc1f96d3 Mon Sep 17 00:00:00 2001
From: samuelgja <samuel.gjabel@gmail.com>
Date: Wed, 11 Feb 2026 18:58:54 +0700
Subject: [PATCH 5/5] chore(joint-react): add claude.md

---
 packages/joint-react/CLAUDE.md | 103 +++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 packages/joint-react/CLAUDE.md

diff --git a/packages/joint-react/CLAUDE.md b/packages/joint-react/CLAUDE.md
new file mode 100644
index 000000000..a3666e430
--- /dev/null
+++ b/packages/joint-react/CLAUDE.md
@@ -0,0 +1,103 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`@joint/react` is the React bindings library for JointJS. It provides React components and hooks for building diagramming applications with JointJS, rendering diagram elements as React components via SVG foreignObject portals.
+
+**Stack:** TypeScript 5.9, React 19 (peer: >=18 <20), esbuild (build), Vite (storybook/dev), Jest 30 + @testing-library/react (testing), ESLint 9 flat config, Storybook 10
+
+## Common Commands
+
+```bash
+# Build (esbuild → dist/cjs, dist/esm, dist/types)
+yarn build
+
+# Run all checks (typecheck + lint + jest)
+yarn test
+
+# Run individual checks
+yarn typecheck              # tsc --noEmit
+yarn lint                   # ESLint
+yarn lint-fix               # ESLint with auto-fix
+yarn jest                   # Jest tests only
+
+# Run a single test file
+yarn jest --testPathPattern="use-elements"
+
+# Run tests in watch mode
+yarn jest --watch
+
+# Storybook (dev server on :6006)
+yarn storybook
+
+# Build storybook
+yarn build-storybook
+```
+
+## Architecture
+
+### Three Control Modes
+
+The library supports three state management modes, determined by props on `GraphProvider`:
+
+1. **Uncontrolled** — Pass `elements`/`links` as initial data. The internal `GraphStore` owns state. No `onElementsChange`/`onLinksChange` callbacks.
+2. **React-controlled** — Pass `onElementsChange`/`onLinksChange`. Changes flow through React state (`useState` setter pattern).
+3. **External-store-controlled** — Pass `externalStore` prop. Integrates with Redux, Zustand, Jotai, etc.
+
+### Component Tree
+
+```
+GraphProvider (provides GraphStoreContext)
+  └── Paper (provides PaperStoreContext, renders canvas)
+        ├── Element portals (React components rendered into SVG via foreignObject)
+        └── Link portals (React components for link rendering)
+```
+
+### Key Source Directories
+
+- **`src/components/`** — `GraphProvider` and `Paper` (the two public components), plus internal `Link`, `Port`, `TextNode`, `Highlighters`
+- **`src/hooks/`** — Public hooks (`useGraph`, `usePaper`, `useElements`, `useLinks`, `useElement`, `useCellActions`, `useNodeSize`, `usePaperEvents`, etc.)
+- **`src/store/`** — `GraphStore` (central state: elements, links, sync) and `PaperStore` (per-paper view state, portals, element sizing)
+- **`src/models/`** — `ReactElement` (empty markup, React renders via portal), `ReactLink`, `ReactPaper` (extended `dia.Paper` with React view lifecycle)
+- **`src/state/`** — Selectors (`mapElementAttributesToData`, `mapLinkAttributesToData`) and sync logic between JointJS models and React state
+- **`src/types/`** — `GraphElement`, `GraphLink`, `PaperProps`, event types
+- **`src/utils/`** — Joint JSX→markup conversion, event handling, scheduling, equality checks
+- **`src/theme/`** — Default link theme and marker presets (arrow, circle, diamond, etc.)
+
+### Data Flow
+
+Elements and links are `Record<dia.Cell.ID, Data>` objects. GraphStore syncs these with JointJS `dia.Graph` models bidirectionally:
+
+1. **React → JointJS:** `updateGraph()` diffs incoming records against current graph cells
+2. **JointJS → React:** `stateSync` listens to model `change:*` events, maps attributes back to data via selectors, and flushes updates
+
+### Rendering Pipeline
+
+`Paper` renders elements via React portals into SVG `<foreignObject>` nodes managed by JointJS. `ReactElement` has empty `markup` — all visual content comes from the `renderElement` callback prop. Large graphs (>100 cells) use `useDeferredValue` for performance.
+
+### Build Output
+
+`build.ts` uses esbuild to produce:
+- `dist/cjs/` — CommonJS (bundled)
+- `dist/esm/` — ES modules (bundled)
+- `dist/types/` — TypeScript declarations (via `tsc --project tsconfig.types.json`)
+
+External deps (react, react-dom, @joint/core, use-sync-external-store) are excluded from bundles.
+
+## Test Setup
+
+- **Framework:** Jest 30 with jsdom environment
+- **Transform:** @swc/jest for TypeScript/JSX
+- **Test location:** `src/**/__tests__/*.test.ts(x)`
+- **Mocks:** `__mocks__/jest-setup.ts` provides SVG DOM stubs (SVGPathElement, SVGAngle, SVGMatrix, ResizeObserver)
+- **Module aliases:** `@joint/react` → `src/index.ts`, `src/*` → `<rootDir>/src/*`
+
+## Key Patterns
+
+- **Portal-based rendering:** React components render into SVG foreignObject nodes owned by JointJS Paper
+- **Context hierarchy:** `GraphStoreContext` → `PaperStoreContext` → `CellIdContext` (nested providers)
+- **Selector subscriptions:** Hooks accept `selector` and `equalityFn` params for fine-grained reactivity (similar to Redux `useSelector`)
+- **Imperative escape hatch:** `Paper` forwards ref to expose `PaperStore` for imperative operations
+- **Scheduler-based batching:** State flushes are batched via a microtask scheduler to avoid excessive re-renders