v2

Author: zbeyens

.agents/AGENTS.md

@@ -25,6 +25,7 @@
 - Barrels: If you change package exports, move public files, add/remove files under exported folders, or CI says `pnpm brl` produced changes, run `pnpm brl` before final verification/commit and include the generated barrel updates.
 - Do not write TDD cases for dead code/legacy removal assertions (for example: "should not contain old API X anymore"). Remove the dead path directly and keep tests focused on current behavior.
 - Prefer inline when used once; extract constants only when reused.
+- Type inference is mandatory for Plate/Plite callback APIs. Do not add explicit callback parameter annotations like `(tx: EditorUpdateTransaction)` to silence TypeScript when the API should infer them; fix the owning generic/API type instead. Explicit annotations are only acceptable at exported public signatures or true external boundary adapters.
 
 ## Tooling
 

.agents/skills/plate-next/SKILL.md

@@ -90,6 +90,11 @@ Rules:
   like `PreInsertOptions`, explicit callback parameter annotations, or
   `Parameters<typeof fn>` plumbing just to silence TypeScript. Fix the owning
   API/source typing so the call site stays inferred.
+- Do not add local fixture-shape aliases in tests, such as
+  `type EditorFixture = { children; selection }`, to hide weak hyperscript
+  typing. If many tests need the same JSX/editor fixture shape, repair or
+  export the test-utils owner type and let call sites use that source-owned
+  fixture type without local casts.
 - Preserve main-style inline test setup. Do not extract `const plugins`,
   `const options`, helper variables, or wrapper factories from a test just to
   placate migrated types when `origin/main` kept the setup inline. Inline
@@ -280,6 +285,8 @@ Default suspicion list:
 - explicit callback/helper types in tests that replace inference from
   `createBasePlugin`, `createBaseEditor`, plugin config, tx groups, or editor
   API calls.
+- local JSX/editor fixture aliases in tests, especially `{ children; selection
+  }` shapes that should come from `@platejs/test-utils`.
 - duplicate Plate helpers around Plite APIs.
 - docs/examples that teach legacy compatibility instead of latest state.
 

AGENTS.md

@@ -30,6 +30,7 @@
 - Barrels: If you change package exports, move public files, add/remove files under exported folders, or CI says `pnpm brl` produced changes, run `pnpm brl` before final verification/commit and include the generated barrel updates.
 - Do not write TDD cases for dead code/legacy removal assertions (for example: "should not contain old API X anymore"). Remove the dead path directly and keep tests focused on current behavior.
 - Prefer inline when used once; extract constants only when reused.
+- Type inference is mandatory for Plate/Plite callback APIs. Do not add explicit callback parameter annotations like `(tx: EditorUpdateTransaction)` to silence TypeScript when the API should infer them; fix the owning generic/API type instead. Explicit annotations are only acceptable at exported public signatures or true external boundary adapters.
 
 ## Tooling
 

packages/core/package.json

@@ -64,7 +64,6 @@
     "nanoid": "^5.1.5",
     "optics-ts": "2.4.1",
     "react-compiler-runtime": "^1.0.0",
-    "scroll-into-view-if-needed": "^3.1.0",
     "use-deep-compare": "^1.3.0",
     "zustand": "^5.0.5",
     "zustand-x": "6.2.1"

packages/core/src/internal/plugin/pipeTransformInitialValue.ts

@@ -12,7 +12,7 @@ export const pipeTransformInitialValue = (editor: BaseEditor) => {
   editor.runtime.pluginCache.transformInitialValue.forEach((key) => {
     const p = editor.getPlugin({ key });
 
-    if (isEditOnly(editor.api.dom.isReadOnly(), p, 'transformInitialValue')) {
+    if (isEditOnly(editor.read.view.isReadOnly(), p, 'transformInitialValue')) {
       return;
     }
 

packages/core/src/internal/plugin/plateChangeHandlers.spec.tsx

@@ -0,0 +1,79 @@
+/** @jsx jsxt */
+
+import { jsxt } from '@platejs/test-utils';
+
+jsxt;
+
+import { createBaseEditor } from '../../lib/editor';
+import { createBasePlugin } from '../../lib/plugin';
+
+describe('plate change handlers', () => {
+  it('dispatches node change handlers from Plite node change events', () => {
+    const onNodeChange = mock();
+    const NodeObserverPlugin = createBasePlugin({
+      handlers: { onNodeChange },
+      key: 'nodeObserver',
+    });
+    const editor = createBaseEditor({
+      plugins: [NodeObserverPlugin],
+      value: [{ children: [{ text: 'hello' }], type: 'p' }],
+    });
+
+    onNodeChange.mockClear();
+
+    editor.update.nodes.set({ variant: 'lead' } as any, { at: [0] });
+
+    expect(onNodeChange).toHaveBeenCalledTimes(1);
+    expect(onNodeChange.mock.calls[0]?.[0]).toMatchObject({
+      node: {
+        children: [{ text: 'hello' }],
+        type: 'p',
+        variant: 'lead',
+      },
+      operation: {
+        path: [0],
+        type: 'set_node',
+      },
+      prevNode: {
+        children: [{ text: 'hello' }],
+        type: 'p',
+      },
+    });
+  });
+
+  it('dispatches text change handlers from Plite text change events', () => {
+    const onTextChange = mock();
+    const TextObserverPlugin = createBasePlugin({
+      handlers: { onTextChange },
+      key: 'textObserver',
+    });
+    const editor = createBaseEditor({
+      plugins: [TextObserverPlugin],
+      selection: {
+        anchor: { offset: 5, path: [0, 0] },
+        focus: { offset: 5, path: [0, 0] },
+      },
+      value: [{ children: [{ text: 'hello' }], type: 'p' }],
+    });
+
+    onTextChange.mockClear();
+
+    editor.update.text.insert('!');
+
+    expect(onTextChange).toHaveBeenCalledTimes(1);
+    expect(onTextChange.mock.calls[0]?.[0]).toMatchObject({
+      node: {
+        children: [{ text: 'hello!' }],
+        type: 'p',
+      },
+      operation: {
+        offset: 5,
+        path: [0, 0],
+        text: '!',
+        type: 'insert_text',
+      },
+      prevText: 'hello',
+      text: 'hello!',
+    });
+  });
+});

packages/core/src/internal/plugin/plateChangeHandlers.ts

@@ -0,0 +1,82 @@
+import type { Descendant, NodeOperation, TextOperation } from '@platejs/plite';
+import { defineEditorExtension } from '@platejs/plite';
+
+import type { BaseEditor } from '../../lib/editor';
+import { pipeOnNodeChange } from '../../lib/utils/pipeOnNodeChange';
+import { pipeOnTextChange } from '../../lib/utils/pipeOnTextChange';
+
+type PlateNodeChangeCallback = (options: {
+  editor: BaseEditor;
+  node: Descendant;
+  operation: NodeOperation;
+  prevNode: Descendant;
+}) => void;
+
+type PlateTextChangeCallback = (options: {
+  editor: BaseEditor;
+  node: Descendant;
+  operation: TextOperation;
+  prevText: string;
+  text: string;
+}) => void;
+
+type PlateChangeCallbacks = {
+  onNodeChange?: PlateNodeChangeCallback | null;
+  onTextChange?: PlateTextChangeCallback | null;
+};
+
+const PLATE_CHANGE_CALLBACKS = new WeakMap<BaseEditor, PlateChangeCallbacks>();
+
+export const setPlateChangeCallbacks = (
+  editor: BaseEditor,
+  callbacks: PlateChangeCallbacks
+) => {
+  PLATE_CHANGE_CALLBACKS.set(editor, callbacks);
+};
+
+const getPlateChangeCallbacks = (editor: BaseEditor): PlateChangeCallbacks =>
+  PLATE_CHANGE_CALLBACKS.get(editor) ?? {};
+
+export const createPlateChangeHandlersExtension = (editor: BaseEditor) =>
+  defineEditorExtension({
+    name: 'plate:change-handlers',
+    onNodeChange({ node, operation, prevNode }) {
+      if (
+        editor.runtime.pluginCache.handlers.onNodeChange.length === 0 &&
+        !getPlateChangeCallbacks(editor).onNodeChange
+      ) {
+        return;
+      }
+
+      const handled = pipeOnNodeChange(editor, node, prevNode, operation);
+
+      if (handled) return;
+
+      getPlateChangeCallbacks(editor).onNodeChange?.({
+        editor,
+        node,
+        operation,
+        prevNode,
+      });
+    },
+    onTextChange({ node, operation, prevText, text }) {
+      if (
+        editor.runtime.pluginCache.handlers.onTextChange.length === 0 &&
+        !getPlateChangeCallbacks(editor).onTextChange
+      ) {
+        return;
+      }
+
+      const handled = pipeOnTextChange(editor, node, text, prevText, operation);
+
+      if (handled) return;
+
+      getPlateChangeCallbacks(editor).onTextChange?.({
+        editor,
+        node,
+        operation,
+        prevText,
+        text,
+      });
+    },
+  });

packages/core/src/internal/plugin/resolveCreatePluginTest.ts

@@ -1,13 +1,7 @@
-import type {
-  AnyPluginConfig,
-  PluginConfig,
-} from '../../lib/plugin/SlatePlugin';
+import type { AnyPluginConfig } from '../../lib/plugin/SlatePlugin';
 
 import { createBaseEditor } from '../../lib/editor';
-import {
-  createBasePlugin,
-  type CreateBasePluginInput,
-} from '../../lib/plugin/createBasePlugin';
+import { createBasePlugin } from '../../lib/plugin/createBasePlugin';
 import { resolvePlugin } from './resolvePlugin';
 
 export const resolvePluginTest = <P extends AnyPluginConfig>(p: P) => {
@@ -24,8 +18,10 @@ export const resolvePluginTest = <P extends AnyPluginConfig>(p: P) => {
   return editor.getPlugin({ key });
 };
 
-export const resolveCreatePluginTest = ((plugin: CreateBasePluginInput) => {
-  const p = createBasePlugin<PluginConfig>(plugin);
+export const resolveCreatePluginTest = ((
+  plugin: Parameters<typeof createBasePlugin>[0]
+) => {
+  const p = createBasePlugin(plugin);
 
   const editor = createBaseEditor({
     plugins: [p],